The wellknown
Tmatrix method
is a widely used technique for solving problems involving electromagnetic
scattering from compact objects. In this method, the scattering properties
of a compact body are encapsulated in its Tmatrix, whose entries
give the amplitudes of the outgoing spherical waves that arise from
irradiating the object with a single regular spherical wave.
scufftmatrix is a specialized tool within the
scuffem code suite for computing the
Tmatrix of arbitrarilyshaped objects with arbitrary
frequencydependent material properties.
To compute the Tmatrix of an object (or a collection of objects)
using scuffscatter, you will

create a geometry file
describing the shapes and material properties of the scattering objects
in your geometry;
 run scufftmatrix with commandline options
specifying the geometry, the maximum lvalue of the spherical
wave to consider (i.e. the dimension of the Tmatrix to compute),
and the frequency range over which to run computations.
You will get back

a text file listing all Tmatrix elements (with lvalues
up to the maximum lvalue you specified) at all frequencies
you requested, and
 optionally, a binary
.HDF5 file containing the
Tmatrix data together with simple scripts for importing
the data into matlab.
1. scufftmatrix CommandLine Options
The following table summarizes all commandline options
currently available in scufftmatrix.
As is true for all programs in the
scuffem suite, commandline
options may be specified in a text file catted to standard
input; see here
for an example of how this works.
Option 
Description 
Options controlling the scattering geometry

geometry MyGeometry.scuffgeo 
Specifies the
geometry file
describing the scattering geometry.
This option is always mandatory.

Options specifying the frequencies considered

Omega xx 
Specifies an angular frequency at which to
run computations, in units of
3•10^{14} rad/s (=c / 1 μm).
The value specified for Omega
may be a
complex number.
You may request computations at more than one frequency
by using the Omega option more than once,
i.e. you may say
Omega 1e2 Omega 1e1 Omega 1 Omega 10
(However, for more than a few frequencies it is more
convenient to use the OmegaFile
option discussed below.)

