                                 DDSCAT.5a.8
                                 ***********

                               Bruce T. Draine
                       Princeton University Observatory
                              Princeton NJ 08544
                         (draine@astro.princeton.edu)

                                     and

                               Piotr J. Flatau
                      University of California, San Diego
                      Scripps Institution of Oceanography
                  La Jolla Shores Dr., La Jolla CA 92093-0221
                            (pflatau@ucsd.edu)

                         [last revised: 97.07.25]
          Copyright (C) 1994,1995,1996,1997 B.T. Draine and P.J. Flatau


                               1. INTRODUCTION
                               ****************

   DDSCAT is a FORTRAN program to calculate scattering and absorption of
electromagnetic radiation by arbitrary targets using the "Discrete Dipole
Approximation" (DDA).  In this approximation the target is replaced by
an array of point dipoles; the electromagnetic scattering problem for the
array of point dipoles is then solved essentially exactly.  The DDA was
apparently first proposed by Purcell and Pennypacker (1973).  DDA theory is
reviewed and developed further by Draine (1988), Draine and Goodman (1993),
and recently reviewed by Draine and Flatau (1994).

   DDSCAT.5a.8 is a FORTRAN implementation of the DDA developed by the authors.
It is intended to be a versatile implementation, suitable for a wide variety
of applications ranging from interstellar dust to atmospheric aerosols.  As
written, the code 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 current version of DDSCAT
uses the DDA formulae from Draine (1988).  The code incorporates Fast Fourier
Transform (FFT) methods (Goodman, Draine, and Flatau 1991).  The Lattice
Dispersion Relation (LDR) prescription (Draine and Goodman 1993) is used for
determining dipole polarizabilities.

   At present the user may choose among different FFT implementations:
(1) FORTRAN implementation (FOURX) from Brenner (1969); 
(2) FORTRAN implementation (CFFT99F) from Temperton (1983); 
(3) FORTRAN implementation (GPFA) from Temperton (1994);
(4) the native vector library implementation (C3DFFT) on Convex computers.

   To facilitate comparisons of the different FFT options, we provide a
separate FORTRAN program TSTFFT which will provide timing information for
comparison of the 3 FORTRAN FFT options.  This will enable the user to make
the best choice of FFT for the particular hardware/architecture being used.
   
   The current release of DDSCAT includes an option to calculate torques
and transverse forces on targets, as described in Draine and Weingartner (1996).

   Detailed instructions for using DDSCAT are contained in the User Guide for
DDSCAT.5a.  The User Guide is available in the ftp directory as either
* UserGuide.ps    : postscript file
* UserGuide.ps.gz : gzipped postscript file
* UserGuide.tex   : LaTeX file; requires encapsulated postcript files f1.eps,
                    f2.eps, f3.eps, f4.eps, and f5.eps .

                              IMPORTANT NOTE
                              **************

   Previous releases of version 5a (including version 5a7), while solving
the scattering problem correctly, unfortunately contained an error in the
routine getmueller.f which calculated complex scattering amplitudes S_i and 
Mueller matrix elements S_ij from the f_ml.  The S_i and S_ij were computed 
correctly only for the special case where target orientation angle PHI = 
scattering angle phi.  Furthermore, there were additional errors in 
calculation of the Mueller matrix elements S_14 and S_31 which resulted in
incorrect evaluation of the polarization fraction "Pol" of scattered light
for incident unpolarized light.

   These errors have been corrected in the present release DDSCAT.5a.8.

   It should be stressed that calculations by DDSCAT.5a.7 and previous releases 
of

* complex scattering amplitudes f_ml [notation of Draine (1988)]
* absorption efficiencies Q_abs
* scattering efficiencies Q_sca
* extinction efficiencies Q_ext
* <cos(theta)> for scattering
* radiation pressure efficiency vector Q_pr
* radiation torque efficiency vector Q_gamma

were all computed and reported correctly.


                               2. AVAILABILITY
                               ***************

   The authors make this code openly available to others, in the hope that
it will prove to be a useful tool.  We ask only that:

* If you publish results obtained using DDSCAT, please consider acknowledging
  the source of the code.

* If you discover any errors in the code, please promptly communicate them to
  the authors.

* 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 "copyleft" distributed with the
  DDSCAT software.

   We also strongly encourage you to send email to the authors identifying
yourself as a user of DDSCAT;  this will enable the authors to notify you of
any bugs, corrections, or improvements in DDSCAT.


                             3. HOW TO COPY IT
                             *****************

                            a) Where to find it
                            ===================

   A copy of the DDSCAT source code is currently located on the computer
"astro", whose full address is "astro.princeton.edu" and "IP" number is
128.112.24.45 (on the Internet network).  This computer allows "anonymous FTP".
To gain access to this computer from another computer on the Internet, type:
      ftp astro.princeton.edu
or, if that didn't work, try
      ftp 128.112.24.45
When you get the login prompt type "anonymous"; when you get the password
prompt type your full email address.  To get to the appropriate subdirectory,
type
      cd draine/scat/ddscat/ver5a8
