text:
\section{Introduction\label{intro}}

DDSCAT is a software package to calculate scattering and
absorption of electromagnetic waves by targets with arbitrary geometries
using the ``discrete dipole approximation'' (DDA).
In this approximation the target is replaced by an array of point dipoles
(or, more precisely, polarizable points); the electromagnetic scattering
problem for an incident periodic wave interacting with this array of
point dipoles is then solved essentially exactly.
The DDA (sometimes referred to as the ``coupled dipole approximation'')
was apparently first proposed by Purcell \& Pennypacker (1973).
DDA theory was reviewed and developed further by Draine (1988),
Draine \& Goodman (1993), reviewed by Draine \& Flatau (1994)
and Draine (2000), and recently extended to periodic structures by
Draine \& Flatau (2008).

{\bf DDSCAT \vers}, the current release of DDSCAT, is an open-source Fortran 90
implementation of the DDA
developed by the authors.\footnote{
	The release history of {\bf DDSCAT} is as follows:
	\begin{itemize}
	\vspace*{-0.4em}
	\item{\bf DDSCAT 4b}: Released 1993 March 12
	\vspace*{-0.4em}
	\item{\bf DDSCAT 4b1}: Released 1993 July 9
	\vspace*{-0.4em}
	\item{\bf DDSCAT 4c}: Although never announced, {\tt DDSCAT.4c}
		was made available to a number of interested users
		beginning 1994 December 18
	\vspace*{-0.4em}
	\item{\bf DDSCAT 5a7}: Released 1996
	\vspace*{-0.4em}
	\item{\bf DDSCAT 5a8}: Released 1997 April 24
	\vspace*{-0.4em}
	\item{\bf DDSCAT 5a9}: Released 1998 December 15
	\vspace*{-0.4em}
	\item{\bf DDSCAT 5a10}: Released 2000 June 15
	\vspace*{-0.4em}
	\item{\bf DDSCAT 6.0}: Released 2003 September 2
	\vspace*{-0.4em}
	\item{\bf DDSCAT 6.1}: Released 2004 September 10
	\vspace*{-0.4em}
	\item{\bf DDSCAT 7.0}: Released 2008 September 1
        \vspace*{-0.4em}
        \item{\bf DDSCAT 7.1}: Released 2010 February 7
	\end{itemize}
	}
It extends DDSCAT to treat structures that are periodic in one or two
dimensions, using methods described by Draine \& Flatau (2008).

DDSCAT is intended to be a versatile tool, suitable for a wide variety
of applications including studies of interstellar dust, atmospheric aerosols,
blood cells, marine microorganisms,
and nanostructure arrays.
As provided, {\bf DDSCAT \vers}\ should be usable
for many applications without
modification, but the program is written in a modular form, so that
modifications, if required, should be fairly straightforward.

The authors make this code openly available to others, in the hope that it
will prove a useful tool.  We ask only that:
\begin{itemize}
\item If you publish results obtained using {{\bf DDSCAT}}, please
	acknowledge the source of the code, and cite relevant papers,
	such as Draine \& Flatau (1994), Draine \& Flatau (2008),
	and this UserGuide (Draine \& Flatau 2010).

\item If you discover any errors in the code or documentation,
	please promptly communicate them to the authors.

\item You comply with the ``copyleft" agreement (more formally, the
	GNU General Public License) of the Free Software Foundation: you may
	copy, distribute, and/or modify the software identified as coming
	under this agreement.
	If you distribute copies of this software, you must give the
	recipients all the rights which you have.
	See the file {\tt doc/copyleft.txt}
        distributed with the DDSCAT software.
\end{itemize}
We also strongly encourage you to send email to
{\tt draine@astro.princeton.edu} identifying
yourself as a user of DDSCAT;  this will enable the authors to notify you of
any bugs, corrections, or improvements in DDSCAT.
Up-to-date information on DDSCAT can be found at \\
\hspace*{2em}{\tt http://www.astro.princeton.edu/$\sim$draine/DDSCAT.html}\\
Information is also available at
{\tt http://ddscat.wikidot.com/start}

The current version, {\bf DDSCAT \vers},
uses the DDA formulae from Draine (1988), with
dipole polarizabilities determined from the Lattice Dispersion
Relation (Draine \& Goodman 1993, Gutkowicz-Krusin \& Draine 2004).
The code incorporates Fast Fourier Transform (FFT) methods
(Goodman, Draine, \& Flatau 1991).
{\bf DDSCAT \vers}\ includes capability to calculate scattering and absorption
by targets that are periodic in one or two dimensions -- arrays of
nanostructures, for example.
The theoretical basis for application of the DDA to periodic structures
is developed in Draine \& Flatau (2008).

We refer you to the list of references at the end of this document for
discussions
of the theory and accuracy of the DDA [in particular,
reviews by Draine and Flatau (1994) and Draine (2000),
and recent extension to 1-d and 2-d arrays by Draine \& Flatau (2008).].
In \S\ref{sec:whats_new} we
describe the principal changes between {\bf DDSCAT \vers}\ and the previous
releases.  The succeeding sections contain instructions for:
\begin{itemize}
\item compiling and linking the code;
\item running a sample calculation;
\item understanding the output from the sample calculation;
\item modifying the parameter file to do your desired calculations;
\item specifying target orientation;
\item changing the {\tt DIMENSION}ing of the source code to accommodate
your desired calculations.
\end{itemize}
The instructions for compiling, linking, and running will be appropriate for a
Linux system; slight changes will be necessary for non-Linux sites,
but they are quite minor and should present no difficulty.

Finally, the current version of this
User Guide can be obtained from\newline
{\tt http://arxiv.org/abs/1002.1505} -- you will be offered
the options of downloading either Postscript or PDF
versions of the User Guide.

\section{Applicability of the DDA\label{sec:applicability}}
The principal advantage of the DDA is that it is completely flexible
regarding the geometry of the target, being limited only by the need to
use an interdipole separation $d$ small compared to
(1) any structural lengths in the target, and
(2) the wavelength $\lambda$.
Numerical studies (Draine \& Goodman 1993; Draine \& Flatau 1994; Draine 2000)
indicate that the second criterion is adequately satisfied if
\begin{equation}
|m|kd< 1~~~,
\label{eq:mkd_max}
\end{equation}
where $m$ is the complex refractive index of the target
material, and $k\equiv2\pi/\lambda$, where $\lambda$ is the wavelength
{\it in vacuo}.
This criterion is valid provide $|m-1| \lower.5ex\hbox{$\; \buildrel < \over \sim \;$} 3$ or so.
When Im$(m)$ becomes large, the DDA solution tends to overestimate
the absorption cross section $C_{\rm abs}$, and it may be necessary to use
interdipole separations $d$ smaller than indicated by eq.\ (\ref{eq:mkd_max})
to reduce the errors in $C_{\rm abs}$ to acceptable values.

If accurate calculations of the scattering phase function
(e.g., radar or lidar cross sections)
are desired,
a more conservative criterion
\begin{equation}
|m|kd < 0.5
\end{equation}
will usually ensure that differential scattering cross sections
$dC_{\rm sca}/d\Omega$ are accurate to within a few percent of the
average differential scattering cross section $C_{\rm sca}/4\pi$
(see Draine 2000).

Let $V$ be the actual volume of solid material in the target.\footnote{
   In the case of an infinite periodic target, $V$ is the volue of
   solid material in one ``Target Unit Cell''.}
If the target is represented by an array of $N$ dipoles, located on
a cubic lattice with lattice spacing $d$,
then
\begin{equation}
V=Nd^3 ~~~.
\end{equation}
We characterize the size of the target by the ``effective radius''
\index{effective radius ${a}_{\rm eff}$}
\index{$a_{\rm eff}$}
\begin{equation}
a_{\rm eff}\equiv(3V/4\pi)^{1/3} ~~~,
\end{equation}
the radius of an equal volume sphere.
A given scattering problem is then characterized by the
dimensionless ``size parameter''
\index{size parameter $x=ka_{\rm eff}$}
\begin{equation}
x\equiv ka_{\rm eff} = \frac{2\pi a_{\rm eff}}{\lambda} ~~~.
\end{equation}
The size parameter can be related to $N$ and $|m|kd$:
\begin{equation}
x\equiv{2\pi a_{\rm eff}\over\lambda} =
{62.04\over|m|}\left({N\over10^6}\right)^{1/3} \cdot |m|kd ~~~.
\end{equation}
Equivalently, the target size can be written
\begin{equation}
a_{\rm eff} = 9.873 {\lambda\over|m|}\left({N\over10^6}\right)^{1/3}
\cdot |m|kd~~~.
\end{equation}
Practical considerations of CPU speed and computer memory currently
available on scientific workstations typically
limit the number
of dipoles employed to $N < 10^6$ (see \S\ref{sec:memory_requirements}
for limitations on $N$ due to available RAM);
for a given $N$, the limitations on $|m|kd$
translate into limitations on the ratio of target size to wavelength.

\noindent
For calculations of total cross sections $C_{\rm abs}$ and $C_{\rm sca}$,
we require $|m|kd < 1$:
\begin{equation}
a_{\rm eff} < 9.88 {\lambda\over |m|}\left({N\over10^6}\right)^{1/3}
{\rm ~~or~~} x < {62.04\over|m|}\left({N\over10^6}\right)^{1/3} ~~~.
\end{equation}
For scattering phase function calculations, we require $|m|kd < 0.5$:
\begin{equation}
a_{\rm eff} < 4.94 {\lambda\over |m|}\left({N\over10^6}\right)^{1/3}
{\rm ~~~~or~~~~} x < {31.02\over|m|}\left({N\over10^6}\right)^{1/3} ~~~.
\end{equation}

It is therefore clear that the DDA is not suitable for very large values of
the size parameter
$x$, or very large values of the refractive index $m$.
The primary utility of the DDA is for scattering by dielectric
targets with sizes comparable to the wavelength.
As discussed by Draine \& Goodman (1993), Draine \& Flatau (1994), and
Draine (2000),
total cross sections calculated with the DDA are
accurate to a few percent provided
$N>10^4$ dipoles are used, criterion (\ref{eq:mkd_max}) is satisfied,
and the refractive index is not too large.

For fixed $|m|kd$, the
accuracy of the approximation degrades with increasing $|m-1|$,
for reasons having to do with the surface polarization of the target
as discussed by Collinge \& Draine (2004).
With the present code, good accuracy can be achieved for $|m-1| < 2$.

Examples illustrating the accuracy of the DDA are shown in
Figs.\ \ref{fig:Qm=1.33+0.01i}--\ref{fig:Qm=2+i} which show overall
scattering and absorption efficiencies as a function of wavelength for
different discrete dipole approximations to a sphere, with $N$ ranging
from 304 to 59728.
The DDA calculations assumed radiation incident along the (1,1,1)
direction in the ``target frame''.
Figs.\ {\ref{fig:dQdom=1.33+0.01i}--\ref{fig:dQdom=2+i} show the scattering
properties calculated with the DDA for $x=ka=7$.
Additional examples can be found in Draine \& Flatau (1994) and Draine (2000).

As discussed below,
{\bf DDSCAT \vers}\ can also calculate scattering and absorption by targets that
are periodic in one or two directions -- for examples, see
Draine \& Flatau (2008).

\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f1.eps}}
\caption{\footnotesize
        Scattering and absorption for a sphere with
	$m=1.33+0.01i$.  The upper panel shows the exact values of $Q_{\rm sca}$
	and $Q_{\rm abs}$, obtained with Mie theory, as functions of $x=ka$.
	The middle and lower panels show fractional errors in $Q_{\rm sca}$ and
	$Q_{\rm abs}$, obtained using {{\bf DDSCAT}}\ with polarizabilities obtained
	from the Lattice Dispersion Relation, and labelled by the number $N$
	of dipoles in each pseudosphere.
	After Fig.\ 1 of Draine \& Flatau (1994).}
	\label{fig:Qm=1.33+0.01i}
\end{figure}

\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f2.eps}}
\caption{\footnotesize
        Same as Fig.\ \protect{\ref{fig:Qm=1.33+0.01i}},
	but for $m=2+i$. After Fig.\ 2 of Draine \& Flatau (1994).}
	\label{fig:Qm=2+i}
\end{figure}
\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f3.eps}}
\caption{\footnotesize
        Differential scattering cross section for
	$m=1.33+0.01i$ pseudosphere and $ka=7$.
	Lower panel shows fractional error compared to exact Mie theory
	result.
	The $N=17904$ pseudosphere has $|m|kd=0.57$, and an rms fractional
	error in $d\sigma/d\Omega$ of 2.4\%.
	After Fig.\ 5 of Draine \& Flatau (1994).}
	\label{fig:dQdom=1.33+0.01i}
\end{figure}
\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f4.eps}}
\caption{\footnotesize
        Same as Fig.\ \protect{\ref{fig:dQdom=1.33+0.01i}}
	but for $m=2+i$.
	The $N=59728$ pseudosphere has $|m|kd=0.65$, and an rms fractional
	error in $d\sigma/d\Omega$ of 6.7\%.
	After Fig.\ 8 of Draine \& Flatau (1994).}
	\label{fig:dQdom=2+i}
\end{figure}

\section{DDSCAT 7.1\label{sec:DDSCATvers}}
\subsection{ What Does It Calculate?}
\subsubsection{Absorption and Scattering by Finite Targets}
{\bf DDSCAT \vers}, like previous versions of {\bf DDSCAT},
solves the problem of scattering and
absorption by a finite target, represented by an array of
polarizable point dipoles, interacting with a monochromatic plane wave incident
from infinity.
{\bf DDSCAT \vers}\ has the capability of automatically generating dipole
array representations for a variety of target geometries
(see \S\ref{sec:target_generation}) and can also accept dipole
array representations of targets supplied by the user (although
the dipoles must be located on a cubic lattice).
The incident plane wave can have arbitrary elliptical
polarization (see \S\ref{sec:incident_polarization}),
and the target can be arbitrarily oriented relative to the
incident radiation (see \S\ref{sec:target_orientation}).
The following quantities are calculated by {\bf DDSCAT \vers}\ :
\begin{itemize}
\item Absorption efficiency factor $Q_{\rm abs}\equiv C_{\rm abs}/\pi a_{\rm eff}^2$,
where $C_{\rm abs}$ is the absorption cross section;
\index{absorption efficiency factor $Q_{\rm abs}$}
\index{$Q_{\rm abs}$}
\item Scattering efficiency factor $Q_{\rm sca}\equiv C_{\rm sca}/\pi a_{\rm eff}^2$,
where $C_{\rm sca}$ is the scattering cross section;
\index{scattering efficiency factor $Q_{\rm sca}$}
\index{$Q_{\rm sca}$}
\item Extinction efficiency factor $Q_{\rm ext}\equiv Q_{\rm sca}+Q_{\rm abs}$;
\index{extinction efficiency factor $Q_{\rm ext}$}
\index{$Q_{\rm ext}$}
\item Phase lag efficiency factor $Q_{\rm pha}$,
\index{phase lag efficiency factor $Q_{\rm pha}$}
\index{$Q_{\rm pha}$}
defined so that the phase-lag
(in radians) of a plane wave after propagating a distance $L$ is just
$n_{t}Q_{\rm pha}\pi a_{\rm eff}^2 L$,
where $n_t$ is the number density of targets.
\item The 4$\times$4 Mueller scattering intensity matrix $S_{ij}$
describing the complete
scattering properties of the target for scattering directions specified
by the user (see \S\ref{sec:mueller_matrix}).
\item Radiation force efficiency vector ${\bf Q}_{\rm rad}$
(see \S\ref{sec:force and torque calculation}).
\item Radiation torque efficiency vector ${\bf Q}_\Gamma$
(see \S\ref{sec:force and torque calculation}).
\end{itemize}
In addition, the user can choose to have {\bf DDSCAT \vers}\ store the solution for
post-processing.  A separate Fortran-90 program {\bf DDfield}
(see \S\ref{sec:calculate E and B fields})
is provided that
can readily calculate ${\bf E}$ and ${\bf B}$ at user-selected locations.

\subsubsection{ Absorption and Scattering by Periodic Arrays of Finite
               Structures}

{\bf DDSCAT \vers}\ includes the capability to solve the problem of scattering and
absorption by an infinite target consisting of a 1-d or 2-d periodic array of
finite structures, illuminated by an incident plane wave.
The finite structures are themselves represented by arrays of point dipoles.

The electromagnetic scattering problem is formulated by Draine \& Flatau
(2008), who show how the problem can be reduced to a finite system of linear
equations, and solved by the same methods used for scattering by finite
targets.

The far-field scattering properties of the 1-d and 2-d periodic arrays can be
conveniently represented by a generalization of the Mueller scattering matrix
to the 1-d or 2-d periodic geometry -- see Draine \& Flatau (2008) for
definition of $S_{ij}^{(1d)}(M,\zeta)$ and $S_{ij}^{(2d)}(M,N)$.
For targets with 1-d periodicity, {\bf DDSCAT \vers}\ calculates
$S_{ij}^{(1d)}(M,\zeta)$ for user-specified $M$ and $\zeta$.
For targets with 2-d periodicity, {\bf DDSCAT \vers}\ calculates
$S_{ij}^{(2d)}(M,N)$ for both transmission and reflection, for user-specified
$(M,N)$.

As for finite targets, the user can choose to have {\bf DDSCAT \vers}\ store the
calculated polarization field for post-processing.
A separate Fortran-90 program {\bf DDfield} is provided to calculate ${\bf E}$
and ${\bf B}$ at user-selected locations, which can be located anywhere
(including within the target).

\subsection{ Application to Targets in Dielectric Media}
	\label{sec:target_in_medium}}
Let $\omega$ be the angular frequency of the incident radiation.
For many applications, the target is essentially {\it in vacuo}, in which
case the dielectric function $\epsilon$ which the user should supply
to {\tt DDSCAT} is the actual complex dielectric function
$\epsilon_{\rm target}(\omega)$,
or complex refractive index
$m_{\rm target}(\omega)=\sqrt{\epsilon_{\rm target}}$
of the target material.
\index{dielectric medium}

However, for many applications of interest (e.g., marine optics, or
biological optics) the ``target'' body is embedded in a (nonabsorbing)
dielectric medium (e.g., water at visible wavelengths)
with (real) dielectric function $\epsilon_{\rm medium}(\omega)$, or
(real) refractive index $m_{\rm medium}(\omega)=\sqrt{\epsilon_{\rm medium}}$.
{{\bf DDSCAT}} is fully applicable to these scattering problems, except
that:
\begin{itemize}
\item The complex ``dielectric function'' or complex ``refractive index''
supplied to {{\bf DDSCAT}} should be
the {\it relative} dielectric function
\index{relative dielectric function}
\begin{equation}
\epsilon(\omega) =
\frac{\epsilon_{\rm target}(\omega)}{\epsilon_{\rm medium}(\omega)}
\end{equation}
or {\it relative} refractive index:
\index{relative refractive index}
\begin{equation}
m(\omega) =
\frac{m_{\rm target}(\omega)}{m_{\rm medium}(\omega)} .
\end{equation}
\item The wavelength $\lambda$ specified in {\tt ddscat.par} should be the
wavelength {\it in the medium}:
\begin{equation}
\lambda = \frac{\lambda_{\rm vac}}{m_{\rm medium}},
\label{eq:lambda_medium}
\end{equation}
where $\lambda_{\rm vac}=2\pi c/\omega$ is the wavelength {\it in vacuo}.
\end{itemize}
Because {{\bf DDSCAT}} will be using the {\it relative refractive index}
$m(\omega)$ and the wavelength {\it in the medium}, the file supplying the
refractive index as a function of wavelength should give the {\it relative
refractive index} or {\it relative dielectric function}
as a function of {\it wavelength in the medium}.
Those using {{\bf DDSCAT}} for
targets that are not {\it in vacuo} must be attentive
to this when preparing the input table(s) giving the {\it relative}
dielectric function or refractive index of the target material(s).

The absorption, scattering, extinction, and phase lag
efficiency factors $Q_{\rm abs}$,
$Q_{\rm sca}$, and $Q_{\rm ext}$ calculated by {{\bf DDSCAT}}
will then be equal to the physical
cross sections for absorption, scattering, and extinction divided by
$\pi a_{\rm eff}^2$.
For example, the attenuation coefficient for radiation
propagating through a medium with a number density $n_{t}$ of
scatterers will be just
$\alpha = n_{t}Q_{\rm ext}\pi a_{\rm eff}^2$.
Similarly, the phase lag (in radians) after propagating a distance $L$ will be
$n_{t}Q_{\rm pha}\pi a_{\rm eff}^2 L$.

The elements $S_{ij}$ of the 4$\times$4 Mueller scattering matrix ${\bf S}$
calculated by {{\bf DDSCAT}} for finite targets
will be correct for scattering in the medium:
\begin{equation}
{\bf I}_{\rm sca} =
\left(\frac{\lambda}{2\pi r}\right)^2
{\bf S}\cdot {\bf I}_{\rm in} ,
\end{equation}
where ${\bf I}_{\rm in}$ and ${\bf I}_{\rm sca}$ are the Stokes vectors for
the incident and scattered light (in the medium),
$r$ is the distance from the target, and
$\lambda$ is the wavelength in the medium (eq.\ \ref{eq:lambda_medium}).
See \S\ref{sec:mueller_matrix} for a detailed discussion of the
Mueller scattering matrix.

The time-averaged
radiative force and torque (see \S\ref{sec:force and torque calculation}) on a
finite target in a dielectric medium are
\begin{equation}
{\bf F}_{\rm rad} = {\bf Q}_{pr}\pi a_{\rm eff}^2 u_{\rm rad} ~~~,
\end{equation}
\begin{equation}
{\bf \Gamma}_{\rm rad} =
{\bf Q}_\Gamma \pi a_{\rm eff}^2 u_{\rm rad} \frac{\lambda}{2\pi} ~~~,
\end{equation}
where the time-averaged energy density is
\begin{equation}
u_{\rm rad}=\epsilon_{\rm medium} \frac{E_0^2}{8\pi} ~~~ ,
\end{equation}
where $E_0\cos(\omega t+\phi)$
is the electric field of the incident plane wave in the medium.

