SPlaC v1.01 
SERS and Plasmonics Codes package for Matlab

Contact: eric.leru@vuw.ac.nz

Website: http://www.victoria.ac.nz/raman/book/codes.aspx         

Contents
%%%%%%%%%

1. License and referencing
2. Description
3. Installation
4. Disclaimer
5. Feedback 
6. Getting started
7. Changes to version 1.01

%%%%%%%%%%%%%
1. License
%%%%%%%%%%%%%

Copyright 2008 Eric Le Ru and Pablo Etchegoin.

This package, including all its files and content are under the
following copyright: 2008 Eric Le Ru and Pablo Etchegoin.

The package may be used freely for research, teaching,
or personal use. The unmodified complete package
(including the README files) may be re-distributed
and freely exchanged for pure research purposes, but cannot
be commercialized or used for commercial/government purposes. 

If research results obtained using the package are published
in the scientific literature (or in any other form), the package
should be appropriately referenced through its link to the book:

E. C. Le Ru and P. G. Etchegoin, Principles of Surface-Enhanced
Raman Spectroscopy and Related Plasmonic Effects
(Elsevier, Amsterdam, 2009).


%%%%%%%%%%%%%%%%
2. Description
%%%%%%%%%%%%%%%%

This package contains a suite of Matlab codes to carry out various EM
calculations relevant to SERS and plasmonics. Most of the underlying theory
and relevant formulae are described in the aforementioned book (see
license above).
The relevant equations and sections from the book are referenced when possible
in the "inline comments" to the codes. However, the codes can also be used
independently of the book (most of the theory can also be found in standard EM
textbooks).

This package includes:

- 30 self-running MatLab codes (functions)
  to reproduce most of the "theoretical" figures of the book 
  (in directory "BookFigures").

- Analytical expressions for the optical properties of silver (Ag)
  and gold (Au) in the visible/NIR region
  (in directory "General").

- Codes to evaluate reflection/refraction at multilayer planar interfaces
  (in directory "Plane").
  These include local-field calculations and example scripts for Surface Plasmon
  Resonances (SPRs) in the Otto and Kretsmann configurations.

- Ellipsoids in the electrostatics approximation
  (in directory "Ellipsoids").
  These include local-field calculations
  relevant to SERS (average and maximum enhancement factors) for prolate
  and oblate spheroids, and for general ellipsoids.
  
- Mie theory codes for plane wave excitation
  (in directory "Mie/PWE").
  These include radiation profile and
  local field calculations along with plotting tools for visualization.

- Extension of Mie theory to dipolar emission
  (in directory "Mie/DIP").
  These include radiation profile and radiative and
  non-radiative enhancements calculations,
  along with plotting tools for visualization.

- Extension of Mie theory to spherical multilayers (e.g. coated sphere)
  (in directory "Mie/MUL").
  These codes reuse many of the codes in "Mie/PWE" and "Mie/DIP".

- Scripts to obtain useful symbolic expressions related to Mie theory
  (in directory "Mie/SYM").
  The Matlab "symbolic toolbox" is necessary to run these.


%%%%%%%%%%%%%%%%%
3. Installation
%%%%%%%%%%%%%%%%%

- Unzip the SPlaC.zip file, keeping the subdirectory structure for
  clarity.
- Then set your Matlab current directory to 'SPlaC' and 
  run the "InitPath.m" function once in Matlab to add all the SPlaC
  subdirectories to your Matlab path. All the SPlaC functions and scripts
  are then accessible from the command line. This allows all codes
  to run and communicate with each other irrespective of the current directory.

Note that you must run "InitPath.m" each time you restart Matlab.
To avoid this step, you may add all SPlaC folders to your Matlab path
permanently or edit the startup.m file to do that (check Matlab
help for details).


%%%%%%%%%%%%%%%
4. Disclaimer
%%%%%%%%%%%%%%%

These codes have been developed and tested with Matlab 7.5.0 (R2007b) 
on a PC running Microsoft Windows XP Pro SP2.
Slight changes may be necessary to run them on older (or newer!) version
of Matlab.

Although every efforts have been made to get rid of bugs (programming
bugs, or even incorrect physical formulae), some may (must, we could say)
still be present. We hope the users will help us identify them and we
will try to update the codes when necessary.

Note also in this context that these codes do not implement a strict
error checking of the user inputs, i.e. following the famous English 
proverb "garbage in, garbage out" (also known as "GIGO" in computer 
science), if the parameters are incorrect during a function call, 
errors will occur.