which will place you in a directory containing various files, including:
* README (a copy of the text you are reading now);
* rel_notes (release notes, including a list of known or suspected bugs);
* ddscat5a8.tar.gz ("gzipped tarfile" used for transfer to other UNIX systems);
* UserGuide.ps (postscript User Guide for DDSCAT)
* UserGuide.ps.gz ("gzipped" postscript User Guide)
* UserGuide.tex (LaTeX source code for "user guide")
* f1.eps, f2.eps, f3.eps, f4.eps f5.eps (encapsulated postscript figures 
  required by UserGuide.tex)
* SRCn.FOR (where n=0,...,9; for transfer to non-UNIX systems);
* GPFA.FOR (for transfer to non-UNIX systems);
* LAPACK.FOR (for transfer to non-UNIX systems);
* MISC.FOR (for transfer to non-UNIX systems);
* PIM.FOR (for transfer to non-UNIX systems);
* copyleft (for transfer to non-UNIX systems);
* ddscat.par (for transfer to non-UNIX systems);
* diel.tab (for transfer to non-UNIX systems).
   You may check the contents of the directory by typing
      ls
which should list the names of these files.

                            b) To a UNIX System
                            ===================

   The file "ddscat5a8.tar.gz" in this directory is a "gzipped" "tar" file for
easy transfer of EVERYTHING you need to other UNIX machines via ftp or tape.
It contains the following:
* The complete FORTRAN source code for the DDA scattering program DDSCAT,
  including the source code for the 3 different FFT implementations;
* The FORTRAN source code for the program CALLTARGET;
* The FORTRAN source code for the program TSTFFT;
* "Makefile" -- for compiling and linking using the UNIX utility "make";
* "rel_notes" -- release notes, including a list of known or suspected bugs;
* "ddscat.par" -- a sample parameter file set up for a test calculation;
* "diel.tab" -- a sample data file for specifying refractive index;
* "UserGuide.ps" -- a postscript User Guide providing extensive instructions
   on how to use DDSCAT.5a
* "README" (a copy of the file you are now reading);
* "copyleft" (a description of the GNU General Public License agreement).
To copy "ddscat5a.tar.gz" to your system, type

      binary                     [invoke ftp "binary" option]
      get ddscat5a8.tar.gz       [to copy it to your computer]
      bye                        [to terminate your ftp session]

   After successfully transferring "ddscat5a8.tar.gz" to your UNIX system you
should do the following:

1. Move ddscat5a8.tar.gz to the desired directory.  In what follows below,
   this directory will be referred to as "~/DDA".  Thus you should now have
   a file "~/DDA/ddscat5a8.tar.gz" .

2. Position yourself in ~/DDA by typing

      cd ~/DDA

3. Now unzip "ddscat5a8.tar.gz" by typing

      gunzip ddscat5a8.tar.gz

   This command should replace the file "ddscat5a8.tar.gz" by a new file
"ddscat5a8.tar".

4. Now "de-tar" the file "ddscat5a8.tar" by typing

      tar -xvf ddscat5a8.tar

   This will:

* create subdirectories ~/DDA/src, ~/DDA/doc, ~/DDA/misc, ~/DDA/IDL
* put "Makefile" and all of the source code in ~/DDA/src;
* put "README", "INSTRUCTIONS", "rel_notes", "ddscat.par", "diel.tab",
  "copyleft", and UserGuide.ps into the directory ~/DDA/doc;
* put miscellaneous source code into the directory ~/DDA/misc
* put some IDL code into the directory ~/DDA/IDL

  After doing this, you should consult the User Guide for further information.

                         c) To a Non-UNIX System
                         =======================

   If, alas, you are on a non-UNIX system, you should IGNORE the file
named "ddscat5a8.tar.gz".  There are a number of ASCII files in the directory in
which you should be located:
* "README" -- a copy of the file you are now reading;
* "UserGuide.ps" -- User Guide (postscript)
* "UserGuide.tex" -- User Guide (LaTeX source)
* "f1.eps" ... "f5.eps" -- encapsulated postscript figures required by 
   UserGuide.tex
* "SRCn.FOR" for n=0,1,...,9  -- the entire source code with a VMS timing
   routine;
* "CGCOMMON.FOR" -- the source code for various routines common to
   conjugate gradient packages;
* "GPFA.FOR" -- the source code for Temperton's GPFA FFT package;
* "LAPACK.FOR" -- the source code for the public domain LAPACK package for
   linear algebra;
* "MISC.FOR" -- a program "calltarget", plus alternate timing routines;
* "PIM.FOR" -- a file containing source code for the PIM package;
* "rel_notes" -- release notes, including a list of known or suspected bugs;
* "ddscat.par" -- a sample parameter file; and
* "diel.tab" -- a sample dielectric file; and
* "copyleft" -- a description of the GNU General Public License agreement.
Copy them to your system using ftp by typing
      get README
      get INSTRUCTIONS
      prompt		[to turn off interactive prompting]
      mget *.FOR	[to transfer all files with .FOR suffix]
      get rel_notes
      get ddscat.par
      get diel.tab
      get copyleft
      get UserGuide.ps	[if you have a postscript printer]
      get UserGuide.tex [if you want LaTeX source for the User Guide]
      mget f*.eps	[if you want to be able to use the LaTeX source for
			 the User Guide]