\bigskip
\section{What's New?\label{sec:whats_new}}
{\bf DDSCAT \vers}\ differs from
{{\bf DDSCAT 6.1}}\ in a number of ways, including:
\begin{enumerate}
\item N.B.: The structure of the parameter file {\tt ddscat.par}
        has been changed: {\tt ddscat.par} files that were used with
	DDSCAT 6.1 will need to be modified.
	See \S\ref{sec:parameter_file} and Appendix \ref{app:ddscat.par}.
\item {\bf DDSCAT 7.0}\ can calculate scattering by targets consisting of
        anisotropic materials with arbitrary orientation.
	Two new target options {\tt ANIFRMFIL} and {\tt SPH\_ANI\_N} are
	provided that make use of this capability.\\
	{\tt ANIFRMFIL}
        reads an input file with a list of dipoles for a
	general anisotropic
        target.  For each dipole, the input file gives the dipole location,
	composition
        for each of three principal axes of the local dielectric tensor,
	and the orientation
        of the local ``Dielectric Frame'' (DF) relative to the
	``Target Frame'' (TF).\\
        Target option {\tt SPH\_ANI\_N}
        creates target consisting of N anisotropic spheres.
        An input file lists, for each sphere, the location,
	radius, composition corresponding to each of three principal axes of
	dielectric tensor, and the orientation of the DF for this sphere
	relative to the TF.
\item The user now has the option of specifying the scattering directions
        either relative to the {\it Lab Frame} (as in DDSCAT 6.1)
	or relative to the {\it Target Frame}.  This is selected by providing
	a new character variable, either {\tt LFRAME} or {\tt TFRAME} in
	the parameter file {\tt ddscat.par}.  Note that this choice {\it must}
	be specified in {\tt ddscat.par}.
\item The user must now specify the value of
       parameter
       {\tt IWRPOL} in the parameter file {\tt ddscat.par}.
       See \S\ref{sec:parameter_file} and Appendix \ref{app:ddscat.par}.
\item A separate Fortran-90 code
       {\bf DDfield} is provided that can read the stored polarization
       array that is written if {\tt IWRPOL} = 1 and use this data to
       calculate ${\bf E}$ and ${\bf B}$ at user-specified positions in or
       near the target.
\item {\bf DDSCAT 7.0}\ can solve the problem
       of scattering and absorption by a target that is periodic in
       one dimension (and finite in the other two dimensions) or
       periodic in two dimensions (and finite in the third) and illuminated
       by a monochromatic plane wave, using periodic boundary conditions
       (PBC).  The theory is
       described in Draine \& Flatau (2008).  A number of built-in target
       options are provided (see \S\ref{sec:target_generation_PBC}), including
       {\tt BISLINPBC}, {\tt CYLNDRPBC}, {\tt DSKLYRPBC},
       {\tt HEXGONPBC}, {\tt LYRSLBPBC}, {\tt RCTGL\_PBC}, {\tt SPHRN\_PBC},
\item {\bf DDSCAT 7.0}\ uses dynamic memory allocation.  An additional line
       is now required in the
       {\tt ddscat.par} file to inform {\bf DDSCAT \vers}\ how much memory should
       initially be allocated to safely generate the requested target.
       Once the target has been generated, {\bf DDSCAT \vers}\ reevaluates the
       memory requirements, and then allocates only the memory required
       to carry out the scattering calculation for the chosen target.
\item The user can choose to compile {\bf DDSCAT 7.0}\ in either single- or
       double-precision.
\item {\bf DDSCAT 7.0}\ includes built-in support for OpenMP;
      if this is enabled,
      certain parts of the calculation can be distributed over available cpu
      cores.  This can speed execution on multi-core systems.
\item {\bf DDSCAT 7.0}\ includes built-in support to use the \Intel\ Math Kernel
      Library (MKL) for calculation of FFTs.
\item {\bf DDSCAT \vers}\ is distributed with a set of examples, including
      both {\tt ddscat.par} files and selected output files.  These
      should be useful to new users.
\item {\bf DDSCAT \vers}\ (version 7.1.0) allows the user to study periodic targets
      with the target unit cell (TUC) geometry (i.e., dipole locations)
      and composition provided via an input file [new target options
      {\tt FRMFILPBC} (\S\ref{sec:FRMFILPBC}) and
      {\tt ANIFILPBC} (\S\ref{sec:ANIFILPBC})].
\item {\bf DDSCAT \vers}\ (version 7.1.0) supports new target options
      {\tt SLAB\_HOLE} (rectangular block with cylindrical hole) and
      {\tt SLBHOLPBC} periodic array of rectangular blocks with cylindrical
      holes.  {\tt SLBHOLPBC} can be used to create a uniform slab with
      uniformly-spaced cylindrical holes in a rectangular pattern.
\item {\bf DDSCAT \vers}\ (version 7.1.0) includes a new version of {\bf DDfield},
      with modification to the structure of the input file {\tt ddfield.in}
      to facilitate sampling the ${\bf E}$ and ${\bf B}$ fields at many points.
\end{enumerate}

\section{Obtaining and Installing the Source Code
         \label{sec:downloading}}
{\bf DDSCAT \vers}\ is written in standard Fortran-90 with a single extension: it uses
the Fortran-95 standard library call {\tt CPU\_TIME} to obtain timing
information.
{\bf DDSCAT \vers}\ is therefore portable to
any system having a f90 or f95 compiler.
It has been successfully
compiled with many different compilers, including {\tt gfortran},
{\tt g95}, {\tt ifort}, {\tt pgf77}, and NAG\textsuperscript{\textregistered} {\tt f95}.

\index{Microsoft Windows}
\index{Vista}
\index{Windows 7}
It is possible to use {\bf DDSCAT \vers}\ on PCs running Microsoft Windows
operating systems, including Vista and Windows 7.
More information on how to do this can be found at\\
\hspace*{4em}{\tt http://code.google.com/p/ddscat}\\

The remainder of this section will assume that the installation is taking
place on a Unix, Linux or Mac OSX system
with the standard developer tools (e.g., {\tt tar}, {\tt make},
and a f90 or f95 compiler) installed.

\index{source code (downloading of)}
The complete source code for
{\bf DDSCAT \vers}\ is
provided in a single gzipped tarfile.

There are 4 ways to obtain the source code:
\begin{itemize}
\item Point your browser to the {\bf DDSCAT}\ home page:\\
{\tt http://www.astro.princeton.edu/$\sim$draine/DDSCAT.html}\\
and right=click on the link to {\tt ddscat7.1.0.tgz} .

\item Point your browser to\\
{\tt http://code.google.com/p/ddscat/}
and download the latest release.

\item Point your browser to\\
{\tt ftp://ftp.astro.princeton.edu/draine/scat/ddscat/7.1.0} \\
right-click on {\tt ddscat7.1.0.tgz} .

\item Use anonymous {\tt ftp} ~to~ {\tt ftp.astro.princeton.edu}.\\
In response to~ ``Name:'' ~enter~ {\tt anonymous}.\\
In response to~ ``Password:'' ~enter your full email address.\\
{\tt cd draine/scat/ddscat/ver7.1.0} \\
{\tt binary} \quad\quad{\it (to enable transfer of binary data)}\\
{\tt get ddscat7.1.0.tgz}
\end{itemize}

\noindent After downloading {\tt ddscat7.1.0.tgz}
into the directory where you would
like {\bf DDSCAT \vers}\ to reside (you should have at least 10 Mbytes of disk space
available), the source code can be installed as follows:

If you are on a Linux system, you should be able to type\\
\hspace*{2em}{\tt tar xvzf ddscat7.1.0.tgz}\\
which will``extract'' the files from the gzipped
tarfile.  If your version of ``tar'' doesn't support the ``z'' option
(e.g., you are running Solaris) then try\\
\hspace*{2em}{\tt zcat ddscat7.1.0.tgz | tar xvf -}\\
If neither of the above work on your system, try the two-stage procedure\\
\hspace*{2em}{\tt gunzip ddscat7.1.0.tgz} \\
\hspace*{2em}{\tt tar xvf ddscat7.1.0.tar} \\
A disadvantage of this two-stage procedure is that it uses more disk
space, since after the second step you will have the uncompressed
tarfile {\tt ddscat7.1.0.tar} -- about 3.8 Mbytes --
in addition to all the files you have extracted
from the tarfile -- another 4.6 Mbytes.

Any of the above approaches should
create subdirectories {\tt src}, {\tt doc}, and {\tt examples\_exp}.
The source code will be in subdirectory {\tt src}, and documentation
in subdirectory {\tt doc}.
The {\tt examples\_exp} subdirectory contains sample {\tt ddscat.par} files
as well as output files for various target options, including
both isolated targets and infinite periodic targets.

\section{Compiling and Linking\label{sec:compiling}}
\index{compiling and linking}
\index{compiling and linking}
In the discussion below, it is assumed that the
{\bf DDSCAT \vers}\ source code has been installed in a directory
{\tt DDA/src}.
The instructions below assume that you are on a Unix, Linux, or Mac OSX
system.

\subsection{ The default Makefile}
It is assumed that the system has the following already installed:
\begin{itemize}
\item a Fortran-90 compiler (e.g., {\tt gfortran}, {\tt g95},
\Intel\ {\tt ifort}, or NAG\textsuperscript{\textregistered} {\tt f95}) .
\item {\tt cpp} -- the ``C preprocessor''.
\end{itemize}
There are a number of different ways to create an executable, depending
on what options the user wants:
\begin{itemize}
\item what compiler and compiler flags?
\item single-  or double-precision?
\item enable OpenMP?
\item enable MKL?
\item enable MPI?
\end{itemize}
Each of the above choices needs requires setting of appropriate
``flags'' in the Makefile.

The default Makefile has the following ``vanilla'' settings:
\begin{itemize}
\item {\tt gfortran -O2}
\item single-precision arithmetic
\item OpenMP not used
\item MKL not used
\item MPI not used.
\end{itemize}
To compile the code with the default settings, simply
position yourself in the directory
{\tt DDA/src}, and type\\
\hspace*{2em}{\tt make ddscat}\\
If you have {\tt gfortran} and {\tt cpp} installed on your system,
the above should work. You will get some warnings from the compiler,
but the code will compile and create an executable {\tt ddscat}.

If you wish to use a different compiler
(or compiler options) you will need to edit the file {\tt Makefile}
to change the choice of compiler (variable {\tt FC}),
compilation options (variable {\tt FFLAGS}), and possibly
and loader options (variable {\tt LDFLAGS}).
The file {\tt Makefile} as provided includes examples for compilers other than
{\tt gfortran}; you may be able to simply ``comment out'' the section of
{\tt Makefile} that was designed for {\tt gfortran}, and ``uncomment''
a section designed for another compiler (e.g., \Intel\ {\tt ifort}).

\subsection{ Optimization}
\index{Fortran compiler!optimization}
The performance of {\bf DDSCAT \vers}\ will benefit from optimization during compilation
and the user should enable the
appropriate compiler flags.

\subsection{ Single vs.\ Double Precision}
\index{precision: single vs. double}
{\bf DDSCAT \vers}\ is written to allow the user to easily generate either single- or
double-precision versions of the executable.
For most purposes, the single-precision precision version of {\bf DDSCAT \vers}\
should work fine, but if you encounter a scattering
problem where the single-precision version
of {\bf DDSCAT \vers}\ seems to be having trouble converging to a solution, you
may wish to try using the double-precision version -- this
can be beneficial in the event that round-off error is compromising
the performance of the conjugate-gradient solver.
Of course, the double precision version will demand about twice as much
memory as the single-precision version,
and will take somewhat longer per iteration.

The only change required
is in the Makefile: for single-precision, set\\
\hspace*{2em}{\tt PRECISION = sp}\\
or for double-precision, set\\
\hspace*{2em}{\tt PRECISION = dp}\\
After changing the {\tt PRECISION} variable in the Makefile
(either sp $\rightarrow$ dp,
or dp $\rightarrow$ sp), it is necessary to recompile the
entire code.  Simply type\\
\hspace*{2em}{\tt make clean}\\
\hspace*{2em}{\tt make ddscat}\\
to create {\tt ddscat} with the appropriate precision.

\subsection{ OpenMP}

OpenMP is a standard for support of shared-memory parallel programming,
and can provide a performance advantage when using {\bf DDSCAT \vers}\ on
platforms with multiple cpus or multiple cores.
OpenMP is supported by many common compilers, such as {\tt gfortran}
and \Intel\ {\tt ifort}.

If you are using a multi-cpu (or multi-core) system with OpenMP
({\tt www.openmp.org}) installed, you can compile {\bf DDSCAT \vers}\ with OpenMP
directives to parallelize some of the calculations.
To do so, simply change\\
\hspace*{2em}{\tt DOMP       =}\\
\hspace*{2em}{\tt OPENMP     =}\\
to\\
\hspace*{2em}{\tt DOMP       = -Dopenmp}\\
\hspace*{2em}{\tt OPENMP     = -openmp}\\
Note: {\tt OPENMP} is compiler-dependent: {\tt gfortran}, for instance,
requires\\
\hspace*{2em}{\tt OPENMP     = -fopenmp}\\

\subsection{ MKL: the \Intel\ Math Kernel Library
            \label{sec:MKL}
            \index{MKL!\Intel\ MKL!DFTI}
            }

\Intel\ offers the Math Kernel Library (MKL) with the ifort compiler.
This library includes {\tt DFTI} for computing FFTs.
At least on some systems, {\tt DFTI} offers better performance than
the GPFA package.

To use the MKL library routine {\tt DFTI}:
\begin{itemize}
\item You must obtain the routine {\tt mkl\_dfti.f90} and place a copy
      in the directory where you are compiling {\bf DDSCAT \vers}.  {\tt mkl\_dfti.f90}
      is \Intel\ proprietary software, so we cannot distribute it
      with the {\bf DDSCAT \vers}\ source code, but it
      should be available on any system with a license for the
      \Intel\ MKL library.
      If you cannot find it, ask your system administrator.
\item Edit the Makefile: define variables {\tt CXFFTMKL.f} and
      {\tt CXFFTMKL.o} to:\\
      \hspace*{2em}{\tt CXFFTMFKL.f = \$(MKL\_f)}\\
      \hspace*{2em}{\tt CXFFTMKL.f = \$(MKL\_o)}
\item Successful linking will require that the appropriate MKL libraries
be available, and that the string {\tt LFLAGS} in the Makefile be
defined so as to include these libraries.\\
{\tt -lmkl\_em64t -lmkl\_intel\_thread -lmkl\_core -lguide
-lpthread -lmkl\_intel\_lp64} appears to work on at least
one installation.
The Makefile contains examples.
\item type\\
      \hspace*{2em}{\tt make clean}\\
      \hspace*{2em}{\tt make ddscat}
\item The parameter file {\tt ddscat.par} should have {\tt FFTMKL}
as the value of {\tt CMETHD}.
\end{itemize}

\subsection{ MPI: Message Passing Interface
            \label{sec:MPI}
            \index{MPI -- Message Passing Interface}
            }

{\bf DDSCAT \vers}\ includes support for parallelization under MPI.
MPI (Message Passing Interface) is a standard for communication between
processes.
More than one implementation of {\tt MPI} exists (e.g., {\tt mpich}
and {\tt openmpi}).
{\tt MPI} support within {\bf DDSCAT \vers}\ is compliant with the MPI-1.2 and MPI-2
standards\footnote{\tt http://www.mpi-forum.org/},
and should be usable under any implementation of {\tt MPI}
that is compatible with those standards.

Many scattering calculations will require multiple orientations of the
target relative to the incident radiation.  For {\bf DDSCAT \vers}, such
calculations are  ``embarassingly parallel'', because they are carried
out essentially independently.  {\bf DDSCAT \vers}\ uses MPI so that scattering
calculations at a single wavelength but for multiple orientations can
be carried out in parallel, with the information for different orientations
gathered together for averaging etc.\ by the master process.

If you intend
to use {\bf DDSCAT \vers}\ for only a single orientation, MPI offers no advantage
for {\bf DDSCAT \vers}\, so you should compile with MPI disabled.
However, if you intend to carry out calculations for multiple orientations,
{\it and} would like to do so in parallel over more than one cpu, {\it and}
you have MPI installed on your platform, then you will want to compile
{\bf DDSCAT \vers}\ with MPI enabled.

To compile with MPI disabled: in the Makefile, set\\
      \hspace*{2em}{\tt DMPI  =}\\
      \hspace*{2em}{\tt MIP.f = mpi\_fake.f90}\\
      \hspace*{2em}{\tt MPI.o = mpi\_fake.o}\\
To compile with MPI enabled: in the Makefile, set\\
      \hspace*{2em}{\tt DMPI  = -Dmpi}\\
      \hspace*{2em}{\tt MIP.f = \$(MPI\_f)}\\
      \hspace*{2em}{\tt MPI.o = \$(MPI\_o)}\\
and edit {\tt LFLAGS} as needed to make sure that you link to the
appropriate MPI library (if in doubt, consult your systems administrator).
The {\tt Makefile} in the distribution includes some examples, but
library names and locations are often system-dependent.
Please do {\it not} direct questions regarding {\tt LFLAGS} to the authors --
ask your sys-admin or other experts familiar with your installation.

Note that the MPI-capable executable can also be used for ordinary serial
calculations using a single cpu.

\subsection{ Device Numbers {\tt IDVOUT} and {\tt IDVERR}
\label{subsec:IDVOUT}}
\index{IDVOUT}
\index{IDVERR}
So far as we know, there are only one operating-system-dependent aspect of
{\bf DDSCAT \vers}: the device number to use for ``standard output".

The variables {\tt IDVOUT} and {\tt IDVERR} specify device numbers
for ``running output" and ``error messages", respectively.
Normally these would both be set to the device number
for ``standard output" (e.g., writing to the screen if running interactively).
Variables {\tt IDVERR} are
set by {\tt DATA} statements in the ``main" program
{\tt DDSCAT.f90} and in the output routine {\tt WRIMSG} (file {\tt wrimsg.f90}).
The executable statement {\tt IDVOUT=0} initializes {\tt IDVOUT} to
0.  In the as-distributed version of {\tt DDSCAT.f90}, the statement

{\tt OPEN(UNIT=IDVOUT,FILE=CFLLOG)}

\noindent causes the output to {\tt UNIT=IDVOUT} to be buffered
and written to the file {\tt ddscat.log\_nnn}, where {\tt nnn=000} for
the first cpu, 001 for the second cpu, etc.
If it is desirable to have this output unbuffered for debugging purposes,
(so that the output will contain up-to-the-moment information)
simply comment out this {\tt OPEN} statement.

\section{Moving the Executable}

Now reposition yourself into the directory {\tt DDA}\
(e.g., type {\tt cd ..}),
and copy the executable
from {\tt src/ddscat} to the {\tt DDA}\ directory by typing

\indent\indent {\tt cp src/ddscat ddscat}

\noindent This should copy the file {\tt DDA/src/ddscat} to
{\tt DDA/ddscat} (you could, alternatively, create a symbolic
link).  Similarly,
copy the sample parameter file {\tt ddscat.par} and the file
{\tt diel.tab} to the
{\tt DDA} directory by typing

\indent\indent{\tt cp doc/ddscat.par ddscat.par}\hfill\break
\indent\indent{\tt cp doc/diel.tab diel.tab}

\section{The Parameter File {\tt ddscat.par}
        \label{sec:parameter_file}}
\index{ddscat.par parameter file}
When the tarfile is unpacked, it will create four directories: {\tt src},
{\tt doc}, {\tt diel}, and {\tt examples\_exp}.
The {\tt examples\_exp} directory has a number of subdirectories,
each with
files for a sample calculation.
Here we focus on the files in the subdirectory {\tt RCTGLPRSM}.

The file
{\tt ddscat.par}
(see also Appendix \ref{app:ddscat.par})
provides parameters to the program {\tt ddscat}:
{\scriptsize
\begin{verbatim}
' ========= Parameter file for v7.1 ==================='
'**** Preliminaries ****'
'NOTORQ' = CMTORQ*6 (NOTORQ, DOTORQ) -- either do or skip torque calculations
'PBCGS2' = CMDSOL*6 (PBCGS2, PBCGST, PETRKP) -- select solution method
'GPFAFT' = CMDFFT*6 (GPFAFT, FFTMKL) -- select FFT method
'GKDLDR' = CALPHA*6 (GKDLDR, LATTDR) -- select prescription for polarizabilities
'NOTBIN' = CBINFLAG (NOTBIN, ORIBIN, ALLBIN) -- specify binary output
'**** Initial Memory Allocation ****'
100 100 100 = dimensioning allowance for target generation
'**** Target Geometry and Composition ****'
'RCTGLPRSM' = CSHAPE*9 shape directive
32 64 64  = shape parameters 1 - 3
1         = NCOMP = number of dielectric materials
'../diel/Au_evap' = file with refractive index 1
'**** Error Tolerance ****'
1.00e-5 = TOL = MAX ALLOWED (NORM OF |G>=AC|E>-ACA|X>)/(NORM OF AC|E>)
'**** Interaction cutoff parameter for PBC calculations ****'
1.00e-2 = GAMMA (1e-2 is normal, 3e-3 for greater accuracy)
'**** Angular resolution for calculation of <cos>, etc. ****'
0.5	= ETASCA (number of angles is proportional to [(3+x)/ETASCA]^2 )
'**** Wavelengths (micron) ****'
0.5000 0.5000 1 'LIN' = wavelengths (first,last,how many,how=LIN,INV,LOG)
'**** Effective Radii (micron) **** '
0.49237 0.49237 1 'LIN' = aeff (first,last,how many,how=LIN,INV,LOG)
'**** Define Incident Polarizations ****'
(0,0) (1.,0.) (0.,0.) = Polarization state e01 (k along x axis)
2 = IORTH  (=1 to do only pol. state e01; =2 to also do orth. pol. state)
'**** Specify which output files to write ****'
1 = IWRKSC (=0 to suppress, =1 to write ".sca" file for each target orient.
1 = IWRPOL (=0 to suppress, =1 to write ".pol" file for each (BETA,THETA)
'**** Prescribe Target Rotations ****'
0.    0.   1  = BETAMI, BETAMX, NBETA  (beta=rotation around a1)
0.    0.   1  = THETMI, THETMX, NTHETA (theta=angle between a1 and k)
0.    0.   1  = PHIMIN, PHIMAX, NPHI (phi=rotation angle of a1 around k)
'**** Specify first IWAV, IRAD, IORI (normally 0 0 0) ****'
0   0   0    = first IWAV, first IRAD, first IORI (0 0 0 to begin fresh)
'**** Select Elements of S_ij Matrix to Print ****'
6	= NSMELTS = number of elements of S_ij to print (not more than 9)
11 12 21 22 31 41	= indices ij of elements to print
'**** Specify Scattered Directions ****'
'LFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
2 = NPLANES = number of scattering planes
0.  0. 180.  5 = phi, thetan_min, thetan_max, dtheta (in deg) for plane 1
90.  0. 180. 5 = phi, thetan_min, thetan_max, dtheta (in deg) for plane 2
\end{verbatim}}

Here we discuss the general structure of {\tt ddscat.par}
(see also Appendix \ref{app:ddscat.par}).
\subsection{ Preliminaries}
{\tt ddscat.par} starts by setting the values of five strings:
\begin{itemize}
\item CMDTRQ specifying whether or not radiative torques
      are to be calculated (e.g., NOTORQ)
\item CMDSOL specifying the solution method (e.g., PBCGS2)
      (see section \S\ref{sec:choice_of_algorithm}).
\item CMDFFT specifying the FFT method (e.g., GPFAFT)
      (see section \S\ref{sec:choice_of_fft}).
\index{GPFAFT -- see ddscat.par}
\index{ddscat.par!GPFAFT}
\item CALPHA specifying the polarizability prescription (e.g., GKDLDR)
      (see \S\ref{sec:polarizabilities}).
\index{GKDLDR -- see ddscat.par}
\index{LATTDR -- see ddscat.par}
\index{ddscat.par!GKDLDR}
\index{ddscat.par!LATTDR}
\item CBINFLAG specifying whether to write out binary files (e.g., NOTBIN)
\index{NOTBIN -- see ddscat.par}
\index{ddscat.par!NOTBIN}
\end{itemize}
\subsection{ Initial Memory Allocation}
Three integers\\
\hspace*{3em}{\tt MXNX  MXNY  MXNZ}\\
are given that need to be equal to or larger than
the anticipated target size (in lattice units) in the $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, and
$\hat{\bf z}_\TF$ directions.  This is required for initial memory allocation.
A value like\\
\hspace*{3em}100 100 100\\
would require initial memory allocation of only $\sim100~$MBytes.
Note that after the target geometry has been determined, {\bf DDSCAT \vers}\ will proceed
to reallocate only as much memory as is actually required for the calculation.

\subsection{ Target Geometry and Composition}
\begin{itemize}
\item CSHAPE specifies the target geometry (e.g., RCTGLPRSM)
\end{itemize}
As provided,
the file {\tt ddscat.par}
is set up to calculate scattering by a 32$\times$64$\times$64
rectangular array of 131072
dipoles.

The user must specify {\tt NCOMP}, which specifies
how many different dielectric functions will be used.
This is then followed by {\tt NCOMP} lines, with each line giving the name
(in quotes) of each dielectric function file.  In our example,
{\tt NCOMP} is set to 1.
The dielectric function of the target material is provided in the file
{\tt ../diel/Au\_evap},
which is gives the refractive index of evaporated Au
over a range of wavelengths.
\index{NCOMP!ddscat.par}
\index{diel.tab -- see ddscat.par}
\index{ddscat.par!diel.tab}

\subsection{ Error Tolerance}
{\tt TOL} = the error tolerance.  Conjugate gradient iteration will proceed
until the linear equations are solved to a fractional error {\tt TOL}.
The sample calculation has {\tt TOL}=$10^{-5}$.

\subsection{ Interaction Cutoff Parameter for PBC Calculations}
{\tt GAMMA} = parameter limiting certain summations that are required for
periodic targets (see Draine \& Flatau 2008).
{\bf The value of {\tt GAMMA} has no effect on
computations for finite targets} --
it can be set to any value, including $0$).

For targets that are periodic in 1 or 2 dimensions,
{\tt GAMMA} needs to be small for high accuracy, but
the required cpu time increases as {\tt GAMMA} becomes smaller.
{\tt GAMMA} = $10^{-2}$ is reasonable for initial calculations,
but you may want to experiment to see if the results you are interested
in are sensitive to the value of {\tt GAMMA}.
Draine \& Flatau (2008) show examples of how computed results for scattering
can depend on the value of $\gamma$.
\index{GAMMA -- see ddscat.par}
\index{ddscat.par!GAMMA}

\subsection{ Angular Resolution for Computation of
            $\langle\cos\theta\rangle$, etc.}
The parameter {\tt ETASCA} determines the selection of scattering angles used
for computation of certain angular averages, such as
$\langle\cos\theta\rangle$ and $\langle\cos^2\theta\rangle$,
and the radiation pressure force
(see \S\ref{sec:force and torque calculation}) and radiative torque
(if {\tt CMDTRQ=DOTORQ}).
Small values of {\tt ETASCA} result in increased accuracy but also cost
additional computation time.
{\tt ETASCA}=0.5 generally gives accurate results.

If accurate computation of $\langle\cos\theta\rangle$
or the radiation pressure force is not required, the user can set
{\tt ETASCA} to some large number, e.g. 10, to minimize unnecessary
computation.

\subsection{ Wavelength}
Wavelengths $\lambda$ are specified one line in {\tt ddscat.par}
consisting of values for 4 variables:\\
\hspace*{2em}
{\tt WAVINI}~ {\tt WAVEND}~ {\tt NWAV}~ {\tt CDIVID}\\
where {\tt WAVINI} and {\tt WAVEND} are real numbers, {\tt NWAV} is an
integer,
and {\tt CDIVID} is a character variable.
\begin{itemize}
\item If {\tt CDIVID = 'LIN'}, the $\lambda$ will be uniformly spaced
beween {\tt WAVINI} and {\tt WAVEND}.
\item If {\tt CDIVID = 'INV'}, the $\lambda$ will be uniformly spaced in
$1/\lambda$ between {\tt WAVINI} and {\tt WAVEND}
\item If {\tt CDIVID = 'LOG'}, the $\lambda$ will be uniformly spaced
in $\log(\lambda)$ between {\tt WAVINI} and {\tt WAVEND}
\item If {\tt CDIVID = 'TAB'}, the $\lambda$ will be read from a
user-supplied file {\tt wave.tab}, with one wavelength per line.
For this case, the values of {\tt WAVINI}, {\tt WAVEND},
and {\tt NWAV} will be disregarded.
\end{itemize}
The sample {\tt ddscat.par} file specifies that the calculations be done for a
single  ($\lambda=0.50$).  The units must be the same as the wavelength
units used in the file specifying the refractive index.  In this case,
we are using ${\mu{\rm m}}$.

\subsection{ Target Size ${a}_{\rm eff}$}
Note that in {\bf DDSCAT}\ the ``effective radius''
$a_{\rm eff}$
\index{effective radius ${a}_{\rm eff}$}
\index{$a_{\rm eff}$}
is the radius of a sphere of
equal volume -- i.e., a sphere of volume $Nd^3$ , where $d$
is the lattice spacing
and $N$ is the number of occupied (i.e., non-vacuum)
lattice sites in the target.
Thus the effective radius $a_{\rm eff} = (3N/4\pi)^{1/3}d$ .
Our target should have a thickness $a=0.5{\mu{\rm m}}$ in the $\hat{\bf x}_\TF$ direction.
If the rectangular solid is $a\times b\times c$, with $a:b:c::32:64:64$,
then $V=abc=4a^3$.  Thus
${a}_{\rm eff}=(3V/4\pi)^{1/3}=(3/\pi)^{1/3}a = 0.49237{\mu{\rm m}}$.

\subsection{ Incident Polarization}
The incident radiation is always assumed to propagate along the $x$ axis in
the ``Lab Frame''.
The sample {\tt ddscat.par} file specifies incident polarization
state ${\hat{\bf e}}_{01}$ to be along the $y$ axis
(and consequently polarization state ${\hat{\bf e}}_{02}$
will automatically be taken to be along the $z$ axis).
{\tt IORTH=2} in {\tt ddscat.par}
calls for calculations to be carried out for both incident polarization
states (${\hat{\bf e}}_{01}$ and ${\hat{\bf e}}_{02}$
-- see \S\ref{sec:incident_polarization}).

\subsection{ Output Files to Write}
The sample {\tt ddscat.par} file sets {\tt 1=IWRKSC}, so that ``.sca''
files will be written out with scattering information for each orientation.

The sample {\tt ddscat.par} file sets {\tt 1=IWRPOL}, so that
a ``.pol'' file will be writtten out for each incident polarization and
each orientation.  Note that each such file has a size that is proportional
to the number of dipoles, and can be quite large.  For this modest test
problem, with $N=131072$ dipoles, the .pol files are each 11.8 MBytes.
These files are only useful if post-processing of the solution is desired,
such as evaluation of the electromagnetic field near the target using
the {\tt DDfield}\index{DDfield} program as
described in \S\ref{sec:calculate E and B fields}.

\subsection{ Target Orientation}
The target is assumed to have two vectors ${\hat{\bf a}}_1$ and
${\hat{\bf a}}_2$ embedded in it; ${\hat{\bf a}}_2$ is perpendicular
to ${\hat{\bf a}}_1$.
\index{$\hat{\bf a}_1$, $\hat{\bf a}_2$ target vectors}
For the present target shape {\tt RCTGLPRSM},
the vector ${\hat{\bf
a}}_1$ is along the $\hat{\bf x}_\TF$ axis of the target, and the vector
${\hat{\bf a}}_2$ is along the $\hat{\bf y}_\TF$ axis (see \S\ref{sec:RCTGLPRSM}).
The target orientation in the Lab Frame is set by three angles: $\beta$,
$\Theta$, and $\Phi$, defined and discussed below in
\S\ref{sec:target_orientation}.
\index{$\Theta$ -- target orientation angle}
\index{$\Phi$ -- target orientation angle}
\index{$\beta$ -- target orientation angle}
Briefly, the polar angles $\Theta$
and $\Phi$ specify the direction of ${\hat{\bf a}}_1$ in the Lab
Frame.  The target is assumed to be rotated around ${\hat{\bf a}}_1$
by an angle $\beta$.  The sample {\tt ddscat.par} file specifies
$\beta=0$ and $\Phi=0$ (see lines in {\tt ddscat.par} specifying
variables {\tt BETA} and {\tt PHI}), and calls for three values of the
angle $\Theta$ (see line in {\tt ddscat.par} specifying variable {\tt
THETA}).  {\bf DDSCAT}\ chooses $\Theta$ values uniformly spaced
in $\cos\Theta$; thus, asking for three values of $\Theta$ between 0
and $90^\circ$ yields $\Theta=0$, $60^\circ$, and $90^\circ$.

\subsection{ Starting Values of {\tt IWAV}, {\tt IRAD}, {\tt IORI}}
Normally we begin the calculation with {\tt IWAVE}=0, {\tt IRAD}=0, and
{\tt IORI}=0.  However, under some circumstances, a prior
calculation may have completed some of the cases.  If so, the user
can specify starting values of {\tt IWAV}, {\tt IRAD}, {\tt IORI};
the computations will begin with this case, and continue.

\subsection{ Which Mueller Matrix Elements?}
The sample parameter file specifies that {\bf DDSCAT}\ should calculate 6 distinct
Mueller scattering matrix elements $S_{ij}$, with
11, 12, 21, 22, 31, 41 being the chosen values of $ij$.

\subsection{ What Scattering Directions?}
\subsubsection{Isolated Finite Targets}
For finite targets, the user may specify the scattering directions in
either the Lab Frame ({\tt 'LFRAME'})
or the Target Frame ({\tt 'TFRAME'}).

For finite targets, such as specified in this sample {\tt ddscat.par},
the $S_{ij}$ are to be calculated for scattering directions specified
by angles $(\theta,\phi)$.

The sample {\tt ddscat.par} specifies that 2 scattering planes
are to be specified:
the first has $\phi=0$ and the second has $\phi=90^\circ$; for
each scattering plane
$\theta$ values run from 0 to $180^\circ$
in increments of $10^\circ$.

\subsubsection{1-D Periodic Targets}

For periodic targets, the scattering directions {\tt must} be specified in the
Target Frame: {\tt 'TFRAME' = CMDFRM} .

Scattering from 1-d periodic targets is discussed in detail by
Draine \& Flatau (2008).
For periodic targets, the user does not specify scattering planes.
For 1-dimensional targets, the user specifies scattering cones, corresponding
to different scattering orders $M$.
For each scattering cone $M$, the user specifies
$\zeta_{\rm min}$, $\zeta_{\rm max}$, $\Delta\zeta$
(in degrees);
the azimuthal angle $\zeta$ will run from
$\zeta_{\rm min}$ to $\zeta_{max}$, in increments of $\Delta\zeta$.
For example:
{\footnotesize
\begin{verbatim}
'TFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
1 = number of scattering cones
0.  0. 180. 0.05  = OrderM zetamin zetamax dzeta for scattering cone 1
\end{verbatim}
}
\subsubsection{2-D Periodic Targets}

For targets that are periodic in 2 dimensions,
the scattering directions {\tt must} be specified in the
Target Frame: {\tt 'TFRAME' = CMDFRM} .

Scattering from targets that are periodic in 2 dimensions
is discussed in detail by
Draine \& Flatau (2008).
For 2-D periodic targets, the user specifies the diffraction orders
$(M,N)$ for
transmitted radiation: the code will automatically calculate
the scattering matrix elements $S_{ij}^{(2d)}(M,N)$ for both
transmitted and reflected radiation for each $(M,N)$ specified by the user.
For example:
{\footnotesize
\begin{verbatim}
'TFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
1 = number of scattering orders
0.  0. = OrderM OrderN for scattered radiation
\end{verbatim}
}

\section{Running {\bf DDSCAT \vers}\ Using the Sample {\tt ddscat.par} File}

\subsection{ Single-Process Execution}

To execute the program on a UNIX system (running either {\tt sh}
or {\tt csh}), simply type

\indent\indent {\tt ./ddscat >\& ddscat.out \&}

\noindent which will redirect the ``standard output'' to the file {\tt
ddscat.out}, and run the calculation in the background.  The sample
calculation [32x24x16=12288 dipole target, 3 orientations, two incident
polarizations, with scattering (Mueller matrix elements $S_{ij}$)
calculated for 38 distinct scattering
directions], requires 27.9 cpu seconds to complete on a 2.0 GHz single-core
Xeon workstation.

\subsection{ Code Execution Under MPI}
\index{MPI -- Message Passing Interface!code execution}

Local installations of {\tt MPI} will vary -- you should consult with
someone familiar with way {\tt MPI} is installed and used on your system.

At Princeton University Dept.\ of Astrophysical Sciences we use {\tt PBS}
(Portable Batch System)\footnote{\tt http://www.openpbs.org}
to schedule jobs.
{\tt MPI} jobs are submitted using {\tt PBS} by first creating a
shell script such as the following example file {\tt pbs.submit}:\\

\noindent
\hspace*{3em}\#!/bin/bash\\
\hspace*{3em}\#PBS -l nodes=2:ppn=1\\
\hspace*{3em}\#PBS -l mem=1200MB,pmem=300MB\\
\hspace*{3em}\#PBS -m bea\\
\hspace*{3em}\#PBS -j oe\\
\hspace*{3em}cd ~\$PBS\_O\_WORKDIR\\
\hspace*{3em}/usr/local/bin/mpiexec ~ddscat\\

\noindent
The lines beginning with {\tt\#PBS -l} specify the required resources:\\
{\tt\#PBS -l nodes=2:ppn=1} specifies that 2 nodes are to be used,
with 1 processor per node.\\
{\tt\#PBS -l mem=1200MB,pmem=300MB} specifies that the total memory
required ({\tt mem}) is 1200MB,
and the maximum physical memory used by any single
process ({\tt pmem}) is 300MB.  The actual definition of {\tt mem} is
not clear, but in practice it seems that it should be set equal to
2$\times$({\tt nodes})$\times$({\tt ppn})$\times$({\tt pmem}) .\\
{\tt\#PBS -m bea} specifies that PBS should send email when the job begins
({\tt b}), and when it ends ({\tt e}) or aborts ({\tt a}).\\
{\tt\#PBS -j oe} specifies that the output from stdout and stderr will be
merged, intermixed, as stdout.

\noindent This example assumes that the executable {\tt dscat} is located
in the same directory where the code is to execute and write its output.
If {\tt ddscat} is located in another directory, simply give the full pathname.
to it.
The {\tt qsub} command is used to submit the {\tt PBS} job:\\
\\
\hspace*{2em}{\tt qsub pbs.submit}\\

As the calculation proceeds, the usual
output files will be written to this directory: for each wavelength,
target size, and target orientation,
there will be a file
{\tt w}{\it aaa}{\tt r}{\it bbb}{\tt k}{\it ccc}{\tt .sca}, where
{\it aaa=000, 001, 002, ...} specifies the wavelength,
{\it bbb=000, 001, 002, ...} specifies the target size,
and
{\it cc=000, 001, 002, ...} specifies the orientation.
For each wavelength and target size there will also be a file
{\tt w}{\it aaa}{\tt r}{\it bbb}{\tt ori.avg} with orientationally-averaged
quantities.
Finally, there will also be tables {\tt qtable},
and {\tt qtable2} with orientationally-averaged cross sections for each
wavelength and target size.

In addition, each processor employed will write to its own log file
{\tt ddscat.log\_}{\it nnn}, where {\it nnn=000, 001, 002, ...}.
These files contain information
concerning cpu time consumed by different parts of the calculation,
convergence to the specified error tolerance, etc.  If you are uncertain
about how the calculation proceeded, examination of these log files
is recommended.

\section{Output Files}

\subsection{ ASCII files\label{subsec:ascii}}

If you run DDSCAT using the command\hfill\break \indent\indent{\tt
ddscat >\& ddscat.out \&} \hfill\break you will have various types of
ASCII files when the computation is complete:
\begin{itemize}
\item a file {\tt ddscat.out};
\index{ddscat.out}
\item a file {\tt ddscat.log\_000};
\index{ddscat.log\_000 -- output file}
\item a file {\tt mtable};
\index{mtable -- output file}
\item a file {\tt qtable};
\index{qtable -- output file}
\item a file {\tt qtable2};
\index{qtable2 file}
\item files {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt ori.avg}
	(one, {\tt w000r000ori.avg}, for the sample calculation);
\index{w000r000ori.avg file -- output file}
\item if {\tt ddscat.par} specified {\tt IWRKSC}=1, there will also be
	files {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .sca} (3 for
	the sample calculation: {\tt w000r000k000.sca}, {\tt w000r000k001.sca},
	{\tt w000r000k002.sca}).
\index{w000r000k000.sca -- output file}
\item if {\tt ddscat.par} specified {\tt IWRPOL}=1, there will also be
        files {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .pol}{\it n}
	for {\it n}=1 and (if {\tt IORTH=2}) {\it n}=2
\index{w000r000k000.pol{\it n} -- output file}
\end{itemize}

The file {\tt ddscat.out} will contain minimal information (it may in fact
be empty).

The file {\tt ddscat.log\_000} will contain any error messages generated as
well as a running report on the progress of the calculation, including
creation of the target dipole array.  During the iterative
calculations, $Q_{\rm ext}$, $Q_{\rm abs}$, and $Q_{pha}$ are printed after
each iteration; you will be able to judge the degree to which
convergence has been achieved.  Unless {\tt TIMEIT} has been disabled,
there will also be timing information.
If the {\tt MPI} option is used to run the code on multiple cpus, there
will be one file of the form {\tt ddscat.log\_nnn} for each of the
cpus, with {\tt nnn=000,001,002,...}.
\index{ddscat.log\_000 -- output file}

The file {\tt mtable} contains a summary of the dielectric constant
used in the calculations.
\index{mtable -- output file}

The file {\tt qtable} contains a summary of the
orientationally-averaged values of $Q_{\rm ext}$, $Q_{\rm abs}$, $Q_{\rm sca}$,
$g(1)=\langle\cos(\theta_s)\rangle$,
$\langle\cos^2(\theta_s)\rangle$, $Q_{bk}$, and $N_{\rm sca}$.
\index{qtable -- output file}
Here $Q_{\rm ext}$,
$Q_{\rm abs}$, and $Q_{\rm sca}$ are the extinction, absorption, and
scattering cross sections divided by $\pi a_{\rm eff}^2$.  $Q_{bk}$ is
the differential cross section for backscattering (area per sr)
divided by $\pi a_{\rm eff}^2$.
$N_{\rm sca}$ is the number of scattering directions used for averaging
over scattering directions (to obtain $\langle\cos\theta\rangle$, etc.)
(see \S\ref{sec:averaging_scattering}).

The file {\tt qtable2} contains a summary of the
orientationally-averaged values of $Q_{pha}$, $Q_{pol}$, and
$Q_{cpol}$.
\index{qtable2 -- output file}
Here $Q_{pha}$ is the ``phase shift'' cross section
divided by $\pi a_{\rm eff}^2$ (see definition in Draine 1988).
$Q_{pol}$ is the ``polarization efficiency factor'', equal to the
difference between $Q_{\rm ext}$ for the two orthogonal polarization
states.  We define a ``circular polarization efficiency factor''
$Q_{cpol}\equiv Q_{pol}Q_{pha}$, since an optically-thin medium with a
small twist in the alignment direction will produce circular
polarization in initially unpolarized light in proportion to
$Q_{cpol}$.

For each wavelength and size, {\bf DDSCAT \vers}\ produces a file with a
name of the form\break{\tt w{\it xxx}r{\it yyy}ori.avg}, where index
{\it xxx} (=000, 001, 002....)  designates the wavelength and index {\it
yyy} (=000, 001, 002...) designates the ``radius''; this file contains $Q$
values and scattering information averaged over however many target
orientations have been specified (see \S\ref{sec:target_orientation}.
\index{w000r000ori.avg -- output file}
The file {\tt w000r000ori.avg} produced by the sample calculation is
provided below in Appendix \ref{app:w000r000ori.avg}.

In addition, if {\tt ddscat.par} has specified {\tt IWRKSC}=1 (as for
the sample calculation), {\bf DDSCAT \vers}\ will generate files with
names of the form {\tt w{\it xxx}r{\it yyy}k{\it zzz}.avg}, where {\it
xxx} and {\it yyy} are as before, and index {\it zzz} =(000,001,002...)
designates the target orientation; these files contain $Q$ values and
scattering information for {\it each} of the target orientations.
\index{IWRKSC -- see ddscat.par}
\index{ddscat.par!IWRKSC}
\index{w000r000k000.sca -- output file}
The structure of each of these files is very similar to that of the {\tt
w{\it xxx}r{\it yyy}ori.avg} files.  Because these files may not be of
particular interest, and take up disk space, you may choose to set
{\tt IWRKSC}=0 in future work.  However, it is suggested that you run
the sample calculation with {\tt IWRKSC}=1.

The sample {\tt ddscat.par} file specifies {\tt IWRKSC}=1 and calls
for use of 1 wavelength, 1 target size, and averaging over 3 target
orientations.  Running {\bf DDSCAT \vers}\ with the sample {\tt
ddscat.par} file will therefore generate files {\tt w000r000k000.sca},
{\tt w000r000k001.sca}, and {\tt w000r000k002.sca} .  To understand the
information contained in one of these files, please consult Appendix
\ref{app:w000r000k000.sca}, which contains an example of the file {\tt
w000r000k000.sca} produced in the sample calculation.

\subsection{ Binary Option\label{subsec:binary}}

It is possible to output an ``unformatted'' or ``binary'' file ({\tt
dd.bin}) with fairly complete information, including header and data
sections.  This is accomplished by specifying either {\tt ALLBIN} or
{\tt ORIBIN} in {\tt ddscat.par} .
\index{ddscat.par!ORIBIN}
\index{ddscat.par!ALLBIN}

Subroutine {\tt writebin.f90} provides an example of how this can be
done.  The ``header'' section contains dimensioning and other
variables which do not change with wavelength, particle geometry, and
target orientation.  The header section contains data defining the
particle shape, wavelengths, particle sizes, and target orientations.
If {\tt ALLBIN} has been specified, the ``data'' section contains, for
each orientation, Mueller matrix results for each scattering
direction.  The data output is limited to actual dimensions of arrays;
e.g. {\tt nscat,4,4} elements of Muller matrix are written rather than
{\tt mxscat,4,4}.  This is an important consideration when writing
postprocessing codes.

\section{Choice of Iterative Algorithm\label{sec:choice_of_algorithm}}
\index{iterative algorithm}
\index{conjugate gradient algorithm}
As discussed elsewhere (e.g., Draine 1988), the problem of
electromagnetic scattering of an incident wave ${\bf E}_{\rm inc}$ by an
array of $N$ point dipoles can be cast in the form
\begin{equation}
{\bf A} {\bf P} = {\bf E}
\label{eq:AP=E}
\end{equation}
where ${\bf E}$ is a $3N$-dimensional (complex) vector of the incident
electric field ${\bf E}_{\rm inc}$ at the $N$ lattice sites, ${\bf P}$ is
a $3N$-dimensional (complex) vector of the (unknown) dipole
polarizations, and ${\bf A}$ is a $3N\times3N$ complex matrix.

Because $3N$ is a large number, direct methods for solving this system
of equations for the unknown vector ${\bf P}$ are impractical, but
iterative methods are useful: we begin with a guess (typically, ${\bf
P}=0$) for the unknown polarization vector, and then iteratively
improve the estimate for ${\bf P}$ until equation (\ref{eq:AP=E}) is
solved to some error criterion.  The error tolerance may be specified
as
\begin{equation}
{|{\bf A}^\dagger {\bf A} {\bf P} - {\bf A}^\dagger {\bf E}| \over
| {\bf A}^\dagger {\bf E} |}
 < h
\label{eq:err_tol}~~~,
\end{equation}
where ${\bf A}^\dagger$ is the Hermitian conjugate of ${\bf A}$
[$(A^\dagger)_{ij} \equiv (A_{ji})^*$], and $h$ is the error
tolerance.  We typically use $h=10^{-5}$ in order to satisfy
eq.(\ref{eq:AP=E}) to high accuracy.  The error tolerance $h$ can be
specified by the user through the parameter {\tt TOL} in
the parameter file {\tt ddscat.par} (see Appendix \ref{app:ddscat.par}).
\index{error tolerance}
\index{ddscat.par!TOL}

A major change in going from {{\bf DDSCAT}}{\bf .4b} to {\bf 5a} (and
subsequent versions) was the implementation of several different
algorithms for iterative solution of the system of complex linear
equations.  {\bf DDSCAT \vers}\ is now
structured to permit solution algorithms to be treated in a fairly
``modular'' fashion, facilitating the testing of different algorithms.
A number of algorithms were compared by Flatau (1997)\footnote{ A postscript
copy of this report -- file {\tt cg.ps} -- is distributed with the
{\bf DDSCAT \vers}\ documentation.}; two of them ({\tt PBCGST} and {\tt PETRKP})
performed well and are
made available to the user in {\bf DDSCAT}.
{\bf DDSCAT \vers}\ now also offers a third option, {\tt PBCGS2}.
The choice of algorithm is made by specifying one of the options:
\begin{itemize}
\item {\tt PBCGS2} --  BiConjugate Gradient with Stabilization as implemented
      in the routine ZBCG2 by M.A. Botchev, University of Twente.
      This is based on the PhD thesis of D.R. Fokkema, and on work
      by Sleijpen \& vanderVorst (1995,1996).
\item {\tt PBCGST} -- Preconditioned BiConjugate Gradient with
	STabilitization method from the Parallel Iterative Methods
	(PIM) package created by R. Dias da Cunha and T. Hopkins.
\index{PBCGST algorithm}
\index{ddscat.par!PBCGST}
\index{PIM package}
\item {\tt PETRKP} -- the complex conjugate gradient algorithm of
	Petravic \& Kuo-Petravic (1979), as coded in the Complex Conjugate
	Gradient package (CCGPACK) created by P.J. Flatau.
	This is the algorithm discussed by Draine (1988) and used in
	previous versions of {{\bf DDSCAT}}.
\index{PETRKP algorithm}
\index{ddscat.par!PETRKP}
\end{itemize}
All three methods work fairly well.
Our experience suggests that {\tt PBCGS2} is generally fastest and
best-behaved, and we recommend that the user try it first.
However, in case it runs into numerical difficulties, {\tt PBCGST} and
{\tt PETRKP} are available as alternatives.\footnote{
The Parallel Iterative Methods (PIM) by Rudnei Dias da Cunha ({\tt
rdd@ukc.ac.uk}) and Tim Hopkins ({\tt trh@ukc.ac.uk}) is a collection
of Fortran 77 routines designed to solve systems of linear equations
on parallel and scalar computers using a variety of iterative methods
(available at \hfill\break {\tt http://www.mat.ufrgs.br/pim-e.html}).
PIM offers a number of iterative methods, including
\begin{itemize}
\item Conjugate-Gradients, CG (Hestenes 1952),
\item Bi-Conjugate-Gradients, BICG (Fletcher 1976),
\item Conjugate-Gradients squared, CGS (Sonneveld 1989),
\item the stabilised version of Bi-Conjugate-Gradients, BICGSTAB (van
	der Vorst 1991),
\item the restarted version of BICGSTAB, RBICGSTAB (Sleijpen \& Fokkema 1992)
\item the restarted generalized minimal residual, RGMRES (Saad 1986),
\item the restarted generalized conjugate residual, RGCR (Eisenstat 1983),
\item the normal equation solvers, CGNR (Hestenes 1952 and CGNE (Craig 1955),
\item the quasi-minimal residual, QMR (highly parallel version due to
	Bucker \& Sauren 1996),
\item transpose-free quasi-minimal residual, TFQMR (Freund 1992),
\item the Chebyshev acceleration, CHEBYSHEV (Young 1981).
\end{itemize}
The source code for these methods is distributed with {\tt DDSCAT} but
only {\tt PBCGST} and {\tt PETRKP} can be called directly via {\tt
ddscat.par}. It is possible to add other options by
changing the code in {\tt getfml.f90}~. Flatau (1997) has compared
the convergence rates of a number of different methods.
A helpful introduction to
conjugate gradient methods is provided by the report ``Conjugate
Gradient Method Without Agonizing Pain" by Jonathan R. Shewchuk,
available as a postscript file: {\tt
   ftp://REPORTS.ADM.CS.CMU.EDU/usr0/anon/1994/CMU-CS-94-125.ps}.
}

\section{Choice of FFT Algorithm\label{sec:choice_of_fft}}
\index{FFT algorithm}
\index{FFTW}
\index{GPFA}
{\bf DDSCAT \vers}\ offers two FFT options:
(1) the GPFA FFT algorithm developed by Dr. Clive Temperton (1992),
\footnote{The GPFA code contains a parameter {\tt LVR} which is set in
          {\tt data} statements in the routines {\tt gpfa2f}, {\tt gpfa3f},
          and {\tt gpfa5f}.  {\tt LVR} is supposed to be optimized to
          correspond to the ``length of a vector register'' on vector
          machines.  As delivered, this parameter is set to 64, which is
          supposed to be appropriate for Crays other than the C90.
          For the C90, 128 is supposed to be preferable (and perhaps
	  ``preferable'' should be read as
	  ``necessary'' -- there is some basis for fearing that results
	  computed on a C90 with {\tt LVR} other than 128 run the risk of being
	  incorrect!)
          The value of {\tt LVR} is not critical for scalar machines, as
          long as it is fairly large.  We found little difference between
          {\tt LVR}=64 and 128 on a Sparc 10/51, on an Ultrasparc 170, and
          on an \Intel\ Xeon cpu.  You may wish to
          experiment with different {\tt LVR} values on your computer
          architecture.  To change {\tt LVR}, you need to edit {\tt gpfa.f90}
          and change the three {\tt data} statements where {\tt LVR} is set.}
and (2) the \Intel\ MKL routine {\tt DFTI}.

\begin{figure}
\centerline{\includegraphics[width=9.0cm]{f5.eps}}
\caption{\label{fig:fft_timings}
        \footnotesize
	Comparison of cpu time required by 3 different FFT
	implementations.
	It is seen that the GPFA and FFTW implementations have comparable
	speeds, much faster than Brenner's FFT implementation.
	}
\end{figure}

The GPFA routine is portable and quite fast:
Figure 5 compares the speed of three FFT implementations: Brenner's, GPFA,
and FFTW ({\tt http://www.fftw.org}).
We see that while for some cases {\tt FFTW 2.1.5} is
faster than the GPFA algorithm, the difference is only marginal.
The FFTW code and GPFA code are quite comparable in
performance -- for some cases the GPFA code is faster, for other cases
the FFTW code is faster.
For target dimensions which are factorizable as $2^i3^j5^k$ (for integer
$i$, $j$, $k$), the GPFA
and FFTW
codes have the same memory requirements.
For targets with extents $N_x$, $N_y$, $N_z$
which are not factorizable as $2^i3^j5^k$, the GPFA code
needs to ``extend'' the computational volume to have values of $N_x$,
$N_y$, and $N_z$ which are factorizable by 2, 3, and 5.
For these cases, GPFA requires somewhat more memory than
FFTW.
However, the fractional difference in required memory
is not large, since integers factorizable
as $2^i3^j5^k$ occur fairly
frequently.\footnote{\label{fn:235}2, 3, 4, 5, 6, 8, 9, 10, 12,
	15, 16, 18, 20, 24, 25, 27, 30, 32, 36, 40,
	45, 48, 50, 54, 60, 64, 72, 75, 80, 81, 90,
	96, 100, 108, 120, 125, 128, 135,
	144, 150, 160, 162, 180, 192, 200  216, 225,
        240, 243, 250, 256, 270, 288, 300, 320, 324, 360, 375, 384, 400, 405,
        432, 450, 480, 486, 500, 512, 540, 576, 600, 625, 640, 648, 675, 720,
        729, 750, 768, 800, 810, 864, 900, 960, 972, 1000, 1024, 1080, 1125,
        1152, 1200, 1215, 1250, 1280, 1296, 1350, 1440, 1458, 1500, 1536,
        1600, 1620, 1728, 1800, 1875, 1920, 1944, 2000, 2025, 2048, 2160,
        2187, 2250, 2304, 2400, 2430, 2500, 2560, 2592, 2700, 2880, 2916,
        3000, 3072, 3125, 3200, 3240, 3375, 3456, 3600, 3645, 3750, 3840,
        3888, 4000, 4050, 4096 are the integers $\leq 4096$
	which are of the form $2^i3^j5^k$.}
[Note: This ``extension'' of the target volume occurs automatically and
is transparent to the user.]

{\bf DDSCAT \vers}\ offers a new FFT option: the \Intel\ Math Kernel
Library {\tt DFTI}.  This is tuned for optimum performance,
and appears to offer real performance advantages on modern multi-core cpus.
With this now available, the FFTW option, which had been included in
{\bf DDSCAT}\ {\bf 6.1}, has been removed from
{\bf DDSCAT \vers}.

The choice of FFT implementation is obtained by specifying one of:
\begin{itemize}
\item{\tt FFTMKL} to use the \Intel\ MKL routine {\tt DFTI}
        (see \S\ref{sec:MKL}).
	{\bf This is recommended, but requires that the \Intel\ Math Kernel
	Library be
	installed on your system}.
\item{\tt GPFAFT} to use the GPFA algorithm (Temperton 1992).{\bf This is
	is not quite as fast as FFTMKL, but is written in plain Fortran-90.}
\end{itemize}

\section{Dipole Polarizabilities\label{sec:polarizabilities}}
\index{LATTDR}
\index{ddscat.par!LATTDR}

\begin{figure}
\centerline{\includegraphics[width=8.3cm]{fldr.eps}}
\caption{\footnotesize
         Scattering and absorption for a $m=1.7+0.1i$ sphere,
         calculated using two prescriptions for the polarizability:
	 LATTDR is the lattice dispersion relation result of Draine \& Goodman
	 (1993).  GKDLDR is the lattice dispersion relation result
	 of Gutkowicz-Krusin \& Draine (2004).
	 Results are shown as a function of scattering parameter
	 $x=2\pi a/\lambda$;
	 the upper scale gives values of $|m|kd$.
	 We see that the cross sections calculated with these two
	 prescriptions are quite similar for $|m|kd\lower.5ex\hbox{$\; \buildrel < \over \sim \;$} 0.5$.
	 For other examples see Gutkowicz-Krusin \& Draine
	 (2004).
	\label{fig:GKDLDR_vs_LATTDR}}
\end{figure}

\index{GKDLDR}
\index{polarizabilities!GKDLDR}
\index{ddscat.par!GKDLDR}
Option {\tt GKDLDR} specifies that the polarizability be prescribed
by the ``Lattice Dispersion Relation'', with the polarizability
found by Gutkowicz-Krusin \& Draine (2004), who corrected a subtle error in
the analysis of Draine \& Goodman (1993).
For $|m|kd\lower.5ex\hbox{$\; \buildrel < \over \sim \;$} 1$,
the {\tt GKDLDR}  polarizability differs slightly from the {\tt LATTDR}
polarizability, but the differences in calculated scattering cross sections
are relatively small, as can be seen from Figure \ref{fig:GKDLDR_vs_LATTDR}.
We recommend option {\tt GKDLDR}.

\index{LATTDR}
\index{polarizabilities!LATTDR}
\index{ddscat.par!LATTDR}
Users wishing to compare can invoke option {\tt LATTDR} to specify that the
``Lattice Dispersion Relation'' of Draine \& Goodman (1993)
be employed to determine the dipole
polarizabilities.
This polarizability also works well.

\section{Dielectric Functions\label{sec:dielectric_func}}
\index{dielectric function of target material}
\index{refractive index of target material}
In order to assign the appropriate dipole polarizabilities, {\bf DDSCAT \vers}\
must be given the dielectric constant of the material (or
materials) of which the target of interest is composed {\it relative to the
dielectric constant of the ambient medium}.
This information is supplied to {\bf DDSCAT \vers}\
through a table (or tables), read by subroutine {\tt DIELEC} in file
{\tt dielec.f90}, and providing either the complex refractive index
$m=n+ik$ or complex dielectric function
$\epsilon=\epsilon_1+i\epsilon_2$ as a function of wavelength
$\lambda$.  Since $m=\epsilon^{1/2}$, or $\epsilon=m^2$, the user must
supply either $m$ or $\epsilon$.

{\bf DDSCAT \vers}\ can calculate scattering and absorption by targets with anisotropic
dielectric functions, with arbitrary orientation of the optical axes relative
to the target shape. See \S\ref{sec:composite anisotropic targets}.

As discussed in \S\ref{sec:target_in_medium}, {\bf DDSCAT}\ calculates
scattering for targets embedded in dielectric media
using the {\it relative} dielectric constant
$\epsilon=\epsilon_{\rm target}(\omega)/\epsilon_{\rm medium}(\omega)$
or the {\it relative} refractive index
$m=m_{\rm target}(\omega)/m_{\rm medium}(\omega)$ and
the wavelength {\it in the medium} $\lambda=(2\pi c/\omega)/m_{\rm medium}$,
where $c$ is the speed of light {\it in vacuo}.

It is therefore important that the table containing the dielectric function
information give the {\it relative} dielectric function or refractive index
as a function of the {\it wavelength in the ambient medium}.

The table formatting is intended to be quite flexible.  The first line
of the table consists of text, up to 80 characters of which will be
read and included in the output to identify the choice of dielectric
function.  (For the sample problem, it consists of simply the
statement {\tt m = 1.33 + 0.01i}.)  The second line consists of 5
integers; either the second and third {\it or} the fourth and fifth
should be zero.
\begin{itemize}
\item The first integer specifies which column the wavelength is stored in.
\item The second integer specifies which column Re$(m)$ is stored in.
\item The third integer specifies which column Im$(m)$ is stored in.
\item The fourth integer specifies which column Re$(\epsilon)$ is stored in.
\item The fifth integer specifies which column Im$(\epsilon)$ is stored in.
\end{itemize}
If the second and third integers are zeros, then {\tt DIELEC} will
read Re$(\epsilon)$ and Im$(\epsilon)$ from the file; if the fourth
and fifth integers are zeros, then Re$(m)$ and Im$(m)$ will be read
from the file.

The third line of the file is used for column headers, and the data
begins in line 4.  {\it There must be at least 3 lines of data:} even
if $\epsilon$ is required at only one wavelength, please supply two
additional ``dummy'' wavelength entries in the table so that the
interpolation apparatus will not be confused.

\section{Calculation of $\langle\cos\theta\rangle$, Radiative Force, and
         Radiation Torque
	\label{sec:force and torque calculation}}

In addition to solving the scattering problem for a dipole array,
{\bf DDSCAT}\ can compute the three-dimensional force ${\bf F}_{\rm rad}$
and torque ${\bf \Gamma}_{\rm rad}$ exerted on this array by the
incident and scattered radiation fields.
The radiation torque calculation is carried
out, after solving the scattering problem, only if {\tt DOTORQ} has
been specified in {\tt ddscat.par}.
\index{DOTORQ}
\index{ddscat.par!DOTORQ}
For each incident polarization
mode, the results are given in terms of dimensionless efficiency
vectors ${\bf Q}_{pr}$ and ${\bf Q}_{\Gamma}$, defined by
\index{radiative force efficiency vector ${\bf Q}_{pr}$}
\index{radiative torque efficiency vector ${\bf Q}_\Gamma$}
\index{${\bf Q}_{pr}$ -- radiative force efficiency vector}
\index{${\bf Q}_\Gamma$ -- radiative torque efficiency vector}
\begin{equation}
{\bf Q}_{\rm pr} \equiv {{\bf F}_{\rm rad} \over
\pi {a}_{\rm eff}^2 u_{\rm rad}} ~~~,
\end{equation}
\begin{equation}
{\bf Q}_\Gamma \equiv {k{\bf \Gamma}_{\rm rad} \over
\pi {a}_{\rm eff}^2 u_{\rm rad}} ~~~,
\end{equation}
where ${\bf F}_{\rm rad}$ and ${\bf \Gamma}_{\rm rad}$ are the time-averaged
force and torque on the dipole array, $k=2\pi/\lambda$ is the
wavenumber {\it in vacuo}, and $u_{\rm rad} = E_0^2/8\pi$ is the
time-averaged energy density for an incident plane wave with amplitude
$E_0 \cos(\omega t + \phi)$.  The radiation pressure efficiency vector
can be written
\begin{equation}
{\bf Q}_{\rm pr} = Q_{\rm ext}{\hat{\bf k}} - Q_{\rm sca}{\bf g} ~~~,
\end{equation}
where ${\hat{\bf k}}$ is the direction of propagation of the incident
radiation, and the vector {\bf g} is the mean direction of propagation
of the scattered radiation:
\begin{equation}\label{eq:gvec}
{\bf g} = {1\over C_{\rm sca}}\int d\Omega
{dC_{\rm sca}({\hat{\bf n}},{\hat{\bf k}})\over d\Omega} {\hat{\bf n}} ~~~,
\end{equation}
where $d\Omega$ is the element of solid angle in scattering direction
${\hat{\bf n}}$, and $dC_{\rm sca}/d\Omega$ is the differential scattering
cross section.
The components of ${\bf Q}_{\rm pr}$ are reported in the Target Frame:
$Q_{{\rm pr},1}\equiv {\bf F}_{\rm rad}\cdot \hat{\bf x}_\TF$,
$Q_{{\rm pr},2}\equiv {\bf F}_{\rm rad}\cdot \hat{\bf y}_\TF$,
$Q_{{\rm pr},3}\equiv {\bf F}_{\rm rad}\cdot \hat{\bf z}_\TF$.

Equations for the evaluation of the radiative force and torque are
derived by Draine \& Weingartner (1996).  It is important to note that
evaluation of ${\bf Q}_{\rm pr}$ and ${\bf Q}_\Gamma$ involves averaging
over scattering directions to evaluate the linear and angular momentum
transport by the scattered wave.  This evaluation requires appropriate
choices of the parameter {\tt ETASCA} -- see
\S\ref{sec:averaging_scattering}.
\index{ETASCA}
\index{ddscat.par!ETASCA}

In addition, {\bf DDSCAT}\ calculates $\langle\cos\theta\rangle$ [the first
component of the vector $g$ in eq.\ (\ref{eq:gvec})] and the
second moment $\langle\cos^2\theta\rangle$.
These two moments are useful measures of the anisotropy of the scattering.
For example, Draine (2003) gives an analytic approximation to the
scattering phase function of dust mixtures that is parameterized by
the two moments
$\langle\cos\theta\rangle$ and $\langle\cos^2\theta\rangle$.

\section{Memory Requirements \label{sec:memory_requirements}}
\index{memory requirements}
\index{MXNX,MXNY,MXNZ}

The memory requirements are determined by the size of the ``computational
volume'' -- this is a rectangular region, of size
{\tt NX}$\times${\tt NY}$\times${\tt NZ} that is large enough to contain
the target.  If using the {\tt GPFAFT} option, then {\tt NX},
{\tt NY}, {\tt NZ} are also required to have only 2,3, and 5 as prime factors
(see footnote \ref{fn:235}).

In single precision, the memory requirement for {\bf DDSCAT \vers}\ is approximately
\begin{equation}
(35.+0.0010\times{\tt NX}\times{\tt NY}\times{\tt NZ}) {\rm ~Mbytes}
~~~~{\rm for~single~precision}
\end{equation}
\begin{equation}
(42+0.0020\times{\tt NX}\times{\tt NY}\times{\tt NZ}) {\rm ~Mbytes}
~~~~{\rm for~double~precision}
\end{equation}
Thus, in single precision, a
48$\times$48$\times$48 calculation requires $\sim$146 MBytes.

The memory is allocated dynamically -- once the target has been created,
{\bf DDSCAT \vers}\ will determine just how much overall memory is needed, and
will allocate it.  However, the user must provide information (via
{\tt ddscat.par}) to allow {\bf DDSCAT \vers}\ to allocate sufficiently large arrays
to carry out the initial target creation.  Initially, the only arrays that
will be allocated are those related to the target geometry, so it is
OK to be quite generous in this initial allowance, as the memory
required for the target generation step is small compared to the
memory required to carry out the full scattering calculation.
\index{memory requirements}

\section{Target Orientation \label{sec:target_orientation}}
\index{target orientation}
\index{Lab Frame (LF)}

Recall that we define a ``Lab Frame'' (LF) in which the incident
radiation propagates in the $+x$ direction.
For purposes of discussion we will always
let unit vectors $\hat{\bf x}_\LF$, $\hat{\bf y}_\LF$, $\hat{\bf z}_\LF=\hat{\bf x}_\LF\times\hat{\bf y}_\LF$
be the three coordinate axes of the LF.

In {\tt ddscat.par} one
specifies the first polarization state ${\hat{\bf e}}_{01}$ (which
obviously must lie in the $y,z$ plane in the LF); {{\bf DDSCAT}}\
automatically constructs a second polarization state ${\hat{\bf
e}}_{02} = \hat{\bf x}_\LF \times {\hat{\bf e}}_{01}^*$ orthogonal to
${\hat{\bf e}}_{01}$.
Users will often find it convenient to let polarization
vectors ${\hat{\bf e}}_{01}={\hat{\bf y}}$, ${\hat{\bf
e}}_{02}={\hat{\bf z}}$ (although this is not mandatory -- see
\S\ref{sec:incident_polarization}).

\begin{figure}
\centerline{\includegraphics[width=16.cm]{f6.eps}}
\caption{\footnotesize
        Target orientation in the Lab Frame.  ${\hat{\bf x}}=\hat{\bf x}_\LF$ is the
	direction of propagation of the incident radiation, and ${\hat{\bf
	y}}=\hat{\bf y}_\LF$ is the direction of the real component (at $x_{\rm LF}=0$, $t=0$)
	of the first incident
	polarization mode.  In this coordinate system, the orientation of
	target axis ${\hat{\bf a}}_1$ is specified by angles $\Theta$ and
	$\Phi$.  With target axis ${\hat{\bf a}}_1$ fixed, the orientation of
	target axis ${\hat{\bf a}}_2$ is then determined by angle $\beta$
	specifying rotation of the target around ${\hat{\bf a}}_1$.  When
	$\beta=0$, ${\hat{\bf a}}_2$ lies in the ${\hat{\bf a}}_1$,$\hat{\bf x}_\LF$
	plane.
	}
\label{fig:target_orientation}
\end{figure}

Recall that definition of a target involves specifying two unit
vectors, ${\hat{\bf a}}_1$ and ${\hat{\bf a}}_2$, which are imagined
to be ``frozen'' into the target.  We require ${\hat{\bf a}}_2$ to be
orthogonal to ${\hat{\bf a}}_1$.  Therefore we may define a ``Target
Frame" (TF) defined by the three unit vectors ${\hat{\bf a}}_1$,
${\hat{\bf a}}_2$, and ${\hat{\bf a}}_3 = {\hat{\bf a}}_1 \times
{\hat{\bf a}}_2$ .
\index{Target Frame (TF)}

For example, when {{\bf DDSCAT}}\ creates a 32$\times$24$\times$16
rectangular solid, it fixes ${\hat{\bf a}}_1$ to be along the longest
dimension of the solid, and ${\hat{\bf a}}_2$ to be along the
next-longest dimension.

{\bf Important Note:} for periodic targets, {\bf DDSCAT \vers}\ requires that the
periodic target have ${\hat{\bf a}}_1=\hat{\bf x}_\TF$ and ${\hat{\bf a}}_2=\hat{\bf y}_\TF$.

Orientation of the target relative to the incident radiation can in
principle be determined two ways:
\begin{enumerate}
\item specifying the direction of ${\hat{\bf a}}_1$ and
      ${\hat{\bf a}}_2$ in the LF, or
\item specifying the directions of $\hat{\bf x}_\LF$ (incidence
	direction) and $\hat{\bf y}_\LF$ in the TF.
\end{enumerate}
{\bf DDSCAT}\ uses method 1.: the angles $\Theta$, $\Phi$, and
$\beta$ are specified in the file {\tt ddscat.par}.  The target is
oriented such that the polar angles $\Theta$ and $\Phi$ specify the
direction of ${\hat{\bf a}}_1$ relative to the incident direction
$\hat{\bf x}_\LF$, where the $\hat{\bf x}_\LF$,$\hat{\bf y}_\LF$ plane has
$\Phi=0$.  Once the direction of ${\hat{\bf a}}_1$ is specified, the
angle $\beta$ then specifies how the target is to rotated around the
axis ${\hat{\bf a}}_1$ to fully specify its orientation.  A more
extended and precise explanation follows:

\subsection{ Orientation of the Target in the Lab Frame}
\index{target orientation}
\index{$\Theta$ -- target orientation angle}
\index{$\Phi$ -- target orientation angle}
\index{$\beta$ -- target orientation angle}
DDSCAT uses three angles, $\Theta$, $\Phi$, and $\beta$, to specify
the directions of unit vectors ${\hat{\bf a}}_1$ and ${\hat{\bf a}}_2$
in the LF (see Fig.\ \ref{fig:target_orientation}).

$\Theta$ is the angle between ${\hat{\bf a}}_1$ and $\hat{\bf x}_\LF$.

When $\Phi=0$, ${\hat{\bf a}}_1$ will lie in the $\hat{\bf x}_\LF,\hat{\bf y}_\LF$
plane.  When $\Phi$ is nonzero, it will refer to
the rotation of ${\hat{\bf a}}_1$ around $\hat{\bf x}_\LF$: e.g.,
$\Phi=90^\circ$ puts ${\hat{\bf a}}_1$ in the $\hat{\bf x}_\LF,\hat{\bf z}_\LF$ plane.

When $\beta=0$, ${\hat{\bf a}}_2$ will lie in the
$\hat{\bf x}_\LF,{\hat{\bf a}}_1$ plane, in such a way that when $\Theta=0$ and
$\Phi=0$, ${\hat{\bf a}}_2$ is in the $\hat{\bf y}_\LF$ direction: e.g,
$\Theta=90^\circ$, $\Phi=0$, $\beta=0$ has
${\hat{\bf a}}_1=\hat{\bf y}_\LF$
and ${\hat{\bf a}}_2=-\hat{\bf x}_\LF$.  Nonzero $\beta$ introduces
an additional rotation of ${\hat{\bf a}}_2$ around ${\hat{\bf a}}_1$:
e.g., $\Theta=90^\circ$, $\Phi=0$, $\beta=90^\circ$ has
${\hat{\bf a}}_1=\hat{\bf y}_\LF$ and ${\hat{\bf a}}_2=\hat{\bf z}_\LF$.

Mathematically:
\begin{eqnarray}
{\hat{\bf a}}_1 &=&   \hat{\bf x}_\LF \cos\Theta
+ \hat{\bf y}_\LF \sin\Theta \cos\Phi
+ \hat{\bf z}_\LF \sin\Theta \sin\Phi
	\\
{\hat{\bf a}}_2 &=& - \hat{\bf x}_\LF \sin\Theta \cos\beta
+ \hat{\bf y}_\LF [\cos\Theta \cos\beta \cos\Phi-\sin\beta \sin\Phi] \nonumber\\
&&+ \hat{\bf z}_\LF [\cos\Theta \cos\beta \sin\Phi+\sin\beta \cos\Phi]
	\\
{\hat{\bf a}}_3 &=&   \hat{\bf x}_\LF \sin\Theta \sin\beta
- \hat{\bf y}_\LF [\cos\Theta \sin\beta \cos\Phi+\cos\beta \sin\Phi] \nonumber\\
  &&         - \hat{\bf z}_\LF [\cos\Theta \sin\beta \sin\Phi-\cos\beta \cos\Phi]
\end{eqnarray}
or, equivalently:
\begin{eqnarray}
\hat{\bf x}_\LF &=&   {\hat{\bf a}}_1 \cos\Theta
           - {\hat{\bf a}}_2 \sin\Theta \cos\beta
           + {\hat{\bf a}}_3 \sin\Theta \sin\beta \\
\hat{\bf y}_\LF &=&   {\hat{\bf a}}_1 \sin\Theta \cos\Phi
           + {\hat{\bf a}}_2 [\cos\Theta \cos\beta \cos\Phi-\sin\beta \sin\Phi]
\nonumber\\
&&         - {\hat{\bf a}}_3 [\cos\Theta \sin\beta \cos\Phi+\cos\beta \sin\Phi]
\\
\hat{\bf z}_\LF &=&   {\hat{\bf a}}_1 \sin\Theta \sin\Phi
           + {\hat{\bf a}}_2 [\cos\Theta \cos\beta \sin\Phi+\sin\beta \cos\Phi]
\nonumber\\
&&         - {\hat{\bf a}}_3 [\cos\Theta \sin\beta \sin\Phi-\cos\beta \cos\Phi]
\end{eqnarray}

\subsection{ Orientation of the Incident Beam in the Target Frame}

Under some circumstances, one may wish to specify the target
orientation such that $\hat{\bf x}_\LF$ (the direction of propagation of
the radiation) and $\hat{\bf y}_\LF$ (usually the first polarization
direction) and $\hat{\bf z}_\LF$ (= $\hat{\bf x}_\LF \times \hat{\bf y}_\LF$)
refer to certain directions in the TF.  Given the definitions of
the LF and TF above, this is simply an exercise in coordinate
transformation.  For example, one might wish to have the incident
radiation propagating along the (1,1,1) direction in the TF (example
14 below).  Here we provide some selected examples:
\begin{enumerate}
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_3$ :
	$\Theta=  0$, $\Phi+\beta=  0$
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_2$ :
	$\Theta=  0$, $\Phi+\beta= 90^\circ$
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_3$ :
	$\Theta= 90^\circ$, $\beta=180^\circ$, $\Phi=  0$
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_1$ :
	$\Theta= 90^\circ$, $\beta=180^\circ$, $\Phi= 90^\circ$
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_2$ :
	$\Theta= 90^\circ$, $\beta=-90^\circ$, $\Phi=  0$
\item$\hat{\bf x}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_1$ :
	$\Theta= 90^\circ$, $\beta=-90^\circ$, $\Phi=-90^\circ$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_1$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_3$ :
	$\Theta=180^\circ$, $\beta+\Phi=180^\circ$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_1$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_2$ :
	$\Theta=180^\circ$, $\beta+\Phi= 90^\circ$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_2$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_3$ :
	$\Theta= 90^\circ$, $\beta=  0$, $\Phi=  0$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_2$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_3$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_1$ :
	$\Theta= 90^\circ$, $\beta=  0$, $\Phi=-90^\circ$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_3$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_1$,
     $\hat{\bf z}_\LF=-{\hat{\bf a}}_2$ :
	$\Theta= 90^\circ$, $\beta=-90^\circ$, $\Phi=  0$
\item$\hat{\bf x}_\LF=-{\hat{\bf a}}_3$,
     $\hat{\bf y}_\LF= {\hat{\bf a}}_2$,
     $\hat{\bf z}_\LF= {\hat{\bf a}}_1$ :
	$\Theta= 90^\circ$, $\beta=-90^\circ$, $\Phi= 90^\circ$
\item$\hat{\bf x}_\LF=({\hat{\bf a}}_1+{\hat{\bf a}}_2)/\surd2$,
     $\hat{\bf y}_\LF={\hat{\bf a}}_3$,
     $\hat{\bf z}_\LF=({\hat{\bf a}}_1-{\hat{\bf a}}_2)/\surd2$ :
	$\Theta=45^\circ$, $\beta=180^\circ$, $\Phi=90^\circ$
\item$\hat{\bf x}_\LF=({\hat{\bf a}}_1+{\hat{\bf a}}_2+{\hat{\bf a}}_3)/\surd3$,
	$\hat{\bf y}_\LF=({\hat{\bf a}}_1-{\hat{\bf a}}_2)/\surd2$,
	$\hat{\bf z}_\LF=({\hat{\bf a}}_1+{\hat{\bf a}}_2-2{\hat{\bf a}}_3)/\surd6$ :\\
	$\Theta=54.7356^\circ$, $\beta=135^\circ$, $\Phi=30^\circ$.
\end{enumerate}

\subsection{ Sampling in $\Theta$, $\Phi$, and $\beta$\label{subsec:sampling}}
\index{orientational sampling in $\beta$, $\Theta$, and $\Phi$}
\index{ddscat.par -- BETAMI,BETAMX,NBETA}
\index{ddscat.par -- THETMI,THETMX,NTHETA}
\index{ddscat.par -- PHIMIN,PHIMAX,NPHI}
The present version, {\bf DDSCAT \vers}, chooses the angles $\beta$,
$\Theta$, and $\Phi$ to sample the intervals ({\tt BETAMI,BETAMX}),
({\tt THETMI,THETMX)}, ({\tt PHIMIN,PHIMAX}), where {\tt BETAMI}, {\tt
BETAMX}, {\tt THETMI}, {\tt THETMX}, {\tt PHIMIN}, {\tt PHIMAX} are
specified in {\tt ddscat.par} .  The prescription for choosing the
angles is to:
\begin{itemize}
\item uniformly sample in $\beta$;
\item uniformly sample in $\Phi$;
\item uniformly sample in $\cos\Theta$.
\end{itemize}
This prescription is appropriate for random orientation of the target,
within the specified limits of $\beta$, $\Phi$, and $\Theta$.

Note that when {\bf DDSCAT \vers}\ chooses angles it handles $\beta$ and
$\Phi$ differently from $\Theta$.
The range for $\beta$ is divided into {\tt NBETA} intervals, and the
midpoint of each interval is taken.  Thus, if you take {\tt
BETAMI}=0, {\tt BETAMX}=90, {\tt NBETA}=2 you will get
$\beta=22.5^\circ$ and $67.5^\circ$.  Similarly, if you take
{\tt PHIMIN}=0, {\tt PHIMAX}=180, {\tt NPHI}=2 you will get
$\Phi=45^\circ$ and $135^\circ$.

Sampling in $\Theta$ is done quite differently from sampling in
$\beta$ and $\Phi$.  First, as already mentioned above, {\bf DDSCAT \vers}\
samples uniformly in $\cos\Theta$, not $\Theta$.
Secondly, the sampling depends on whether {\tt NTHETA} is even or odd.
\begin{itemize}
\item If {\tt NTHETA} is odd, then the values of $\Theta$ selected
	include the extreme values {\tt THETMI} and {\tt THETMX}; thus,
        {\tt THETMI}=0, {\tt THETMX}=90, {\tt NTHETA}=3 will give you
	$\Theta=0,60^\circ,90^\circ$.
\item If {\tt NTHETA} is even, then the range of $\cos\Theta$ will be
	divided into {\tt NTHETA} intervals, and the midpoint of each interval
	will be taken; thus, {\tt THETMI}=0, {\tt THETMX}=90, {\tt NTHETA}=2
	will give you $\Theta=41.41^\circ$ and $75.52^\circ$
	[$\cos\Theta=0.25$ and $0.75$].
\end{itemize}
The reason for this is that if odd {\tt NTHETA} is specified, then the
``integration'' over $\cos\Theta$ is performed using Simpson's rule
for greater accuracy.  If even {\tt NTHETA} is specified, then the
integration over $\cos\Theta$ is performed by simply taking the
average of the results for the different $\Theta$ values.

If averaging over orientations is desired, it is recommended that the
user specify an {\it odd} value of {\tt NTHETA} so that Simpson's rule
will be employed.

\section{Orientational Averaging\label{sec:orientational_averaging}}
\index{orientational averaging}

{{\bf DDSCAT}} has been constructed to facilitate the computation of
orientational averages.  How to go about this depends on the
distribution of orientations which is applicable.

\subsection{ Randomly-Oriented Targets}
\index{orientational averaging!randomly-oriented targets}
For randomly-oriented targets, we wish to compute the orientational
average of a quantity $Q(\beta,\Theta,\Phi)$:
\begin{equation}
\langle Q \rangle = {1\over 8\pi^2}\int_0^{2\pi}d\beta
\int_{-1}^1 d\cos\Theta
\int_0^{2\pi}d\Phi ~ Q(\beta,\Theta,\Phi) ~~~.
\end{equation}
To compute such averages, all you need to do is edit the file {\tt
ddscat.par} so that DDSCAT knows what ranges of the angles $\beta$,
$\Theta$, and $\Phi$ are of interest.  For a randomly-oriented target
with no symmetry, you would need to let $\beta$ run from 0 to
$360^\circ$, $\Theta$ from 0 to $180^\circ$, and $\Phi$ from 0 to
$360^\circ$.

For targets with symmetry, on the other hand, the ranges of $\beta$,
$\Theta$, and $\Phi$ may be reduced.  First of all, remember that
averaging over $\Phi$ is relatively ``inexpensive", so when in doubt
average over 0 to $360^\circ$; most of the computational ``cost" is
associated with the number of different values of ($\beta$,$\Theta$)
which are used.  Consider a cube, for example, with axis ${\hat{\bf
a}}_1$ normal to one of the cube faces; for this cube $\beta$ need run
only from 0 to $90^\circ$, since the cube has fourfold symmetry for
rotations around the axis ${\hat{\bf a}}_1$.  Furthermore, the angle
$\Theta$ need run only from 0 to $90^\circ$, since the orientation
($\beta$,$\Theta$,$\Phi$) is indistinguishable from ($\beta$,
$180^\circ-\Theta$, $360^\circ-\Phi$).

For targets with symmetry, the user is encouraged to test the
significance of $\beta$,$\Theta$,$\Phi$ on targets with small numbers
of dipoles (say, of the order of 100 or so) but having the desired
symmetry.

\subsection{ Nonrandomly-Oriented Targets}
\index{orientational averaging!nonrandomly-oriented targets}

Some special cases (where the target orientation distribution is
uniform for rotations around the $x$ axis = direction of propagation
of the incident radiation), one may be able to use {\bf DDSCAT \vers}\
with appropriate choices of input parameters.  More generally,
however, you will need to modify subroutine {\tt ORIENT} to generate a
list of {\tt NBETA} values of $\beta$, {\tt NTHETA} values of
$\Theta$, and {\tt NPHI} values of $\Phi$, plus two weighting arrays
{\tt WGTA(1-NTHETA,1-NPHI)} and {\tt WGTB(1-NBETA)}.  Here {\tt WGTA}
gives the weights which should be attached to each ($\Theta$,$\Phi$)
orientation, and {\tt WGTB} gives the weight to be attached to each
$\beta$ orientation.  Thus each orientation of the target is to be
weighted by the factor {\tt WGTA}$\times${\tt WGTB}.  For the case of
random orientations, {\bf DDSCAT}\ chooses $\Theta$ values which
are uniformly spaced in $\cos\Theta$, and $\beta$ and $\Phi$ values
which are uniformly spaced, and therefore uses uniform
weights\hfill\break \indent\indent {\tt WGTB}=1./{\tt
NBETA}\hfill\break

\noindent When {\tt NTHETA} is even, {{\bf DDSCAT}}\ sets\hfill\break
\indent\indent {\tt WGTA}=1./({\tt NTHETA}$\times${\tt
NPHI})\hfill\break

\noindent but when {\tt NTHETA} is odd, {{\bf DDSCAT}}\ uses Simpson's
rule when integrating over $\Theta$ and \hfill\break \indent\indent
{\tt WGTA}= (1/3 or 4/3 or 2/3)/({\tt NTHETA}$\times${\tt NPHI})

Note that the program structure of {{\bf DDSCAT}}\ may not be ideally
suited for certain highly oriented cases.  If, for example, the
orientation is such that for a given $\Phi$ value only one $\Theta$
value is possible (this situation might describe ice needles oriented
with the long axis perpendicular to the vertical in the Earth's
atmosphere, illuminated by the Sun at other than the zenith) then it
is foolish to consider all the combinations of $\Theta$ and $\Phi$
which the present version of {{\bf DDSCAT}}\ is set up to do.  We hope
to improve this in a future version of {{\bf DDSCAT}}.

\section{Target Generation: Isolated Finite Targets
         \label{sec:target_generation}}
\index{target generation}
DDSCAT contains routines to generate dipole arrays representing finite
targets of various geometries, including spheres, ellipsoids,
rectangular solids, cylinders, hexagonal prisms, tetrahedra, two
touching ellipsoids, and three touching ellipsoids.  The target type
is specified by variable {\tt CSHAPE} on line 9 of {\tt ddscat.par},
up to 12 target shape parameters ({\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt
SHPAR}$_3$, ...) on line 10.
\index{ddscat.par!CSHAPE}
\index{ddscat.par!SHPAR$_1$,SHPAR$_2$,...}
The target geometry is most conveniently described in a
coordinate system attached to the target which we refer to as the
``Target Frame'' (TF), with orthonormal
unit vectors $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF\equiv\hat{\bf x}_\TF\times\hat{\bf y}_\TF$.
Once the target is generated, the
orientation of the target in the Lab Frame is accomplished as
described in \S\ref{sec:target_orientation}.

Every target generation routine will specify
\begin{itemize}
\item The ``occupied'' lattice sites;
\item The composition associated with each occupied lattice site;
\item Two ``target
axes'' $\hat{\bf a}_1$ and $\hat{\bf a}_2$ that are used as references when specifying
the target orientation; and
\item The location of the Target Frame origin of coordinates.
\end{itemize}

Target geometries currently supported include
\index{target shape options!FROM\_FILE}
\subsection{ FROM\_FILE = Target composed of possibly anisotropic material,
            defined by list of dipole locations and ``compositions''
	    obtained from a file
            \label{sec:FROM_FILE}}
        If anisotropic, the ``microcrystals'' in the target are assumed
	to be aligned with the principal axes of the dielectric tensor
	parallel to $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, and $\hat{\bf z}_\TF$.
        This option causes {{\bf DDSCAT}} to read the target geometry
	and composition information from a file {\tt shape.dat}
	instead of automatically generating one of the geometries for
	which DDSCAT has built-in target generation capability.
	The {\tt shape.dat} file is read by routine {\tt REASHP}
	(file {\tt reashp.f90}).
	The file {\tt shape.dat} gives the number $N$ of dipoles in the
	target, the components of the
	``target axes'' $\hat{\bf a}_1$ and $\hat{\bf a}_2$ in
	the Target Frame (TF), the vector $x_0(1-3)$ determining the
	correspondence between the integers {\tt IXYZ} and
	actual coordinates in the TF, and specifications for the
	location and ``composition'' of each dipole.
	The user can customize {\tt REASHP} as needed to conform to the
	manner in which the target description is stored in file
	{\tt shape.dat}.
	However, as supplied, {\tt REASHP} expects the file {\tt shape.dat}
	to have the following structure:
	\begin{itemize}
	  \item one line containing a description; the first 67 characters will
	        be read and printed in various output statements
	  \item {\tt N} = number of dipoles in target
	  \item $a_{1x}$ $a_{1y}$ $a_{1z}$ = x,y,z components (in TF)
	    of $\bf{a}_1$
	\item $a_{2x}$ $a_{2y}$ $a_{2z}$ = x,y,z components (in TF)
	    of $\bf{a}_2$
        \item $d_x/d$ ~$d_y/d$ ~$d_z/d$ = 1. 1. 1. = relative spacing of
              dipoles in $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$ directions
	\item $x_{0x}$ ~$x_{0y}$ ~$x_{0z}$ = TF coordinates
              $x_{\rm TF}/d$ ~$y_{\rm TF}/d$ ~$z_{\rm TF}/d$ corresponding to
	      lattice site {\tt IXYZ}= 0 0 0
	\item (line containing comments)
	\item {\footnotesize
	      $dummy$ {\tt IXYZ(1,1) IXYZ(1,2) IXYZ(1,3)
		ICOMP(1,1) ICOMP(1,2) ICOMP(1,3)}
              }
	\item {\footnotesize
	      $dummy$ {\tt IXYZ(2,1) IXYZ(2,2) IXYZ(2,3)
		ICOMP(2,1) ICOMP(2,2) ICOMP(2,3)}
              }
	\item {\footnotesize
              $dummy$ {\tt IXYZ(3,1) IXYZ(3,2) IXYZ(3,3)
		ICOMP(3,1) ICOMP(3,2) ICOMP(3,3)}
              }
	\item ...
	\item {\footnotesize
              $dummy$ {\tt IXYZ(J,1) IXYZ(J,2) IXYZ(J,3)
		ICOMP(J,1) ICOMP(J,2) ICOMP(J,3)}
              }
	\item ...
	\item {\footnotesize
              $dummy$ {\tt IXYZ(N,1) IXYZ(N,2) IXYZ(N,3)
		ICOMP(N,1) ICOMP(N,2) ICOMP(N,3)}
              }
	\end{itemize}
	where $dummy$ is a number (integer or floating point)that might,
        for example, identify the dipole.  This number will {\it not}
        be used in any calculations.\\
	If the target material at location {\tt J} is isotropic,
	{\tt ICOMP(J,1)}, {\tt ICOMP(J,2)}, and
	{\tt ICOMP(J,3)} have the same value.

{\footnotesize
\begin{verbatim}
--- demo file for target option FROM_FILE (homogeneous,isotropic target) ---
8       = NAT
1.000   0.000   0.000   = target vector a1 (in TF)
0.000   1.000   0.000   = target vector a2 (in TF)
1.      1.      1.      = d_x/d  d_y/d  d_z/d  (normally 1 1 1)
0.5     0.5     0.5      = X0(1-3) = location in lattice of "target origin"
J    JX   JY   JZ  ICOMPX,ICOMPY,ICOMPZ
1     0    0    0   1  1  1
2     0    0    1   1  1  1
3     0    1    0   1  1  1
4     0    1    1   1  1  1
5     1    0    0   1  1  1
6     1    0    1   1  1  1
7     1    1    0   1  1  1
8     1    1    1   1  1  1
\end{verbatim}}

\noindent The above sample target consists of 8 dipoles arranged to represent a cube.\\
This example is homogeneous: All sites have composition 1\\
The target origin {\tt X0} is set to be at the center of the target\\
Note that ICOMPX,ICOMPY,ICOMPZ could differ, allowing treatment
of anisotropic targets, provided the dielectric tensor at each location
is diagonal in the TF.

{\footnotesize
\begin{verbatim}
--- demo file for target option FROM_FILE (inhomogeneous, isotropic target) ---
8       = NAT
1.000   0.000   0.000   = target vector a1 (in TF)
0.000   1.000   0.000   = target vector a2 (in TF)
1.      1.      1.      = d_x/d  d_y/d  d_z/d  (normally 1 1 1)
0.5     0.5     0.5      = X0(1-3) = location in lattice of "target origin"
J    JX   JY   JZ  ICOMPX,ICOMPY,ICOMPZ
1     0    0    0   1  1  1
2     0    0    1   1  1  1
3     0    1    0   1  1  1
4     0    1    1   1  1  1
5     1    0    0   2  2  2
6     1    0    1   2  2  2
7     1    1    0   2  2  2
8     1    1    1   2  2  2
\end{verbatim}}

\noindent This sample target consists of 8 dipoles
arranged to represent a cube.\\
This example is inhomogeneous: The lower half of the cube (JX=0) has isotropic
composition 1\\
The upper half of the cube (JX=1) has isotropic composition 2\\
The target origin {\tt X0} is set to be at the center of the target.\\
Note that ICOMPX, ICOMPY, ICOMPZ can be different, allowing treatment
of anisotropic targets, provided the dielectric tensor at each location
is diagonal in the TF.

{\bf Sample calculation:}
The directory {\tt examples\_exp/FROM\_FILE} contains files for calculation
of scattering by a $0.5{\mu{\rm m}}\times1{\mu{\rm m}}\times1{\mu{\rm m}}$ Au block,
represented by a $32\times64\times64$ dipole array.

\index{target shape options!ANIFRMFIL}
\subsection{ ANIFRMFIL = General anistropic target defined by list of dipole
            locations,``compositions'', and material orientations obtained
            from a file
            \label{sec:ANIFRMFIL}}
	This option causes {{\bf DDSCAT}}\ to read the target geometry
	information from a file {\tt shape.dat} instead of automatically
	generating one of the geometries listed below.
	The file {\tt shape.dat} gives the number $N$ of dipoles in the
	target, the components of the
	``target axes'' $\hat{\bf a}_1$ and $\hat{\bf a}_2$ in
	the Target Frame (TF), the vector $x_0(1-3)$ determining the
	correspondence between the integers {\tt IXYZ} and
	actual coordinates in the TF, and specifications for the
	location and ``composition'' of each dipole.
	For each dipole $J$, the file {\tt shape.dat} provides  the location
	{\tt IXYZ($J$,1-3)}, the composition identifier integer
	{\tt ICOMP($J$,1-3)} specifying the
	dielectric function corresponding to the three principal axes of
	the dielectric tensor, and angles $\Theta_{\rm DF}$,
	$\Phi_{\rm DF}$, and $\beta_{\rm DF}$ specifying the orientation of the
	local
	\index{Dielectric Frame (DF)}
	``Dielectric Frame'' (DF) relative to the ``Target Frame'' (TF)
	(see \S\ref{sec:composite anisotropic targets}).
	The DF is the reference frame in which the dielectric tensor is
	diagonalized.
	The Target Frame is the reference frame in which we specify the
	dipole locations.

	The {\tt shape.dat}
	file is read by routine {\tt REASHP} (file {\tt reashp.f90}).
	The user can customize {\tt REASHP} as needed to conform to the
	manner in which the target geometry is stored in file {\tt shape.dat}.
	However, as supplied, {\tt REASHP} expects the file {\tt shape.dat}
	to have the following structure:
	\begin{itemize}
	\item one line containing a description; the first 67 characters will
		be read and printed in various output statements.
	\item {\tt N} = number of dipoles in target
	\item $a_{1x}$ $a_{1y}$ $a_{1z}$ = x,y,z components (in Target Frame)
	of $\bf{a}_1$
	\item $a_{2x}$ $a_{2y}$ $a_{2z}$ = x,y,z components (in Target Frame)
	of $\bf{a}_2$
        \item $d_x/d$ ~$d_y/d$ ~$d_z/d$ = 1. 1. 1. = relative spacing of
              dipoles in $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$ directions
	\item $x_{0x}$~ $x_{0y}$~ $x_{0z}$ = TF coordinates
              $x_{\rm TF}/d$~ $y_{\rm TF}/d$~ $z_{\rm TF}/d$ corresponding to
	      lattice site {\tt IXYZ}= 0 0 0
	\item (line containing comments)
	\item {\footnotesize
	      $dummy$ {\tt IXYZ(1,1-3)
		ICOMP(1,1-3)
	        THETADF(1) PHIDF(1) BETADF(1)}}
	\item {\footnotesize
	      $dummy$ {\tt IXYZ(2,1-3)
		ICOMP(2,1-3)
	        THETADF(2) PHIDF(2) BETADF(2)}}
	\item {\footnotesize
              $dummy$ {\tt IXYZ(3,1-3)
		ICOMP(3,1-3)
                THETADF(3) PHIDF(3) BETADF(3)}}
	\item ...
	\item {\footnotesize
              $dummy$ {\tt IXYZ(J,1-3)
		ICOMP(J,1-3)
                THETADF(J) PHIDF(J) BETADF(J)}}
	\item ...
	\item {\footnotesize
              $dummy$ {\tt IXYZ(N,1-3)
		ICOMP(N,1-3)
                THETADF(N) PHIDF(N) BETADF(N)}}
	\end{itemize}
	Where $dummy$ is a number (either integer or floating point) that
        might, for example, give the number identifying the dipole.  This
        number will {\it not} be used in any calculations.\\
	{\tt THETADF PHIDF BETADF} should be given in {\bf radians}.\\

        Here is an example of the first few lines of a target description
        file suitable for target option {\tt ANIFRMFIL}:

{\footnotesize
\begin{verbatim}
--- demo file for target option ANIFRMFIL (this line is for comments) ---
8       = NAT
1.000   0.000   0.000   = target vector a1 (in TF)
0.000   1.000   0.000   = target vector a2 (in TF)
1.      1.      1.      = d_x/d  d_y/d  d_z/d  (normally 1 1 1)
0.      0.      0.      = X0(1-3) = location in lattice of "target origin"
J    JX   JY   JZ  ICOMP(J,1-3) THETADF PHIDF BETADF
1     0    0    0   1  1  1    0.     0.      0.
2     0    0    1   1  1  1    0.     0.      0.
3     0    1    0   1  1  1    0.     0.      0.
4     0    1    1   1  1  1    0.     0.      0.
5     1    0    0   2  3  3    0.5236 1.5708  0.
6     1    0    1   2  3  3    0.5236 1.5708  0.
7     1    1    0   2  3  3    0.5236 1.5708  0.
8     1    1    1   2  3  3    0.5236 1.5708  0.
\end{verbatim}}

This sample target consists of 8 dipoles arranged to represent a cube.\\
Half of the cube (dipoles with JX=0) has isotropic composition 1.
For this case,
the angles THETADF, PHIDF, BETADF do not matter, and it convenient to
set them all to zero.\\
The other half of the cube (dipoles with JX=1)
consists of a uniaxial material, with dielectric
function 2 for E fields parallel to one axis (the ``c-axis''),
and dielectric function 3 for E fields perpendicular
to the c-axis≈. The c-axis is
$30^o$ (0.5236 radians) away from $\hat{\bf x}_\TF$,
and lies in the $\hat{\bf x}_\TF$-$\hat{\bf z}_\TF$ plane (having been
rotated by 1.5708 radians around $\hat{\bf x}_\TF$).\\
Note that ICOMP(J,K) can be different for K=1,3, allowing treatment
of anisotropic targets, provided the dielectric tensor at each location
is diagonal in the TF.

\index{target shape options!ANIELLIPS}
\subsection{ ANIELLIPS =  Homogeneous, anisotropic ellipsoid.
         \label{sec:ANIELLIPS}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$},
	{\tt SHPAR}$_3$ define the ellipsoidal boundary:
\begin{equation}
	\left(\frac{x_{\rm TF}/d}{{\tt SHPAR}_1}\right)^2+
        \left(\frac{y_{\rm TF}/d}{{\tt SHPAR}_2}\right)^2+
        \left(\frac{z_{\rm TF}/d}{{\tt SHPAR}_3}\right)^2 = \frac{1}{4}
        ~~~,
\end{equation}
The TF origin is located at the centroid of the ellipsoid.
\index{target shape options!ANI\_ELL\_2}
\subsection{ ANI\_ELL\_2 = Two touching, homogeneous, anisotropic
	    ellipsoids, with distinct compositions
            \label{sec:ANI_ELL_2}}
	Geometry as for {\tt ELLIPSO\_2};
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt SHPAR}$_3$
        have same meanings as for {\tt ELLIPSO\_2}.
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	Line connecting ellipsoid centers is
	$\parallel \hat{\bf a}_1 = \hat{\bf x}_\TF$.\\
	TF origin is located between ellipsoids, at point of contact.\\
	It is assumed that (for both ellipsoids) the dielectric tensor
	is diagonal in the TF.
	User must set {\tt NCOMP}=6 and provide
	$xx$, $yy$, $zz$ components of dielectric tensor for
	first ellipsoid, and $xx$, $yy$, $zz$ components of
	dielectric tensor for second
	ellipsoid (ellipsoids are in order of increasing $x_{\rm TF}$).
\index{target shape options!ANI\_ELL\_3}
\subsection{ ANI\_ELL\_3 = Three touching homogeneous, anisotropic ellipsoids
	    with same size and orientation but distinct dielectric tensors
            \label{sec:ANI_ELL_3}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt SHPAR}$_3$
        have same meanings as for {\tt ELLIPSO\_3}.\\
	Target axis ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	(along line of ellipsoid centers), and
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	TF origin is located at center of middle ellipsoid.\\
	It is assumed that dielectric tensors
	are all diagonal in the TF.
	User must set {\tt NCOMP}=9 and provide $xx$, $yy$, $zz$
	elements of dielectric tensor
	for first ellipsoid, $xx$, $yy$, $zz$ elements for second ellipsoid,
	and $xx$, $yy$, $zz$ elements for third ellipsoid
	(ellipsoids are in order of increasing $x_{\rm TF}$).
\index{target shape options!ANIRCTNGL}
\subsection{ ANIRCTNGL = Homogeneous, anisotropic, rectangular solid
            \label{sec:ANIRCTNGL}}
	x, y, z lengths/$d$ = {\tt SHPAR$_1$}, {\tt SHPAR$_2$},
        {\tt SHPAR}$_3$.\\
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$
	in the TF. \\
        $(x_{\rm TF},y_{\rm TF},z_{\rm TF})=(0,0,0)$ at middle of upper target surface,
	(where ``up'' = $\hat{\bf x}_\TF$).  (The target surface is taken to be $d/2$
	about the upper dipole layer.)\\
	Dielectric tensor is assumed to be diagonal in the target frame.\\
	User must set {\tt NCOMP}=3 and
	supply names of three files for $\epsilon$ as a function
	of wavelength or energy: first for $\epsilon_{xx}$,
	second for $\epsilon_{yy}$, and third for $\epsilon_{zz}$,
	as in the following sample {\tt ddscat.par} file:
	{\scriptsize
\begin{verbatim}
' ============ Parameter file for v7.1.0 ==================='
'**** PRELIMINARIES ****'
'NOTORQ'= CMTORQ*6 (DOTORQ, NOTORQ) -- either do or skip torque calculations
'PBCGS2'= CMDSOL*6 (PBCGS2, PBCGST, PETRKP) -- select solution method
'GPFAFT'= CMETHD*6 (GPFAFT, FFTMKL)
'GKDLDR'= CALPHA*6 (GKDLDR, LATTDR)
'NOTBIN'= CBINFLAG (ALLBIN, ORIBIN, NOTBIN)
'ANIRCTNGL'= CSHAPE*9 shape directive
'**** Initial Memory Allocation ****'
10 25 50 = upper bound on target extent
'**** Target Geometry and Composition ****'
'ANIRCTNGL'= CSHAPE*9 shape directive
10 25 50 = shape parameters SHPAR1, SHPAR2, SHPAR3
3         = NCOMP = number of dielectric materials
'/u/draine/DDA/diel/m2.00_0.10' = name of file containing dielectric function
'/u/draine/DDA/diel/m1.50_0.00'
'/u/draine/DDA/diel/m1.50_0.00'
'**** Error Tolerance ****'
1.00e-5 = TOL = MAX ALLOWED (NORM OF |G>=AC|E>-ACA|X>)/(NORM OF AC|E>)
'**** Interaction cutoff parameter for PBC calculations ****'
5.00e-3 = GAMMA (1e-2 is normal, 3e-3 for greater accuracy)
'**** Angular resolution for calculation of <cos>, etc. ****'
2.0     = ETASCA (number of angles is proportional to [(2+x)/ETASCA]^2 )
'**** Wavelengths (micron) ****'
500. 500. 1 'INV' = wavelengths (first,last,how many,how=LIN,INV,LOG)
'**** Effective Radii (micron) **** '
30.60 30.60 1  'LIN' = eff. radii (first, last, how many, how=LIN,INV,LOG)
'**** Define Incident Polarizations ****'
(0,0) (1.,0.) (0.,0.) = Polarization state e01 (k along x axis)
2 = IORTH  (=1 to do only pol. state e01; =2 to also do orth. pol. state)
'**** Specify which output files to write ****'
1 = IWRKSC (=0 to suppress, =1 to write ".sca" file for each target orient.
1 = IWRPOL (=0 to suppress, =1 to write ".pol" file for each (BETA,THETA)
'**** Prescribe Target Rotations ****'
 0.   0.  1  = BETAMI, BETAMX, NBETA (beta=rotation around a1)
 0.  90.  3  = THETMI, THETMX, NTHETA (theta=angle between a1 and k)
 0.   0.  1  = PHIMIN, PHIMAX, NPHI (phi=rotation angle of a1 around k)
'**** Specify first IWAV, IRAD, IORI (normally 0 0 0) ****'
0   0   0    = first IWAV, first IRAD, first IORI (0 0 0 to begin fresh)
'**** Select Elements of S_ij Matrix to Print ****'
6       = NSMELTS = number of elements of S_ij to print (not more than 9)
11 12 21 22 31 41       = indices ij of elements to print
'**** Specify Scattered Directions ****'
'LFRAME' = CMDFRM*6 ('LFRAME' or 'TFRAME' for Lab Frame or Target Frame)
2 = number of scattering planes
0.  0. 180. 30 = phi, thetan_min, thetan_max, dtheta (in degrees) for plane A
90. 0. 180. 30 = phi, ... for plane B
\end{verbatim}
}
\index{target shape options!CONELLIPS}
\subsection{ CONELLIPS = Two concentric ellipsoids
            \label{sec:CONELLIPS}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$},
	{\tt SHPAR}$_3$ = lengths/$d$ of the {\it outer} ellipsoid
        along the $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$ axes;\\
	{\tt SHPAR}$_4$, {\tt SHPAR}$_5$, {\tt SHPAR}$_6$
	= lengths/$d$ of the
	{\it inner} ellipsoid along the $\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$ axes.\\
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$,
                    ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	TF origin is located at centroids of ellipsoids.\\
	The ``core" within the inner ellipsoid is composed of isotropic
	material 1;
	the ``mantle" between inner and outer
	ellipsoids is composed of isotropic material 2.\\
	User must set {\tt NCOMP}=2 and provide dielectric functions for
	``core'' and ``mantle'' materials.
\index{target shape options!CYLINDER1}
\subsection{ CYLINDER1 = Homogeneous, isotropic finite cylinder
            \label{sec:CYLINDER1}}
	{\tt SHPAR$_1$} = length/$d$,
	{\tt SHPAR$_2$} = diameter/$d$, with\\
	{\tt SHPAR}$_3$ = 1 for cylinder axis
        $\hat{\bf a}_1\parallel \hat{\bf x}_\TF$:
	$\hat{\bf a}_1=(1,0,0)_{\rm TF}$
	            and $\hat{\bf a}_2=(0,1,0)_{\rm TF}$;\\
	{\tt SHPAR}$_3$ = 2 for cylinder axis
        $\hat{\bf a}_1\parallel \hat{\bf y}_\TF$:
        $\hat{\bf a}_1=(0,1,0)_{\rm TF}$
	            and $\hat{\bf a}_2=(0,0,1)_{\rm TF}$;\\
	{\tt SHPAR}$_3$ = 3 for cylinder axis
        $\hat{\bf a}_1\parallel \hat{\bf z}_\TF$:
	$\hat{\bf a}_1=(0,0,1)_{\rm TF}$
	            and $\hat{\bf a}_2=(1,0,0)_{\rm TF}$ in the TF.\\
	TF origin is located at centroid of cylinder.\\
	User must set {\tt NCOMP}=1.
\index{target shape options!CYLNDRCAP}
\subsection{ CYLNDRCAP = Homogeneous, isotropic finite cylinder with
            hemispherical endcaps.
            \label{sec:CYLNDRCAP}}
	{\tt SHPAR$_1$} = cylinder length/$d$
	({\it not} including end-caps!) and
	{\tt SHPAR$_2$} = cylinder diameter/$d$,
	with cylinder axis
	$={\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.
	The total length along the target axis (including the endcaps) is
	({\tt SHPAR$_1$}+{\tt SHPAR$_2$})$d$. \\
	TF origin is located at centroid of cylinder.\\
	User must set {\tt NCOMP}=1.
\index{target shape options!DSKRCTNGL}
\subsection{ DSKRCTNGL = Disk on top of a homogeneous rectangular slab
            \label{sec:DSKRCTNGL}}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a disk of composition 1
	    resting on top of a rectangular block of composition 2.
	    Materials 1 and 2 are assumed to be homogeneous and isotropic.\\
	    {\tt ddscat.par} should set {\tt NCOMP} to 2 .
	    \ \\
	    The cylindrical disk has thickness {\tt SHPAR$_1$}$\times d$ in the
	    x-direction, and diameter {\tt SHPAR$_2$}$\times d$.
	    The rectangular block is assumed to have thickness
	    {\tt SHPAR}$_3$$\times$d in the x-direction, length
	    {\tt SHPAR}$_4$$\times d$ in the y-direction,
	    and length {\tt SHPAR}$_5$$\times d$ in the z-direction.
	    The lower surface of the cylindrical disk is in the $x=0$ plane.
	    The upper surface of the slab is also in the $x=0$ plane.

	    The Target Frame origin (0,0,0) is located where the symmetry
	    axis of the disk intersects the $x=0$ plane (the upper surface
	    of the slab, and the lower surface of the disk).
	    In the Target Frame,
	    dipoles representing the rectangular block are located at
	    $(x/d,y/d,z/d)=(j_x+0.5,j_y+\Delta_y,j_z+\Delta_z)$, where
	    $j_x$, $j_y$, and $j_z$ are integers. $\Delta_y=0$ or 0.5
	    depending on whether {\tt SHPAR}$_4$ is even or odd.
	    $\Delta_z=0$ or 0.5 depending on whether {\tt SHPAR}$_5$ is
	    even or odd.

            Dipoles representing the disk are located at\\
	    \hspace*{1.0cm}$x/d = 0.5 , 1.5 ,...,
	    [{\rm int}({\tt SHPAR}_4+0.5)-0.5]$

	    As always, the physical size of the target is fixed by
	    specifying the value of the effective radius
	    ${a}_{\rm eff}\equiv(3V_{\rm T}/4\pi)^{1/3}$,
	    where $V_{\rm T}$
	    is the total volume of solid material in the target.
	    For this geometry, the number of dipoles in the target will
	    be approximately
	    $N=[{\tt SHPAR}_1\times{\tt SHPAR}_2\times{\tt SHPAR}_3 +
	    (\pi/4)(({\tt SHPAR}_4)^2\times{\tt SHPAR}_5)]$,
	    although the exact number may differ because of the
	    dipoles are required to be located on a rectangular lattice.
	    The dipole spacing $d$ in physical units
	    is determined from the specified value of ${a}_{\rm eff}$ and
	    the number $N$ of dipoles in the target:
	    $d=(4\pi/3N)^{1/3}{a}_{\rm eff}$.
	    This option requires 5 shape parameters:\newline
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR1 SHPAR$_2$ SHPAR3 SHPAR4 SHPAR}$_5$\\
	    \ \\
	where\\
	{\tt SHPAR$_1$} = [disk thickness (in $\hat{\bf x}_\TF$ direction)]/$d$
        [material 1]\\
	{\tt SHPAR$_2$} = (disk diameter)/$d$\\
	{\tt SHPAR}$_3$ = (brick thickness in $\hat{\bf x}_\TF$ direction)/$d$
	[material 2]\\
	{\tt SHPAR}$_4$ = (brick thickness in $\hat{\bf y}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_5$ = (brick thickness in $\hat{\bf z}_\TF$ direction)/$d$\\
	\ \\
	The overall size of the target (in terms of numbers of
	dipoles) is determined by parameters
	{\tt (SHPAR1+SHPAR4), SHPAR$_2$}, and {\tt SHPAR}$_3$.
	The periodicity in the TF $y$ and $z$ directions is determined
	by parameters {\tt SHPAR}$_4$ and {\tt SHPAR}$_5$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.

	The ``computational volume'' is determined by
	({\tt SHPAR$_1$+SHPAR}$_4$)$\times${\tt SHPAR$_2$}$\times${\tt SHPAR}$_3$.

	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = \hat{\bf x}_\TF = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = \hat{\bf y}_\TF= (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles  $\Theta$, $\Phi$, and $\beta$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

\index{target shape options!DW1996TAR}
\subsection{ DW1996TAR = 13 block target used by Draine \& Weingartner (1996).
            \label{sec:DW199TAR}}
	Single, isotropic material.
	Target geometry was used in study by Draine \& Weingartner (1996)
	of radiative torques on irregular grains.
	${\hat{\bf a}}_1$ and ${\hat{\bf a}}_2$
	are principal axes with largest and
	second-largest moments of inertia.
	User must set {\tt NCOMP=1}.
	Target size is controlled by shape parameter {\tt SHPAR(1)} =
	width of one block in lattice units.\\
	TF origin is located at centroid of target.
\index{ELLIPSOID}
\index{target shape options!ELLIPSOID}
\subsection{ ELLIPSOID = Homogeneous, isotropic ellipsoid.
            \label{sec:ELLIPSOID}}
	``Lengths''
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$},
	{\tt SHPAR}$_3$ in the $x$, $y$, $z$ directions in the TF:
\begin{equation}
	\left(\frac{x_{\rm TF}}{{\tt SHPAR}_1 d}\right)^2+
        \left(\frac{y_{\rm TF}}{{\tt SHPAR}_2 d}\right)^2+
        \left(\frac{z_{\rm TF}}{{\tt SHPAR}_3 d}\right)^2 = \frac{1}{4}
        ~~~,
\end{equation}
	where $d$ is the interdipole spacing.\\
	The target axes are set to ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$ and
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	Target Frame origin = centroid of ellipsoid.\\
	User must set {\tt NCOMP}=1 on line 9 of {\tt ddscat.par}.\\
	A {\bf homogeneous, isotropic sphere} is obtained by setting
	{\tt SHPAR$_1$} = {\tt SHPAR$_2$} = {\tt SHPAR}$_3$ = diameter/$d$.
\index{target shape options!ELLIPSO\_2}
\subsection{ ELLIPSO\_2 = Two touching, homogeneous, isotropic ellipsoids,
	    with distinct compositions
            \label{sec:ELLIPSO_2}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$},
        {\tt SHPAR}$_3$=x-length/$d$, y-length/$d$,
	$z$-length/$d$ of one ellipsoid.
	The two ellipsoids have identical shape, size, and orientation,
	but distinct dielectric functions.
	The line connecting ellipsoid centers is along the $\hat{\bf x}_\TF$-axis.
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	[along line connecting ellipsoids]
	and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	Target Frame origin = midpoint between ellipsoids
        (where ellipsoids touch).\\
	User must set {\tt NCOMP}=2 and provide dielectric function file names
	for both ellipsoids.
	Ellipsoids are in order of increasing $x_{\rm TF}$:
	first dielectric function is for ellipsoid with
	center at negative $x_{\rm TF}$, second dielectric function for
	ellipsoid with center at positive $x_{\rm TF}$.
\index{target shape options!ELLIPSO\_3}
\subsection{ ELLIPSO\_3 = Three touching homogeneous, isotropic ellipsoids
	    of equal size and orientation, but distinct compositions
            \label{sec:ELLIPSO_3}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt SHPAR}$_3$ have same meaning
        as for {\tt ELLIPSO\_2}.
	Line connecting ellipsoid centers is parallel to $\hat{\bf x}_\TF$ axis.
	Target axis ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	(along line of ellipsoid centers), and
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	Target Frame origin = centroid of middle ellipsoid.\\
	User must set {\tt NCOMP}=3 and provide (isotropic) dielectric
	functions for first, second, and third ellipsoid.

{\bf Sample calculation:}
The directory {\tt examples\_exp/ELLIPSOID} contains {\tt ddscat.par} for
calculation of scattering by a sphere with refractive index $m=1.5+0.01i$
and
$2\pi a/\lambda=5$, represented by a $N=110592$ dipole
pseudosphere just fitting within a
$48\times48\times48$ computational volume.
\index{target shape options!HEX\_PRISM}
\subsection{ HEX\_PRISM = Homogeneous, isotropic hexagonal prism
            \label{sec:HEX_PRISM}}
	{\tt SHPAR$_1$} = (Length of prism)/$d$ = (distance between hexagonal
	faces)/$d$,\\
	{\tt SHPAR$_2$} = (distance between opposite vertices of one hexagonal
	face)/$d$ = 2$\times$hexagon side/$d$.\\
	{\tt SHPAR}$_3$ selects one of 6 orientations of the prism in the
        Target Frame (TF).\\
	Target axis ${\hat{\bf a}}_1$ is along the prism axis (i.e., normal to
	the hexagonal faces), and
	target axis ${\hat{\bf a}}_2$ is normal to one of the rectangular
	faces.  There are 6 options for {\tt SHPAR}$_3$:\\
	{\tt SHPAR}$_3$ = 1 for ${\hat{\bf a}}_1\parallel\hat{\bf x}_{\rm TF}$
         and ${\hat{\bf a}}_2\parallel\hat{\bf y}_{\rm TF}$\quad;\quad
	{\tt SHPAR}$_3$ = 2 for ${\hat{\bf a}}_1\parallel\hat{\bf x}_{\rm TF}$
        and ${\hat{\bf a}}_2\parallel\hat{\bf z}_{\rm TF}$\quad;\\
	{\tt SHPAR}$_3$ = 3 for ${\hat{\bf a}}_1\parallel\hat{\bf y}_{\rm TF}$
        and ${\hat{\bf a}}_2\parallel\hat{\bf x}_{\rm TF}$\quad;\quad
	{\tt SHPAR}$_3$ = 4 for ${\hat{\bf a}}_1\parallel\hat{\bf y}_{\rm TF}$
        and ${\hat{\bf a}}_2\parallel\hat{\bf z}_{\rm TF}$\quad;\\
	{\tt SHPAR}$_3$ = 5 for ${\hat{\bf a}}_1\parallel\hat{\bf z}_{\rm TF}$
        and ${\hat{\bf a}}_2\parallel\hat{\bf x}_{\rm TF}$\quad;\quad
	{\tt SHPAR}$_3$ = 6 for ${\hat{\bf a}}_1\parallel\hat{\bf z}_{\rm TF}$
        and ${\hat{\bf a}}_2\parallel\hat{\bf y}_{\rm TF}$\\
	TF origin is located at the centroid of the target.\\
	User must set {\tt NCOMP}=1.
\index{target shape options!LAYRDSLAB}
\subsection{ LAYRDSLAB = Multilayer rectangular slab
            \label{sec:LAYRDSLAB}}
        Multilayer rectangular slab with overall x, y, z
	lengths
	$a_x = {\tt SHPAR}_1\times d$ \\
	$a_y = {\tt SHPAR}_2\times d$,\\
	$a_z = {\tt SHPAR}_3\times d$.\\
	Upper surface is at $x_{\rm TF}=0$, lower surface at $x_{\rm TF}=-{\tt SHPAR}_1\times d$\\
	${\tt SHPAR}_4$ = fraction which is composition 1 (top layer).\\
	${\tt SHPAR}_5$ = fraction which is composition 2 (layer below top)\\
	${\tt SHPAR}_6$ = fraction which is composition 3 (layer below comp 2)\\
	$1-({\tt SHPAR}_4+{\tt SHPAR}_5+{\tt SHPAR}_6)$ = fraction which is
	composition 4 (bottom layer).\\
	To create a bilayer slab, just set
	${\tt SHPAR}_5={\tt SHPAR}_6=0$\\
	To create a trilayer slab, just set ${\tt SHPAR}_6=0$\\
	User must set {\tt NCOMP}=2,3, or 4 and provide dielectric function
	files for each of the two layers.
	Top dipole layer is at $x_{\rm TF}=-d/2$.
	Origin of TF is at center of top surface.
\index{target shape options!MLTBLOCKS}
\subsection{ MLTBLOCKS = Homogeneous target constructed from cubic ``blocks''
            \label{sec:MLTBLOCKS}}
	Number and location of blocks are specified in separate file
	{\tt blocks.par} with following structure:\\
	\hspace*{2em}one line of comments (may be blank)\\
	\hspace*{2em}{\tt PRIN} (= 0 or 1 -- see below)\\
	\hspace*{2em}{\tt N} (= number of blocks) \\
	\hspace*{2em}{\tt B}  (= width/$d$ of one block) \\
	\hspace*{2em}$x_{\rm TF}$ $y_{\rm TF}$ $z_{\rm TF}$
		(= position of 1st block in units of {\tt B}$d$)\\
	\hspace*{2em}$x_{\rm TF}$ $y_{\rm TF}$ $z_{\rm TF}$
	(= position of 2nd block in units of {\tt B}$d$) )\\
	\hspace*{2em}... \\
	\hspace*{2em}$x_{\rm TF}$ $y_{\rm TF}$ $z_{\rm TF}$
	        (= position of {\tt N}th block in units of {\tt B}$d$)\\
	If {\tt PRIN}=0, then ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$,
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.
	If {\tt PRIN}=1, then ${\hat{\bf a}}_1$ and ${\hat{\bf a}}_2$ are set
	to principal
	axes with largest and second largest moments of inertia,
	assuming target to be of uniform density.
	User must set {\tt NCOMP=1}.
\index{target shape options!RCTGLPRSM}
\subsection{ RCTGLPRSM = Homogeneous, isotropic, rectangular solid
            \label{sec:RCTGLPRSM}}
	x, y, z lengths/$d$ = {\tt SHPAR$_1$}, {\tt SHPAR$_2$},
        {\tt SHPAR}$_3$.\\
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$
	and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.\\
	TF origin at center of upper surface of solid:
	target extends from $x_{\rm TF}/d=-{\tt SHPAR}_1$ to 0,\\
	$y_{\rm TF}/d$ from $-0.5\times{\tt SHPAR_2}$ to $+0.5\times{\tt SHPAR_2}$\\
	$z_{\rm TF}/d$ from $-0.5\times{\tt SHPAR_3}$ to $+0.5\times{\tt SHPAR_3}$\\
	User must set {\tt NCOMP}=1.

The directory {\tt examples\_exp/RCTGLPRSM} contains {\tt ddscat.par} for
 calculation
of scattering by a $0.5{\mu{\rm m}}\times1{\mu{\rm m}}\times1{\mu{\rm m}}$ Au block,
represented by a $32\times64\times64$ dipole array.

\index{target shape options!RCTGLBLK3}
\subsection{ RCTGLBLK3 = Stack of 3 rectangular blocks, with centers on
            the $\hat{\bf x}_\TF$ axis.
            \label{sec:RCTBLK3}}
        Each block consists of a distinct material.  There are 9 shape
	parameters:\\
        {\tt SHPAR$_1$} = (upper solid thickness in $\hat{\bf x}_\TF$ direction)/$d$
        [material 1]\\
        {\tt SHPAR$_2$} = (upper solid width in $\hat{\bf y}_\TF$ direction)/$d$\\
        {\tt SHPAR}$_3$ = (upper solid width in $\hat{\bf z}_\TF$ direction)/$d$\\
        {\tt SHPAR}$_4$ = (middle solid thickness in $\hat{\bf x}_\TF$ direction)/$d$
        [material 2]\\
        {\tt SHPAR}$_5$ = (middle solid width in $\hat{\bf y}_\TF$ direction)/$d$\\
        {\tt SHPAR}$_6$ = (middle solid width in $\hat{\bf z}_\TF$ direction)/$d$\\
        {\tt SHPAR}$_7$ = (lower solid thickness in $\hat{\bf x}_\TF$ direction)/$d$
        [material 3]\\
        {\tt SHPAR}$_8$ = (lower solid width in $\hat{\bf y}_\TF$ direction)/$d$\\
        {\tt SHPAR}$_9$ = (lower solid width in $\hat{\bf z}_\TF$ direction)/$d$\\
	TF origin is at center of top surface of material 1.
\index{target shape options!SLAB\_HOLE}
\subsection{ SLAB\_HOLE = Rectangular slab with a cylindrical hole.
            \label{sec:SLAB_HOLE}}
        The target consists of a rectangular block with a cylindrical
        hole with the axis passing through the centroid and aligned
        with the $\hat{\bf x}_\TF$ axis.
        The block dimensions are
        $a\times b\times c$.
        The cylindrical hole has radius $r$.
        The pertinent line in {\tt ddscat.par} should read\\
        {\tt SHPAR$_1$ SHPAR$_2$ SHPAR$_3$ SHPAR$_4$}\\
        where\\
        {\tt SHPAR$_1$} = $a/d$ ($d$ is the interdipole spacing) \\
        {\tt SHPAR$_2$} = $b/a$ \\
        {\tt SHPAR$_3$} = $c/a$ \\
        {\tt SHPAR$_4$} = $r/a$ \\
        Ideally, {\tt SHPAR}$_1$,
        {\tt SHPAR}$_2\times${\tt SHPAR}$_1$,
        {\tt SHPAR}$_3\times${\tt SHPAR}$_1$ will be integers (so that the
        cubic lattice can accurately approximate the desired target
        geometry), and
        {\tt SHPAR}$_4\times${\tt SHPAR}$_1$ will be large enough for
        the circular cross section to be well-approximated.\\
        The TF origin is at the center of the top surface (the top surface
        lies in the $\hat{\bf y}_\TF-\hat{\bf z}_\TF$ plane, and extends from
        $y_{{\rm TF}}=-b/2$ to $+b/2$,
        and $z_{\rm TF}=-c/2$ to $+c/2$).
        The cylindrical hole axis runs from $(x_{\rm TF}=0,y_{\rm TF}=0,z_{\rm TF}=0)$ to
        $(x_{\rm TF}=-a,y_{\rm TF}=0,z_{\rm TF}=0)$.
\index{target shape options!SPHERES\_N}
\subsection{ SPHERES\_N = Multisphere target = union of $N$
	    spheres of single isotropic material
            \label{sec:SPHERES_N}}
	Spheres may overlap if desired.
	The relative locations and sizes of these spheres are
	defined in an external file, whose name (enclosed in single quotes)
	is passed through {\tt ddscat.par}.  The length of the file name
	should not exceed 80 characters.
	The pertinent line in {\tt ddscat.par} should read\\
	{\tt SHPAR$_1$ SHPAR$_2$} {\it 'filename'} (quotes must be used)\\
	where {\tt SHPAR$_1$} = target diameter in $x$ direction
	(in Target Frame) in units of $d$\\
	{\tt SHPAR$_2$}= 0 to have $a_1=(1,0,0)_{\rm TF}$, $a_2=(0,1,0)_{\rm TF}$.\\
	{\tt SHPAR$_2$}= 1 to use principal axes of moment of inertia
	tensor for $a_1$ (largest $I$) and $a_2$ (intermediate $I$).\\
	{\it filename} is the name of the file specifying the locations and
	relative sizes of the spheres.\\
	The overall size of the multisphere target (in terms of numbers of
	dipoles) is determined by parameter {\tt SHPAR$_1$}, which is
	the extent of the multisphere target in the $x$-direction, in
	units of the lattice spacing $d$.\\
	The file {\it `filename'} should have the
	following structure:\\ \\
	\hspace*{2em}$N$ (= number of spheres)\\
	\hspace*{2em}line of comments (may be blank)\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}$x_1$ $y_1$ $z_1$ $a_1$ (arb. units)\\
	\hspace*{2em}$x_2$ $y_2$ $z_2$ $a_2$ (arb. units)\\
	\hspace*{2em} ... \\
	\hspace*{2em}$x_N$ $y_N$ $z_N$ $a_N$ (arb. units)\\ \\
	where $x_j$, $y_j$, $z_j$ are the coordinates (in the TF)
	of the center of sphere $j$,
	and $a_j$ is the radius of sphere $j$.\\
	Note that $x_j$, $y_j$, $z_j$, $a_j$ ($j=1,...,N$) establish only
	the {\it shape} of the $N-$sphere target.  For instance,
	a target consisting of two touching spheres with the line between
	centers parallel to the $x$ axis could equally well be
	described by lines 6 and 7 being\\
	\hspace*{2em}0 ~0 ~0 ~0.5\\
	\hspace*{2em}1 ~0 ~0 ~0.5\\
	or\\
	\hspace*{2em}0 ~0 ~0 ~1\\
	\hspace*{2em}2 ~0 ~0 ~1\\
	The actual size (in physical units) is set by the value
	of $a_{\rm eff}$ specified in {\tt ddscat.par}, where, as
	always, $a_{\rm eff}\equiv (3 V/4\pi)^{1/3}$, where $V$ is the
	total volume of material in the target.\\
	Target axes $\hat{\bf a}_1$ and $\hat{\bf a}_2$ are set to
	be principal axes of moment of inertia tensor (for uniform density),
	where $\hat{\bf a}_1$
	corresponds to the largest eigenvalue, and $\hat{\bf a}_2$ to the
	intermediate eigenvalue.\\
	The TF origin is taken to be located at the volume-weighted
	centroid.\\
	User must set {\tt NCOMP}=1.
\index{target shape options!SPHROID\_2}
\subsection{ SPHROID\_2 = Two touching homogeneous, isotropic spheroids,
	   with distinct compositions
           \label{sec:SPHROID_2}}
	First spheroid has length {\tt SHPAR$_1$} along symmetry axis,
        diameter {\tt SHPAR$_2$} perpendicular to symmetry axis.
	Second spheroid has length {\tt SHPAR}$_3$ along symmetry axis,
	diameter {\tt SHPAR}$_4$ perpendicular to symmetry axis.
	Contact point is on line connecting centroids.
	Line connecting centroids is in $\hat{\bf x}_\TF$ direction.
	Symmetry axis of first spheroid is in $\hat{\bf y}_\TF$ direction.
	Symmetry axis of second spheroid is in direction
	$\hat{\bf y}_\TF\cos({\tt SHPAR}_5)+\hat{\bf z}_\TF\sin({\tt SHPAR}_5)$,
	and {\tt SHPAR}$_5$ is in degrees.
	If {\tt SHPAR}$_6=0.$, then target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$,
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.
	If {\tt SHPAR}$_6=1.$, then axes ${\hat{\bf a}}_1$ and
        ${\hat{\bf a}}_2$ are set to
	principal axes with largest and 2nd largest moments of inertia assuming
	spheroids to be of uniform density.\\
	Origin of TF is located between spheroids, at point of contact.\\
	User must set {\tt NCOMP}=2 and provide dielectric function files for
	each spheroid.
\index{target shape options!SPH\_ANI\_N}
\subsection{ SPH\_ANI\_N = Multisphere target consisting of the union of $N$
	    spheres of various materials, possibly anisotropic
            \label{sec:SPH_ANI_N}}
	Spheres may NOT overlap.
	The relative locations and sizes of these spheres are
	defined in an external file, whose name (enclosed in single quotes)
	is passed through {\tt ddscat.par}.  The length of the file name
	should not exceed 80 characters.
	Target axes $\hat{\bf a}_1$ and $\hat{\bf a}_2$ are set to
	be principal axes of moment of inertia tensor (for uniform density),
	where $\hat{\bf a}_1$
	corresponds to the largest eigenvalue, and $\hat{\bf a}_2$ to the
	intermediate eigenvalue.\\
	The TF origin is taken to be located at the volume-weighted
	centroid.\\
	The pertinent line in {\tt ddscat.par} should read\\
	{\tt SHPAR$_1$ SHPAR$_2$} {\it `filename'} (quotes must be used)\\
	where {\tt SHPAR$_1$} = target diameter in $x$ direction
	(in Target Frame) in units of $d$\\
	{\tt SHPAR$_2$}= 0 to have $a_1=(1,0,0)_{\rm TF}$, $a_2=(0,1,0)_{\rm TF}$
	in Target Frame.\\
	{\tt SHPAR$_2$}= 1 to use principal axes of moment of inertia
	tensor for $a_1$ (largest $I$) and $a_2$ (intermediate $I$).\\
	{\it filename} is the name of the file specifying the locations and
	relative sizes of the spheres.\\
	The overall size of the multisphere target (in terms of numbers of
	dipoles) is determined by parameter {\tt SHPAR$_1$}, which is
	the extent of the multisphere target in the $x$-direction, in
	units of the lattice spacing $d$.
	The file {\it `filename'} should have the
	following structure:\\ \\
	\hspace*{2em}$N$ (= number of spheres)\\
	\hspace*{2em}line of comments (may be blank)\\
		\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
        \hspace*{2em}$x_1$~ $y_1$~ $z_1$~ $r_1$~ $Cx_1$~ $Cy_1$~ $Cz_1$~
	$\Theta_{{\rm DF},1}$~ $\Phi_{{\rm DF},1}$~ $\beta_{{\rm DF},1}$\\
	\hspace*{2em}$x_2$~ $y_2$~ $z_2$~ $r_2$~ $Cx_2$~ $Cy_2$~ $Cz_2$~
	$\Theta_{{\rm DF},2}$~ $\Phi_{{\rm DF},2}$~ $\beta_{{\rm DF},2}$\\
	\hspace*{2em} ... \\
	\hspace*{2em}$x_N$ $y_N$ $z_N$ $r_N$ $Cx_N$ $Cy_N$ $Cz_N$
	$\Theta_{{\rm DF},N}$ $\Phi_{{\rm DF},N}$ $\beta_{{\rm DF},N}$\\ \\
	where $x_j$, $y_j$, $z_j$ are the coordinates of the center,
	and $r_j$ is the radius of sphere $j$ (arbitrary units),
	$Cx_j$, $Cy_j$, $Cz_j$ are integers specifying the ``composition''
	of sphere $j$ in the $x,y,z$ directions in the ``Dielectric Frame''
	\index{Dielectric Frame (DF)}
	(see \S\ref{sec:composite anisotropic targets})
	of sphere $j$, and
	\index{$\Theta_{\rm DF}$}
	$\Theta_{{\rm DF},j}$
	\index{$\Phi_{\rm DF}$}
	$\Phi_{{\rm DF},j}$
	\index{$\beta_{\rm DF}$}
	$\beta_{{\rm DF},j}$
	are angles (in radians) specifying orientation of the
	dielectric frame (DF) of
	sphere $j$ relative to the Target Frame.
	Note that $x_j$, $y_j$, $z_j$, $r_j$ ($j=1,...,N$) establish only
	the {\it shape} of the $N-$sphere target, just as for
	target option {\tt NSPHER}.
	The actual size (in physical units) is set by the value
	of $a_{\rm eff}$ specified in {\tt ddscat.par}, where, as
	always, $a_{\rm eff}\equiv (3 V/4\pi)^{1/3}$, where $V$ is the
	volume of material in the target.\\
	User must set {\tt NCOMP} to the number of different dielectric
	functions being invoked (i.e., the range of $\{Cx_j,Cy_j,Cz_j\}$.

	Note that while the spheres can be anisotropic and of differing
	composition, they can of course also be isotropic and of a single
	composition, in which case the relevant lines in the file
	{\it 'filename'} would be simply\\ \\
	\hspace*{2em}$N$ (= number of spheres)\\
	\hspace*{2em}line of comments (may be blank)\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}line of comments (may be blank) [N.B.: changed from v7.0.7]\\
	\hspace*{2em}$x_1$~ $y_1$~ $z_1$~ $r_1$~ 1 ~1 ~1 ~0 ~0 ~0\\
	\hspace*{2em}$x_2$~ $y_2$~ $z_2$~ $r_2$~ 1 ~1 ~1 ~0 ~0 ~0\\
	\hspace*{2em} ... \\
	\hspace*{2em}$x_N$ $y_N$ $z_N$ $r_N$ ~1 ~1 ~1 ~0 ~0 ~0\\

Subdirectory {\tt examples\_exp/SPH\_ANI\_N} contains {\tt ddscat.par} for
calculating scattering by a random aggregate of 64 spheres
[aggregated according following the ``BAM2'' aggregation process
described by Shen, Draine \& Johnson (2008)].
32 of the spheres are assumed to consist of ``astrosilicate'', and
32 of crystalline graphite, with random orientations for each of the 32
graphite spheres.
Each sphere is assumed to have a radius $0.050{\mu{\rm m}}$.
The entire cluster is represented by $N=7947$ dipoles, or about 124 dipoles
per sphere.
Scattering and absorption are calculated for $\lambda=0.55{\mu{\rm m}}$.
\index{target shape options!TETRAHDRN}
\subsection{ TETRAHDRN = Homogeneous, isotropic tetrahedron
            \label{sec:TETRAHDRN}}
	{\tt SHPAR$_1$}=length/$d$
	of one edge.
	Orientation: one face parallel to $\hat{\bf y}_\TF,\hat{\bf z}_\TF$ plane,
	opposite ``vertex" is in $+\hat{\bf x}_\TF$
	direction, and one edge is parallel to $\hat{\bf z}_\TF$.
	Target axes ${\hat{\bf a}}_1=(1,0,0)_{\rm TF}$ [emerging from one vertex]
        and ${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$ [emerging from an edge] in the TF.
	User must set {\tt NCOMP}=1.
\index{target shape options!TRNGLPRSM}
\subsection{ TRNGLPRSM = Triangular prism of homogeneous, isotropic material
            \label{sec:TRNGLPRSM}}
	{\tt SHPAR$_1$, SHPAR$_2$, SHPAR$_3$, SHPAR$_4$} $= a/d$, $b/a$,
        $c/a$, $L/a$\\
	The triangular cross section has sides of width $a$, $b$, $c$.
	$L$ is the length of the prism.
	$d$ is the lattice spacing.
	The triangular cross-section
	has interior angles $\alpha$, $\beta$, $\gamma$
	(opposite sides $a$, $b$, $c$) given by
	$\cos\alpha=(b^2+c^2-a^2)/2bc$, $\cos\beta=(a^2+c^2-b^2)/2ac$,
	$\cos\gamma=(a^2+b^2-c^2)/2ab$.
	In the Target Frame, the prism axis is in the $\hat{\bf x}$ direction,
	the normal to the rectangular face of width $a$ is (0,1,0),
	the normal to the rectangular face of width $b$ is
	$(0,-\cos\gamma,\sin\gamma)$, and
	the normal to the rectangular face of width  $c$ is
	$(0,-\cos\gamma,-\sin\gamma)$.
\index{target shape options!UNIAXICYL}
\subsection{ UNIAXICYL = Homogeneous finite cylinder with uniaxial anisotropic
	    dielectric tensor
            \label{sec:UNIAXICYL}}
	{\tt SHPAR$_1$}, {\tt SHPAR$_2$} have same meaning as for
	{\tt CYLINDER1}.
	Cylinder axis $={\hat{\bf a}}_1=(1,0,0)_{\rm TF}$,
	${\hat{\bf a}}_2=(0,1,0)_{\rm TF}$.
	It is assumed that the dielectric tensor $\epsilon$
	is diagonal in the TF,
	with $\epsilon_{yy}=\epsilon_{zz}$.
	User must set
	{\tt NCOMP}=2.
	Dielectric function 1 is for ${\bf E} \parallel {\bf\hat{a}}_1$
	(cylinder axis), dielectric function 2 is for
	${\bf E} \perp {\bf\hat{a}}_1$.
\bigskip
\index{target routines: modifying}
\subsection{ Modifying Existing Routines or Writing New Ones}

The user should be able to easily modify these routines, or write new
routines, to generate targets with other geometries.  The user should
first examine the routine {\tt target.f90} and modify it to call any new
target generation routines desired.  Alternatively, targets may be
generated separately, and the target description (locations of dipoles
and ``composition" corresponding to x,y,z dielectric properties at
each dipole site) read in from a file by invoking the option {\tt
FROM\_FILE} in {\tt ddscat.f90}.

Note that it will also be necessary to modify the routine {\tt reapar.f90}
so that it will accept whatever new target option is added to the
target generation code
.
\bigskip
\subsection{ Testing Target Generation using CALLTARGET}
\index{CALLTARGET}
It is often desirable to be able to run the target generation routines
without running the entire {{\bf DDSCAT}}\ code.  We have therefore
provided a program {\tt CALLTARGET} which allows the user to generate
targets interactively; to create this executable just type\footnote{
	Non-Linux sites: The source code for {\tt CALLTARGET} is in the file
	{\tt CALLTARGET.f90}.  You must compile and link {\tt CALLTARGET.f90},
	{\tt ddcommon.f90}, {\tt dsyevj3.f90}, {\tt errmsg.f90},
	{\tt gasdev.f90}, {\tt p\_lm.f90},
        {\tt prinaxis.f90}, {\tt ran3.f90}, {\tt reashp.f90}, {\tt sizer.f90},
        {\tt tar2el.f90}, {\tt tar2sp.f90}, {\tt tar3el.f90},
        {\tt taranirec.f90},
        {\tt tarblocks.f90}, {\tt tarcel.f90}, {\tt tarcyl.f90},
        {\tt tarcylcap.f90},
        {\tt tarell.f90}, {\tt target.f90}, {\tt targspher.f90},
        {\tt tarhex.f90}, {\tt tarnas.f90}, {\tt tarnsp.f90},
	{\tt tarpbxn.f90}, {\tt tarprsm.f90}, {\tt tarrctblk3.f90},
        {\tt tarrecrec.f90}, {\tt tarslblin.f90},
        {\tt tartet.f90}, and {\tt wrimsg.f90}.
	}
\hfill\break \indent\indent{\tt make calltarget} .\hfill\break
The program {\tt calltarget} is to be run interactively; the prompts are
self-explanatory.  You may need to edit the code to change the device
number {\tt IDVOUT} as for {\tt DDSCAT} (see \S\ref{subsec:IDVOUT}
above).

\index{target.out -- output file}
After running, {\tt calltarget} will leave behind an ASCII file
{\tt target.out}
which is a list of the occupied lattice sites in the last target generated.
The format of {\tt target.out} is the same as the format of the {\tt shape.dat}
files read if option {\tt FROM\_FILE} is used (see above).
Therefore you can simply \\
\indent\indent{\tt mv target.out shape.dat} \\
and then use {\tt DDSCAT}
with the option {\tt FROM\_FILE} (or option {\tt ANIFRMFIL} in the case
of anisotropic target materials with arbitrary orientation relative to
the Target Frame)
in order to input a target shape generated by {\tt CALLTARGET}.

\index{CALLTARGET and PBC}
Note that {\tt CALLTARGET} -- designed to generate finite targets --
can be used with some of the ``PBC'' target options
(see \S\ref{sec:target_generation_PBC} below) to generate a list
of dipoles in the TUC.
At the moment, {\tt CALLTARGET} has support for target options
{\tt BISLINPBC}, {\tt DSKBLYPBC}, and {\tt DSKRCTPBC}.

\section{Target Generation: Periodic Targets
         \label{sec:target_generation_PBC}}
\index{target generation: infinite periodic targets}
A periodic target consists of a ``Target Unit Cell'' (TUC) which is then
repeated in either the $\hat{\bf y}_\TF$ direction, the $\hat{\bf z}_\TF$ direction, or
both.  Please see Draine \& Flatau (2008) for illustration of how
periodic targets are assembled out of TUCs, and how the scattering from these
targets in different diffraction orders $M$ or $(M,N)$
is constrained by the periodicity.

The following options are included in {\bf DDSCAT}:
\index{target shape options!FRMFILPBC}
\subsection{ FRMFILPBC = periodic target with TUC geometry and composition
            input from a file
            \label{sec:FRMFILPBC}}
        The TUC can have arbitrary geometry and inhomogeneous
        composition, and is assumed to repeat periodically in either
        1-d (y or z) or 2-d (y and z).\\
        The pertinent line in {\tt ddscat.par} should read\\
        {\tt SHPAR$_1$ SHPAR$_2$} {\it 'filename'} (quotes must be used)\\
        {\tt SHPAR}$_1$ = $P_y/d$~~~
            ($P_y$ = periodicity in $\hat{\bf y}_\TF$ direction)\\
        {\tt SHPAR}$_2$ = $P_z/d$~~~
            ($P_z$ = periodicity in $\hat{\bf z}_\TF$ direction)\\
        {\it filename} is the name of the file specifying the locations
        of the dipoles, and the ``composition" at each dipole location.  The
        composition can be anisotropic, but the dielectric tensor must
        be diagonal in the TF.  The shape and composition of the TUC
        are provided {\it exactly} as for target option {\tt FROM$\_$FILE}
        -- see \S\ref{sec:FROM_FILE}\\
        If {\tt SHPAR}$_1=0$ then the target does {\it not} repeat in the
            $\hat{\bf y}_\TF$ direction.\\
        If {\tt SHPAR}$_2=0$ then the target does {\it not} repeat in the
            $\hat{\bf z}_\TF$ direction.\\
\index{target shape options!ANIFILPBC}
\subsection{ ANIFILPBC = general anisotropic periodic target with TUC
            geometry and composition input from a file
            \label{sec:ANIFILPBC} }
        The TUC can have arbitrary geometry and inhomogeneous
        composition, and is assumed to repeat periodically in either
        1-d (y or z) or 2-d (y and z).\\
        The pertinent line in {\tt ddscat.par} should read\\
        {\tt SHPAR$_1$ SHPAR$_2$} {\it 'filename'} (quotes must be used)\\
        {\tt SHPAR}$_1$ = $P_y/d$~~~
            ($P_y$ = periodicity in $\hat{\bf y}_\TF$ direction)\\
        {\tt SHPAR}$_2$ = $P_z/d$~~~
            ($P_z$ = periodicity in $\hat{\bf z}_\TF$ direction)\\
        {\it filename} is the name of the file specifying the locations
        of the dipoles, and the "composition" at each dipole location.  The
        composition can be anisotropic, and the dielectric tensor need not
        be diagonal in the TF.  The shape and composition of the TUC
        are provided {\it exactly} as for target option {\tt ANIFRMFIL} --
        see \S\ref{sec:ANIFRMFIL}\\
        If {\tt SHPAR}$_1=0$ then the target does {\it not} repeat in the
            $\hat{\bf y}_\TF$ direction.\\
        If {\tt SHPAR}$_2=0$ then the target does {\it not} repeat in the
            $\hat{\bf z}_\TF$ direction.\\
\index{target shape options!BISLINPBC}
\subsection{ BISLINPBC = Bi-Layer Slab with Parallel Lines}
        The target consists of a bi-layer slab, on top of which there is
        a ``line'' with rectangular cross-section.\\
	The ``line'' on top
	is composed of material 1, has height $X_1$ (in the $\hat{\bf x}_\TF$ direction),
	width $Y_1$ (in the $\hat{\bf y}_\TF$ direction), and
	is infinite in extent in the $\hat{\bf z}_\TF$ direction.\\
	The bilayer slab has width $Y_2$ (in the $\hat{\bf y}_\TF$ direction).
	It is consists of a layer of thickness $X_2$ of material 2, on top
	of a layer of material 3 with thickness $X_3$.\\
	{\tt SHPAR}$_1$ = $X_1/d$~~~~ ($X_1$ = thickness of line)\\
	{\tt SHPAR}$_2$ = $Y_1/d$~~~~ ($Y_1$ = width of line)\\
	{\tt SHPAR}$_3$ = $X_2/d$~~~~ ($X_2$ = thickness of upper layer of
	slab)\\
	{\tt SHPAR}$_4$ = $X_3/d$~~~~ ($X_3$ = thickness of lower layer of
	slab)\\
	{\tt SHPAR}$_5$ = $Y_2/d$~~~~ ($Y_2$ = width of slab)\\
	{\tt SHPAR}$_6$ = $P_y/d$~~~~ ($P_y$ = periodicity in $\hat{\bf y}_\TF$
        direction).\\

	If {\tt SHPAR}$_6$ = 0, the target is NOT periodic in the $\hat{\bf y}_\TF$
	direction, consisting of a single column, infinite in the $\hat{\bf z}_\TF$
	direction.
\index{target shape options!CYLNDRPBC}
\index{periodic boundary conditions}
\subsection{ CYLNDRPBC = Target consisting of homogeneous cylinder
                     repeated in
                     target y and/or z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of an infinite array of cylinders.
	    The individual cylinders
	    are assumed to be homogeneous and isotropic,
	    just as for option RCTNGL (see \S\ref{sec:RCTGLPRSM}).
	    \ \\
	    Let us
	    refer to a single cylinder as the Target Unit Cell (TUC).
	    The TUC
	    is then repeated in the target y- and/or z-directions, with
	    periodicities {\tt PYD}$\times d$\index{PYD} and
	    {\tt PZD}$\times d$,\index{PZD} where $d$ is the lattice spacing.
	    To repeat in only one direction, set either {\tt PYD} or
	    {\tt PZD} to zero.\\
	    This option requires 5 shape parameters:
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR$_3$ SHPAR$_4$ SHPAR}$_5$\\
	    \ \\
	where {\tt SHPAR$_1$,SHPAR$_2$,SHPAR$_3$,SHPAR$_4$,SHPAR$_5$} are
        numbers:\\
	{\tt SHPAR}$_1$ = cylinder length along axis (in units of $d$)
	in units of $d$\\
	{\tt SHPAR$_2$} = cylinder diameter/$d$\\
	{\tt SHPAR}$_3$ = 1 for cylinder axis $\parallel \hat{\bf x}_\TF$\\
        \hspace*{5em}= 2 for cylinder axis $\parallel \hat{\bf y}_\TF$\\
        \hspace*{5em}= 3 for cylinder axis $\parallel \hat{\bf z}_\TF$
	                 (see below)\\
	{\tt SHPAR}$_4$ = {\tt PYD} = periodicity/$d$ in $\hat{\bf y}_\TF$ direction
        ( = 0 to suppress repetition)\\
	{\tt SHPAR}$_5$ = {\tt PZD} = periodicity/$d$ in $\hat{\bf z}_\TF$ direction
        ( = 0 to suppress repetition)\\
	\ \\
	The overall size of the TUC (in terms of numbers of
	dipoles) is determined by parameters
	{\tt SHPAR1} and {\tt SHPAR$_2$}.
	The orientation of a single cylinder is determined by {\tt SHPAR}$_3$.
	The periodicity in the TF $y$ and $z$ directions is determined
	by parameters {\tt SHPAR}$_4$ and {\tt SHPAR}$_5$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}, with the usual
	correspondence $d=(4\pi/3N)^{1/3}{a}_{\rm eff}$, where $N$ is the number
	of dipoles in the TUC.

	With target option {\tt CYLNDRPBC}, the target
	becomes a periodic structure, of infinite extent.
	\begin{itemize}
	\item If ${\tt NPY}>0$ and ${\tt NPZ}>0$,
              then the target cylindrical TUC
              repeats in the $\hat{\bf y}_\TF$ direction,
	      with periodicity ${\tt NPY}\times d$.
        \item If ${\tt NPY}=0$ and ${\tt NPZ}>0$
	      then the target cylindrical TUC
	      repeats in the $\hat{\bf z}_\TF$ direction,
	       with periodicity ${\tt NPZ}\times d$.
        \item If ${\tt NPY}>0$ and ${\tt NPZ}>0$
	      then the target cylindrical TUC
	      repeats in the $\hat{\bf y}_\TF$ direction,
	      with periodicity ${\tt NPY}\times d$, and in
	      the $\hat{\bf z}_\TF$ direction,
	       with periodicity ${\tt NPZ}\times d$.
        \end{itemize}

	\noindent
	{\bf Target Orientation:} The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = (1,0,0)_{\rm TF}$
	and
	${\hat{\bf a}}_2 = (0,1,0)_{\rm TF}$.
        Note that ${\hat{\bf a}}_1$ does {\bf not} necessarily
	coincide with the cylinder axis: individual
	cylinders may have any of 3 different orientations in the TF.\\
	\ \\

	\noindent
	{\bf Example 1:} One could construct a single infinite cylinder
	\index{infinite cylinder}
	with the following two lines in {\tt ddscat.par}:\\
	\ \\
	100  1 100 \\
	1.0\ \ \  100.49\ \ \  2\ \ \  1.0\ \ \  0.\\
	\ \\
	The first line ensures that there will be enough memory allocated
	to generate the target.
	The TUC would be a thin circular ``slice'' containing just one layer
	of dipoles.  The diameter of the circular slice would be about
	100.49$d$ in
	extent, so the TUC would have approximately
	$(\pi/4)\times(100.49)^2=7931$ dipoles
	(7932 in the actual realization) within a $100\times1\times100$
	``extended target volume''.
	The TUC would be oriented with the cylinder axis in the $\hat{\bf y}_\TF$
        direction
	({\tt SHPAR3=2}) and the structure would repeat in the $\hat{\bf y}_\TF$
         direction
	with a period of $1.0\times d$.
	{\tt SHPAR}$_5$=0 means that there will be no repetition in the $z$
	direction.
	As noted above, the ``target axis'' vector
	$\hat{\bf a}_1 = \hat{\bf x}_\TF$.

	Note that {\tt SHPAR}$_1$, {\tt SHPAR}$_2$, {\tt SHPAR}$_4$, and
        {\tt SHPAR}$_5$ need not be integers.
        However, {\tt SHPAR}$_3$, determining the orientation of the cylinders
        in the TF, can only take on the values 1,2,3.

	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the periodic
	structure.

{\bf Sample calculation:}
The subdirectory {\tt examples\_exp/CYLNDRPBC} contains {\tt ddscat.par}
for calculating scattering by an infinite cylinder with $m=1.33+0.01i$ for
$2\pi R/\lambda=10$, where $R$ is the cylinder radius.
\index{target shape options!DSKBLYPBC}
\index{periodic boundary conditions}
\subsection{ DSKBLYPBC = Target consisting of a periodic array of disks on top
            of a two-layer rectangular slabs.}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a periodic or biperiodic array of Target Unit Cells (TUCs),
            each TUC consisting of a disk of composition 1
	    resting on top of a rectangular block consisting of
	    two layers: composition 2 on top and composition 3 below.
	    Materials 1, 2, and 3 are assumed to be homogeneous and isotropic.
	    \ \\
	    This option requires 8 shape parameters:\newline
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	${\tt SHPAR}_1~~{\tt SHPAR}_2~~{\tt SHPAR}_3~~{\tt SHPAR}_4~~{\tt SHPAR}_5~~{\tt SHPAR}_6~~{\tt SHPAR}_7~~{\tt SHPAR}_8$\\
	    \ \\
	where\\
	{\tt SHPAR}$_1$ = disk thickness in $x$ direction
	(in Target Frame) in units of $d$\\
	{\tt SHPAR}$_2$ = (disk diameter)/$d$\\
	{\tt SHPAR}$_3$ = (upper slab thickness)/$d$\\
	{\tt SHPAR}$_4$ = (lower slab thickness)/$d$\\
	{\tt SHPAR}$_5$ = (slab extent in $\hat{\bf y}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_6$ = (slab extent in $\hat{\bf z}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_7$ = period in $\hat{\bf y}_\TF$ direction/$d$\\
	{\tt SHPAR}$_8$ = period in $\hat{\bf z}_\TF$ direction/$d$\\
	\ \\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.\\
	\ \\
	The ``computational volume'' is determined by\\
	({\tt SHPAR$_1$+SHPAR$_3$+SHPAR$_4$})$\times${\tt SHPAR}$_5\times${\tt SHPAR}$_6$.\\
	\ \\
	    The lower surface of the cylindrical disk is in the $x=0$ plane.
	    The upper surface of the slab is also in the $x=0$ plane.
	    It is required that
            ${\tt SHPAR}_2\leq{\rm min}({\tt SHPAR}_4,{\tt SHPAR}_5)$.\\
	    \ \\
	    The Target Frame origin (0,0,0) is located where the symmetry
	    axis of the disk intersects the $x=0$ plane (the upper surface
	    of the slab, and the lower surface of the disk).\\
	    In the Target Frame,
            dipoles representing the disk are located at\\
	    \hspace*{1.0cm}$x/d = 0.5 , 1.5 ,...,
	    [{\rm int}({\tt SHPAR}_1+0.5)-0.5]$\\
	    and at $(y,z)$ values \\
	    \hspace*{1.0cm}$y/d = \pm 0.5, \pm 1.5, ...$ and\\
	    \hspace*{1.0cm}$z/d = \pm 0.5, \pm 1.5, ...$ satisfying\\
	    \hspace*{1.0cm}$(y^2+z^2) \leq ({\tt SHPAR}_2/2)^2 d^2$.

	    Dipoles representing the rectangular slab
	    are located at
	    $(x/d,y/d,z/d)=(j_x+0.5,j_y+\Delta y,j_z+\Delta z)$, where
	    $j_x$, $j_y$, and $j_z$ are integers. $\Delta y=0$ or 0.5
	    depending on whether {\tt SHPAR}$_5$ is even or odd.
	    $\Delta z=0$ or 0.5 depending on whether {\tt SHPAR}$_6$ is
	    even or odd.\\
	    \ \\
	    The TUC
	    is repeated in the target y- and z-directions, with
	    periodicities {\tt SHPAR$_7$}$\times d$ and
            {\tt SHPAR}$_8$$\times d$.

	    As always, the physical size of the target is fixed by
	    specifying the value of the effective radius
	    ${a}_{\rm eff}\equiv(3V_{\rm TUC}/4\pi)^{1/3}$,
	    where $V_{\rm TUC}$
	    is the total volume of solid material in one TUC.
	    For this geometry, the number of dipoles in the target will
	    be approximately
	    $$N=
	    (\pi/4)\times{\tt SHPAR}_1\times({\tt SHPAR}_2)^2+
	    [{\tt SHPAR}_3+{\tt SHPAR}_4]
	    \times{\tt SHPAR}_5\times{\tt SHPAR}_6 $$
	    although the exact number may differ because of the
	    dipoles are required to be located on a rectangular lattice.
	    The dipole spacing $d$ in physical units
	    is determined from the specified value of ${a}_{\rm eff}$ and
	    the number $N$ of dipoles in the target:
	    $d=(4\pi/3N)^{1/3}{a}_{\rm eff}$.\\
	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = \hat{\bf x}_\TF = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = \hat{\bf y}_\TF= (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

\index{target shape options!DSKRCTPBC}
\index{periodic boundary conditions}
\subsection{ DSKRCTPBC = Target consisting of homogeneous rectangular brick plus
                     a disk,
                     extended in
                     target y and z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a biperiodic array of Target Unit Cells.  Each Target
	    Unit Cell (TUC) consists of a disk of composition 1
	    resting on top of a rectangular block of composition 2.
	    Materials 1 and 2 are assumed to be homogeneous and isotropic.
	    \ \\
	    The cylindrical disk has thickness {\tt SHPAR$_1$}$\times d$ in the
	    x-direction, and diameter {\tt SHPAR$_2$}$\times d$.
	    The rectangular block is assumed to have thickness
	    {\tt SHPAR}$_3$$\times$d in the x-direction,
	    extent {\tt SHPAR}$_4$$\times d$ in the y-direction,
	    and extent {\tt SHPAR}$_5$$\times d$ in the z-direction.
	    The lower surface of the cylindrical disk is in the $x=0$ plane.
	    The upper surface of the slab is also in the $x=0$ plane.
	    It is required that
            {\tt SHPAR$_2$}$\leq$min({\tt SHPAR4,SHPAR}$_5$).

	    The Target Frame origin (0,0,0) is located where the symmetry
	    axis of the disk intersects the $x=0$ plane (the upper surface
	    of the slab, and the lower surface of the disk).
	    In the Target Frame,
	    dipoles representing the rectangular block are located at
	    $(x/d,y/d,z/d)=(j_x+0.5,j_y+\Delta y,j_z+\Delta z)$, where
	    $j_x$, $j_y$, and $j_z$ are integers. $\Delta y=0$ or 0.5
	    depending on whether {\tt SHPAR}$_4$ is even or odd.
	    $\Delta z=0$ or 0.5 depending on whether {\tt SHPAR}$_5$ is
	    even or odd.\\
	    \hspace*{1.0cm}
	    $j_x = -[{\rm int}({\tt SHPAR}_3+0.5)] , ... , -1$.
	     \\
	    \hspace*{1.0cm}
	    $j_y = -[{\rm int}(0.5\times{\tt SHPAR}_4-0.5) + 1]$ , ... ,
            $j_z = -[{\rm int}({\tt SHPAR}_4+0.5)-0.5]$\\
	    \hspace*{1.0cm}
	    $y/d = -[{\rm int}(0.5\times{\tt SHPAR}_4+0.5)-0.5] , ... ,
                    [{\rm int}(0.5\times{\tt SHPAR}_4+0.5)-0.5]$\\
            \hspace*{1.0cm}
	    $z/d =  -[{\rm int}(0.5\times{\tt SHPAR}_5+0.5)-0.5] , ... ,
                     [{\rm int}(0.5\times{\tt SHPAR}_5+0.5)-0.5]$\\
            where ${\rm int}(x)$ is the greatest integer less than or equal
	    to $x$.
            Dipoles representing the disk are located at\\
	    \hspace*{1.0cm}$x/d = 0.5 , 1.5 ,...,
	    [{\rm int}({\tt SHPAR}_4+0.5)-0.5]$\\
	    and at $(y,z)$ values \\
	    \hspace*{1.0cm}$y/d = \pm 0.5, \pm 1.5, ...$ and\\
	    \hspace*{1.0cm}$z/d = \pm 0.5, \pm 1.5, ...$ satisfying\\
	    \hspace*{1.0cm}$(y^2+z^2) \leq ({\tt SHPAR}_5/2)^2 d^2$.

	    The TUC
	    is repeated in the target y- and z-directions, with
	    periodicities {\tt SHPAR$_6$}$\times d$ and
	    {\tt SHPAR}$_7$$\times d$.
	    As always, the physical size of the target is fixed by
	    specifying the value of the effective radius
	    ${a}_{\rm eff}\equiv(3V_{\rm TUC}/4\pi)^{1/3}$,
	    where $V_{\rm TUC}$
	    is the total volume of solid material in one TUC.
	    For this geometry, the number of dipoles in the target will
	    be approximately
	    $N=[{\tt SHPAR}_1\times{\tt SHPAR}_2\times{\tt SHPAR}_3 +
	    (\pi/4)(({\tt SHPAR}_4)^2\times{\tt SHPAR}_5)]$,
	    although the exact number may differ because of the
	    dipoles are required to be located on a rectangular lattice.
	    The dipole spacing $d$ in physical units
	    is determined from the specified value of ${a}_{\rm eff}$ and
	    the number $N$ of dipoles in the target:
	    $d=(4\pi/3N)^{1/3}{a}_{\rm eff}$.
	    This option requires 7 shape parameters:\newline
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR$_3$ SHPAR$_4$ SHPAR$_5$ SHPAR$_6$
         SHPAR$_7$}\\
	    \ \\
	where\\
	{\tt SHPAR$_1$} = [disk thickness (in $\hat{\bf x}_\TF$ direction)]/$d$
        [material 1]\\
	{\tt SHPAR$_2$} = (disk diameter)/$d$\\
	{\tt SHPAR}$_3$ = (brick thickness in $\hat{\bf x}_\TF$ direction)/$d$
        [material 2]\\
	{\tt SHPAR}$_4$ = (brick length in $\hat{\bf y}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_5$ = (brick length in $\hat{\bf z}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_6$ = periodicity in $\hat{\bf y}_\TF$ direction/$d$\\
	{\tt SHPAR}$_7$ = periodicity in $\hat{\bf z}_\TF$ direction/$d$\\
	\ \\
	The overall extent of the TUC (the ``computational volume'')
	is determined by parameters
	{\tt (SHPAR1+SHPAR4), max(SHPAR$_2$,SHPAR$_4$}, and
	{\tt max(SHPAR$_3$,SHPAR$_5$)}.
	The periodicity in the TF $y$ and $z$ directions is determined
	by parameters {\tt SHPAR}$_6$ and {\tt SHPAR}$_7$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.

	The target
	is a periodic structure, of infinite extent in the target
	y- and z- directions.
	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = \hat{\bf x}_\TF = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = \hat{\bf y}_\TF= (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

{\bf Sample calculation:}
Subdirectory {\tt examples\_exp/DSKRCTPBC} contains {\tt ddscat.par} for
calculating scattering by a $0.0500{\mu{\rm m}}$ thick Si$_3$N$_4$ slab with
a periodic array of Au disks, with periodicity $0.0800{\mu{\rm m}}$,
disk diameter $0.0500{\mu{\rm m}}$, and disk height $0.0400{\mu{\rm m}}$, for
light with wavelength $\lambda=0.5320{\mu{\rm m}}$.
The radiation is incident at an angle of $60^\circ$ relative to the
surface normal.
\index{target shape options!HEXGONPBC}
\index{periodic boundary conditions}
\subsection{ HEXGONPBC = Target consisting of homogeneous hexagonal prism
                     repeated in
                     target y and/or z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a periodic or biperiodic array of hexagonal prisms.
	    The individual prisms are assumed to be homogeneous and isotropic,
	    just as for option RCTNGL (see \S\ref{sec:RCTGLPRSM}).
	    \ \\
	    Let us
	    refer to a single hexagonal prism as the Target Unit Cell (TUC).
	    The TUC
	    is then repeated in the target y- and z-directions, with
	    periodicities {\tt PYD}$\times d$\index{PYD} and
	    {\tt PZD}$\times d$,\index{PZD} where $d$ is the lattice spacing.
	    To repeat in only one direction, set either {\tt PYD} or
	    {\tt PZD} to zero.\\
	    This option requires 5 shape parameters:
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR3 SHPAR4 SHPAR}$_5$\\
	    \ \\
	where{\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt SHPAR}$_3$,
        {\tt SHPAR}$_4$, {\tt SHPAR}$_5$ are numbers: \\
	{\tt SHPAR$_1$} = prism length along prism axis (in units of $d$)
	in units of $d$\\
	{\tt SHPAR$_2$} = 2$\times$length of one hexagonal side/$d$\\
	{\tt SHPAR}$_3$ = 1,2,3,4,5 or 6 to specify prism orientation
	                 in the TF (see below)\\
	{\tt SHPAR}$_4$ = {\tt PYD} = periodicity in TF $y$ direction/$d$\\
	{\tt SHPAR}$_5$ = {\tt PZD} = periodicity in TF $z$ direction/$d$\\
	\ \\
	The overall size of the TUC (in terms of numbers of
	dipoles) is determined by parameters
	{\tt SHPAR$_1$, SHPAR$_2$}, and {\tt SHPAR}$_3$.
	The periodicity in the TF $y$ and $z$ directions is determined
	by parameters {\tt SHPAR}$_4$ and {\tt SHPAR}$_5$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}, with the usual
	correspondence $d=(4\pi/3N)^{1/3}{a}_{\rm eff}$, where $N$ is the number
	of dipoles in the TUC.

	With target option {\tt HEXGONPBC}, the target
	becomes a periodic structure, of infinite extent in the target
	y- and z- directions (assuming both {\tt NPY} and {\tt NPZ} are
	nonzero).

	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = \hat{\bf x}_\TF = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = \hat{\bf y}_\TF = (0,1,0)_{\rm TF}$.

	The individual
	hexagons may have any of 6 different orientations relative to the
	slab:
	Let unit vectors $\hat{\bf h}$ be $\parallel$ to the axis of the
	hexagonal prism, and
	let unit vector $\hat{\bf f}$ be normal to one of the rectangular
	faces of the hexagonal prism.
	Then\\
	{\tt SHPAR3=1} for $\hat{\bf h}\parallel \hat{\bf x}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf y}_{\rm TF}$\\
	{\tt SHPAR3=2} for $\hat{\bf h}\parallel \hat{\bf x}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf z}_{\rm TF}$\\
	{\tt SHPAR3=3} for $\hat{\bf h}\parallel \hat{\bf y}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf x}_{\rm TF}$\\
	{\tt SHPAR3=4} for $\hat{\bf h}\parallel \hat{\bf y}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf z}_{\rm TF}$\\
	{\tt SHPAR3=5} for $\hat{\bf h}\parallel \hat{\bf z}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf x}_{\rm TF}$\\
	{\tt SHPAR3=6} for $\hat{\bf h}\parallel \hat{\bf z}_{\rm TF}$,
	                  $\hat{\bf f}\parallel \hat{\bf y}_{\rm TF}$\\

	For example, one could construct a single infinite hexagonal column
	\index{infinite hexagonal column}
	with the following line in {\tt ddscat.par}:\\
	\ \\
	2.0\ \ \ 100.0\ \ \  3\ \ \  2.0\ \ \  0.\\
	\ \\
	The TUC would be a thin hexagonal ``slice'' containing two layers
	of dipoles.  The edges of the hexagon would be about 50$d$ in
	extent, so the TUC would have approximately
	$(3\sqrt{3}/2)\times50^2\times2=
	12990$ dipoles (13024 in the actual realization)
	within a $90\times2\times100$ ``extended target volume''.
	The TUC would be oriented with the hexagonal axis in the
	$\hat{\bf y}_{\rm TF}$
	direction, with $\hat{\bf z}_{\rm TF}$ normal to a rectangular
	faces of the prism
	({\tt SHPAR3=3}), and the structure would repeat in the
	$\hat{\bf y}_{\rm TF}$ direction
	with a period of $2\times d$ ({\tt SHPAR4=2.0}).
	{\tt SHPAR5=0} means that there will be no repetition in the
	$\hat{\bf z}_{\rm TF}$
	direction.

	Note that {\tt SHPAR$_1$}, {\tt SHPAR$_2$}, {\tt SHPAR}$_4$, and
        {\tt SHPAR}$_5$ need not be integers.
        However, {\tt SHPAR}$_5$, determining the
	orientation of the prisms in the TF, can only take on the values
	1,2,3,4,5,6.

	{\bf Important Note:}
	For technical reasons, {\tt PYD} and {\tt PZD} must not be smaller than
	the ``extended'' target extent in the $\hat{\bf y}_{\rm TF}$
	and $\hat{\bf z}_{\rm TF}$ directions.
	When the GPFAFT\index{GPFAFT} option is used
	for the 3-dimensional FFT calculations,
	the extended target volume always
	has dimensions/$d = 2^a3^b5^c$, where $a$, $b$, and $c$ are
	nonnegative
	integers, with (dimension/$d)\geq 1$).

	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the periodic
	structure.

\index{target shape options!LYRSLBPBC}
\index{periodic boundary conditions}
\subsection{ LYRSLBPBC = Target consisting of layered slab,
                     extended in
                     target y and z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of an array of multilayer bricks, layered in the $\hat{\bf x}_\TF$ direction.
	    The size of each brick
	    in the $\hat{\bf y}_\TF$ and $\hat{\bf z}_\TF$ direction is specified.
	    Up to 4 layers are allowed.\\
	    The bricks are repeated in the $\hat{\bf y}_\TF$ and $\hat{\bf z}_\TF$ direction
	    with a specified periodicity.
	    If $L_y=P_y$ and $L_z=P_z$, then the target
	    consists of a continuous multilayer slab.  For this case,
	    it is most economical to set $L_y/d=L_z/d=P_y/d=P_z/d=1$.\\
            If $P_y=0$, then repetition in the $\hat{\bf y}_\TF$ direction is
            suppressed -- the target repeats only in the $\hat{\bf z}_\TF$ direction.\\
            If $P_z=0$, then repetition in the $\hat{\bf z}_\TF$ direction is
            suppressed -- the target repeats only in the $\hat{\bf y}_\TF$ direction.\\
	    The upper surface of the slab is asssume to be located at
	    $x_{\rm TF}=0$.  The lower surface of the slab is at
	    $x_{\rm TF}=-L_x=-$~{\tt SHPAR1}$\times d$.\\
	    The multilayer slab geometry is specified with 9 parameters.
	    The pertinent line in {\tt ddscat.par} should read \\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR$_3$ SHPAR$_4$ SHPAR$_5$ SHPAR$_6$
             SHPAR$_7$ SHPAR$_8$ SHPAR$_9$}\\
	    \ \\
	where\\
	{\tt SHPAR}$_1$ = $L_x/d$ = (brick thickness in $\hat{\bf x}_\TF$ direction)$/d$\\
	{\tt SHPAR}$_2$ = $L_y/d$ = (brick extent in $\hat{\bf y}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_3$ = $L_z/d$ = (brick extent in $\hat{\bf z}_\TF$ direction)/$d$\\
	{\tt SHPAR}$_4$ = fraction of the slab with composition 1\\
	{\tt SHPAR}$_5$ = fraction of the slab with composition 2\\
	{\tt SHPAR}$_6$ = fraction of the slab with composition 3\\
	{\tt SHPAR}$_7$ = fraction of the slab with composition 4\\
	{\tt SHPAR}$_8$ = $P_y/d$ = (periodicity in $\hat{\bf y}_\TF$ direction)/$d$
             (0 to suppress repetition in $\hat{\bf y}_\TF$ direction)\\
	{\tt SHPAR}$_9$ = $P_z/d$ = (periodicity in $\hat{\bf z}_\TF$ direction)/$d$
             (0 to suppress repetition in $\hat{\bf z}_\TF$ direction)\\
	\ \\
	For a slab with only one layer, set {\tt SHPAR}$_5=0$,
	{\tt SHPAR}$_6=0$, {\tt SHPAR}$_7=0$.\\
	For a slab with only two layers, set {\tt SHPAR}$_6=0$ and
	{\tt SHPAR}$_7=0$.\\
	For a slab with only three layers, set {\tt SHPAR}$_7=0$.\\
	The user must set {\tt NCOMP} equal to
	the number of nonzero thickness layers.\\
	The number $N$ of dipoles in one TUC is
	$N={\rm nint}({\tt SHPAR}_1)\times{\rm nint}({\tt SHPAR}_2)\times
	{\rm nint}({\tt SHPAR}_3)$.

	The fractions {\tt SHPAR$_2$}, {\tt SHPAR}$_3$, {\tt SHPAR}$_4$,
	and {\tt SHPAR}$_5$ {\it must} sum to 1.
	The number of dipoles in each of the layers will be integers
	that are close to ${\rm  nint}({\tt SHPAR}_1*{\tt SHPAR}_4)$,
	${\rm  nint}({\tt SHPAR}_1*{\tt SHPAR}_5)$,
	${\rm  nint}({\tt SHPAR}_1*{\tt SHPAR}_6)$,
	${\rm  nint}({\tt SHPAR}_1*{\tt SHPAR}_7)$,

	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.  Because of the way
	${a}_{\rm eff}$ is defined
	($4\pi {a}_{\rm eff}^3/3 \equiv Nd^3$),
	it should be set to
	$$ {a}_{\rm eff} = (3/4\pi)^{1/3} N^{1/3} d = (3/4\pi)^{1/3}
	(L_x L_y L_z)^{1/3}$$.

	With target option {\tt LYRSLBPBC}, the target
	becomes a periodic structure, of infinite extent in the target
	y- and z- directions.
	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

	For this option, there are only two allowed scattering directions,
	corresponding to transmission and specular reflection.
	{\bf DDSCAT}\ will calculate both the transmission and reflection
	coefficients.\\
	The last two lines in {\tt ddscat.par} should appear as in the
	following example {\tt ddscat.par} file.  This example is
	for a slab with two layers: the slab is 26 dipole layers thick;
	the first layer comprises 76.92\%
	of the thickness, the second layer 23.08\% of the thickness.
	The wavelength is $0.532\mu$m, the thickness is
	$L_x=(4\pi/3)^{1/3}N_x^{2/3}{a}_{\rm eff}=(4\pi/3)^{1/3}(26)^{2/3}0.009189=
	0.1300{\mu{\rm m}}$.\\
	The upper layer thickness is $0.2308L_x=0.0300{\mu{\rm m}}$\\
	{\tt ddscat.par} is set up to calculate a single orientation:
	in the Lab Frame,
	the target is rotated through an angle $\Theta=120^\circ$, with
	$\Phi=0$.  In this orientation, the incident radiation is propagating
	in the $(-0.5,0.866,0)$ direction in the Target Frame, so that it
	is impinging on target layer 2 (Au).
	\\
{\footnotesize\begin{verbatim}
' =========== Parameter file for v7.1.0 ==================='
'**** PRELIMINARIES ****'
'NOTORQ' = CMTORQ*6 (DOTORQ, NOTORQ) -- either do or skip torque calculations
'PBCGS2' = CMDSOL*6 (PBCGS2, PBCGST, PETRKP) -- select solution method
'GPFAFT' = CMETHD*6 (GPFAFT, FFTMKL)
'GKDLDR' = CALPHA*6 (GKDLDR, LATTDR)
'NOTBIN' = CBINFLAG (ALLBIN, ORIBIN, NOTBIN)
'**** Initial Memory Allocation ****'
26  1  1  = upper bounds on size of TUC
'**** Target Geometry and Composition ****'
'LYRSLBPBC' = CSHAPE*9 shape directive
26 1 1 0.7692 0.2308 0 0 1 1 = shape parameters SHPAR1 - SHPAR9
2         = NCOMP = number of dielectric materials
'/u/draine/work/DDA/diel/Eagle_2000' = refractive index 1
'/u/draine/work/DDA/diel/Au_evap'    = refractive index 2
'**** Error Tolerance ****'
1.00e-5 = TOL = MAX ALLOWED (NORM OF |G>=AC|E>-ACA|X>)/(NORM OF AC|E>)
'**** Interaction cutoff parameter for PBC calculations ****'
5.00e-3 = GAMMA (1e-2 is normal, 3e-3 for greater accuracy)
'**** Angular resolution for calculation of <cos>, etc. ****'
0.5	= ETASCA (number of angles is proportional to [(3+x)/ETASCA]^2 )
'**** Wavelengths (micron) ****'
0.5320 0.5320 1 'INV' = wavelengths (first,last,how many,how=LIN,INV,LOG)
'**** Effective Radii (micron) **** '
0.009189 0.009189 1 'LIN' = eff. radii (first,last,how many,how=LIN,INV,LOG)
'**** Define Incident Polarizations ****'
(0,0) (1.,0.) (0.,0.) = Polarization state e01 (k along x axis)
2 = IORTH  (=1 to do only pol. state e01; =2 to also do orth. pol. state)
'**** Specify which output files to write ****'
1 = IWRKSC (=0 to suppress, =1 to write ".sca" file for each target orient.
1 = IWRPOL (=0 to suppress, =1 to write ".pol" file for each (BETA,THETA)
'**** Prescribe Target Rotations ****'
0.   0.   1  = BETAMI, BETAMX, NBETA (beta=rotation around a1)
120. 120. 1  = THETMI, THETMX, NTHETA (theta=angle between a1 and k)
0.   0.   1  = PHIMIN, PHIMAX, NPHI (phi=rotation angle of a1 around k)
'**** Specify first IWAV, IRAD, IORI (normally 0 0 0) ****'
0   0   0    = first IWAV, first IRAD, first IORI (0 0 0 to begin fresh)
'**** Select Elements of S_ij Matrix to Print ****'
6	= NSMELTS = number of elements of S_ij to print (not more than 9)
11 12 21 22 31 41	= indices ij of elements to print
'**** Specify Scattered Directions ****'
'TFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
1 = number of scattering orders
0.  0. = (M,N) for scattering
\end{verbatim}}
\index{target shape options!RCTGL\_PBC}
\index{periodic boundary conditions}
\subsection{ RCTGL\_PBC = Target consisting of homogeneous rectangular brick,
                     extended in
                     target y and z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a biperiodic array of rectangular bricks.
	    The bricks are assumed to be homogeneous and isotropic,
	    just as for option RCTNGL (see \S\ref{sec:RCTGLPRSM}).
	    \ \\
	    Let us
	    refer to a single rectangular brick as the Target Unit Cell (TUC).
	    The TUC
	    is then repeated in the $y_{\rm TF}$- and $z_{\rm TF}$-directions, with
	    periodicities {\tt PYAEFF}$\times {a}_{\rm eff}$ and
	    {\tt PZAEFF}$\times {a}_{\rm eff}$, where
	    ${a}_{\rm eff}\equiv(3V_{\rm TUC}/4\pi)^{1/3}$,
	    where $V_{\rm TUC}$
	    is the total volume of solid material in one TUC.
	    This option requires 5 shape parameters:\newline
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	${\tt SHPAR}_1~~{\tt SHPAR}_2~~{\tt SHPAR}_3~~{\tt SHPAR}_4~~{\tt SHPAR}_5$\\
	    \ \\
	where\\
	{\tt SHPAR$_1$} = (brick thickness)/$d$ in the $x_{\rm TF}$ direction\\
	{\tt SHPAR$_2$} = (brick thickness)/$d$ in the $y_{\rm TF}$ direction\\
	{\tt SHPAR}$_3$ = (brick thickness)/$d$ in the $z_{\rm TF}$ direction\\
	{\tt SHPAR}$_4$ = periodicity/$d$ in the $y_{\rm TF}$ direction\\
	{\tt SHPAR}$_5$ = periodicity/$d$ in the $z_{\rm TF}$ direction\\
	\ \\
	The overall size of the TUC (in terms of numbers of
	dipoles) is determined by parameters
	{\tt SHPAR$_1$, SHPAR$_2$}, and {\tt SHPAR}$_3$.
	The periodicity in the $y_{\rm TF}$ and $z_{\rm TF}$ directions is determined
	by parameters {\tt SHPAR}$_4$ and {\tt SHPAR}$_5$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.

	With target option {\tt RCTGL\_PBC}, the target
	becomes a periodic structure, of infinite extent in the target
	y- and z- directions.
	The target axes (in the TF)
	are set to ${\hat{\bf a}}_1 = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above); for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

{\bf Sample Calculation:}
Subdirectory {\tt examples\_exp/RCTGL\_PBC} contains {\tt ddscat.par}
for scattering by an infinite slab, constituted from $16\times1\times1$
dipole TUCs.
\index{target shape options!RECRECPBC}
\index{periodic boundary conditions}
\subsection{ RECRECPBC = Rectangular solid resting on top of another
                        rectangular solid, repeated periodically in
                        target y and z directions using
                        periodic boundary conditions}
	    The TUC consists of a single rectangular ``brick'', of material
	    1, resting on top of a second rectangular brick, of material 2.
	    The centroids of the two bricks along a line in the $\hat{\bf x}_\TF$
	    direction.
	    The bricks are assumed to be homogeneous, and materials 1 and
	    2 are assumed to be isotropic.
	    The TUC
	    is then repeated in the $y_{\rm TF}$- and $z_{\rm TF}$-directions, with
	    periodicities {\tt SHPAR}$_4\times d$ and
	    {\tt SHPAR}$_5\times d$.
	    is the total volume of solid material in one TUC.
	    This option requires 5 shape parameters:\newline
	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR3 SHPAR4 SHPAR}$_5$\\
	    \ \\
	where\\
	{\tt SHPAR}$_1$ = (upper brick thickness)/$d$ in the
	$\hat{\bf x}_\TF$ direction\\
	{\tt SHPAR}$_2$ = (upper brick thickness)/$d$ in the
	$\hat{\bf y}_\TF$ direction\\
	{\tt SHPAR}$_3$ = (upper brick thickness)/$d$ in the
	$\hat{\bf z}_\TF$ direction\\
	{\tt SHPAR}$_4$ = (lower brick thickness)/$d$ in the
	$\hat{\bf x}_\TF$ direction\\
	{\tt SHPAR}$_5$ = (lower brick thickness)/$d$ in the
	$\hat{\bf y}_\TF$ direction\\
	{\tt SHPAR}$_6$ = (lower brick thickness)/$d$ in the
	$\hat{\bf z}_\TF$ direction\\
	{\tt SHPAR}$_7$ = periodicity/$d$ in the $\hat{\bf y}_\TF$ direction\\
	{\tt SHPAR}$_8$ = periodicity/$d$ in the $\hat{\bf z}_\TF$ direction\\
	\ \\
	The actual numbers of dipoles $N_{1x}$, $N_{1y}$, $N_{1z}$,
	along each dimension of the upper brick, and $N_{2x}$, $N_{2y}$,
	$N_{2z}$ along each dimension of the lower brick, just be integers.
	Usually,
	$N_{1x}={\rm nint}({\tt SHPAR}_1)$,
	$N_{1y}={\rm nint}({\tt SHPAR}_2)$,
	$N_{1z}={\rm nint}({\tt SHPAR}_3)$,
	$N_{2x}={\rm nint}({\tt SHPAR}_4)$,
	$N_{2y}={\rm nint}({\tt SHPAR}_5)$,
	$N_{2z}={\rm nint}({\tt SHPAR}_6)$,
	where ${\rm nint}(x)$ is the integer nearest to $x$, but
	under some circumstances $N_{1x}$, $N_{1y}$, $N_{1z}$,
	$N_{2x}$, $N_{2y}$, $N_{2z}$ might be larger or smaller by 1 unit.

	The overall size of the TUC (in terms of numbers of
	dipoles) is determined by parameters
	{\tt SHPAR}$_1$ -- {\tt SHPAR}$_6$:
\begin{equation}
N = \left(N_{1x}\times N_{1y}\times N_{1z}\right)
    + \left(N_{2x}\times N_{2y}\times N_{2z}\right)
\end{equation}
	The periodicity in the $\hat{\bf y}_\TF$ and $\hat{\bf z}_\TF$ directions is determined
	by parameters {\tt SHPAR}$_7$ and {\tt SHPAR}$_8$.\\
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}:
\begin{equation}
d = (4\pi/3N)^{1/3}{a}_{\rm eff}
\end{equation}

	The target
	is a periodic structure, of infinite extent in the $\hat{\bf y}_\TF$ and
	$\hat{\bf z}_\TF$ directions.
	The target axes
	are set to ${\hat{\bf a}}_1 = \hat{\bf x}_\TF$ --
	i.e., normal to the ``slab'' -- and
	${\hat{\bf a}}_2 = \hat{\bf y}_\TF$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above)
	specifying the orientation of the target axes ${\hat{\bf a}}_1$
	and  ${\hat{\bf a}}_2$ relative to the direction of incidence;
	for example,
	$\Theta=0$ would be for radiation incident normal to the slab.

	The scattering directions are specified by specifying the
	diffraction order $(M,N)$; for each diffraction order one
	transmitted wave direction and one reflected wave direction
	will be calculated, with the dimensionless $4\times4$ scattering
	matrix $S^{(2d)}$ calculated for each scattering direction.
	At large distances from the infinite slab, the
	scattered Stokes vector in the (M,N) diffraction order is
\begin{equation}
        I_{sca,i}(M,N) = \sum_{j=1}^{4} S_{ij}^{(2d)} I_{in,j}
\end{equation}
where $I_{in,j}$ is the incident Stokes vector.  See
Draine \& Flatau (2008) for interpretation of the $S_{ij}$ as
transmission and reflection efficiencies.
\index{target shape options!SLBHOLPBC}
\index{periodic boundary conditions}
\subsection{ SLBHOLPBC = Target consisting of a periodic array of
             rectangular blocks, each containing a cylindrical hole
             \label{sec:SLBHOLPBC}}
        Individual blocks have extent $(a,b,c)$ in the $(\hat{\bf x}_\TF,\hat{\bf y}_\TF,\hat{\bf z}_\TF)$
        directions,
        and the cylindrical hole has radius $r$.
        The period in the $\hat{\bf y}_\TF$-direction is $P_y$, and
        the period in the $\hat{\bf z}_\TF$-direction is $P_z$.\\
        The pertinent line in {\tt ddscat.par} should consist of\\
        {\tt SHPAR}$_1$ {\tt SHPAR}$_2$ {\tt SHPAR}$_3$ {\tt SHPAR}$_4$
        {\tt SHPAR}$_5$ {\tt SHPAR}$_6$\\
        where {\tt SHPAR}$_1 = a/d$ ($d$ is the interdipole spacing)\\
        {\tt SHPAR$_2$} = $b/a$ \\
        {\tt SHPAR$_3$} = $c/a$ \\
        {\tt SHPAR$_4$} = $r/a$ \\
        {\tt SHPAR$_5$} = $P_y/d$ \\
        {\tt SHPAR$_6$} = $P_z/d$.\\
        Ideally, $a/d=${\tt SHPAR}$_1$,
        $b/d=${\tt SHPAR}$_2\times${\tt SHPAR}$_1$, and
        $c/d=${\tt SHPAR}$_3\times${\tt SHPAR}$_1$ will be integers (so that the
        cubic lattice can accurately approximate the desired target).
        If $P_y=0$ and $P_z>0$ the target is periodic in the
        $\hat{\bf z}_\TF$-direction only.\\
        If $P_y>0$ and $P_z=0$ the target is periodic in the
        $\hat{\bf y}_\TF$-direction only.\\
        If $P_y>0$ it is required that $P_y\geq b$,
        and if $P_z>0$ it is required that $P_z\geq c$, so that
        the blocks do not overlap.\\
        With $P_y=b$ and $P_z=c$, the blocks are juxtaposed
        to form a periodic array of cylindrical holes in a solid slab.\\
        Example: {\tt ddscat\_SLBHOLPBC.par} is a sample {\tt ddscat.par}
        for a periodic array of cylindrical holes in a slab of thickness
        $a$, with holes of radius $r$, and period $P_y$ and $P_d$
\index{target shape options!SPHRN\_PBC}
\index{periodic boundary conditions}
\subsection{ SPHRN\_PBC = Target consisting of group of N spheres, extended in
                     target y and z directions using
                     periodic boundary conditions}
            This option causes {{\bf DDSCAT}}\ to create a target consisting
	    of a periodic array of $N-$sphere structures, where one
	    $N-$sphere structure consists of $N$ spheres, just
	    as for target option {\tt NANSPH} (see \S\ref{sec:SPH_ANI_N}).
	    Each sphere can be of arbitary composition, and can be
	    anisotropic if desired.
	    Information
	    for the description of one $N$-sphere structure is supplied via
	    an external file,
	    just as for target option {\tt NANSPH} --
	    see \S\ref{sec:SPH_ANI_N}).\\
	    \ \\
	    Let us refer to a single $N$-sphere structure as
            the Target Unit Cell (TUC).
	    The TUC
	    is then repeated in the $y_{\rm TF}$- and $z_{\rm TF}$-directions, with
	    periodicities {\tt PYAEFF}$\times {a}_{\rm eff}$ and
	    {\tt PZAEFF}$\times {a}_{\rm eff}$, where
	    ${a}_{\rm eff}\equiv(3V_{\rm TUC}/4\pi)^{1/3}$,
	    where $V_{\rm TUC}$
	    is the total volume of solid material in one TUC.
	    This option requires 3 shape parameters:\newline
	    {\tt DIAMX} = maximum extent of target in the target frame x
	                  direction/$d$\newline
            {\tt PYAEFF} = periodicity in target y direction/${a}_{\rm eff}$\newline
	    {\tt PZAEFF} = periodicity in target z direction/${a}_{\rm eff}$.

	    The pertinent line in {\tt ddscat.par} should read\\
	    \ \\
	{\tt SHPAR$_1$ SHPAR$_2$ SHPAR}$_3$ {\it `filename'}
        (quotes must be used)\\
	    \ \\
	where\\
	{\tt SHPAR$_1$} = target diameter in $x$ direction
	(in Target Frame) in units of $d$\\
	{\tt SHPAR$_2$}= {\tt PYAEFF}\\
	{\tt SHPAR}$_3$= {\tt PZAEFF}.\\
	{\it filename} is the name of the file specifying the locations and
	relative sizes of the spheres.\\
	\ \\
	The overall size of the TUC (in terms of numbers of
	dipoles) is determined by parameter {\tt SHPAR$_1$}, which is
	the extent of the multisphere target in the $x$-direction, in
	units of the lattice spacing $d$.
	The physical size of the TUC is specified by the value of
	${a}_{\rm eff}$ (in physical units, e.g. cm),
	specified in the file {\tt ddscat.par}.

	The location of the spheres in the TUC, and their composition, is
	specified in file {\it `filename'}.

	Please consult \S\ref{sec:SPH_ANI_N} above
	for detailed information concerning the information in this file,
	and its arrangement.}

	Note that while the spheres can be anisotropic and of differing
	composition, they can of course also be isotropic and of a single
	composition, in which case the relevant lines in the
	file {\it 'filename'} should read\\
	$x_1$ $y_1$ $z_1$ $r_1$ 1 1 1 0 0 0 \\
	$x_2$ $y_2$ $z_2$ $r_2$ 1 1 1 0 0 0 \\
	$x_3$ $y_3$ $z_3$ $r_3$ 1 1 1 0 0 0 \\
	...\\
	i.e., every sphere has isotropic composition {\tt ICOMP=1} and
	the three dielectric function orientation angles are set to zero.

	When the user uses target option {\tt SPHRN\_PBC}, the target now
	becomes a periodic structure, of infinite extent in the target
	y- and z- directions.
	The target axis ${\hat{\bf a}}_1 = \hat{\bf x}_\LF = (1,0,0)_{\rm TF}$ --
	i.e., normal to the ``slab'' -- and target
	axis ${\hat{\bf a}}_2 = \hat{\bf y}_\LF = (0,1,0)_{\rm TF}$.
	The orientation of the incident radiation relative to the target
	is, as for all other targets, set by the usual orientation
	angles $\beta$, $\Theta$, and $\Phi$
	(see \S\ref{sec:target_orientation} above).
	The scattering directions are, just as for other targets,
	determined by the scattering angles $\theta_s$, $\phi_s$ (see
	\S\ref{sec:scattering_directions} below).

	The scattering problem for this infinite structure, assumed to
	be illuminated by an incident monochromatic plane wave, is
	essentially solved ``exactly'', in the sense that the electric
	polarization of each of the constituent dipoles is due to the
	electric field produced by the incident plane wave plus {\it all}
	of the other dipoles in the infinite target.

	However, the assumed target will, of course, act as a perfect
	diffraction
	grating if the scattered radiation is calculated as the coherent
	sum of all the oscillating dipoles in this periodic structure: the
	far-field
	scattered intensity would be zero in all directions except those
	where the Bragg scattering condition is satisfied, and in those
	directions the far-field scattering intensity would be infinite.

	To suppress this singular behavior, we calculate the far-field
	scattered intensity as though the separate TUCs
	scatter incoherently.
	The scattering efficiency $Q_{\rm sca}$ and the absorption efficiency
	$Q_{\rm abs}$ are defined to be the scattering and absorption cross
	section per TUC, divided by $\pi {a}_{\rm eff}^2$, where
	${a}_{\rm eff}\equiv(3V_{\rm TUC}/4\pi)^{1/3}$, where $V_{\rm TUC}$ is
	the volume of solid material per TUC.

	Note: the user is allowed to set the target periodicity in the
	target $y_{\rm TF}$ (or $z_{\rm TF}$) direction to values that could be smaller
        than the total extent of one TUC in the target $y_{\rm TF}$
	(or $z_{\rm TF}$) direction.
	This is physically allowable, {\it provided that the spheres from
	one TUC do not overlap with the spheres from neighboring TUCs}.
	Note that {\bf DDSCAT}\ does {\it not} check for such overlap.
\index{target shape options!TRILYRPBC}
\subsection{ TRILYRPBC = Three stacked rectangular blocks,
            repeated periodically}
	The target unit cell (TUC) consists of a stack of 3 rectangular blocks
	with centers on the $\hat{\bf x}_\TF$ axis.
	The TUC is repeated in either the $\hat{\bf y}_\TF$ direction, the $\hat{\bf z}_\TF$
	direction, or both.
	A total of 11 shape parameters must be specified:\\
        {\tt SHPAR$_1$} = x-thickness of upper layer/$d$ [material 1]\\
        {\tt SHPAR$_2$} = y-width/$d$ of upper layer\\
        {\tt SHPAR}$_3$ = z-width/$d$ of upper layer\\
        {\tt SHPAR}$_4$ = x-thickness/$d$ of middle layer [material 2]\\
        {\tt SHPAR}$_5$ = y-width/$d$ of middle layer\\
        {\tt SHPAR}$_6$ = z-width/$d$ of middle layer\\
        {\tt SHPAR}$_7$ = x-width/$d$ of lower layer\\
        {\tt SHPAR}$_8$ = y-width/$d$ of lower layer\\
        {\tt SHPAR}$_9$ = z-width/$d$ of lower layer\\
        {\tt SHPAR}$_{10}$ = period/$d$ in y direction\\
        {\tt SHPAR}$_{11}$= period/$d$ in z direction

\section{Scattering Directions
\label{sec:scattering_directions}}

\subsection{ Isolated Finite Targets}

\index{scattering directions}
\index{$\theta_s$ -- scattering angle}
\index{$\phi_s$ -- scattering angle}
\index{CMDFRM -- specifying scattering directions}
\index{LFRAME}
\index{TFRAME}

{{\bf DDSCAT}}\ calculates scattering in selected directions, and elements of
the scattering matrix are reported in the output
files {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .sca} .
The scattering direction is specified through angles $\theta_s$ and $\phi_s$
(not to be confused with the angles $\Theta$ and $\Phi$ which specify the
orientation of the target relative to the incident radiation!).

For isolated finite targets ({\it i.e.,} PBC {\it not} employed)
there are two options for specifying the scattering direction, with the
option determined by the value of the string {\tt CMDFRM} read from
the input file {\tt ddscat.par}.

\begin{enumerate}
\item If the user specifies {\tt CMDFRM='LFRAME'},
      then the angles $\theta$, $\phi$
      input from {\tt ddscat.par} are understood to specify the
      scattering directions relative to the Lab Frame
      (the frame where the incident beam is in the $x-$direction).

      When {\tt CMDFRM='LFRAME'},
      the angle $\theta$ is simply the scattering angle $\theta_s$: the
      angle between
      the incident beam (in direction $\hat{\bf x}_\LF$) and the
      scattered beam ($\theta_s=0$ for forward scattering,
      $\theta_s=180^\circ$ for backscattering).

      The angle $\phi$ specifies the
      orientation of the ``scattering
      plane'' relative to the $\hat{\bf x}_\LF - \hat{\bf y}_\LF$
      plane.
      When $\phi=0$ the scattering plane is assumed to coincide with the
      $\hat{\bf x}_\LF - \hat{\bf y}_\LF$ plane.
      When $\phi=90^\circ$ the scattering plane is assumed to coincide with
      the ${\hat{\bf x}_\LF-\hat{\bf z}_\LF}$ plane.
      Within the scattering plane the scattering directions are specified by
      $0\leq\theta\leq180^\circ$.
      Thus:
\begin{equation}
\hat{\bf n}_s =
\hat{\bf x}_\LF\cos\theta + \hat{\bf y}_\LF\sin\theta\cos\phi + \hat{\bf z}_\LF\sin\theta\sin\phi
~~~,~~~
\end{equation}

\item If the user specifies {\tt CMDFRM='TFRAME'},
      then the angles $\theta$, $\phi$
      input from {\tt ddscat.par} are understood to specify the
      scattering directions $\bf\hat{n}_s$ relative to the Target Frame
      (the frame defined by target axes $\hat{\bf x}_\TF$,
      $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$).
      $\theta$ is the angle between $\hat{\bf n}_s$ and $\hat{\bf x}_\TF$,
      and $\phi$ is the angle between the $\hat{\bf n}_s-\hat{\bf x}_\TF$ plane
      and the $\hat{\bf x}_\TF-\hat{\bf y}_\TF$ plane.
      Thus:
\begin{equation}
\hat{\bf n}_s = \hat{\bf x}_\TF\cos\theta + \hat{\bf y}_\TF\sin\theta\cos\phi + \hat{\bf z}_\TF\sin\theta\sin\phi
~~~.~~~
\end{equation}

\end{enumerate}

Scattering directions for which the scattering properties are to
be calculated are set in the parameter file {\tt ddscat.par} by
specifying one or more scattering planes (determined by the value of $\phi_s$)
and for each scattering plane, the number and range of $\theta_s$ values.
The only limitation is that the number of scattering directions not exceed
the parameter {\tt MXSCA} in {\tt DDSCAT.f} (in the code as distributed it
is set to {\tt MXSCA=1000}).

\subsection{Scattering Directions for Targets that are Periodic in 1 Dimension
\label{sec:scattering_directions:1d}}

For targets that are periodic, scattering is only allowed in certain
directions (see Draine \& Flatau 2008).
If the user has chosen a PBC target (e.g,
{\tt CYLNDRPBC}, {\tt HEXGONPBC}, or {\tt RCTGL\_PBC}), {\tt SPHRN\_PBC}
but has set one of the periodicities to zero, then the target is
periodic in only one dimension -- e.g., {\tt CYLNDRPBC} could be used
to construct a single infinite cylinder.

In this case, the scattering directions are specified by giving an integral
diffraction order $M=0,\pm1,\pm2,...$ and one angle, the azimuthal angle
$\zeta$ around the target repetition axis.
The diffraction order $M$ determines the projection of ${\bf k}_{s}$
onto the repetition direction.
For a given order $M$, the scattering angles with $\zeta=0\rightarrow2\pi$
form a cone around the repetition direction.

For example, if ${\tt PYD}>0$ (target repeating in the $y_{\rm TF}$ direction),
then $M$ determines the value of $k_{sy}={\bf k}_s \cdot \hat{\bf y}_{\rm TF}$,
where $\hat{\bf y}_{\rm TF}$ is the unit vector in the Target Frame $y-$direction:
\begin{equation}
k_{sy} = k_{0y} + 2\pi M/L_y
\end{equation}
where $k_{0y}\equiv {\bf k}_0\cdot \hat{\bf y}_{\rm TF}$, where ${\bf k}_0$
is the incident
$k$ vector.
Note that  the
diffraction order $M$ {\it must} satisfy the condition
\begin{equation}\label{eq:condition on M}
(k_{0y}-k_{0})(L_y/2\pi) < M < (k_0-k_{0y})(L_y/2\pi)
\end{equation}
where $L_y={\tt PYD}\times d$ is the periodicity along the $y$ axis in the
Target Frame.
$M=0$ is always an allowed diffraction order.
\index{PYD}

The azimuthal angle $\zeta$ defines a right-handed rotation of the
scattering direction around the target repetition axis.
Thus for a target repetition axis $\hat{\bf y}_{\rm TF}$,
\begin{eqnarray}
k_{sx} &=& k_\perp \cos\zeta ~~~,
\\
k_{sz} &=& k_\perp \sin\zeta ~~~,
\end{eqnarray}
where $k_\perp = (k_0^2-k_{sy}^2)^{1/2}$, with $k_{sy}=k_{0y}+2\pi M/L_y$.
For a target with repetition axis $z_{\rm TF}$,
\begin{eqnarray}
k_{sx} &=& k_\perp \cos\zeta ~~~,
\\
k_{sy} &=& k_\perp \sin\zeta ~~~,
\end{eqnarray}
where $k_\perp = (k_0^2-k_{sz}^2)^{1/2}$, $k_{sz}=k_{0z}+2\pi M/L_z$.

The user selects a diffraction order $M$ and the azimuthal angles $\zeta$
to be used for that $M$
via one line in {\tt ddscat.par}.  An example would be
to use {\tt CYLNDRPBC} to construct an infinite cylinder with the cylinder
direction in the $\hat{\bf y}_{\rm TF}$ direction:
{\scriptsize
\begin{verbatim}
' ============== Parameter file for v7.1.0 ==================='
'**** PRELIMINARIES ****'
'NOTORQ' = CMTORQ*6 (DOTORQ, NOTORQ) -- either do or skip torque calculations
'PBCGS2' = CMDSOL*6 (PBCGS2, PBCGST, PETRKP) -- select solution method
'GPFAFT' = CMETHD*6 (GPFAFT, FFTMKL)
'GKDLDR' = CALPHA*6 (GKDLDR, LATTDR)
'NOTBIN' = CBINFLAG (NOTBIN, ORIBIN, ALLBIN)
'**** Initial Memory Allocation ****'
50 50 50 = size allowance for target generation
'**** Target Geometry and Composition ****'
'CYLNDRPBC' = CSHAPE*9 shape directive
2.0 20. 2 2.0 0. = shape parameters SHPAR1, SHPAR2, SHPAR3, SHPAR4, SHPAR5,
1         = NCOMP = number of dielectric materials
'/u/draine/work/DDA/diel/m1.33_0.01' = name of file containing dielectric function
'**** Error Tolerance ****'
1.00e-5 = TOL = MAX ALLOWED (NORM OF |G>=AC|E>-ACA|X>)/(NORM OF AC|E>)
'**** Interaction cutoff parameter for PBC calculations ****'
5.00e-3 = GAMMA (1e-2 is normal, 3e-3 for greater accuracy)
'**** Angular resolution for calculation of <cos>, etc. ****'
0.5	= ETASCA (number of angles is proportional to [(3+x)/ETASCA]^2 )
'**** Wavelengths (micron) ****'
6.283185 6.283185 1 'INV' = wavelengths (first,last,how many,how=LIN,INV,LOG)
'**** Effective Radii (micron) **** '
2 2 1 'LIN' = eff. radii (first, last, how many, how=LIN,INV,LOG)
'**** Define Incident Polarizations ****'
(0,0) (1.,0.) (0.,0.) = Polarization state e01 (k along x axis)
2 = IORTH  (=1 to do only pol. state e01; =2 to also do orth. pol. state)
1 = IWRKSC (=0 to suppress, =1 to write ".sca" file for each target orient.)
1 = IWRPOL (=0 to suppress, =1 to write ".pol" file for each (BETA,THETA))
'**** Prescribe Target Rotations ****'
0.   0.   1  = BETAMI, BETAMX, NBETA (beta=rotation around a1)
60. 60.   1  = THETMI, THETMX, NTHETA (theta=angle between a1 and k)
0.   0.   1  = PHIMIN, PHIMAX, NPHI (phi=rotation angle of a1 around k)
'**** Specify first IWAV, IRAD, IORI (normally 0 0 0) ****'
0   0   0    = first IWAV, first IRAD, first IORI (0 0 0 to begin fresh)
'**** Select Elements of S_ij Matrix to Print ****'
6	= NSMELTS = number of elements of S_ij to print (not more than 9)
11 12 21 22 31 41	= indices ij of elements to print
'**** Specify Scattered Directions ****'
'TFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
1 = number of scattering cones
0.  0. 360. 30 = M, zeta_min, zeta_max, dzeta (in degrees)
\end{verbatim}}

In this example, a single diffraction order $M=0$ is selected, and
$\zeta$ is to run from $\zeta_{\rm min}=0$ to $\zeta_{\rm max}=360^\circ$
in increments of $\delta\zeta = 30^\circ$.

There may be additional lines, one per diffraction order.  Remember, however,
that every diffraction order must satisfy eq.\ (\ref{eq:condition on M}).

\subsection{Scattering Directions for Targets for Doubly-Periodic Targets
\label{sec:scattering_directions:2d}}
\index{PBC = periodic boundary conditions}
\index{PYD}
\index{PZD}

If the user has specified nonzero periodicity in both the $y$ and $z$
directions, then the scattering directions are specified by two
integers -- the diffraction orders $M,N$ for the $\hat{\bf y},\hat{\bf z}$
directions.
The scattering directions are
\begin{equation} \label{eq:k_s(M,N)}
{\bf k}_s = \pm\, \frac{k_n}{k_0} \left({\bf k}_0\cdot\hat{\bf x}_\TF\right)\hat{\bf x}_\TF +
          \left({\bf k}_{0}\cdot\hat{\bf y}_\TF+\frac{2\pi M}{L_y}\right)\hat{\bf y}_\TF +
          \left({\bf k}_{0}\cdot\hat{\bf z}_\TF+\frac{2\pi N}{L_z}\right)\hat{\bf z}_\TF
\end{equation}
\begin{equation}
k_n \equiv \left[k_0^2 -
           \left({\bf k}_0\cdot\hat{\bf y}_\TF+\frac{2\pi M}{L_y}\right)^2 +
           \left({\bf k}_0\cdot\hat{\bf z}_\TF+\frac{2\pi N}{L_z}\right)^2
           \right]^{1/2}
\end{equation}
where the $+$ sign gives transmission, and the $-$ sign gives reflection.
The integers $M$ and $N$ {\it must} together satisfy the inequality
\begin{equation}\label{eq:condition on M and N}
(k_{0y} + 2\pi M/L_y)^2 + (k_{0z} + 2\pi N/L_z)^2 < k_{0}^2
\end{equation}
which, for small values of $L_y$ and $L_z$, may limit the scattering to only
$(M,N)=(0,0)$. [Of course, $(0,0)$ is {\it always} allowed].
For each $(M,N)$ specified in {\tt ddscat.par}, {\bf DDSCAT \vers}\ will calculate
the generalized Mueller matrix $S_{ij}^{(2d)}(M,N)$ -- see \S
At large distances from the infinite slab, the
scattered Stokes vector in the $(M,N)$ diffraction order is
\begin{equation}
        I_{sca,i}(M,N) = \sum_{j=1}^{4} S_{ij}^{(2d)}(M,N) I_{in,j}
\end{equation}
where $I_{in,j}$ is the incident Stokes vector, and $S_{ij}^{(2d)}(M,N)$
is the generalization of the $4\times4$ M\"uller scattering matrix to
targets that are periodic in 2-directions (Draine \& Flatau 2008).
There are distinct $S_{ij}^{(2d)}(M,N)$ for transmission and for
reflection, corresponding to the $\pm$ in eq.\ (\ref{eq:k_s(M,N)}).

Draine \& Flatau (2008, eq. 69-71) show how
the $S_{ij}^{(2d)}(M,N)$ are easily
related to familiar "transmission coefficients"
and "reflection coefficients".

Here is a sample {\tt ddscat.par} file as an example:
{\scriptsize
\begin{verbatim}
' ============== Parameter file for v7.1.0 ==================='
'**** PRELIMINARIES ****'
'NOTORQ' = CMTORQ*6 (DOTORQ, NOTORQ) -- either do or skip torque calculations
'PBCGS2' = CMDSOL*6 (PBCGS2, PBCGST, PETRKP) -- select solution method
'GPFAFT' = CMETHD*6 (GPFAFT, FFTMKL)
'GKDLDR' = CALPHA*6 (GKDLDR, LATTDR)
'NOTBIN' = CBINFLAG (NOTBIN, ORIBIN, ALLBIN)
'**** Initial Memory Allocation ****'
50 50 50 = dimensioning allowance for target generation
'**** Target Geometry and Composition ****'
'RCTGL_PBC' = CSHAPE*9 shape dirctive
20.0 1.0 1.0 1.0 1.0 = shape parameters PAR1, PAR2, PAR3,...
1         = NCOMP = number of dielectric materials
'/u/draine/work/DDA/diel/m1.33_0.01' = name of file containing dielectric function
'**** CONJUGATE GRADIENT DEFINITIONS ****'
0       = INIT (TO BEGIN WITH |X0> = 0)
1.00e-5 = TOL = MAX ALLOWED (NORM OF |G>=AC|E>-ACA|X>)/(NORM OF AC|E>)
'**** Interaction cutoff parameter for PBC calculations ****'
5.00e-3 = GAMMA (1e-2 is normal, 3e-3 for greater accuracy)
'**** Angular resolution for calculation of <cos>, etc. ****'
0.5	= ETASCA (number of angles is proportional to [(3+x)/ETASCA]^2 )
'**** Wavelengths (micron) ****'
6.283185 6.283185 1 'INV' = wavelengths (first,last,how many,how=LIN,INV,LOG)
'**** Effective Radii (micron) **** '
2 2 1 'LIN' = eff. radii (first, last, how many, how=LIN,INV,LOG)
'**** Define Incident Polarizations ****'
(0,0) (1.,0.) (0.,0.) = Polarization state e01 (k along x axis)
2 = IORTH  (=1 to do only pol. state e01; =2 to also do orth. pol. state)
1 = IWRKSC (=0 to suppress, =1 to write ".sca" file for each target orient.)
1 = IWRPOL (=0 to suppress, =1 to write ".pol" file for each (BETA,THETA))
'**** Prescribe Target Rotations ****'
0.   0.   1  = BETAMI, BETAMX, NBETA (beta=rotation around a1)
60. 60.   1  = THETMI, THETMX, NTHETA (theta=angle between a1 and k)
0.   0.   1  = PHIMIN, PHIMAX, NPHI (phi=rotation angle of a1 around k)
'**** Specify first IWAV, IRAD, IORI (normally 0 0 0) ****'
0   0   0    = first IWAV, first IRAD, first IORI (0 0 0 to begin fresh)
'**** Select Elements of S_ij Matrix to Print ****'
6	= NSMELTS = number of elements of S_ij to print (not more than 9)
11 12 21 22 31 41	= indices ij of elements to print
'**** Specify Scattered Directions ****'
'TFRAME' = CMDFRM (LFRAME, TFRAME for Lab Frame or Target Frame)
1 = number of scattering orders
0  0 = M, N (diffraction orders)
\end{verbatim}}

\section{Incident Polarization State\label{sec:incident_polarization}}

\index{polarization of incident radiation}
Recall that the ``Lab Frame'' is defined such that the incident radiation
is propagating along the $\hat{\bf x}_\LF$ axis.
{\bf DDSCAT}\ allows the user to specify a
general elliptical polarization
for the incident radiation, by specifying the (complex) polarization
vector ${\hat{\bf e}}_{01}$.
The orthonormal polarization state
${\hat{\bf e}}_{02}=\hat{\bf x}_\LF\times{\hat{\bf e}}_{01}^*$ is
generated automatically if {\tt ddscat.par} specifies {\tt IORTH=2}.

For incident linear polarization, one can simply set ${\hat{\bf
e}}_{01}={\hat{\bf y}}$ by specifying \\
{\tt (0,0) (1,0) (0,0)}\\
in {\tt ddscat.par}; then ${\hat{\bf e}}_{02}={\hat{\bf z}}$.
For polarization
mode ${\hat{\bf e}}_{01}$ to correspond to right-handed circular
polarization, set ${\hat{\bf e}}_{01}=({\hat{\bf y}}+i{\hat{\bf
z}})/\surd2$ by specifying {\tt (0,0) (1,0) (0,1)} in {\tt ddscat.par}
({\bf DDSCAT}\ automatically takes care of the normalization of
${\hat{\bf e}}_{01}$); then
${\hat{\bf e}}_{02}=(i{\hat{\bf y}}+{\hat{\bf z}})/\surd2$,
corresponding to left-handed circular polarization.

\section{Averaging over Scattering Directions:
         $g(1)=\langle\cos\theta_s\rangle$,
	etc.\label{sec:averaging_scattering}}
\subsection{Angular Averaging}
\index{averages over scattering angles}
\index{scattering -- angular averages}

\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f_cube_S11.eps}}
\caption{\label{fig:cube_S11}
\footnotesize
Scattered intensity for incident unpolarized light for a cube
with $m=1.5+0.001i$ and $x=2\pi a_{\rm eff}/\lambda=6.5$
(i.e., $d/\lambda=1.6676$, where $d$ is the length of a side).
The cube is tilted with respect to the incident radiation, with
$\Theta=30^\circ$, and rotated by $\beta=15^\circ$ around its axis
to break reflection symmetry.
The Mueller matrix element $S_{11}$ is shown for 4 different scattering
planes.
The strong forward scattering lobe is evident.
It is also seen that the scattered intensity is a strong function
of scattering angle $\phi_s$ as well as $\theta_s$ -- at a given
value of $\theta_s$ (e.g., $\theta_s=120^\circ$),
the scattered intensity can vary by orders of magnitude
as $\phi_s$ changes by $90^\circ$.}
\end{figure}

\index{scattering by tilted cube}
An example of scattering by a nonspherical target is shown in Fig.
\ref{fig:cube_S11}, showing the scattering for a tilted cube.
Results are shown for
four different scattering planes.

{{\bf DDSCAT}}\ automatically carries out numerical integration of various
scattering properties,
including
\begin{itemize}
\item$\langle\cos\theta_s\rangle$;
\item$\langle\cos^2\theta_s\rangle$;
\item${\bf g}=\langle\cos\theta_s\rangle\hat{\bf x}_\LF+
	\langle\sin\theta_s\cos\phi_s\rangle{\hat{\bf y}}+
	\langle\sin\theta_s\sin\phi_s\rangle{\hat{\bf z}}~$
	(see \S\ref{sec:force and torque calculation});

\item${\bf Q}_{\Gamma}$, provided
  option {\tt DOTORQ} is specified (see
\S\ref{sec:force and torque calculation}).
\end{itemize}
The angular averages are
accomplished by evaluating the scattered intensity for
selected scattering directions $(\theta_s,\phi_s)$,
and taking the appropriately weighted
sum.
Suppose that we have $N_\theta$ different values of
$\theta_s$,
\begin{equation}
\theta = \theta_j, ~~~j=1,..., N_\theta
~~~,
\end{equation}
and for each value of $\theta_j$, $N_\phi(j)$ different values of $\phi_s$:
\begin{equation}
\phi_s = \phi_{j,k}, ~~~k=1,...,N_\phi(j) ~~~.
\end{equation}
For a given $j$, the values of $\phi_{j,k}$ are assumed to be uniformly spaced:
$\phi_{j,k+1}-\phi_{j,k}=2\pi/N_\phi(j)$.
The angular average of a quantity $f(\theta_s,\phi_s)$ is
approximated by
\begin{equation}
\label{eq:average}
\langle f \rangle \equiv \frac{1}{4\pi}\int_{0}^{\pi}\sin\theta_s d\theta_s
\int_{0}^{2\pi}d\phi_s f(\theta_s,\phi_s)
~\approx~ \frac{1}{4\pi}\sum_{j=1}^{N_\theta}
                    \sum_{k=1}^{N_\phi(j)} f(\theta_j,\phi_{j,k}) \Omega_{j,k}
\end{equation}
\begin{equation}
\Omega_{j,k} = \frac{\pi}{N_\phi(j)}
\left[\cos(\theta_{j-1})-\cos(\theta_{j+1})\right]
~~~,
~~~j=2,...,N_\theta-1
~~~.
\end{equation}
\begin{equation}
\Omega_{1,k} = \frac{2\pi}{N_\phi(1)}
\left[1-\frac{\cos(\theta_1)+\cos(\theta_2)}{2}\right]
~~~,
\end{equation}
\begin{equation}
\Omega_{N_\theta,k} =
\frac{2\pi}{N_\phi(N_\theta)}
\left[
\frac{\cos(\theta_{N_\theta-1})+\cos(\theta_{N_\theta})}{2}
+1\right]
~~~.
\end{equation}
For a sufficiently large number of scattering directions
\begin{equation}
N_{\rm sca} \equiv \sum_{j=1}^{N_\theta} N_\phi(j)
\end{equation}
the sum (\ref{eq:average}) approaches
the desired integral,
but the calculations can be a significant cpu-time
burden, so efficiency is an important consideration.

\subsection{Selection of Scattering Angles $\theta_s,\phi_s$}

\index{scattering angles $\theta_s$, $\phi_s$}
\index{$\theta_s$ -- scattering angle}
\index{$\phi_s$ -- scattering angle}
Beginning with {\bf DDSCAT 6.1}, an improved approach is taken to
evaluation of the angular average.
Since targets with large values of $x=2\pi a_{\rm eff}/\lambda$
in general have strong forward scattering, it is important to obtain
good sampling of the forward scattering direction.
To implement a preferential
sampling of the forward scattering directions,
the scattering directions $(\theta,\phi)$
are chosen so that $\theta$ values correspond to equal intervals in
a monotonically increasing function $s(\theta)$.
The function $s(\theta)$ is chosen to have a
negative second derivative $d^2s/d\theta^2 < 0$
so that the density of scattering directions will be higher for
small values of $\theta$.
{\bf DDSCAT}\ takes
\begin{equation}
s(\theta) = \theta + \frac{\theta}{\theta+\theta_0} ~~~.
\end{equation}
This provides increased resolution (i.e., increased $ds/d\theta$) for
$\theta < \theta_0$.
We want this for the forward scattering lobe, so we take
\begin{equation}
\theta_0 = \frac{2\pi}{1+x}
~~.
\end{equation}
The $\theta$ values run from $\theta=0$ to $\theta=\pi$,
corresponding to uniform increments
\begin{equation}
\Delta s=\frac{1}{N_\theta-1}\left(\pi+\frac{\pi}{\pi+\theta_0}\right)
~~~.
\end{equation}
\index{$\eta$ -- parameter for selection of scattering angles}
If we now require that
\begin{equation}
\max[\Delta\theta] \approx \frac{\Delta s}{(ds/d\theta)_{\theta=\pi} }=
\eta \frac{\pi/2}{3+x}
~~~,
\end{equation}
we determine the number of values of $\theta$:
\begin{equation}
N_\theta = 1 + \frac{2(3+x)}{\eta} \frac{
\left[1+1/(\pi+\theta_0)\right]}{\left[1+\theta_0/(\pi+\theta_0)^2\right]}
~~~.
\end{equation}
Thus for small values of $x$, $\max[\Delta\theta]=30^\circ \eta$,
and for $x\gg 1$, $\max[\Delta\theta]\rightarrow 90^\circ\eta/x$.
For a sphere, minima in the scattering pattern are separated by
$\sim180^\circ/x$, so $\eta=1$ would be expected to marginally
resolve structure in the scattering function.
Smaller values of $\eta$ will obviously lead to improved sampling
of the scattering function, and more accurate angular averages.

\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f_sph_eta.eps}}
\caption{\label{fig:err_eta_sphere}
\footnotesize
Errors in $\langle\cos\theta\rangle$
and $\langle\cos^2\theta\rangle$ calculated for a $N=17904$ dipole
pseudosphere with $m=1.33+0.01i$,
as functions of $x=2\pi a/\lambda$.
Results are shown
for different values of the parameter $\eta$.
}
\end{figure}
\begin{figure}
\centerline{\includegraphics[width=8.3cm]{f_cube_eta.eps}}
\caption{\label{fig:err_eta_cube}
\footnotesize
Same as Fig.\ \ref{fig:err_eta_sphere}, but for a $N=32768$ dipole
cube with $m=1.5+0.001i$.
}
\end{figure}

The scattering angles $\theta_j$ used for the angular averaging are
then given by
\begin{equation}
\theta_j = \frac{(s_j-1-\theta_0)+
\left[(1+\theta_0-s_j)^2+4\theta_0s_j\right]^{1/2}}{2}
~~~,
\end{equation}
where
\begin{equation}
s_j = \frac{(j-1)\pi}{N_\theta-1}\left[1+\frac{1}{\pi+\theta_0}\right]
~~~j=1,...,N_\theta
~~~.
\end{equation}

For each $\theta_j$, we must choose values of $\phi$.
For $\theta_1=0$ and $\theta_{N_\theta}=\pi$
only a single value of $\phi$ is needed
(the scattering is independent of $\phi$ in these two directions).
For $0<\theta_j<\pi$ we use
\begin{equation}
N_\phi=\max\left\{3,{\rm nint}\left[4\pi\sin(\theta_j)/
(\theta_{j+1}-\theta_{j-1})\right]\right\}
~~~,
\end{equation}
where ${\rm nint}=$ nearest integer.  This provides sampling in $\phi$
consistent with the sampling in $\theta$.

\subsection{Accuracy of Angular Averaging as a Function of $\eta$}

\index{$\eta$ -- parameter for choosing scattering angles}
Figure \ref{fig:err_eta_sphere} shows the absolute errors in
$\langle\cos\theta\rangle$ and $\langle\cos^2\theta\rangle$ calculated
for a sphere with refractive index $m=1.33+0.01i$
using the above prescription for choosing scattering angles.
The error is shown as a function of
scattering parameter $x$.
We see that accuracies of order 0.01 are attained with $\eta=1$, and
that the above prescription provides an accuracy which is approximately
independent of $x$.
We recommend using values of $\eta\leq 1$ unless accuracy in the
angular averages is not important.

\section{Scattering by Finite Targets: The Mueller Matrix
\label{sec:mueller_matrix}}
\index{Mueller matrix for scattering}
\index{$S_{ij}$ -- 4$\times$4 Mueller scattering matrix}

\subsection{Two Orthogonal Incident Polarizations ({\tt IORTH=2})}
\index{IORTH parameter}
\index{ddscat.par!IORTH}

Throughout the following discussion, $\hat{\bf x}$, $\hat{\bf y}$,
$\hat{\bf z}$ are unit vector defining the Lab Frame (thus
$\hat{\bf k}_0=\hat{\bf x}$).

{\bf DDSCAT}\ internally computes the scattering properties of the
dipole array in terms of a complex scattering matrix
$f_{ml}(\theta_s,\phi_s)$ (Draine 1988), where index $l=1,2$ denotes
the incident polarization state, $m=1,2$ denotes the scattered
polarization state, and $\theta_s$,$\phi_s$ specify the scattering
direction.  Normally {{\bf DDSCAT}}\ is used with {\tt IORTH=2} in
{\tt ddscat.par}, so that the scattering problem will be solved for
both incident polarization states ($l=1$ and 2); in this subsection it
will be assumed that this is the case.

Incident polarization states $l=1,2$ correspond to polarization states
${\hat{\bf e}}_{01}$, ${\hat{\bf e}}_{02}$; recall that polarization
state ${\hat{\bf e}}_{01}$ is user-specified, and
${\hat{\bf e}}_{02}=\hat{\bf x}\times{\hat{\bf e}}_{01}^*$.\footnote{
   Draine (1988) adopted the convention
   $\hat{\bf e}_{02}=\hat{\bf x}\times\hat{\bf e}_{01}^*$.
   The customary definition of $\hat{\bf e}_{i\perp}$ is
   $\hat{\bf e}_{i\perp}\equiv\hat{\bf e}_{i\parallel}\times\hat{\bf k}$.
   Thus, if $\hat{\bf e}_{01}=\hat{\bf e}_{i\parallel}$, then
   $\hat{\bf e}_{02}=-\hat{\bf e}_{i\perp}$.
   }\footnote{
   A frequent choice is $\hat{\bf e}_{01}=\hat{\bf y}_{\rm LF}$,
   with
   $\hat{\bf e}_{02}=\hat{\bf x}_{\rm LF}\times\hat{\bf y}_{\rm LF} = \hat{\bf z}_{\rm LF}$.
   }
Scattered
polarization state $m=1$ corresponds to linear polarization of the
scattered wave parallel to the scattering plane
(${\hat{\bf e}}_1={\hat{\bf e}}_{\parallel s}=\hat{\theta}_s$) and $m=2$
corresponds to linear polarization perpendicular to the scattering
plane (in the $+\hat{\phi}_s$ direction).
The scattering matrix $f_{ml}$ was defined (Draine 1988) so that
the scattered electric field ${\bf E}_s$ is related to the incident
electric field ${\bf E}_i(0)$ at the origin
(where the target is assumed to be located) by
\index{$f_{ij}$ -- amplitude scattering matrix}
\begin{equation}
\left(
\begin{array}{c}
	{\bf E}_s\cdot\hat{\theta}_s\\
	{\bf E}_s\cdot\hat{\phi}_s
\end{array}
\right)
=
{\exp(i{\bf k}_s\cdot{\bf r})\over kr}
\left(
\begin{array}{cc}
	f_{11}&f_{12}\\
	f_{21}&f_{22}
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{01}^*\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{02}^*
\end{array}
\right) ~~~.
\label{eq:f_ml_def}
\end{equation}
\index{$S_j$ -- scattering amplitude matrix}
The 2$\times$2 complex
{\it scattering amplitude matrix} (with elements $S_1$, $S_2$,
$S_3$, and $S_4$) is defined so that (see Bohren \& Huffman 1983)
\begin{equation}
\left(
\begin{array}{c}
	{\bf E}_s\cdot\hat{\theta}_s\\
	-{\bf E}_s\cdot\hat{\phi}_s
\end{array}
\right)
=
{\exp(i{\bf k}_s\cdot{\bf r})\over -ikr}
\left(
\begin{array}{cc}
	S_2&S_3\\
	S_4&S_1
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\parallel}\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\perp}
\end{array}
\right)~~~,
\label{eq:S_ampl_def}
\end{equation}
where
${\hat{\bf e}}_{i\parallel}$, ${\hat{\bf e}}_{i\perp}$ are (real) unit vectors
for incident polarization
parallel and perpendicular to the scattering plane (with the
customary definition of
${\hat{\bf e}}_{i\perp}={\hat{\bf e}}_{i\parallel}\times{\hat{\bf x}_{\rm LF}}$).

From (\ref{eq:f_ml_def},\ref{eq:S_ampl_def}) we may write
\begin{equation}
\left(
\begin{array}{cc}
	S_2&S_3\\
	S_4&S_1
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\parallel}\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\perp}
\end{array}
\right)
=
-i
\left(
\begin{array}{cc}
	f_{11}&f_{12}\\
	-f_{21}&-f_{22}
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{01}^*\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{02}^*
\end{array}
\right) ~~~.
\label{eq:fml_rel_S_v1}
\end{equation}

Let
\begin{eqnarray}
	a&\equiv& {\hat{\bf e}}_{01}^*\cdot\hat{\bf y}_\LF~~~,\\
	b&\equiv& {\hat{\bf e}}_{01}^*\cdot\hat{\bf z}_\LF~~~,\\
	c&\equiv& {\hat{\bf e}}_{02}^*\cdot\hat{\bf y}_\LF~~~,\\
	d&\equiv& {\hat{\bf e}}_{02}^*\cdot\hat{\bf z}_\LF~~~.
\end{eqnarray}
Note that since ${\hat{\bf e}}_{01}, {\hat{\bf e}}_{02}$ could be
complex (i.e., elliptical polarization),
the quantities $a,b,c,d$ are complex.
\index{polarization -- elliptical}
Then
\begin{equation}
\left(
\begin{array}{c}
	{\hat{\bf e}}_{01}^*\\
	{\hat{\bf e}}_{02}^*
\end{array}
\right)
=
\left(
\begin{array}{cc}
	a&b\\
	c&d
\end{array}
\right)
\left(
\begin{array}{c}
	\hat{\bf y}_\LF\\
	\hat{\bf z}_\LF
\end{array}
\right)
\end{equation}
and eq. (\ref{eq:fml_rel_S_v1}) can be written
\begin{equation}
\left(
\begin{array}{cc}
	S_2&S_3\\
	S_4&S_1
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\parallel}\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\perp}
\end{array}
\right)
=
i
\left(
\begin{array}{cc}
	-f_{11}&-f_{12}\\
	f_{21}&f_{22}
\end{array}
\right)
\left(
\begin{array}{cc}
	a&b\\
	c&d
\end{array}
\right)
\left(
\begin{array}{c}
	{\bf E}_i(0)\cdot\hat{\bf y}_\LF \\
	{\bf E}_i(0)\cdot\hat{\bf z}_\LF
\end{array}
\right) ~~~.
\label{eq:fml_rel_S_v2}
\end{equation}

The incident polarization states ${\hat{\bf e}}_{i\parallel}$ and
${\hat{\bf e}}_{i\perp}$ are related to $\hat{\bf x}_\LF$, $\hat{\bf y}_\LF$, $\hat{\bf z}_\LF$ by
\begin{equation}
\left(
\begin{array}{c}
	\hat{\bf y}_\LF\\
	\hat{\bf z}_\LF
\end{array}
\right)
=
\left(
\begin{array}{cc}
	\cos\phi_s&	\sin\phi_s\\
	\sin\phi_s&	-\cos\phi_s
\end{array}
\right)
\left(
\begin{array}{c}
	{\hat{\bf e}}_{i\parallel}\\
	{\hat{\bf e}}_{i\perp}
\end{array}
\right);
\label{eq:yz_vs_eis}
\end{equation}
substituting (\ref{eq:yz_vs_eis}) into (\ref{eq:fml_rel_S_v2}) we
obtain
\begin{equation}
\left(\!
\begin{array}{cc}
	S_2&S_3\\
	S_4&S_1
\end{array}
\!\right)
\left(\!
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\parallel}\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\perp}
\end{array}
\!\right)
=
i
\left(\!
\begin{array}{cc}
	-f_{11}&-f_{12}\\
	f_{21}&f_{22}
\end{array}
\!\right)
\left(\!
\begin{array}{cc}
	a&b\\
	c&d
\end{array}
\!\right)
\left(\!
\begin{array}{cc}
	\cos\phi_s&	\sin\phi_s\\
	\sin\phi_s&	-\cos\phi_s
\end{array}
\!\right)
\left(\!
\begin{array}{c}
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\parallel}\\
	{\bf E}_i(0)\cdot{\hat{\bf e}}_{i\perp}
\end{array}
\!\right)
\label{eq:fml_rel_S_v3}
\end{equation}

Eq. (\ref{eq:fml_rel_S_v3}) must be true for all ${\bf E}_i(0)$, so we
obtain an expression for the complex scattering amplitude matrix in terms
of the $f_{ml}$:
\index{$f_{ij}$ -- scattering amplitude matrix}
\index{$S_{j}$ -- scattering amplitude matrix}
\begin{equation}
\left(
\begin{array}{cc}
	S_2&S_3\\
	S_4&S_1
\end{array}
\right)
=
i
\left(
\begin{array}{cc}
	-f_{11}&-f_{12}\\
	f_{21}&f_{22}
\end{array}
\right)
\left(
\begin{array}{cc}
	a&	b\\
	c&	d
\end{array}
\right)
\left(
\begin{array}{cc}
	\cos\phi_s&\sin\phi_s\\
	\sin\phi_s&-\cos\phi_s
\end{array}
\right)~~~.
\label{eq:fml_rel_S_v4}
\end{equation}
This provides the 4 equations used in subroutine {\tt GETMUELLER} to
compute the scattering amplitude matrix elements:
\begin{eqnarray}
S_1 &=& -i\left[
	f_{21}(b\cos\phi_s-a\sin\phi_s)
	+f_{22}(d\cos\phi_s-c\sin\phi_s)
	\right]~~~,\label{eq:S_1_relto_f21andf22}\\
S_2 &=& -i\left[
	f_{11}(a\cos\phi_s+b\sin\phi_s)
	+f_{12}(c\cos\phi_s+d\sin\phi_s)
	\right]~~~,\\
S_3 &=& i\left[
	f_{11}(b\cos\phi_s-a\sin\phi_s)
	+f_{12}(d\cos\phi_s-c\sin\phi_s)
	\right]~~~,\\
S_4 &=& i\left[
	f_{21}(a\cos\phi_s+b\sin\phi_s)
	+f_{22}(c\cos\phi_s+d\sin\phi_s)
	\right] ~~~.
\end{eqnarray}

\subsection{Stokes Parameters}
\index{Stokes vector $(I,Q,U,V)$}

It is both convenient and customary to characterize both incident and
scattered radiation by 4 ``Stokes parameters'' --
the elements of the ``Stokes vector''.
There are different conventions in the literature; we adhere to the
definitions of the Stokes vector ($I$,$Q$,$U$,$V$) adopted in the
excellent treatise by Bohren \&
Huffman (1983), to which the reader is referred for further detail.
Here are some examples of Stokes vectors $(I,Q,U,V)=(1,Q/I,U/I,V/I)I$:
\begin{itemize}
\item $(1,0,0,0)I$ : unpolarized light (with intensity $I$);
\item $(1,1,0,0)I$ : 100\% linearly polarized with ${\bf E}$ parallel to the
        scattering plane;
\item $(1,-1,0,0)I$ : 100\% linearly polarized with ${\bf E}$ perpendicular
        to the scattering plane;
\item $(1,0,1,0)I$ : 100\% linearly polarized with ${\bf E}$ at +45$^\circ$
        relative to the scattering plane;
\item $(1,0,-1,0)I$ : 100\% linearly polarized with ${\bf E}$ at -45$^\circ$
        relative to the scattering plane;
\item $(1,0,0,1)I$ : 100\% right circular polarization ({\it i.e.,} negative
        helicity);
\item $(1,0,0,-1)I$ : 100\% left circular polarization ({\it i.e.,} positive
        helicity).
\end{itemize}

\subsection{Relation Between Stokes Parameters of Incident and Scattered
Radiation: The Mueller Matrix}
\index{Mueller matrix for scattering}
\index{$S_{ij}$ -- 4$\times$4 Mueller scattering matrix}

It is convenient to describe the scattering properties of a finite
target in terms of
the $4\times4$ Mueller matrix $S_{ij}$ relating the Stokes parameters
$(I_i,Q_i,U_i,V_i)$ and
$(I_s,Q_s,U_s,V_s)$ of
the incident and scattered radiation:
\begin{equation}
\left(
\begin{array}{c}
	I_s\\
	Q_s\\
	U_s\\
	V_s
\end{array}
\right)
=
{1\over k^2r^2}
\left(
\begin{array}{cccc}
	S_{11}&S_{12}&S_{13}&S_{14}\\
	S_{21}&S_{22}&S_{23}&S_{24}\\
	S_{31}&S_{32}&S_{33}&S_{34}\\
	S_{41}&S_{42}&S_{43}&S_{44}
\end{array}
\right)
\left(
\begin{array}{c}
	I_i\\
	Q_i\\
	U_i\\
	V_i
\end{array}
\right)~~~.
\end{equation}
Once the amplitude scattering matrix elements are obtained, the Mueller
matrix elements can be computed (Bohren \& Huffman 1983):
\begin{eqnarray}
S_{11}&=&\left(|S_1|^2+|S_2|^2+|S_3|^2+|S_4|^2\right)/2~~~,\nonumber\\
S_{12}&=&\left(|S_2|^2-|S_1|^2+|S_4|^2-|S_3|^2\right)/2~~~,\nonumber\\
S_{13}&=&{\rm Re}\left(S_2S_3^*+S_1S_4^*\right)~~~,\nonumber\\
S_{14}&=&{\rm Im}\left(S_2S_3^*-S_1S_4^*\right)~~~,\nonumber\\
S_{21}&=&\left(|S_2|^2-|S_1|^2+|S_3|^2-|S_4|^2\right)/2~~~,\nonumber\\
S_{22}&=&\left(|S_1|^2+|S_2|^2-|S_3|^2-|S_4|^2\right)/2~~~,\nonumber\\
S_{23}&=&{\rm Re}\left(S_2S_3^*-S_1S_4^*\right)~~~,\nonumber\\
S_{24}&=&{\rm Im}\left(S_2S_3^*+S_1S_4^*\right)~~~,\nonumber\\
S_{31}&=&{\rm Re}\left(S_2S_4^*+S_1S_3^*\right)~~~,\nonumber\\
S_{32}&=&{\rm Re}\left(S_2S_4^*-S_1S_3^*\right)~~~,\nonumber\\
S_{33}&=&{\rm Re}\left(S_1S_2^*+S_3S_4^*\right)~~~,\nonumber\\
S_{34}&=&{\rm Im}\left(S_2S_1^*+S_4S_3^*\right)~~~,\nonumber\\
S_{41}&=&{\rm Im}\left(S_4S_2^*+S_1S_3^*\right)~~~,\nonumber\\
S_{42}&=&{\rm Im}\left(S_4S_2^*-S_1S_3^*\right)~~~,\nonumber\\
S_{43}&=&{\rm Im}\left(S_1S_2^*-S_3S_4^*\right)~~~,\nonumber\\
S_{44}&=&{\rm Re}\left(S_1S_2^*-S_3S_4^*\right)~~~.
\end{eqnarray}
These matrix elements are computed in {\tt DDSCAT} and passed to subroutine
{\tt WRITESCA} which handles output of scattering properties.
Although the Muller matrix has 16 elements, only 9 are independent.

The user can select up to 9 distinct Muller matrix elements to be
printed out in the output files
{\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .sca} and
{\tt w}{\it xxx}{\tt r}{\it yyy}{\tt ori.avg}; this choice is made by
providing a list of indices in {\tt ddscat.par}
(see Appendix \ref{app:ddscat.par}).

If the user does not provide a list of elements,
{\tt WRITESCA} will provide a ``default'' set of 6 selected elements:
$S_{11}$, $S_{21}$, $S_{31}$, $S_{41}$
(these 4 elements describe the intensity and polarization
state for scattering of unpolarized incident radiation),
$S_{12}$, and $S_{13}$.

In addition, {\tt WRITESCA} writes out the linear polarization $P$ of the
scattered light for incident unpolarized light
(see Bohren \& Huffman 1983):
\begin{equation}
P = \frac{(S_{21}^2+S_{31}^2)^{1/2}}{S_{11}} ~~~.
\end{equation}

\subsection{Polarization Properties of the Scattered Radiation}
\index{polarization of scattered radiation}
The scattered radiation is fully characterized by its Stokes vector
$(I_s,Q_s,U_s,V_s)$.
As discussed in Bohren \& Huffman (eq. 2.87), one can determine the
linear polarization of the Stokes vector by operating on it
by the Mueller matrix of an ideal linear polarizer:
\begin{equation}
{\bf S}_{\rm pol} = \frac{1}{2}
\left(\begin{array}{cccc}
  1&\cos2\xi&\sin2\xi&0\\
  \cos2\xi&\cos^22\xi&\cos2\xi\sin2\xi&0\\
  \sin2\xi&\sin2\xi\cos2\xi&\sin^22\xi&0\\
  0&0&0&0\\
\end{array}\right)
\end{equation}
where $\xi$ is the angle between the unit vector $\hat{\theta}_s$ parallel
to the scattering plane (``SP'') and the ``transmission'' axis of the linear
polarizer.  Therefore the intensity of light polarized parallel to
the scattering plane is obtained by taking $\xi=0$ and operating on
$(I_s,Q_s,U_s,V_s)$ to obtain
\begin{eqnarray}
I({\bf E}_s\parallel {\rm SP})&=&\frac{1}{2}(I_s + Q_s)\\
&=&\frac{1}{2k^2r^2}
\left[
(S_{11}+S_{21})I_i +
(S_{12}+S_{22})Q_i +
(S_{13}+S_{23})U_i +
(S_{14}+S_{24})V_i
\right]~.~~~~~
\end{eqnarray}
Similarly, the intensity of light polarized perpendicular to the scattering
plane is obtained by taking $\xi=\pi/2$:
\begin{eqnarray}
I({\bf E}_s\perp {\rm SP}) &=& \frac{1}{2}(I_s - Q_s)\\
&=& \frac{1}{2k^2r^2}
\left[
(S_{11}-S_{21})I_i +
(S_{12}-S_{22})Q_i +
(S_{13}-S_{23})U_i +
(S_{14}-S_{24})V_i
\right]~.~~~~~
\end{eqnarray}

\subsection{Relation Between Mueller Matrix and Scattering Cross Sections}
\index{Mueller matrix for scattering}
\index{polarization of scattered radiation}
\index{$S_{ij}$ -- 4$\times$4 Mueller scattering matrix}
\index{differential scattering cross section $dC_{\rm sca}/d\Omega$}
Differential scattering cross sections can be obtained directly from the
Mueller matrix elements by noting that
\begin{equation}
I_s = \frac{1}{r^2} \left(\frac{dC_{\rm sca}}{d\Omega}\right)_{s,i} I_i
~~~.
\end{equation}
Let SP be the ``scattering plane'': the plane
containing the incident and scattered directions of propagation.
Here we consider some special cases:
\begin{itemize}
\item Incident light unpolarized: Stokes vector $s_i=I(1,0,0,0)$:
\begin{itemize}
  \item cross section for scattering with
    polarization ${\bf E}_s\parallel$ SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} =
      \frac{1}{2k^2}\left( |S_2|^2 + |S_3|^2 \right)
      =
      \frac{1}{2k^2}\left( S_{11}+S_{21}\right)
    \end{equation}
  \item cross section for scattering with
    polarization ${\bf E}_s\perp$ SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} =
      \frac{1}{2k^2}\left( |S_1|^2 + |S_4|^2 \right)
      =
      \frac{1}{2k^2}\left( S_{11}-S_{21}\right)
    \end{equation}
  \item total intensity of scattered light:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} =
      \frac{1}{2k^2}\left( |S_1|^2 + |S_2|^2 + |S_3|^2 + |S_4|^2 \right)
      =
      \frac{1}{k^2} S_{11}
    \end{equation}
   \end{itemize}
\item Incident light polarized with ${\bf E}_i\parallel$ SP:
  Stokes vector $s_i=I(1,1,0,0)$:
\begin{itemize}
  \item cross
    section for scattering with polarization ${\bf E}_s\parallel$ to SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} |S_2|^2 =
      \frac{1}{2k^2}\left(S_{11}+S_{12}+S_{21}+S_{22}\right)
    \end{equation}
  \item cross
    section for scattering with polarization ${\bf E}_s\perp$ to SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} |S_4|^2 =
      \frac{1}{2k^2}\left(S_{11}+S_{12}-S_{21}-S_{22}\right)
    \end{equation}
  \item total scattering cross section:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} \left(|S_2|^2+|S_4|^2\right) =
      \frac{1}{k^2} \left(S_{11}+S_{12}\right)
    \end{equation}
\end{itemize}
\item Incident light polarized with ${\bf E}_i\perp$ SP:
  Stokes vector $s_i=I(1,-1,0,0)$:
\begin{itemize}
  \item cross section
    for scattering with polarization ${\bf E}_s\parallel$ to SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} |S_3|^2 =
      \frac{1}{2k^2}\left(S_{11}-S_{12}+S_{21}-S_{22}\right)
    \end{equation}
  \item cross section
    for scattering with polarization ${\bf E}_s\perp$ SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} |S_1|^2 =
      \frac{1}{2k^2}\left(S_{11}-S_{12}-S_{21}+S_{22}\right)
    \end{equation}
  \item total
    scattering cross section:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2} \left(|S_1|^2+|S_3|^2\right) =
      \frac{1}{k^2}\left(S_{11}-S_{12}\right)
    \end{equation}
\end{itemize}
\item Incident light linearly polarized at angle $\gamma$ to SP:
  Stokes vector $s_i = I(1,\cos2\gamma,\sin2\gamma,0)$:
\begin{itemize}
  \item cross section for scattering with polarization
    ${\bf E}_s\parallel$ to SP:
    \begin{equation}
      \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{2k^2}\left[
	(S_{11}+S_{21}) +
	(S_{12}+S_{22})\cos2\gamma +
	(S_{13}+S_{23})\sin2\gamma\right]
      \end{equation}
    \item cross section for scattering with polarization
      ${\bf E}_s\perp$ SP:
      \begin{equation}
        \frac{dC_{\rm sca}}{d\Omega} = \frac{1}{2k^2}
        \left[
	(S_{11}-S_{21}) +
	(S_{12}-S_{22})\cos2\gamma +
	(S_{13}-S_{23})\sin2\gamma
	\right]
      \end{equation}
    \item total scattering cross section:
      \begin{equation}
	\frac{dC_{\rm sca}}{d\Omega} = \frac{1}{k^2}\left[
	  S_{11} + S_{12}\cos2\gamma + S_{13}\sin2\gamma\right]
	\end{equation}
      \end{itemize}
\end{itemize}

\subsection{One Incident Polarization State Only ({\tt IORTH=1})}
\index{IORTH}
\index{ddscat.par!IORTH}

In some cases it may be desirable to limit the calculations to a
single incident polarization state -- for example, when each solution
is very time-consuming, and the target is known to have some symmetry
so that solving for a single incident polarization state may be
sufficient for the required purpose.  In this case, set {\tt IORTH=1}
in {\tt ddscat.par}.

When {\tt IORTH=1}, only $f_{11}$ and $f_{21}$ are available;
hence, {{\bf DDSCAT}}\ cannot
automatically generate the Mueller matrix elements.
In this case, the output routine {\tt WRITESCA} writes out the quantities
$|f_{11}|^2$, $|f_{21}|^2$, ${\rm Re}(f_{11}f_{21}^*)$, and
${\rm Im}(f_{11}f_{21}^*)$ for each of the scattering directions.

The differential scattering cross section for scattering with polarization
${\bf E}_s \parallel$ and $\perp$ to the scattering plane are
\begin{eqnarray}
\left(\frac{dC_{\rm sca}}{d\Omega}\right)_{s,\parallel} &=& \frac{1}{k^2}|f_{11}|^2
\\
\left(\frac{dC_{\rm sca}}{d\Omega}\right)_{s,\perp} &=& \frac{1}{k^2}|f_{21}|^2
\end{eqnarray}

Note, however, that if {\tt IPHI} is greater than 1, {{\bf DDSCAT}}\
will automatically set {\tt IORTH=2} even if {\tt ddscat.par}
specified {\tt IORTH=1}: this is because when more than one value of
the target orientation angle $\Phi$ is required, there is no
additional ``cost'' to solve the scattering problem for the second
incident polarization state, since when solutions are available for
two orthogonal states for some particular target orientation, the
solution may be obtained for another target orientation differing only
in the value of $\Phi$ by appropriate linear combinations of these
solutions.  Hence we may as well solve the ``complete'' scattering
problem so that we can compute the complete Mueller matrix.

\section{Scattering by Periodic Targets: Generalized Mueller Matrix
\label{sec:generalized mueller matrix}}
\index{Mueller matrix for infinite targets, periodic in 1-d}
\index{Mueller matrix for infinite targets, periodic in 2-d}

The Mueller scattering matrix $S_{ij}(\theta)$
described above
was originally defined (see, e.g., Bohren \& Huffman 1983)
to describe scattering of incident plane waves
by finite targets, such as aerosol particles or dust grains.

Draine \& Flatau (2008) have extended the Mueller scattering matrix
formalism to also apply to targets that are periodic and infinite in
one or two dimensions (e.g., an infinite chain of particles, or a
two-dimensional array of particles).

\subsection{Mueller Matrix $S_{ij}^{(1d)}$ for Targets
Periodic in One Direction}

The dimensionless
$4\times4$ matrix $S_{ij}^{(1d)}(M,\zeta)$ describes the scattering properties
of targets that are periodic in one dimension.
In the radiation zone,
for incident Stokes vector $I_{\rm in}$, the scattered Stokes vector in
direction $(M,\zeta)$ (see \S\ref{sec:scattering_directions:1d})
is (see Draine \& Flatau 2008, eq.\ 63)
\begin{equation}
I_{{\rm sca},i}(M,\zeta) =
\frac{1}{k_0R}\sum_{j=1}^4 S_{ij}^{(1d)}(M,\zeta) \, I_{{\rm in},j}
~~~,~~~
\end{equation}
where $R$ is the distance from the target repetition axis.

{\bf DDSCAT \vers}\ reports the
scattering matrix elements $S_{ij}^{(nd)}$ in the output files
{\tt w}{\it aaa}{\tt r}{\it bbb}{\tt k}{\it ccc}{\tt .sca}.

\subsection{Mueller Matrix $S_{ij}^{(2d)}(M,N)$ for Targets Periodic in
Two Directions}

For targets that are periodic in two directions, the scattering intensities
are described by
the dimensionless
$4\times4$ matrix $S_{ij}^{(2d)}(M,N)$.
In the radiation zone,
for incident Stokes vector $I_{{\rm in}}$, the scattered Stokes
vector in scattering order $(M,N)$ is
(see Draine \& Flatau 2008, eq.\ 64)
\begin{equation}
I_{{\rm sca},i}(M,N) =
\sum_{j=1}^4 S_{ij}^{(2d)}(M,N) \, I_{{\rm in},j}
~~~,~~~
\end{equation}
where
integers $(M,N)$ define the scattering order
(see \S\ref{sec:scattering_directions:2d}).  For given $(M,N)$ there
are actually two possible scattering directions -- corresponding to
transmission and reflection (see \S\ref{sec:scattering_directions:2d}),
and for each there is a value of $S_{ij}^{(2d)}(M,N)$.

For targets with 2-d periodicity, the scattering matrix elements
$S_{ij}^{(2d)}(M,N)$ are directly related to the usual
transmission coefficient and reflection coefficient
(see Draine \& Flatau 2008, eq.\ 69-71).

\index{anisotropic materials!BETADF!THETADF!PHIDF!Dielectric Frame (DF)}
\section{Composite Targets with Anisotropic Constituents
         \label{sec:composite anisotropic targets}}

Section \ref{sec:target_generation} includes
targets composed of anisotropic materials
(ANIELLIPS, ANIRCTNGL, ANI\_ELL\_2, ANI\_ELL\_3).
However, in each of these cases it is assumed that the dielectric tensor
of the target material is diagonal in the
\index{Target Frame}
``Target Frame''.  For targets
consisting of a single material (in a single domain), it is obviously possible
to choose the ``Target Frame'' to coincide with a frame in which the
dielectric tensor is diagonal.

However, for inhomogeneous targets containing anisotropic materials as,
e.g., inclusions, the optical axes of the constituent material may be
oriented differently in different parts of the target.  In this case,
it is obviously not possible to choose a single reference frame such that
the dielectric tensor is diagonalized for all of the target material.

To extend DDSCAT to cover this case, we must allow for off-diagonal elements
of the dielectric tensor, and therefore of the dipole polarizabilities.
It will be assumed that the dielectric tensor $\epsilon$ is symmetric
(this excludes magnetooptical materials -- check this).

Let the material at a given location in the grain have a dielectric
tensor
\index{dielectric tensor}
with complex eigenvalues $\epsilon^{(j)}$, $j=1-3$.  These are the
diagonal elements of the dielectric tensor in a frame where it is diagonalized
(i.e., the frame coinciding with the principal axes of the dielectric tensor).
Let this frame in which the dielectric tensor is diagonalized have
unit vectors $\hat{\bf e}_j$ corresponding to the principal axes of
the dielectric tensor.
We need to describe the orientation of the
\index{Dielectric Frame (DF)}
``Dielectric Frame'' (DF)
-- defined by the ``dielectric axes'' $\hat{\bf e}_j$ --
relative to the Target Frame.
It is convenient to do so with rotation angles analogous to the rotation
angles $\Theta$, $\Phi$, and $\beta$ used
to describe the orientation of the Target Frame in the Lab Frame:
Suppose that we start with unit vectors $\hat{\bf e}_j$ aligned with the
target frame $\hat{\bf x}_j$.
\begin{enumerate}
\index{$\Theta_{\rm DF}$}
\item Rotate the DF through an angle $\theta_{\rm DF}$
around axis $\hat{\bf y}_\TF$,
so that $\theta_{\rm DF}$ is now the angle between $\hat{\bf e}_1$ and
$\hat{\bf x}_\TF$.
\index{$\Phi_{\rm DF}$}
\item Now rotate the DF through an angle $\phi_{\rm DF}$
around axis $\hat{\bf x}_\TF$,
in such a way that $\hat{\bf e}_2$ remains in the $\hat{\bf x}_\TF-\hat{\bf e}_1$
plane.
\index{$\beta_{\rm DF}$}
\item Finally, rotate the DF through an angle $\beta_{\rm DF}$ around axis
$\hat{\bf e}_1$.
\end{enumerate}
The unit vectors $\hat{\bf e}_i$ are related to the TF basis vectors
$\hat{\bf x}_\TF$, $\hat{\bf y}_\TF$, $\hat{\bf z}_\TF$ by:
\begin{eqnarray}
{\hat{\bf e}}_1 &=&   \hat{\bf x}_\TF \cos\theta_{\rm DF}
+ \hat{\bf y}_\TF \sin\theta_{\rm DF} \cos\phi_{\rm DF}
+ \hat{\bf z}_\TF \sin\theta_{\rm DF} \sin\phi_{\rm DF}
	\\
{\hat{\bf e}}_2 &=& - \hat{\bf x}_\TF \sin\theta_{\rm DF} \cos\beta_{\rm DF}
+ \hat{\bf y}_\TF [\cos\theta_{\rm DF} \cos\beta_{\rm DF} \cos\phi_{\rm DF}-
\sin\beta_{\rm DF} \sin\phi_{\rm DF}] \nonumber\\
&&+ \hat{\bf z}_\TF [\cos\theta_{\rm DF} \cos\beta_{\rm DF} \sin\phi_{\rm DF}+
\sin\beta_{\rm DF} \cos\phi_{\rm DF}]
	\\
{\hat{\bf e}}_3 &=&   \hat{\bf x}_\TF \sin\theta_{\rm DF} \sin\beta_{\rm DF}
- \hat{\bf y}_\TF [\cos\theta_{\rm DF} \sin\beta_{\rm DF} \cos\phi_{\rm DF}+
\cos\beta_{\rm DF} \sin\phi_{\rm DF}] \nonumber\\
  &&         - \hat{\bf z}_\TF [\cos\theta_{\rm DF} \sin\beta_{\rm DF}
\sin\phi_{\rm DF}-\cos\beta_{\rm DF} \cos\phi_{\rm DF}]
\end{eqnarray}
or, equivalently:
\begin{eqnarray}
\hat{\bf x}_\TF &=&   {\hat{\bf e}}_1 \cos\theta_{\rm DF}
           - {\hat{\bf e}}_2 \sin\theta_{\rm DF} \cos\beta_{\rm DF}
           + {\hat{\bf e}}_3 \sin\theta_{\rm DF} \sin\beta_{\rm DF} \\
\hat{\bf y}_\TF &=&   {\hat{\bf e}}_1 \sin\theta_{\rm DF} \cos\phi_{\rm DF}
           + {\hat{\bf e}}_2 [\cos\theta_{\rm DF} \cos\beta_{\rm DF} \cos\phi_{\rm DF}-\sin\beta_{\rm DF} \sin\phi_{\rm DF}]
\nonumber\\
&&           - {\hat{\bf e}}_3 [\cos\theta_{\rm DF} \sin\beta_{\rm DF} \cos\phi_{\rm DF}+\cos\beta_{\rm DF} \sin\phi_{\rm DF}]
\\
\hat{\bf z}_\TF &=&   {\hat{\bf e}}_1 \sin\theta_{\rm DF} \sin\phi_{\rm DF}
           + {\hat{\bf e}}_2 [\cos\theta_{\rm DF} \cos\beta_{\rm DF} \sin\phi_{\rm DF}+\sin\beta_{\rm DF} \cos\phi_{\rm DF}]
\nonumber\\
&&           - {\hat{\bf e}}_3 [\cos\theta_{\rm DF} \sin\beta_{\rm DF} \sin\phi_{\rm DF}-\cos\beta_{\rm DF} \cos\phi_{\rm DF}]
\end{eqnarray}
Define the rotation matrix
$R_{ij}\equiv \hat{\bf x}_i\cdot\hat{\bf e}_j$:
{\footnotesize
\begin{equation}
R_{ij}=
\end{equation}
\begin{equation}
\left(
\begin{array}{ccc}
\cos\theta_{\rm DF} &
\sin\theta_{\rm DF}\cos\phi_{\rm DF} &
\sin\theta_{\rm DF}\sin\phi_{\rm DF} \\
\!\!\!\!\!\!-\!\sin\theta_{\rm DF}\cos\beta_{\rm DF}\! &
\cos\theta_{\rm DF}\cos\beta_{\rm DF}\cos\phi_{\rm DF}\!-\!
\sin\beta_{\rm DF}\sin\phi_{\rm DF} &
\cos\theta_{\rm DF}\cos\beta_{\rm DF}\sin\phi_{\rm DF}\!+\!
\sin\beta_{\rm DF}\cos\phi_{\rm DF}\!\!\!\!
\\
\sin\theta_{\rm DF}\sin\beta_{\rm DF} &
\!\!\!-\!\cos\theta_{\rm DF}\sin\beta_{\rm DF}\cos\phi_{\rm DF}\!-\!
\cos\beta_{\rm DF}\sin\phi_{\rm DF}\!\! &
\!-\!\!\cos\theta_{\rm DF}\sin\beta_{\rm DF}\sin\phi_{\rm DF}\!+\!
\cos\beta_{\rm DF}\cos\phi_{\rm DF}\!\!\!\!\!
\end{array}
\right)
\end{equation}
and its inverse
\begin{equation}
(R^{-1})_{ij} =
\end{equation}
\begin{equation}
\left(
\begin{array}{ccc}
\cos\theta_{\rm DF} &
-\sin\theta_{\rm DF}\cos\beta_{\rm DF} &
\sin\theta_{\rm DF}\sin\beta_{\rm DF}
\\
\!\!\!\sin\theta_{\rm DF}\cos\phi_{\rm DF}\!\! &
\!\!\cos\theta_{\rm DF}\cos\beta_{\rm DF}\cos\phi_{\rm DF}\!-\!
\sin\beta_{\rm DF}\sin\phi_{\rm DF} &
-\cos\theta_{\rm DF}\sin\beta_{\rm DF}\cos\phi_{\rm DF}\!-\!
\cos\beta_{\rm DF}\sin\phi_{\rm DF}\!\!\!\!
\\
\!\!\!\sin\theta_{\rm DF}\sin\phi_{\rm DF} &
\!\!\cos\theta_{\rm DF}\cos\beta_{\rm DF}\sin\phi_{\rm DF}\!+\!
\sin\beta_{\rm DF}\cos\phi_{\rm DF}\!\! &
-\cos\theta_{\rm DF}\sin\beta_{\rm DF}\sin\phi_{\rm DF}\!+\!
\cos\beta_{\rm DF}\cos\phi_{\rm DF}\!\!\!\!
\end{array}
\right)
\end{equation}
}
The dielectric tensor is diagonal in the DF.
If we calculate the dipole polarizabilility tensor in the DF it will
also be diagonal, with elements
\begin{equation}
\alpha^{\rm DF} =
\left(
\begin{array}{ccc}
\alpha_{11}^{\rm DF} & 0 & 0 \\
0 & \alpha_{22}^{\rm DF} & 0 \\
0 & 0 & \alpha_{33}^{\rm DF}
\end{array}
\right)
\end{equation}
The polarizability tensor in the TF is given by
\begin{equation}
\label{eq:alpha^TF from alpha^DF}
(\alpha^{\rm TF})_{im} =
R_{ij} (\alpha^{\rm DF})_{jk} (R^{-1})_{km}
\end{equation}

Thus, we can describe a general anisotropic material if we provide,
for each lattice site, the three diagonal elements $\epsilon_{jj}^{\rm DF}$
of the dielectric
tensor in the DF, and the three rotation angles $\theta_{\rm DF}$,
$\beta_{\rm DF}$, and $\phi_{\rm DF}$.
We first use the LDR prescription and the elements to obtain the
three diagonal elements $\alpha_{jj}^{\rm DF}$ of the polarizability
tensor in the DF.
We then calculate the polarizability tensor $\alpha^{\rm TF}$ using
eq.\ (\ref{eq:alpha^TF from alpha^DF}).

\section{Postprocessing: Calculating ${\bf E}$ and ${\bf B}$ In or Near the Target
            \label{sec:calculate E and B fields}
            }
\index{Electric field in or near the target}
\index{Magnetic field in or near the target}
For some scientific applications (e.g., surface-enhanced Raman
scattering) one wishes to calculate the electric field just outside
the target boundary.  It may also be of interest to calculate the
electromagnetic field at positions within the target volume.
{\bf DDSCAT}\ includes tools to carry out such calculations.

When {\bf DDSCAT}\ is run with option {\tt IWRPOL}=1\index{IWRPOL}, it creates
files {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .pol}{\it n}
	for {\it n}=1 and (if {\tt IORTH=2}) {\it n}=2.
These files store the solution for the dipole polarizations, allowing
postprocessing.
Of particular interest is calculation of the electromagnetic
field at locations in or near the target.

To facilitate this, we provide a Fortran subroutine
{\tt READPOL}\index{READPOL} (in the
file {\tt readpol.f90}) that
reads in data from
the {\tt w}{\it xxx}{\tt r}{\it yyy}{\tt k}{\it zzz}{\tt .pol}{\it n}
file.

In addition, we provide a Fortran program {\tt DDfield.f90}\index{DDfield}
that calls
subroutine {\tt READPOL}, and uses the data read in by {\tt READPOL}
to calculate the electric and magnetic field at locations
specified by the user.
The ${\bf E}$ and ${\bf B}$ contributions from the oscillating dipoles
are calculated [including retardation effects -- see, e.g., equations
(7) and (10) from Draine \& Weingartner (1996)] giving the ``exact''
electromagnetic field contributed by the oscillating dipoles.  The incident
plane wave field is added to the field generated by the oscillating dipoles
to obtain the total ${\bf E}$ and ${\bf B}$ at the specified location.

The user is interested in the continuous and finite field in a real target,
as opposed to the field generated by an array of oscillating point dipoles,
which diverges as one approaches any one of the dipoles.
To suppress the divergences, the contributions of dipoles
within a distance $d$ of the selected point is obtained by multiplying the
``exact''
contribution from the point dipole by a factor $\phi(r)$ that goes
to zero more rapidly than $r^3$, thus ensuring
that
the electric field contribution from an individual dipole
goes to zero as we approach the dipole location.
This is desired, because the discrete dipole approximation is based on the
assumption that a given dipole is polarized by the electric field from the
incident wave plus the electric field contributed
by all {\it other} dipoles.
When dealing with periodic (i.e., infinite) targets, the function
$\phi(r)$ smoothly suppresses the contributions from distant dipoles,
allowing the summations to be truncated.
Please refer to
Draine \& Flatau (2008) for further discussion of $\phi(r)$ and
examples of results calculated by {\tt DDfield}.

To calculate the electric and magnetic field at user-selected locations:
\begin{itemize}
\item Run {\tt ddscat} with {\tt WRPOL}=1 to create a file with the
     stored polarization
     (for example,\\ {\tt w000r000k000.pol1})
\item Compile and link the {\tt DDfield} code, by entering the {\tt src}
      directory and typing\\
     {\tt make ddfield} \\
     This will create an executable named {\tt DDfield}
\item Use an editor to create a file {\tt ddfield.in} providing the
      name of the file ({\it in quotes!, where ``quote" should be the
      ``apostrophe" character})
      containing the stored target polarization, \\
      followed by the value of the {\it interaction cutoff parameter}
      $\gamma$ (see Draine \& Flatau 2008, eq.\ 79) to be used, \\
      followed
      by the information defining a "track" along which ${\bf E}$ and ${\bf B}$
      will be sampled.  The track is specified by the beginning and end
      points $(x_1,y_1,z_1)$ and $(x_N,y_N,z_N)$ in the TF,
      in units of dipole spacing $d$, followed by an
      integer specifying the number $N$ of points in the track.
      Thus, for example:\\
     '{\it filename}'\\
     $\gamma$\\
     $x_1/d$~~ $y_1/d$~~ $z_1/d$~~ $x_N/d$~~ $y_N/d$~~ $z_N/d$~~ $N$
     ~~~~{\it for track 1}\\
     $x_1/d$~~ $y_1/d$~~ $z_1/d$~~ $x_N/d$~~ $y_N/d$~~ $z_N/d$~~ $N$
     ~~~~{\it for track 2}\\
     ...\\
     $x_1/d$~~ $y_1/d$~~ $z_1/d$~~ $x_N/d$~~ $y_N/d$~~ $z_N/d$~~ $N$
     ~~~~{\it for last track}\\
     \\
     Here ~$x_j/d$~~ $y_j/d$~~ $z_j/d$~ are integer or decimal numbers giving the
     coordinates (in the ``Target Frame'', in units of the lattice
     spacing $d$) of the positions at which the electromagnetic field is to
     be evaluated.

\item Type\\
     \hspace*{2em}{\tt ddfield}\\
     to run the executable.

\item The output will be written to two files, {\tt DDfield.E} and
{\tt DDBfield.B}, containing the electric and magnetic fields
(given as complex vectors) at each chosen location.  The fields are evaluated
at a time when the
factor $e^{-i\omega t}$ is 1 (e.g., $t=0$, $2\pi/\omega$, ....).
\end{itemize}

\subsection{Sample Calculation}

Here is an example of an input file {\tt ddfield.in}:
{\footnotesize\begin{verbatim}
'w000r000k000.pol1'      = name of file with stored polarization
5.00e-3 = gamma (interaction cutoff parameter)
-64.   0.  0. 32.  0.  0. 481   (xa,ya,za , xb,yb,zb , NAB)
\end{verbatim}}

The above example will sample the EM field at 481 points uniformly
spaced along a track running from $(x/d, y/d, z/d)=(-64, 0, 0)$
to $(32, 0, 0)$ at intervals of $\delta x=0.2d$.

Here's a second example of an input file {\tt ddfield.in}:
{\footnotesize\begin{verbatim}
'w000r000k000.pol1'     = name of file with stored polarization
5.00e-3 = gamma (interaction cutoff parameter)
-64. 32.64 32.64 32 32.64 32.64 481  (xa,ya,za , xb,yb,zb , NAB)
\end{verbatim}}

Note that $x$,
$y$, $z$ are specified in the {\bf Target Frame}, and in units of $d$.
To properly locate these you will need to know the
location of the TF origin $(0,0,0)$ -- see the target descriptions in
\S\S\ref{sec:target_generation},\ref{sec:target_generation_PBC}.

We have run {\tt DDfield} on the output created by the ``test problem''
of a rectangular gold block with
dimensions $0.5{\mu{\rm m}}\times1{\mu{\rm m}}\times1{\mu{\rm m}}$ illuminated
by a plane wave with wavelength $\lambda=0.5{\mu{\rm m}}$
incident normal to the $1{\mu{\rm m}}\times1{\mu{\rm m}}$ surface.
The Au
target has refractive index $m=0.9656+1.8628i$
(dielectric function $\epsilon=-2.5374+3.5975i$).
(see \S\ref{sec:parameter_file}).

For the $(x,0,0)$ track running through the center of the slab,
the output {\tt DDfield.E} file will look like

\tiny
\begin{verbatim}
    131072 = number of dipoles in Target
Extent of occupied lattice sites
       1      32 = JXMIN,JXMAX
       1      64 = JYMIN,JYMAX
       1      64 = JZMIN,JZMAX
  -32.000000    0.000000 = (x_TF/d)min,(x_TF/d)max
  -32.000000   32.000000 = (y_TF/d)min,(y_TF/d)max
  -32.000000   32.000000 = (z_TF/d)min,(z_TF/d)max
   -0.499997    0.000000 = xmin(TF),xmax(TF) (phys. units)
   -0.499997    0.499997 = ymin(TF),ymax(TF) (phys. units)
   -0.499997    0.499997 = zmin(TF),zmax(TF) (phys. units)
    0.015625 = d (phys units)
    0.000000    0.000000 = PYD,PZD = period_y/dy, period_z/dz
    0.000000    0.000000 = period_y, period_z (phys. units)
    0.500000 = wavelength in ambient medium (phys units)
    0.196349 = k_x*d for incident wave
    0.000000 = k_y*d for incident wave
    0.000000 = k_z*d for incident wave
 5.000E-03 = gamma (parameter for summation cutoff)
  0.000000  0.000000 = (Re,Im)E_inc,x(0,0,0)
  1.000000  0.000000 = (Re,Im)E_inc,y(0,0,0)
  0.000000  0.000000 = (Re,Im)E_inc,z(0,0,0)
    x/d      y/d      z/d     ----- E_x -----   ----- E_y ------   ----- E_z -----
 -64.0000   0.0000   0.0000  0.00000  0.00000   0.26693 -0.79540   0.00000  0.00000
 -63.8000   0.0000   0.0000  0.00000  0.00000   0.23994 -0.72895   0.00000  0.00000
 -63.6000   0.0000   0.0000  0.00000  0.00000   0.21246 -0.66168   0.00000  0.00000
 -63.4000   0.0000   0.0000  0.00000  0.00000   0.18452 -0.59368   0.00000  0.00000
 -63.2000   0.0000   0.0000  0.00000  0.00000   0.15614 -0.52505   0.00000  0.00000
 -63.0000   0.0000   0.0000  0.00000  0.00000   0.12738 -0.45588   0.00000  0.00000
 -62.8000   0.0000   0.0000  0.00000  0.00000   0.09826 -0.38630   0.00000  0.00000
 -62.6000   0.0000   0.0000  0.00000  0.00000   0.06882 -0.31641   0.00000  0.00000
 -62.4000   0.0000   0.0000  0.00000  0.00000   0.03910 -0.24629   0.00000  0.00000
 -62.2000   0.0000   0.0000  0.00000  0.00000   0.00915 -0.17606   0.00000  0.00000
 -62.0000   0.0000   0.0000  0.00000  0.00000  -0.02102 -0.10582   0.00000  0.00000
 -61.8000   0.0000   0.0000  0.00000  0.00000  -0.05135 -0.03568   0.00000  0.00000
 -61.6000   0.0000   0.0000  0.00000  0.00000  -0.08178  0.03426   0.00000  0.00000
 -61.4000   0.0000   0.0000  0.00000  0.00000  -0.11230  0.10390   0.00000  0.00000
 -61.2000   0.0000   0.0000  0.00000  0.00000  -0.14287  0.17314   0.00000  0.00000
 -61.0000   0.0000   0.0000  0.00000  0.00000  -0.17343  0.24187   0.00000  0.00000
 ...
  30.0000   0.0000   0.0000  0.00000  0.00000  -0.34868 -0.04369   0.00000  0.00000
  30.2000   0.0000   0.0000  0.00000  0.00000  -0.34974 -0.05307   0.00000  0.00000
  30.4000   0.0000   0.0000  0.00000  0.00000  -0.35052 -0.06257   0.00000  0.00000
  30.6000   0.0000   0.0000  0.00000  0.00000  -0.35103 -0.07216   0.00000  0.00000
  30.8000   0.0000   0.0000  0.00000  0.00000  -0.35124 -0.08185   0.00000  0.00000
  31.0000   0.0000   0.0000  0.00000  0.00000  -0.35119 -0.09163   0.00000  0.00000
  31.2000   0.0000   0.0000  0.00000  0.00000  -0.35082 -0.10148   0.00000  0.00000
  31.4000   0.0000   0.0000  0.00000  0.00000  -0.35020 -0.11141   0.00000  0.00000
  31.6000   0.0000   0.0000  0.00000  0.00000  -0.34926 -0.12140   0.00000  0.00000
  31.8000   0.0000   0.0000  0.00000  0.00000  -0.34804 -0.13144   0.00000  0.00000
  32.0000   0.0000   0.0000  0.00000  0.00000  -0.34645 -0.14151   0.00000  0.00000
\end{verbatim}}

In the example given, the incident wave is propagating in the $+x$ direction.
The first layer of dipoles in the rectangular target is at $x/d=-31.5$, and the
last layer is at $x/d=-0.5$.
The ``surface'' of the target is at $x/d=-32$ ($x=-0.50{\mu{\rm m}}$) and
$x/d=0$ ($x=0$).

Figure \ref{fig:E_block} shows how $|E|^2$ varies along the tracks specified by the
above two sample {\tt ddfield.in} files.
As expected, the wave is strongly suppressed in the interior of the Au block.

\begin{figure}
\centerline{\includegraphics[width=8.3cm,angle=270]{f_E_block.eps}}
\caption{\label{fig:E_block}
         \footnotesize
         Solid line: $|E|^2$ on track passing through center of Au block for
         the sample problem calculated using target option {\tt RCTGLPRSM}.
         Dotted lines show where the Au block surface is located.
         Note how weak the ${\bf E}$ field is inside the Au.
         Dashed line: $|E|^2$ on track passing near the corner of
         the slab.
         Incident radiation is propagating in the $+x$ direction.
}
\end{figure}
\section{Finale}

This User Guide is somewhat inelegant, but we hope that it will prove
useful.  The structure of the {\tt ddscat.par} file is intended to be
simple and suggestive so that, after reading the above notes once, the
user may not have to refer to them again.

Known bugs in
{\bf DDSCAT}\ will be posted
at the {\bf DDSCAT}\ web site,\\
\hspace*{3em}{\tt http://www.astro.princeton.edu/}$\sim${\tt draine/DDSCAT.html}\\
and the latest version of {\bf DDSCAT}\ will always be available at this site.
The source code is also available at\\
\hspace*{3em}{\tt http://code.google.com/p/ddscat/}\\
There is also a wiki:\\
\hspace*{3em}{\tt http://ddscat.wikidot.com/start}

\medskip
Users are encouraged to provide B. T. Draine
({\tt draine@astro.princeton.edu}) with their
email address; email notification of bug fixes,
and any new releases of {\bf DDSCAT},
will be made known to those who do!

\index{SCATTERLIB}
P. J. Flatau maintains the WWW page
``SCATTERLIB - Light Scattering Codes Library"
with URL {\tt http://atol.ucsd.edu/$\sim$pflatau}.
The SCATTERLIB Internet site is a library of light scattering codes.
Emphasis is on providing source
codes (mostly FORTRAN). However, other information related to scattering
on spherical and
non-spherical particles is collected: an extensive list of references
to light scattering methods, refractive index, etc.
This URL page contains section on the discrete dipole approximation.

\medskip
Concrete suggestions for improving {{\bf DDSCAT}}\ (and this User Guide) are
welcomed.

\medskip
Users of {\bf DDSCAT}\ may wish to cite papers describing DDA theory and its
implementation, such as Draine (1988), Draine \& Flatau (2004),
and Draine \& Flatau (2008).  The latter reference describes extension of
the DDA to periodic structures, and generalization of the Mueller
scattering matrix to describe scattering by 1-d and 2-d periodic
structures.

To cite this User Guide, we suggest the following
citation:\\
\hspace*{3em}Draine, B.T., \& Flatau, P.J. 2010,
``User Guide for the Discrete
Dipole Approximation Code\\
\hspace*{3em}DDSCAT (Version 7.1)'', http://arxiv.org/abs/1002.1505\\

\bigskip
Finally, the authors have one special request:
We would appreciate preprints and (especially!)
reprints of any papers which make use of {{\bf DDSCAT}}!

\section{Acknowledgments}

\begin{itemize}
\index{ESELF}
\item The routine {\tt ESELF} making use of the FFT was originally written by
Jeremy Goodman, Princeton University Observatory.
\item The FFT routine {\tt FOURX}, used in the comparison of different
FFT routines,
is based on a FFT routine written by Norman
Brenner (Brenner 1969).
\index{GPFAPACK}
\item The {\tt GPFAPACK} package was written by Clive Temperton (1992), and
generously made available by him for use with {\tt DDSCAT}.
\item Much of the work involved in modifying {\tt DDSCAT} to use {\tt MPI}
was done by Matthew Collinge, Princeton University.
\item The conjugate gradient routine {\tt ZBCG2} was written by
M.A. Botchev \\
({\tt http://www.math.utwente.nl/$\sim$botchev/}), based on
earlier work by D.R. Fokkema (Dept. of Mathematics, Utrecht University).
\item Art Lazanoff (NASA Ames Research Center) did most of the coding necessary
to use OpenMP and to use the {\tt DFTI} library routine from the
\Intel\ Math Kernel Library, as well as considerable testing of the new
code.
\end{itemize}
We are deeply
indebted to all of these authors for making their work and code available.

We wish also to acknowledge bug reports and suggestions from {{\bf DDSCAT}}
users, including
Rodrigo Alcaraz de la Osa,
Michel Devel,
Souraya Goumri-Said,
Bala Krishna Juluri,
Stefan Kniefl,
Henrietta Lemke,
Georges Levi,
Shuzhou Li,
Wang Lin,
Paul Mulvaney,
Timo Nousianen,
Stuart Prescott,
Sanaz Vahidinia,
Berhnard Wasserman,
and Mike Wolff.

Development of {{\bf DDSCAT}}\ was supported in part by
National Science Foundation
grants AST-8341412, AST-8612013, AST-9017082, AST-9319283,
AST-9616429, AST-9988126, AST-0406883 to BTD,
in part by support from the Office of Naval Research
Young Investigator Program to PJF, in part by DuPont Corporate Educational
Assistance to PJF, and in part by the United Kingdom Defence Research Agency.

redpajama_set_name: RedPajamaArXiv