Index of /~draine/scat/ddscat/ver4c

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[ ]diel.tab1994-12-02 12:01 193  
[ ]instructions.ps1994-12-19 09:58 261K 
[ ]scatlib.info1995-05-17 08:57 1.9K 
[ ]ddscat.par1996-03-27 10:12 1.6K 
[TXT]INSTRUCTIONS1996-05-29 12:21 63K 
[ ]GPFA.FOR1996-05-29 12:39 55K 
[ ]ddscat4c.tar.Z1996-05-29 12:39 367K 
[TXT]MISC.FOR1996-05-29 12:39 22K 
[TXT]SRC0.FOR1996-05-29 12:39 44K 
[ ]SRC1.FOR1996-05-29 12:39 42K 
[TXT]SRC2.FOR1996-05-29 12:39 30K 
[TXT]SRC3.FOR1996-05-29 12:39 35K 
[TXT]SRC4.FOR1996-05-29 12:39 41K 
[TXT]SRC5.FOR1996-05-29 12:39 44K 
[ ]SRC6.FOR1996-05-29 12:39 28K 
[ ]SRC7.FOR1996-05-29 12:39 28K 
[ ]SRC8.FOR1996-05-29 12:39 42K 
[ ]SRC9.FOR1996-05-29 12:39 33K 

Table of Contents

DDSCAT.4c.1

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

                                     and

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

                           [last revised: 95.03.03]
                Copyright (C) 1994,1995 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.4c.1 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. Dr. Clive Temperton (European Center for Medium-Range Weather Forecasting), the author of the GPFA implementation, has generously permitted us to include the source code gpfa.f in our distribution. Thus, options (1), (2), and (3) are available to all users of DDSCAT. Option (4) is available only on Convex computers.

GPFA is the preferred FORTRAN option, as it is generally faster than FOURX or CFFT99F, but does not require any more memory than FOURX. In some cases, CFFT99F may be faster, but it has greater memory requirements. It is relatively straightforward to modify the code to use "native" FFT implementations which may be available on other 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.

Detailed instructions for using DDSCAT are contained in the "INSTRUCTIONS" file.

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:

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/ver4c
which will place you in a directory containing 19 files:

b) To a UNIX System

The file "ddscat4c.tar.Z" in this directory is a compressed "tar" file for easy transfer of EVERYTHING you need to other UNIX machines via ftp or tape. It contains the following:

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

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

  1. Move ddscat4c.tar.Z to the desired directory. In what follows below, this directory will be referred to as "~/DDA". Thus you should now have a file "~/DDA/ddscat4c.tar.Z" .
  2. Position yourself in ~/DDA by typing

cd ~/DDA

3. Now uncompress "ddscat4c.tar.Z" by typing

uncompress ddscat4c.tar.Z

This command should replace the file "ddscat4c.tar.Z" by a new file "ddscat4c.tar".

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

tar -xvbf 1024 ddscat4c.tar

This will:

Note: if you encounter problems with "tar -xvbf", you may wish to try using "tar -xovbf 1024 ddscat4c.tar". The options for "tar" are unfortunately somewhat system-dependent -- consult your local Unix guru if you still have problems.

After doing this, you may need to edit the "Makefile" file. The entries for "FC", "FFLAGS", "FFLAGS2", and "LDFLAGS" are compiler-dependent. The entries in the original "Makefile" work for Sun FORTRAN under SunOS 4.1 or Solaris 2.3. In addition to the compiler name ("FC"). compiler flags ("FFLAGS", "FFLAGS2"), and loader flags ("LDFLAGS"), the "timer" routine will also be system-dependent. A number of timer routines (e.g., "timeit_sun.f") are provided; to select the right one you should "uncomment out" ONE of the definitions of "timeit" in the Makefile (i.e., delete the "#" symbol in column 1). Examples are provided for a number of common operating systems (e.g., IBM AIX, SGI IRIX, HP AUX). This should be all that is necessary for the sample calculation. After making sure that you have the correct compiler/linker/timeit options, you can simply type
make all
which should result in creation of two executables: "ddscat" and "calltarget". The former is for the sample calculation; the latter allows you to create various targets without firing up DDSCAT itself. For further information you should consult the file "INSTRUCTIONS".

