/** \file focalfields.h
		\author Vishnu Krishnamachari
		\date June 2006 - May 2008
		\brief Contains all the headers.
		
		Use this header file in your source code. This header file automatically includes the precompiled headers and the other headers defined in this package.
*/

/** \mainpage Focus3D -- A focal fields package documentation
		\author Vishnu Krishnamachari,	University of California Irvine, Irvine, CA, USA
		\date June 2006 - May 2008
		\version 2.0
		\section intro-sec Introduction
		
		This package which consists of a set of c++ header files along with c++ source files is meant to be used for 
			-# the calculation of the vectorial fields near the focus of a high numerical aperture objective
			-# the calculation of coherent far-field radiation from the dipoles present in the focal volume
			-# the generation of the excitation fields for various coherent microscopy techniques such as coherent anti-Stokes Raman scattering (CARS), second-harmonic generation (SHG), third harmonic generation (THG), etc,.
			
		This package provides three classes:
			-# focus3d_parameters : 
					- it holds the parameters that are required for simulating the the focal fields and far-field radiation. 
					- it provides methods for loading, saving and test the integrity of the parameters.
					- the objects of this class are used to initialize the rest of the two classes.
			-# focus3d ::
					- provides functions for generating the focal field distribution for arbitrary input fields
					- includes methods for integrating scattering effects as perturbations as angular weighting factors 
					- internally it makes use of the blitz++ arrays for mathematical calculations
					- provides functions for saving the results to external files or blitz arrays within the calling program
			-# dipole_radiation :
					- provides functions for calculating the far-field radiation for arbitrary three dimensional dipole distribution 
					- internally it makes use of the blitz++ arrays for mathematical calculations
					- provides functions for saving the results to external files or blitz arrays within the calling program
					
			In a typical program, one can use the focus3d class to generate the focal fields or the excitation fields and pipe this field distribution as the dipole field to the dipole_radiation class to calculate the far-field radiation.	
				
		\section theory Mathematical background
		The focal field distribution (\f$ \mathbf{E}_f \f$	) at wavelength \f$\lambda\f$ with wavevector magnitude \f$k\f$ due to a lens of focal length \f$f\f$ is given in angular spectrum representation as
		\f[
		\mathbf{E}_f(x,y,z) = \frac{if}{\lambda}\mathrm{e}^{-ikf} \int_0^{\theta_{max}} \mathrm{d}\theta \int_0^{2\pi}\mathrm{d}\phi \left(\frac{n_1}{n_2}\right)^{1/2} \sqrt{\cos\theta} \sin\theta\,  \mathrm{e}^{ik(x\sin\theta\cos\phi + y\sin\theta\sin\phi + z\cos\theta)}\ R^{-1} L^{-1} R \mathbf{E}_{inc}
		\f]
		where the variable \f$ \theta \f$ is the polar angle and \f$ \phi \f$ is the azimuthal angle; the limit of integration \f$ \theta_{max} \f$ corresponds to the numerical apaerture of the lens; \f$ n_1 \f$ is the refractive index before the refraction at the lens and \f$ n_2 \f$ is the refractive index after the refraction at the lens; \f$ \mathbf{E}_{inc}(\theta,\phi)\f$ is the incident field on the lens; \f$ R(\phi) \f$ and \f$ L(\theta) \f$ are the coordinate transformation \f$ 3\times 3 \f$ matrices are given by 
		\f{eqnarray*}
		R(\phi) &=& \left[ \begin{array}{ccc} \cos\phi & \sin\phi & 0\\ -\sin\phi & \cos\phi & 0\\ 0 & 0 & 1\end{array}\right]\\
		L(\theta) &=& \left[ \begin{array}{ccc} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta\end{array}\right]
		\f}
		The opeartion \f$ R^{-1}L^{-1}R\f$ on \f$ \mathbf{E}_{inc}\f$ leads to refraction of the incident fields due to the curvature of the lens. If a scattering medium is present between the lens surface and the focal point, the rays that reach the focal point from the lens get perturbed and their amplitudes and phases get scrambled. This scrambling of phase and amplitude by the scattering medium can be modeled as a scalar angular weight function, \f$ G(\theta,\phi) \f$. These angular weights for various \f$ (\theta,\phi) \f$ are calculated using Monte-carlo simulations. This weight function can be included in the above formula as
		\f[
		\mathbf{E}_f(x,y,z) = \frac{if}{\lambda}\mathrm{e}^{-ikf} \int_0^{\theta_{max}} \mathrm{d}\theta \int_0^{2\pi}\mathrm{d}\phi \left(\frac{n_1}{n_2}\right)^{1/2} \sqrt{\cos\theta} \sin\theta\,  \mathrm{e}^{ik(x\sin\theta\cos\phi + y\sin\theta\sin\phi + z\cos\theta)}\ G(\theta,\phi) \left(\begin{array}{lllll} 
		{E_i}_x ( C^2_\phi C_\theta + S^2_\phi ) &+& {E_i}_y( -(1-C_\theta) S_\phi C_\phi ) &+& {E_i}_z ( -S_\theta C_\phi )\\
		{E_i}_x ( -(1-C_\theta) S_\phi C_\phi ) &+& {E_i}_y( S^2_\phi C_\theta + C^2_\phi ) &+& {E_i}_z ( -S_\theta S_\phi )\\
		{E_i}_x ( S_\theta C_\phi ) &+& {E_i}_y( S_\theta S_\phi ) &+& {E_i}_z( C_\theta )
		\end{array}\right)
		\f]
		where \f$ {E_i}_x \f$, \f$ {E_i}_y \f$, and \f$ {E_i}_z \f$ are the x- y- and z-components of the incident field and the sine and cosine functions are abbreviated as \f$ S \f$ and \f$ C \f$ respectively. Evaluation of thie above double integral gives the three components of the electric field at \f$(x,y,z)\f$ near the focus of the lens. In this package, the numerical integration is performed using the Simpson 1/3-rule.  
		
		The above Eq. is used for calculating the focal field for various wavelengths. In the case of CARS, the focal fields for the pump and the Stokes wavelengths are calculated. The CARS excitation at the focal volume is generated by simply multiplying the fields according the relationship
		\f[
		E_{CARS} = \chi^{(3)} E_{pump}E_{stokes}^{*}E_{pump}
		\f]
		
		The excitation volume is modeled as a collection of dipoles with their magnitude and orientation being equal to those of the excitation field at that point. Thus the electric vector at a far-field point, say at the surface of the collection lens of focal length f',  \f$(f',\theta,\phi)\f$ is simply a coherent sum of the fields originating from individual points \f$(x,y,z)\f$ near the focus. 
		\f[
		\mathbf{E}_{far} = -\int\mathrm{d}x\int\mathrm{d}y\int\mathrm{d}z\,  \frac{\mathrm{e}^{i\mathbf{k}\cdot\mathbf{R}}}{4\pi\left|\mathbf{R}\right|^3}\ \left[\mathbf{R}(x,y,z) \times \mathbf{R}(x,y,z) \times \mathbf{E}_{dipole}(x,y,z)\right]
		\f]
		where 
		\f[
		\mathbf{R}(x,y,z) = (X-x)\hat{i} + (Y-y) \hat{j} + (Z-z) \hat{k}
		\f]
		with \f$ X = f'\sin\theta\cos\phi \f$, \f$ Y = f'\sin\theta\sin\phi \f$, and \f$ Z = f'\cos\theta \f$. After performing the vector product operations, we have the far-field electric vector as
		\f[
		\mathbf{E}_{far}(f',\theta,\phi) = -\int\mathrm{d}x\int\mathrm{d}y\int\mathrm{d}z\,  \mathrm{e}^{-ik(x\sin\theta\cos\phi + y\sin\theta\sin\phi + z\cos\theta)}\frac{\mathrm{e}^{ikf'}}{4\pi\left|\mathbf{R}\right|^3}\ 
		\left(
		\begin{array}{lllll}
		{E_d}_x\left(-(Y-y)^2 - (Z-z)^2\right) &+& {E_d}_y(X-x)(Y-y) &+& {E_d}_z(X-x)(Z-z)\\
		{E_d}_x(X-x)(Y-y) &+& {E_d}_y\left(-(X-x)^2 - (Z-z)^2\right) &+& {E_d}_z(Y-y)(Z-z)\\
		{E_d}_x(X-x)(Z-z) &+& {E_d}_y(Y-y)(Z-z) &+& {E_d}_z\left(-(X-x)^2 - (Y-y)^2\right)\\
		\end{array}
		\right)
		\f]
		where \f$ {E_d}_x \f$, \f$ {E_d}_y \f$, and \f$ {E_d}_z \f$ are the x,y, and z-components of the dipole field.	This is the field on the spherical surface of the collecting lens. If the collecting lens a complete sphere, then the above Eq. gives the radiation pattern from the dipole distribution. The three dimensional integral in the above equation is numerically calculated in this software package using Simpson 1/3-rule. 
			
		The field after refraction at the spherical surface is obtained by pre-multiplying \f$ \mathbf{E}_{far}\f$ with the coordinate transformation matrix combination \f$ R^{-1}L^{-1}R \f$ where the matrices \f$ R(\phi) \f$ and \f$ L(\theta) \f$ are defined in the beginning of this section. Hence the refracted field \f$ \mathbf{E}_{refr}\f$ is
		\f{eqnarray*}
		\mathbf{E}_{refr}(f',\theta,\phi)  &=& R^{-1}L^{-1}R\ \mathbf{E}_{far}(f',\theta,\phi) \\
		&=& \left(\begin{array}{lllll} 
		{E_{far}}_x ( C^2_\phi C_\theta + S^2_\phi ) &+& {E_{far}}_y( -(1-C_\theta) S_\phi C_\phi ) &+& {E_{far}}_z ( -S_\theta C_\phi )\\
		{E_{far}}_x ( -(1-C_\theta) S_\phi C_\phi ) &+& {E_{far}}_y( S^2_\phi C_\theta + C^2_\phi ) &+& {E_{far}}_z ( -S_\theta S_\phi )\\
		{E_{far}}_x ( S_\theta C_\phi ) &+& {E_{far}}_y( S_\theta S_\phi ) &+& {E_{far}}_z( C_\theta )
		\end{array}\right)
		\f}
		
		The c++ code implemented in this package defines one class, focus3d, to compute \f$ \mathbf{E}_f(x,y,z) \f$ and a second one, dipole_radiation, to compute \f$ \mathbf{E}_{far}(f',\theta,\phi) \f$ and \f$ \mathbf{E}_{refr}(f',\theta,\phi) \f$. In this software package, the effects of refractive index mismatch are neglected.
		
		\section code-org Code organization and important methods
		The following paragraphs briefly discuss the usage of this software package in your programs. The pre-requirement to using this package is that the programmer should be familiar with the workings of blitz++ library, especially, the arrays - how they are created, stored and manipulated. The blitz library and its documentation can be obtained from http://www.oonumerics.org/blitz/manual/blitz.html .
		
		\subsection code-org1 focus3d_parameters class
		Objects of the focus3d_parameters class hold the parameters for simulating the focal fields and the far-field radiation. This class provides methods for setting the default values for the parameters, loading them from a file, saving them to a file, and performing integrity checks on the parameters. All the data members of this class, which are seventeen in number, are all public data types and hence can be changed from the within the code. The important methods of this class are focus3d_parameters::load(), focus3d_parameters::save(), focus3d_parameters::print(), focus3d_parameters::set_default() and focus3d_parameters::test() apart from the overloaded assignment operator and the comparison operators. Note that the usage of assignment operator does not result in a shared memory.
		
		\subsection code-org2 focus3d class
		Objects of this class can be used to calculate the three-dimensional three-component focal fields. Instantiation of an object ( focus3d::focus3d() ) of this class is done by passing a focus3d_parameters object. Important methods which may be called before the actual calculation of the focal fields are focus3d::reset_parameters() to change the previously loaded parameters, focus3d::set_incident_field() to set the incident field, and focus3d::set_angular_weights to include the effects of scattering on the focal properties. Use focus3d::calculate_focus() method (either of the two variants) to perform this calculation. To save the results to the hard drive, use focus3d::save_results().
		
		\subsection code-org3 dipole_radiation class
		Objects of this class are used to calculate the far-field radiation from a distribution of dipoles near the focus of a collecting lens. Instantiation of an object ( dipole_radiation::dipole_radiation() ) of this class is done by passing a focus3d_paramters object. Important methods which may be called before the actual calculation of the far-field radiation are dipole_radiation::reset_parameters() to change the previously loaded parameters, and dipole_radiation::set_dipole_field() to set the distribution of radiating dipoles. To calculate the far-field radiation use dipole_radiation::calculate_radiation(). Often it is required to calculate the refracted radiation after the collecting lens. This is done by calling dipole_radiation::calculate_refraction() after invoking dipole_radiation::calculate_radiation() or directly using dipole_radiation::calculate_refracted_radiation(). Save the calculated results using dipole_radiation::save_results().  
		
		\section examples Example Code
		The package consists of, apert from the source files and the header files, a static library, libfocalfields.a in the lib/ directory of the package. Programmer should link this file while creating the executable. In the source code, only one header file namely, focalfields.h present in the include/ directory, needs to be included. For easy compilation, a makefile would be very helpful. Suppose mysource.cpp is the source tthat needs to be compiled to create an excutable, the following makefile can be used:
		\code
		LIBDIR = <focal-fields package dir>/lib/
		INCLUDES = <focal-fields package dir>/include/
		
		mysource.exe : mysource.cpp
			g++ mysource.cpp -Wall -I$(INCLUDES) -L$(LIBDIR) -lm -lblitz -lfocalfields -o mysource.exe
		\endcode
		This will create an executable mysource.exe after linking with the static libraries.
		
		Below is a listing of some of the example programs written using the focal fields package. They provide a good review of the essential commands required for efficiently using this package.
		
		\subsection eg1 To calculate the focal field:
		focal_volume.h
		\include focal_volume.h
		focal_volume.cpp
		\include focal_volume.cpp
		
		\subsection eg2 To calculate the radiation from the focal volume:
		radiation_from_focal_volume.h
		\include radiation_from_focal_volume.h
		radiation_from_focal_volume.cpp
		\include radiation_from_focal_volume.cpp
		
		\subsection eg3 To calculate successive focus, radiation and focus:
		successive_focus_radiate_focus.h
		\include successive_focus_radiate_focus.h
		successive_focus_radiate_focus.cpp
		\include successive_focus_radiate_focus.cpp
		
		\subsection eg4 To calculate CARS excitation:
		cars_excitation.h
		\include cars_excitation.h
		cars_excitation.cpp
		\include cars_excitation.cpp
*/

#ifndef __FOCAL_FIELDS_PACKAGE_ALL_H__
#define __FOCAL_FIELDS_PACKAGE_ALL_H__

#include "utilities.h"
#include "focus3d_parameters.h"
#include "focus3d.h"
#include "focus3dws.h"
#include "dipole_radiation.h"

#endif