The authors do not accept any responsibility for improper use of the 
codes, accidental errors that might still be present in them, or 
improper interpretation of their limitations and/or results derived 
therefrom. It is the responsibility of the user to check the validity 
of the inputs/outputs, their physical interpretation, and their 
suitability for his/her specific problem.

%%%%%%%%%%%%%%%
5. Feedback
%%%%%%%%%%%%%%%

We would like to hear from the users of these codes to improve them.
This includes simple issues of layouts and organization
of the information or plain errors.
Please feel free to send us any feedback (good or bad), bug reports,
questions, comments, or suggestions to:
eric.leru@vuw.ac.nz


%%%%%%%%%%%%%%%%%%%%
6. Getting started
%%%%%%%%%%%%%%%%%%%%

The easiest way (perhaps) to start realizing the extent of the codes, 
and what can be done with them, is to try to reproduce the figures from 
the book in the directory "BookFigures". From this latter directory, 
each individual m-file (a MatLab function) reproduces a specific 
figure  shown in the book and its accompanying calculations.

The reason for trying to gain familiarity with the codes by reproducing 
figures is twofold. First of all, the codes run by themselves and, 
therefore, the inexperienced user is spared the work of having to 
decide which parameters he/she needs to start the calculation. In 
addition, the figures and the results can (and should) be used in 
conjunction with the book itself. In that manner, a lengthy explanation 
of the physical meaning of the calculation (which would be impossible 
to include in the code itself) is readily available. Moreover, the reader
can also adapt the figure to his/her specific needs, or "play with the
parameters" to get a deeper understanding.

Once the is user familiar with the meaning of the calculation,
the codes producing the figures can be inspected. 
The most important programming lines are accompanied by a suitable comment 
or remark. We believe any user with a minimum of experience in MatLab 
can easily follow the logic of the calculation. The main exception
to this are the lines of code used for plotting and visualization, which
are not explained in as much detail, but can be understood using the
Matlab help.
For example, the MatLab script “MakeFig6_11.m”, to reproduce Figure 11 
of Chapter 6, contains under close inspection a call to the routine: 
“PweSolveSingleSphere”, which solves the Mie scattering problem for a 
single sphere. This code therefore provides a hands-on example of how 
to call this routine.
In this way, a potential user can learn without much effort and through examples 
how the different routines can be pieced together to produce a specific 
outcome. This can then be potentially be used for different needs or 
applications beyond the ones shown in the book. 

In the case of the codes for Mie theory, two functions, "tt PweFullMonty" and
"DipFullMonty" are also provided
to give an illustration of the possibilities of the codes by producing
a number of representative figures. These are a good starting point to
browse and understand the codes. These can be called simply by running the scripts
"PweFullMonty" for Mie theory for plane wave excitation, and
"DipFullMonty" for Mie theory for dipole emission.

Finally, the codes can be browsed in HTML format in the SPlaC online
help. Thanks to the cross-linking of all functions and scripts, this
provides a relatively easy and efficient way to navigate the codes.
The SPlaC online help can be found at:
http://www.victoria.ac.nz/raman/book/Codes/helpstart.html
from where it can also be downloaded as a zip file for local browsing.

%%%%%%%%%%%%%%%%%%%%%%%%%%%
7. Changes to version 1.01
%%%%%%%%%%%%%%%%%%%%%%%%%%%

Below is a summary of the changes made from v1.0 to v1.01
Note that the help files were not updated.

1/ In PwePlotThetaDep:

Legend is incorrect.

Replaced sLegend{2*ll-1} and  sLegend{2*ll} by
sLegend{ll} and sLegend{ll+length(lambda0)}

It now reads:

    % prepare legend for figure
    sLegend{ll}=['F_{E4}^0(\theta,\phi=0) - \lambda=' num2str(lambda(indLambda(ll)))];
    sLegend{ll+length(lambda0)}=['F_{E4}^0(\theta,\phi=90^\circ) - \lambda=' num2str(lambda(indLambda(ll)))];

2/ In EllEMproperties:

Added the computations of Qext, and Qsca in the ES approximation for the ellipsoid.

3/ In MakeFig6_18:

Updated calls to EllEMproperties to account for change above
In comments, changed [1 x H] by [H x 1] (error)

4/ Since the 2013 Matlab release, the use of besselj, bessely, or besselh has been changed,
which results in an error. All instances have therefore been replaced with the new syntax:

[numat, rhomat] = meshgrid(nu,rho);
f=besselj(numat, rhomat);

in GenZnAll, GenRBall, GenRBpsi2, GenRBxi2.

At the same time, bsxfun was used in place of repmat to speed up computations.

5/ The syntax of taylor has also changed and this was updated in
SymScriptSphBessel and SymScrriptZnAll