Computing TMatrices of arbitrary objects with scufftmatrix
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 scufftmatrix, 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 sphericalwave index of the spherical waves to consider (which determines the dimension of the computed Tmatrix), and the frequency range over which to run computations.
You will get back

a text file listing the Tmatrix elements , at all frequencies you requested, for all pairs of vectorsphericalwave indices satisfying

optionally, a binary
.HDF5
file containing the Tmatrix data together with simple scripts for importing the data into julia.
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.
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
OmegaFile MyFile
Omega
specifies an angular frequency at which to run computations, in units of rad/sec (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, which specifies a file containing an
entire list of Omega
values, one per line; blank lines and comments (lines beginning with #
) are skipped.
Option describing the range of sphericalwave indices
lMax 3
Request calculation of Tmatrix entries with spherical wave indices up to and including (and all values and polarizations). As described below, for a maximum value of the matrix has dimension where .
If you do not specify this option, the default value is lMax=3
.
Options controlling output files
FileBase MyFileBase
Sets the base file name for output files. Tmatrix
data in text format are written to FileBase.TMatrix.
Tmatrix data in binary (HDF5) format are written
to FileBase_wXXXX.HDF5
where XXXX
denotes the
angular frequency.
If not specified,
FileBase
defaults to the base filename of the .scuffgeo
file.
WriteHDF5Files
This boolean flag requests that binary Tmatrix data be written
to HDF5 files.
A separate HDF5 file is created for each frequency,
with file name FileBase_wXXXX.HDF5
where XXXX
denotes
the angular frequency. T matrix data are written
in the form of a realvalued matrix (data set) named T
with dimension ;
for columns and give the
real and imaginary parts of the matrix entry for
column .
Here is
the total number of vector spherical waves with
(Tmatrix rows and columns
are indexed as shown in this table.)
Note that, in contrast to textbased output, binary data output is disabled by default; you must specify this option to enable binary data output.
2. scufftmatrix Output Files
1. Tmatrix data in text form
scufftmatrix always writes Tmatrix
data to a textbased output file named FileBase.TMatrix,
where FileBase
is the value you gave for the FileBase
commandline parameter. (If you didn't set this option,
FileBase
defaults to MyGeometry
where MyGeometry.scuffgeo
was the name of the file you specified with the geometry
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 A La Ma Pa B Lb Mb Pb real(T) imag (T)
The tuple(A,La,Ma,Pa)
labels the spherical wave that constitutes the
row index for the Tmatrix entry.
(Here (La,Ma)
= are the usual sphericalwave
indices, Pa
= is a polarization
index (0 or 1 for and type
vector spherical waves respectively) and A
=
is an integer in the range that uniquely
indexes the spherical wave. (See the table below).
The tuple(B,Lb,Mb,Pb)
labels the spherical wave that constitutes the
column index for the Tmatrix entry.
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 and column index is the amplitude of the outgoing spherical wave with indices that results 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
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 WriteHDF5Files
commandline argument, then
Tmatrix data will be written in binary HDF5
format to
files named FileBase_wXXXX.HDF5
where XXXX
stands for
the angular frequency .
Ordering and indexing of spherical waves
For a fixed single value of there are spherical waves: pairs of sphericalwave indices times 2 polarizations (\mathbf{M},\mathbf{N}). The total number of distinct spherical waves with is . This is the dimension of the matrix computed at each frequency. (Note that I exclude waves from my indexing scheme entirely.)
The rows and columns of the matrix are indexed by integers running from to . Spherical waves are ordered and indexed as follows:
The integer index for a given triple may be computed according to
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 and magnetic spheres
We start with the canonical textbook stalwart of scattering from a homogeneous sphere of uniform isotropic relative permittivity and relative permeability
Analytical expressions for Tmatrix elements
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 matrix is diagonal and independent of the sphericalwave index, with dependent elements
where , are the usual spherical Bessel and Hankel functions and
Geometry and mesh files
The first step is to create meshed surfaces representing spheres discretized with various resolutions, then write scuffem geometry files describing spheres of various material properties. This process is described in detail here. In this case we will use two gmsh mesh files for a sphere of radius :

Sphere_327.msh
, a moderateresolution mesh with 327 internal triangle edges, and 
Sphere_1362.msh
, a finer mesh with 1362 internal triangle edges.
For each meshing resolution I will create 3 .scuffgeo
files
describing spheres of different materials:

perfect metal (PEC),

homogeneous dielectric with , and

homogeneous dielectric/magnetic with .
OBJECT Sphere
MESHFILE Sphere_327.msh
ENDOBJECT
OBJECT Sphere
MESHFILE Sphere_327.msh
MATERIAL CONST_EPS_10
ENDOBJECT
OBJECT Sphere
MESHFILE Sphere_327.msh
MATERIAL CONST_EPS_10_MU_5
ENDOBJECT
Frequency list
We create a simple file called
OmegaFile
containing a
list of angular frequencies (in units of rad/sec)
at which to compute Tmatrices:
0.10000000
0.11853758
....
6.00000000
Run scufftmatrix
And now we launch scufftmatrix:
% scufftmatrix geometry E10Sphere_327.scuffgeo omegafile OmegaFile lmax 3
This produces the file E10Sphere_327.TMatrix
, which contains one
Tmatrix entry per line, with a file header at the top to
remind you which is which:
# scufftmatrix run on hikari (11/06/17::01:34:31)
# columns:
# 1 omega
# 2,3,4,5 (alpha, {L,M,P}_alpha) (Tmatrix row index)
# 6,7,8,9 ( beta, {L,M,P}_beta) (Tmatrix columnindex)
# 10, 11 real, imag T_{alpha, beta}
0.1 0 1 1 +0 0 1 1 +0 1.34273817e07 +3.62883443e04
0.1 0 1 1 +0 1 1 1 +1 +1.13651828e09 1.05703395e06
...
...
...
3.25 2 1 +0 0 9 2 1 1 +8.56628506e05 +2.48397970e04
...
...
...
As an example, the lowest line above is interpreted as follows: At angular frequency rad/sec, for the sphericalwave pair [where is a type wave with and is an type wave with , the matrix element is
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
This produces the file E10Sphere_1362.TMatrix
, with file format
similar to the above.
Here are plots of and , for both nonmagnetic and magnetic spheres, as computed (1) by scufftmatrix, with both coarse and finer meshes, (2) using the exact analytical formulas above. (Here is the gnuplot script I used to generate the plots.)