c) To a Non-UNIX System

If, alas, you are on a non-UNIX system, you should IGNORE the file named "ddscat4c.tar.Z". There are 16 ASCII files in the directory in which you should be located:

The files "SRCn.FOR" , for n=0-9, plus GPFA.FOR, contains all the DDSCAT source code with 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 11 files "SRC0.FOR,...,SRC9.FOR, and GPFA.FOR. 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 file "INSTRUCTIONS" for more information.

4. SAMPLE CALCULATION

After successful compilation, make sure that the files "ddscat.par" and "diel.tab" are located in the same directory in which you will run DDSCAT (the directory containing the executable "ddscat"). As provided, the program DDSCAT is dimensioned to allow calculations for objects extending at most 8 lattice spacings in the x, y, or z directions; the resulting executable requires about 811 kilobytes of memory. This size is sufficient for the sample calculation.
The file "ddscat.par" is a parameter file; the sample provided is set up to calculate DDA scattering by a 8x6x4 rectangular array of 192 dipoles, with an effective radius (radius of a sphere of equal volume) a=1 micron, at a wavelength of 6.2832 micron (and scattering parameter x=2*pi*a/lambda=1). The refractive index m=1.33+0.01i of the target material for this sample calculation is provided in the file "diel.tab", which is a simple table of either dielectric function or refractive index as a function of wavelength. (See the "INSTRUCTIONS" file for details on the formatting of the file.) The name of this file ("diel.tab" in this case) is passed to DDSCAT through the parameter file "ddscat.par".
As provided, ddscat.par is set up to calculate DDA solutions using Brenner's FORTRAN FFT implementation.
The incident radiation is always taken to propagate in the +x direction. As provided, ddscat.par specifies incident polarization state "1" to be in the y direction. DDSCAT will then construct incident polarization state "2" to be in the x cross y = z direction.
As provided, ddscat.par calls for a total of three different target orientations, with calculation for two incident polarization states. Scattered intensities are calculated for two scattering planes (phi=0 and 90) at intervals of 30 degrees in the scattering angle theta [in a real calculation you would of course sample more finely in theta]. The angle phi=0 for the x-y plane; phi=90 for the x-z plane.
On a Unix system, the executable program will be named "ddscat", and may be run by simply typing "ddscat"; the program provides "running output" to unit 0, which for Sun FORTRAN corresponds to "standard output" (e.g., writing to the terminal screen) without buffering. If 0 is not an acceptable unit number on your system, you should edit the DATA statements in DDSCAT where the variables IDVOUT and IDVERR are initialized. In addition to writing to "standard output", upon completion of this sample calculation DDSCAT should have created a total of 7 new files, named "mtable", "qtable", "qtable2", "w00r00k000.sca", "w00r00k001.sca", w00r00k002.sca", and "w00r00ori.avg". The contents of these files for the sample calculation are given (and explained) in the "INSTRUCTIONS"; you should compare your results with these expected values to verify that the code is working properly.

5. OTHER SCATTERING PROBLEMS

After successfully running the sample calculation, you should consult the file "INSTRUCTIONS" for information on how to modify the "ddscat.par" file to solve other scattering problems.

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. We are indebted to all of these authors for making their code available.

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 "ddscat4c.tar.Z" was created

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

      cd ~/DDA/ver4c
      tar cvbf 1024 ddscat4c.tar src doc misc
      compress ddscat4c.tar

Here "~/DDA/ver4c" is a directory containing version 4c of the DDA program. The "tar" command was used to create a file "ddscat4c.tar" (in the directory "~/DDA/ver4c") with a blocksize of 1024 bytes. The tarfile contains the contents of the directories ~/DDA/ver4c/src and ~/DDA/ver4c/doc. The "compress" command was used to create the compressed file "ddscat4c.tar.Z".

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.

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.