
1) INTRODUCTION
***************

This library computes the free space Green's tensor and the free space filtered
Green's tensor for 2- and 3-dimensional spaces. It can be used for a Fortran
or a C++ program.

For two-dimensional problems, the z-direction is considered as the 
longitudinal symmetry. General 2D problem comes up when the dependence of 
the field in the z-direction is exp(i*Kz*z), where Kz=Kref*cos(Theta). For 
the case that Theta is equal to PI/2, there is no z-dependence of the field 
any more and the field is propagating parallel to the 2D-plane. For this 
special case, the Green's tensor is more simple and 2 independent cases can 
be observed, namely the TE and TM.

The Green's tensor, L and M terms are defined in Ref. [1].

I would be very pleased if you cite Refs. [1,2] in each of your publications 
where this code is used. Please, cite at least Ref. [2], thank you.

Please do not hesitate to contact the author for all suggestions, questions, 
bug reports or other comments (email: piller@ifh.ee.ethz.ch)

2) DESCRIPTION OF THE FORTRAN FUNCTIONS 
***************************************

The first step is to select and initialize the Green's tensor using the 
subroutine 'grtset'. Next, the Green's tensor, magnetic Green's tensor, L term,
M term, respectively the farfield Green's tensor can be evaluated using the 
subroutine 'grtgel',  'grtgma', 'grtl',  'grtm', respectively 'grtgelff'.

Finally the data of the currently initialized Green's tensor can be printed 
with 'grtprint'.

Definition of the types:
------------------------

int:      integer
double:   floating-point double precision (REAL*8)
Complex:  complex double precision (COMPLEX*16)
vect3d:   array of 3 double
Tensor:   array of 9 Complex

Definition of the Green's tensor
--------------------------------

subroutine grtset
      (int&     type, 
       Complex& kref,         //Wavenumber in the reference medium
       Complex& epsilonref,   //Permittivity of the reference medium
       double&  meshsize,     //Size of the mesh                    
       double&  theta)        

type is 3   for 3D
        2   for 2D (general 2D problem)
        21  for 2DTM
        22  for 2DTE
       -3   for 3D   filtered 
       -2   for 2D   filtered (general 2D problem)
       -21  for 2DTM filtered
       -22  for 2DTE filtered


Evaluation of the Green's Tensor
--------------------------------

subroutine grtgel
      (Tensor& T,             //Result
       vect3d& r,             //Position of observation
       vect3d& rp);           //Position of the source 

Evaluation of the magnetic Green's Tensor
-----------------------------------------

subroutine grtgma
      (Tensor& T,             //Result                 
       vect3d& r,             //Position of observation
       vect3d& rp)            //Position of the source 


Evaluation of the source dyadic L
---------------------------------

subroutine grtl(Tensor& T)               //Result


Evaluation of the self-induction term M
---------------------------------------

subroutine grtm(Tensor& T)               //Result


Evaluation of farfield Green's tensor
-------------------------------------

subroutine grtgelff
        (Tensor& T,           //Result                 
         vect3d& n,           //Farfield direction
         vect3d& rp)          //Position of the source 

Print the data
--------------

subroutine grtprint()


3) DESCRIPTION OF THE C++ CLASSES
*********************************

Include:
--------
The following header file has to be included:

#include "Green.h"

Definition of the types:
------------------------

vect3d:   array of 3 double 
           constructor:     vect3d(double x, double y, double z);
           public members:  double x, y, z;

vect3dc:  array of 3 Complex
           constructor:     vect3d(Complex x, Complex y, Complex z);
           public members:  Complex x, y, z;

Tensor:   array of 3 vect3dc
           public members:  vect3dc x, y, z;

Green's tensor Classes
----------------------

The different Green's function are represented by 8 different classes
derived from the class GreenTensor:

Green3D:     3D
Green2D:     2D (general 2D problem)
Green2DTM:   2DTM
Green2DTM:   2DTE
FGreen3D:    3D   filtered 
FGreen2D:    2D   filtered (general 2D problem)
FGreen2DTM:  2DTM filtered
FGreen2DTM:  2DTE filtered


The constructor of all these classes is called with the parameters:

Green3d(Complex kref,        //Wavenumber in the reference medium  
        Complex EpsilonRef,  //Permittivity of the reference medium
        double MeshSize);    //Size of the mesh                    

except the classes Green2D and FGreen2D, which have to be called with the 
Theta additional parameter:

Green2d(Complex kref,        //Wavenumber in the reference medium  
        Complex Epsilonref,  //Permittivity of the reference medium
        double Meshsize,     //Size of the mesh                    
        double Theta);


Evaluation of the Green's Tensor
--------------------------------

Tensor GreenTensor::GreenE(vect3d& r,        //Position of observation
                           vect3d& rp);      //Position of the source 

Evaluation of the magnetic Green's Tensor
-----------------------------------------

Tensor GreenTensor::GreenM(vect3d& r,        //Position of observation
                           vect3d& rp);      //Position of the source 

Evaluation of the source dyadic L
---------------------------------

Tensor GreenTensor::L();

Evaluation of the self-induction term M
---------------------------------------

Tensor GreenTensor::M();

Evaluation of farfield Green's tensor
-------------------------------------

Tensor GreenTensor::TensorFFE(vect3d& n,     //Farfield direction
                              vect3d& rp);   //Position of the source 


4) INSTALLATION OF THE GREEN'S TENSOR LIBRARY
*********************************************

The compilation and usage of the library require a Fortran and a C++ compiler 
and the nag library. The library has been tested on SUN and HP cluster with 
the f77 compiler, the CC (on SUN) and g++ (on HP-Cluster). For other 
implementation you may have to customize the makefile (See comments in 
Makefile).

1) Put all the files in the same directory
2) Execute the makefile: make all

This operation produces the library "libgreen.a" and the example Fortran 
program "fgreen" and C++ program "cgreen". Library and test programs are stoked 
in the subdirectory "Obj".

For the usage of this library, you have to link your programs with the 
following library:
 
   - C++ library (libC.a)
   - C mathematic library (libm.a)
   - C++ complex library (libcomplex.a) (with gnu g++, mathematic and complex 
                                         library are included in libg++.a)
   - NAG library (libnag.a)
   - the present Green's tensor library (libgreen.a)
   - Fortran libraries


For example, the corresponding command for compiling and linking the program 
"program.f" is:

f77 program.f -LGreensLibraryDirectory -lC -lm -lcomplex -lgreen -lnag

or if the library has been compiled with g++:

f77 program.f -LGreensLibraryDirectory -lg++ -lgreen -lnag

where GreensLibraryDirectory is the directory containing the library libgreen.a

5) REFERENCES
*************

[1] N. B. Piller and O. J. F. Martin, "Increasing the  performance of the 
    Coupled-Dipole Approximation: A spectral approach," IEEE Antennas and 
    Propagation, August 1998.

[2] N. B. Piller, "Coupled-dipole approximation for high permittivity 
    materials," submitted to Optics Communication.