The files "SRCn.FOR" , for n=0-9, plus CGCOMMON.FOR, GPFA.FOR, LAPACK.FOR, and 
PIM.FOR, contain all the DDSCAT source code including a timing routine 
suitable for VMS systems.  If you are on a VMS system, you can simply use a 
standard FORTRAN compiler to compile and link the routines in the 12 *.FOR 
files.  If you are on a non-VMS system, the timing routine (SUBROUTINE TIMEIT) 
supplied in "SRC9.FOR" may not work, in which case you should replace it with 
one of the alternate timing routines in the file "MISC.FOR" (comments within 
each routine will indicate what operating system it is appropriate to).
   The file "MISC.FOR" also contains code for a program CALLTARGET which
uses the target generation routines from DDSCAT to allow you to interactively
create various target lattices.  Consult the User Guide for more information.

                               ACKNOWLEDGMENTS
                               ***************

   The routine ESELF making use of the FFT was originally written by Jeremy J.
Goodman.  The FFT routine FOURX is based on a FFT routine written by Norman M.
Brenner.  The FFT routine CXFFT3 is based on a FFT routine written by Clive J.
Temperton.  The routine REFICE was written by Steven B. Warren, based on
Warren (1984).  The routine REFWAT was written by Eric A. Smith.  The GPFA
FFT routine was written by Clive Temperton, and generously made available by
him.  The LAPACK package is the result of work by Jack Dongarra and others at
the Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd., Courant 
Institute, Argonne National Lab, and Rice University.  The PIM package
(including routines in CGCOMMON) are due to Rudnei Dias da Cunha and Tim
Hopkins.  We are indebted to all of these authors for making their code 
available.

   We also thank those who have called our attention to bugs in earlier
versions of this code, in particular Mike Wolff and Henriette Lemke.

   Development of this code was supported in part by National Science
Foundation grants AST-8341412, AST-8612013, AST-9017082, AST-9319283, and in 
part by Air Force Office of Scientific Research grant AFOSR-88-0143.


                  APPENDIX: How "ddscat5a8.tar.gz" was created
                  ******************************************

   In case you need to know, the file "ddscat5a8.tar.gz" in this directory was
created using the following procedure on a Sun workstation running Solaris 2.5:

      cd ~/DDA/ver5a8
      tar cvf ddscat5a8.tar src doc misc IDL
      gzip ddscat5a8.tar

Here "~/DDA/ver5a8" is a directory containing version 5a8 of the DDA program.
The "tar" command was used to create a file "ddscat5a8.tar" (in the directory
"~/DDA/ver5a8").  The file "ddscat5a8.tar" includes the complete directories 
"~/DDA/ver5a8/src", "~/DDA/ver5a8/doc", "~/DDA/ver5a8/misc", and 
"~/DDA/ver5a8/IDL".  
The "gzip" command was used to create the gzipped file "ddscat5a8.tar.gz".


                                 REFERENCES
                                 **********

Brenner, N.M. 1969, IEEE Trans. Audio Electroacoust. AU-17, 128.

Draine, B.T. 1988, "The Discrete-Dipole Approximation and its Application to
   Interstellar Graphite Grains", Astrophys. J. 333, 848-872.

Draine, B.T., and Goodman, J. J. 1993, "Beyond Clausius-Mossotti: Wave
   Propagation on a Polarizable Point Lattice and the Discrete Dipole
   Approximation", Astrophys. J., 405, 685-697.

Draine, B.T., and Flatau, P.J. 1994, "Discrete-dipole approximation for
   scattering calculations", J. Opt. Soc. Am. A., 11, 1491-1499.

Draine, B.T., and Weingartner, J. 1996, "Radiative Torques on Interstellar 
   Grains: I. Superthermal Rotation", Ap. J., 470, 551.

Draine, B.T., and Weingartner, J. 1997, "Radiative Torques on Interstellar
   Grains: II. Alignment with the Magnetic Field", Ap. J., submitted.

Goodman, J.J., Draine, B.T., and Flatau, P.J. 1991, "Application of FFT
   Techniques to the Discrete Dipole Approximation, Opt. Lett., 16, 1198-
   1200.

Purcell, E.M., and Pennypacker, C.R. 1973, "Scattering and Absorption of Light
   by Nonspherical Dielectric Grains", Astrophys. J. 186, 705-714.

Temperton, C.J. 1983, "Self-sorting mixed-radix Fast Fourier Transforms",
   J. Comp. Phys. 52, 1-23.

Temperton, C.J. 1994, private communication.

Warren, S.G. 1984, "Optical Constants of Ice from the Ultraviolet to the
   Microwave", Appl. Opt., 23, 1206-1225.
