

libscuff API Documentation:
Defining Incident Fields with IncField

In libscuff, the incident field in an
electromagnetic scattering problem is described by a
C++ base class named IncField.
libscuff comes with several builtin
implementations (that is, derived subclasses) of this class for
commonlyencountered types of incident field (including plane waves,
point sources, and Gaussian laser beams), but it is also easy to write
your own implementation by mimicing the example below.
The basic way to use a derived subclass of IncField
in a libscuff program is to create
an instance of the class and then pass (a pointer to) this instance
to the AssembleRHSVector class method of
RWGGeometry :
MyIncFieldType *IF = new MyIncFieldType( MyParameters, ... )
HVector *V = G>AssembleRHSVector(Omega, IF);
Within the AssembleRHSVector routine, the incident field
will be evaluated at a large number of points on the surfaces of the
scattering objects in your geometry to compute the elements of the
RHS vector in the BEM scattering problem.
Although the values of the incidentfield components depend on the
angular frequency ω and on the permittivity ε
and permeability μ of the medium in which the field propagates,
you will see below that the class constructors below do not require
that these parameters be specified. Instead, their values are
configured automatically by libscuff
using the value of the Omega parameter
specified when AssembleRHSVector() is called.
The first few sections below describe how to instantiate the
builtin derived subclasses of IncField that come
with the libscuff distribution.
The final section discusses an example of how to write a homemade
IncField routine for describing a nonstandard type
incident field.
1. Plane waves
The fields of a plane wave are
where E_{0} and n are the complex
Efield polarization vector and the propagation vector,
respectively.
The corresponding derived subclass of IncField
is PlaneWave ; the constructor is
PlaneWave( const cdouble E0[3], const double nHat[3] );
where E0 and nHat define the
components of E_{0} and n.
Examples
A linearlypolarized plane wave traveling in the positive
z direction with Efield pointing in the
x direction:
cdouble lPol[3] = { 1.0, 0.0, 0.0 };
double nHat[3] = { 0.0, 0.0, 1.0 };
PlaneWave lpw( lPol, nHat );
HVector *B=AssembleRHSVector(Omega, &lpw);
lpw = scuff.PlaneWave([1,0,0], [0,0,1])
A rightcircularlypolarized plane wave traveling in the positive
z direction:
cdouble cPol[3] = { cdouble(1.0,0.0), cdouble(0.0,1.0), 0.0 };
double nHat[3] = { 0.0, 0.0, 1.0 };
PlaneWave cpw( cPol, nHat );
HVector *B=AssembleRHSVector(Omega, &cpw);
cpw = scuff.PlaneWave( [1+1i,1+1i,0], [0,0,1])
RHS = G.AssembleRHSVector(Omega, cpw)
2. Point dipole sources
The field of a point electric dipole located at x_{0} is
The corresponding derived subclass of IncField
is PointSource ; the constructor is
PointSource( const double X0[3],
const cdouble P[3]);
int Type = LIF_ELECTRIC_DIPOLE);
where X0 and P define the
components of x_{0} and P.
(Note that if you are measuring length in units of μm,
as is common in scuffem
applications, then a point electric dipole with
moment e.g. P={0.0 0.0 1.0} has magnitude
8.85•10^{18} coulombs•μm
or
8.85•10^{12} coulombs•meters.)
The optional Type parameter may be set to
LIF_MAGNETIC_DIPOLE to obtain the fields
of a point magnetic dipole; these are related
to the fields of a point electric dipole according to
Note that, for the magnetic dipole case, the quantity
P should be set to the
magnetic dipole moment times Z
divided by μ_{0}.
It is perfectly acceptable for the location of a point dipole
source to lie inside one of the material bodies in your
scattering geometry. You don't have to do anything special
in this case; if the point X0 lies inside
one of the material objects specified in your .scuffgeo
file, libscuff will automatically
detect this and proceed accordingly.
3. Gaussian laser beams
The scuffem implementation of the
field of a Gaussian laser beam was contributed by
Johannes Feist
and follows this paper:
"Electromagnetic Gaussian Beams Beyond the Paraxial Approximation,"
by C. J. R. Sheppard and S. Saghafi,
Journal of the Optical Society of America A
16 1381 (1999)
(
http://dx.doi.org/10.1364/JOSAA.16.001381).
The corresponding derived subclass of IncField
is GaussianBeam ; the constructor is
GaussianBeam( const double X0[3],
const double KProp[3],
const cdouble E0[3],
const double W[3],
);
Here X0 is the location of the beam center,
KProp is the propagation vector,
E0 is the complex Efield polarization
vector, and W is the beam waist. (In the limit
of infinite W , the field becomes a plane wave
with Efield polarization vector E0
and propagation vector KProp. )
4. Composite incident fields
The IncField class contains a Next field that you
can use to contruct an incident field consisting of a combination
of the various types of fields described above.
Here's an example in which the incident field in a scattering problem
consists of two incoming plane waves together with the field of a point
source:
PlaneWave *PW = new PlaneWave( Pol1, nHat1 );
PW>Next = new PlaneWave( Pol2, nHat2 );
PW>Next>Next = new PointSource( X0, P );
// the parameter passed to AssembleRHSVector is the head of the list
AssembleRHSVector( Omega, PW );
5. Customizing IncField for an arbitrary
incident field profile
If you need to solve scattering problems involving other types of
incident fields, you can create your own derived subclass of
IncField .
Probably the easiest way to do this is
to copy the file src/libs/libIncField/PlaneWave.cc
that comes with the scuffem source
distribution and modify the constructor and the
GetFields() routine.
Incident Field Sources Inside Scattering Objects
The discussion so far has assumed that the incident field arises from
sources that lie in the exterior medium of a scattering problem.
In some cases you may need to solve scattering problems in which
the incident field arises from sources contained inside one of the
material bodies in your geometry. In contrast to other scattering
formulations, in SIE/BEM approaches this distinction is important
and must be communicated to the scuffem
core library routines.
There are two ways to tell libscuff that
the sources of an IncField are contained inside a
material body.
 You can set the
ObjectLabel field in the
IncField to the label of the object inside
of which the field sources lie.
(The label is the string following the OBJECT
keyword in the .scuffgeo file.) In the case
of nested objects (i.e. the field sources lie inside an
object which is itself contained in another object),
set ObjectLabel to the label of the immediate
containing object. The default value of ObjectLabel
is NULL , which corresponds to field sources in
the exterior medium.
 Alternatively, if you are implementing your own derived subclass
of
IncField , you can leave the ObjectLabel
field equal to NULL and instead provide an implementation
of the GetSourcePoint() virtual class method:
bool GetSourcePoint(double X[3]);
Your implementation of this method should fill in the components of
X with the cartesian coordinates of the point at which
your field sources lie, and should return true.
libscuff will then automatically
figure out which (if any) object in the scattering geometry contains
this point.
The default implementation of GetSourcePoint in the
IncField base class simply returns false,
which tells libscuff to look at the
ObjectLabel field instead.



