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 T-matrix, whose entries
give the amplitudes of the outgoing spherical waves that arise from
irradiating the object with a single regular spherical wave.
scuff-tmatrix is a specialized tool within the
scuff-em code suite for computing the
T-matrix of arbitrarily-shaped objects with arbitrary
frequency-dependent material properties.
To compute the T-matrix of an object (or a collection of objects)
using scuff-scatter, you will
create a geometry file
describing the shapes and material properties of the scattering objects
in your geometry;
- run scuff-tmatrix with command-line options
specifying the geometry, the maximum l-value of the spherical
wave to consider (i.e. the dimension of the T-matrix to compute),
and the frequency range over which to run computations.
You will get back
a text file listing all T-matrix elements (with l-values
up to the maximum l-value you specified) at all frequencies
you requested, and
- optionally, a binary
.HDF5 file containing the
T-matrix data together with simple scripts for importing
the data into matlab.
1. scuff-tmatrix Command-Line Options
The following table summarizes all command-line options
currently available in scuff-tmatrix.
As is true for all programs in the
scuff-em suite, command-line
options may be specified in a text file catted to standard
input; see here
for an example of how this works.
Options controlling the scattering geometry
| Specifies the
describing the scattering geometry.
This option is always mandatory.
Options specifying the frequencies considered
Specifies an angular frequency at which to
run computations, in units of
3•1014 rad/s (=c / 1 μm).
The value specified for
may be a
You may request computations at more than one frequency
by using the
--Omega option more than once,
i.e. you may say
--Omega 1e-2 --Omega 1e-1 --Omega 1 --Omega 10
(However, for more than a few frequencies it is more
convenient to use the
option discussed below.)
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
Options describing the range of l-values considered
Request calculation of T-matrix entries with spherical wave indices
up to l=
The dimension of the T-matrix computed at each frequency
For example, if you specify
--lMax 3, then
the T-matrices computed will be 15x15 matrices, with
entries indexed by spherical-wave indices
(l,m)=(1,-1), (1,0), (1,0), (2,-2), ..., (3,3).
If you do not specify this option, the default value
Options controlling output files
Requests that the text-based output data be written to the
If this file is not specified, the text-based output data are
written by default to a file named
Geometry.scuffgeo was the name of the
scuff-em geometry file you specified
--geometry command-line option.
Requests that binary T-matrix data be written to
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
T-matrix data; see the examples below.)
Note that, in contrast to text-based output, binary data
output is disabled by default; you must specify this option
to enable binary data output.
| Specifies the names of
cache files for geometric data.
--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.
--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
files, plus any data that were newly generated during the
course of the scuff-tmatrix run.
--Cache XX option is equivalent to saying
--ReadCache XX --WriteCache XX.
For more information on geometric data caching in
2. scuff-tmatrix Output Files
1. T-matrix data in text form
scuff-tmatrix always writes T-matrix
data to a text-based output file. (By default this file is named
was the name of the geometry file you specified with the
option; alternatively, you can specify your own output file name using the
Each line of the text-based output file contains a single T-matrix
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 T-matrix entry.
(Here P identifies the polarization and is either
E for M- or
E-type 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
The final two entries on the line are the real and imaginary parts of
the T-matrix entry for the given pair of spherical waves
at the given frequency.
Physically, the T-matrix 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
See below for a simple shell script you can use to
extract a particular T-matrix entry vs. frequency
Also see below for a
code that you can use to import T-matrix data into a
2. T-matrix data in binary form
If you specify the
--HDF5File command-line argument,
then T-matrix data will be written in binary
HDF5 format to the specified file. The T-matrix
for each frequency will be stored as a separate dataset with
a title like
T_1.23456 where the number indicates the
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
T-matrix data in
MyFile.hdf5 into a
matlab session. See below for examples
of how this works.
3. scuff-tmatrix Examples
Here are some examples of calculations you can do with
scuff-tmatrix. Input files and
command-line runscripts for all these examples are included
share/scuff-em/examples subdirectory of
the scuff-em 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 T-matrix may be computed
analytically, making it a useful benchmark for our numerical
The first step is to create a geometry mesh and a
file for the sphere. This process is described in detail
simplicity in this case we will take the sphere to have a constant
relative dielectric permittivity of εr=10 at
We will start with the sphere mesh containing 327 internal edges;
E10Sphere_327.scuffgeo looks like this:
We create a simple file called
containing a list of angular frequencies (in units of 3•1014 rad/s)
at which to compute T-matrices:
And now we launch scuff-tmatrix:
% scuff-tmatrix --geometry E10Sphere_654.scuffgeo --omegafile OmegaValues.dat --cache Sphere.cache
This produces the file
which contains one T-matrix entry per line:
To assess the impact of meshing fineness, let's re-run the example with
a finer mesh. We will use the sphere mesh with 1362 interior edges:
% scuff-tmatrix --geometry E10Sphere_1362.scuffgeo --omegafile OmegaValues.dat --cache Sphere.cache
This produces the file
with file format similar to the above.
To look at individual T-matrix entries as a function of frequency,
it is convenient to extract those entries from the
file into their own little file.
Here is a simple
shell script, named simply
Filter, which takes either
4 or 7 command-line 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 T-matrix entries
with row and column index equal to (P,L,M). The second will filter
out off-diagonal T-matrix entries with given row and column indices.
In both cases the filtered data are written to a file named something like
MyFile.M11.M22 with three numbers
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 off-diagonal 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 T-Matrix data into julia
that you can use to read T-matrix data
.TMatrix output file produced by
For example, after following the example outlined above
to produce a data file named
you could go like this to import the T-matrix data into
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 T-matrix data,
TList[n,:,:] is the T-matrix corresponding
to angular frequency