OmegaFile xx 
Specifies the name of a file containing a list
of frequencies at which to do computations.
The file should contain one frequency per line; blank
lines and comments (lines beginning with # )
are ignored.

Options describing the range of lvalues considered


Request calculation of Tmatrix entries with spherical wave indices
up to l=xx .
The dimension of the Tmatrix computed at each frequency
is DxD , where D=(lMax+1)(lMax+1)1 .
For example, if you specify lMax 3 , then
the Tmatrices computed will be 15x15 matrices, with
entries indexed by sphericalwave indices
(l,m)=(1,1), (1,0), (1,0), (2,2), ..., (3,3).
If you do not specify this option, the default value
is lMax=5 .

Options controlling output files

OutputFile MyOutputFile 

Requests that the textbased output data be written to the
file MyPowerFile.dat.
If this file is not specified, the textbased output data are
written by default to a file named Geometry.TMatrix ,
where Geometry.scuffgeo was the name of the
scuffem geometry file you specified
with the geometry commandline option.


Requests that binary Tmatrix data be written to
the file MyFile.hdf5. (Specifying this option
will automatically enable the generation of a
matlab import script named
MyFile.m which you can execute at the
matlab command line to import
Tmatrix data; see the examples below.)
Note that, in contrast to textbased output, binary data
output is disabled by default; you must specify this option
to enable binary data output.

Cache options

Cache MyCache.scuffcache 

ReadCache InCache1.scuffcache 
ReadCache InCache2.scuffcache 
WriteCache OutCache.scuffcache 

Specifies the names of
cache files for geometric data.
The ReadCache option allows you to specify a
file from which geometric data will be preloaded before
the calculation begins. This option may be specified
any number of times. If the specified file does not exist,
the option is silently ignored.
The WriteCache option allows you to specify
a file to which geometric data will be written after the
calculation has completed. The resulting cache file will
contain any data that were preloaded from ReadCache
files, plus any data that were newly generated during the
course of the scufftmatrix run.
The Cache XX option is equivalent to saying
ReadCache XX WriteCache XX.
For more information on geometric data caching in
scuffem,
see
here.

2. scufftmatrix Output Files
1. Tmatrix data in text form
scufftmatrix always writes Tmatrix
data to a textbased output file. (By default this file is named
MyGeometry.TMatrix , where MyGeometry.scuffgeo
was the name of the geometry file you specified with the geometry
option; alternatively, you can specify your own output file name using the
OutputFile option.)
Each line of the textbased output file contains a single Tmatrix
element at a single frequency. The format of each line is this:
Omega P L M PPrime LPrime MPrime real(T) imag (T)

The triple (P,L,M) labels the spherical wave that
constitutes the row index for the Tmatrix entry.
(Here P identifies the polarization and is either
M or E for M or
Etype waves, respectively; L is an integer between 1 and
lMax inclusive; and M is an integer between
L and L inclusive.
Similarly, the triple (PPrime,LPrime,MPrime) labels the
spherical wave that constitutes the column index into the
Tmatrix.
The final two entries on the line are the real and imaginary parts of
the Tmatrix entry for the given pair of spherical waves
at the given frequency.
Physically, the Tmatrix element with row index
(P,L,M) and column index (PPrime, LPrime, MPrime)
is the amplitude of the outgoing spherical wave with
indices (P,L,M) that arises from illuminating your
object with a regular spherical wave with indices
(PPrime,LPrime,MPrime.)
See below for a simple shell script you can use to
extract a particular Tmatrix entry vs. frequency
from the .TMatrix file.
Also see below for a
julia
code that you can use to import Tmatrix data into a
julia
session.
2. Tmatrix data in binary form
If you specify the HDF5File commandline argument,
then Tmatrix data will be written in binary
HDF5 format to the specified file. The Tmatrix
for each frequency will be stored as a separate dataset with
a title like T_1.23456 where the number indicates the
frequency.
Also, if you say HDFFile MyFile.hdf5 , then, in
addition to the MyFile.hdf5 file, you will get a file
MyFile.m , which is a simple script for importing the
Tmatrix data in MyFile.hdf5 into a
matlab session. See below for examples
of how this works.
3. scufftmatrix Examples
Here are some examples of calculations you can do with
scufftmatrix. Input files and
commandline runscripts for all these examples are included
in the share/scuffem/examples subdirectory of
the scuffem installation.
4a. Dielectric sphere
We start with the canonical textbook stalwart of scattering from
a dielectric sphere. This is an example (indeed, the only example)
of a dielectric object whose Tmatrix may be computed
analytically, making it a useful benchmark for our numerical
computation.
The first step is to create a geometry mesh and a .scuffgeo
file for the sphere. This process is described in detail
here. For
simplicity in this case we will take the sphere to have a constant
relative dielectric permittivity of ε_{r}=10 at
all frequencies.
We will start with the sphere mesh containing 327 internal edges;
the file E10Sphere_327.scuffgeo looks like this:
OBJECT E10Sphere
MESHFILE Sphere.msh
MATERIAL CONST_EPS_10
ENDOBJECT
We create a simple file called
OmegaValues.dat
containing a list of angular frequencies (in units of 3•10^{14} rad/s)
at which to compute Tmatrices:
0.010
0.013
...
5.0
And now we launch scufftmatrix:
% scufftmatrix geometry E10Sphere_654.scuffgeo omegafile OmegaValues.dat cache Sphere.cache
This produces the file E10Sphere_654.TMatrix ,
which contains one Tmatrix entry per line:
To assess the impact of meshing fineness, let's rerun the example with
a finer mesh. We will use the sphere mesh with 1362 interior edges:
% scufftmatrix geometry E10Sphere_1362.scuffgeo omegafile OmegaValues.dat cache Sphere.cache
This produces the file E10Sphere_1362.TMatrix ,
with file format similar to the above.
To look at individual Tmatrix entries as a function of frequency,
it is convenient to extract those entries from the .TMatrix
file into their own little file.
Here is a simple
shell script, named simply Filter , which takes either
4 or 7 commandline arguments, as follows:
Filter MyFile.TMatrix P L M
Filter MyFile.TMatrix P L M PPrime LPrime MPrime
The first invocation will filter out only the diagonal Tmatrix entries
with row and column index equal to (P,L,M). The second will filter
out offdiagonal Tmatrix entries with given row and column indices.
In both cases the filtered data are written to a file named something like
MyFile.M11 or MyFile.M11.M22 with three numbers
per line:
Let's extract a few diagonal matrix entries:
Filter Sphere_327.TMatrix E 1 1 # get the (M11, M11) diagonal entry; produces file Sphere327.M11
Filter Sphere_327.TMatrix M 2 0
and a couple of offdiagonal matrix entries:
Filter Sphere_327.TMatrix M 1 1 E 1 1 # produces file Sphere327.M11.E11
Filter Sphere_327.TMatrix M 2 1 M 1 1
4. Reading TMatrix data into julia
Here's a
julia function
that you can use to read Tmatrix data
from the .TMatrix output file produced by
scufftmatrix:
ReadTMatrix.jl .
For example, after following the example outlined above
to produce a data file named E10Sphere_654.TMatrix ,
you could go like this to import the Tmatrix data into
julia:
% julia
julia> reload("ReadTMatrix.jl");
julia> (OmegaList, TList) = ReadTMatrix("E10Sphere_654.TMatrix");
11 frequencies, LMax=2, TMatrix dimension=256
Now the vector OmegaList contains the unique values
of the angular frequency at which you requested Tmatrix data,
and TList[n,:,:] is the Tmatrix corresponding
to angular frequency OmegaList[n].
