M. T. Homer Reid MIT Home Page
Physics Problems Research teaching My Music About Me Miscellany


Computing T-Matrices of arbitrary objects with scuff-tmatrix

The well-known T-matrix 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 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

  1. create a geometry file describing the shapes and material properties of the scattering objects in your geometry;

  2. 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

  1. 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

  2. optionally, a binary .HDF5 file containing the T-matrix data together with simple scripts for importing the data into matlab.

Table Of Contents
1. scuff-tmatrix Command-Line Options
2. scuff-tmatrix Output Files
3. scuff-tmatrix Examples
4a. Dielectric Sphere
4b. Dielectic Cube
4. Reading T-Matrix data into julia

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.

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•1014 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 1e-2 --Omega 1e-1 --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 l-values considered
 --lMax xx 
Request calculation of T-matrix entries with spherical wave indices up to l=xx.

The dimension of the T-matrix computed at each frequency is DxD, where D=(lMax+1)(lMax+1)-1.

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 is lMax=5.

Options controlling output files
 --OutputFile MyOutputFile
Requests that the text-based output data be written to the file MyPowerFile.dat.

If this file is not specified, the text-based output data are written by default to a file named Geometry.TMatrix, where Geometry.scuffgeo was the name of the scuff-em geometry file you specified with the --geometry command-line option.

 --HDF5File MyFile.hdf5 
Requests that binary T-matrix 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 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.

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 scuff-tmatrix run.

The --Cache XX option is equivalent to saying --ReadCache XX --WriteCache XX.

For more information on geometric data caching in scuff-em, see here.

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 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 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 M or 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 T-matrix.

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 (PPrime,LPrime,MPrime.)

See below for a simple shell script you can use to extract a particular T-matrix entry vs. frequency from the .TMatrix file.

Also see below for a julia code that you can use to import T-matrix data into a julia session.

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 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 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 in the 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 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

We create a simple file called OmegaValues.dat 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 E10Sphere_654.TMatrix, 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 E10Sphere_1362.TMatrix, 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 .TMatrix 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 or MyFile.M11.M22 with three numbers per line:

Omega real(T) imag (T)

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

Here's a julia function that you can use to read T-matrix data from the .TMatrix output file produced by scuff-tmatrix: 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 T-matrix 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 T-matrix data, and TList[n,:,:] is the T-matrix corresponding to angular frequency OmegaList[n].

Core Library

Computing T-Matrices of arbitrary objets with scuff-tmatrix, by Homer Reid
Last Modified: 11/16/16