Integrating frequencydependent data with scuffintegrate
Many application codes in the scuffem suite compute physical quantities defined by definite integrals over real or imaginary frequencies, with the numerical value of the integrand at each point obtained by solving individual scuffem scattering problems at that frequency. For example,

scuffcas3d and scuffcaspol compute zerotemperature Casimir quantities by integrating contributions from imaginary frequencies : Here is a zerotemperature Casimir energy/force/torque (scuffcas3d) or CasimirPolder potential (scuffcaspol) and is the spectral density of contributions to from fluctuations at imaginary frequency , which may be obtained by solving scuffem scattering calculations at imaginary frequency .

scuffneq computes the total rate of energy or momentum transfer from a source body to a destination body by integrating contributions from real frequencies : Here is the contribution of body to quantity (a heattransfer rate, force, or torque) for body , is the BoseEinstein statistical factor, and are the temperatures of the source body and the environment, and is a "generalized flux" quantity that may be computed by solving scuffem scattering calculations at frequency .
The integrals over and are evaluated by numerical cubaturethat is, as weighted sums of integrand samples. In a perfect world, it would be possible for scuffem application codes to choose appropriate integration strategies automatically, hiding these details from the user and reporting just the frequencyintegrated quantities . This is in fact the strategy that was adopted in early incarnations of the scuffem codes.
In the real world, however, the behavior of integrand functions like and varies widely from problem to problem, depending on factors such as the shapes and materials of bodies in the scattering geometry and the quantity being computed. For this reason, it's hard for scuffem to make intelligent automatic choices of integration strategies, and attempts to do so without user input may result in misleading or even flatout incorrect data.
For this reason, the modern approach to frequency integration
in scuffem is to ask users to define a
list of frequencies at which to sample the integrand; this
list is passed to scuffem application codes using the
XiFile
or OmegaFile
commandline options, and in
response the code produces an output file reporting values
of the integrand at the specified points. The frequency
integral may then be calculated as as postprocessing step
using the information reported in the frequencyresolved
data files, and this is the task for which scuffintegrate
exists.
scuffintegrate is a generalpurpose tool, not limited to scuffem applications
Actually, scuffintegrate is designed to be a generalpurpose numericalintegration tool, not particularly tied to scuffem; given a data file containing samples of some function at sample points distributed over an interval , scuffintegrate approximates the integral . (It does this by constructing a thirdorder spline interpolant through the data, then integrating the interpolant via numerical quadrature.) The code offers commandline options to specify how the data file is to be interpreted (for example, which columns are the samples and which are the samples). There is no restriction on the number or spacing of the sample points; the variable x need not correspond to a real or imaginary frequency, and the function need not be a generalized flux, Casimir integrand, or any other quantity reported by a scuffem calculation.
But for data files that do come from scuffem calculations, scuffintegrate knows what to do automatically with minimal user input
In addition to the fully generalpurpose mode described above,
scuffintegrate also has builtin automatic support for
certain specialized types of scuffem
data filessuch as the .SIFlux
files produced by scuffneqdesigned
to make it easy to run the tool to get the frequencyintegrated data you want with minimal user input
required.
1. Using scuffintegrate as a generalpurpose numerical integrator
Integrating a single function of a single variable
The simplest usage of scuffintegrate is to integrate
a single function of a single variable ; as noted
above, this is a generalpurpose use of the code, independent
of scuffem, in which and need not be a frequency and
a generalized flux, but could have any arbitrary significance.
Suppose we have a file called fData
in which
are tabulated numerical pairs , ,
where :
x1 f1 x2 f2 ... xN fN
Then to compute we can just go like this:
% scuffintegrate datafile fData freqColumn 1 dataColumn 2
This will produce a file named fData.Integrated
containing
a single line of data: the integrated value of .
If the frequency and/or integrand values are printed in
different columns of the data file, just adjust the
freqColumn
and dataColumn
options accordingly. For
example, if the data file looks like this:
<stuff> <stuff> x1 <stuff> <stuff> f1 <stuff> ... <stuff> <stuff> x2 <stuff> <stuff> f2 <stuff> ... ... <stuff> <stuff> xN <stuff> <stuff> fN <stuff> ...
you would use freqcolumn 3 datacolumn 6.
In this case, the content of the other columns (the <stuff>
in the above snippet) is ignored.
Integrating multiple functions of frequency
More generally, you may have multiple integrand functions
, each sampled at the same set of values,
You can integrate all of these
at once simply by specifying multiple dataColumn
options. For example, if you have functions and
and you have a file named fgData
with the format
x1 f1 g1 x2 f2 g2 ... xN fN gN
then you can say
% scuffintegrate datafile fgData freqColumn 1 dataColumn 2 datacolumn 3
and the resulting output file fgData.Integrated
will report values for both and .
Giving names to data columns
In the legend at the top of the .Integrated
output file,
the values of the various integrated functions will by default
be labeled data 0
, data 1
, etc. If you want to give more
descriptive names, just follow each dataColumn
option
with a dataName
option.
For example, if
columns 8 and 11 of your data file respectively
report values of force and torque integrands, you might say
, say
dataColumn 8 dataName Force dataColumn 11 dataName Torque
.
Integrating functions of frequency and other parameters
In many cases we will have functions that depend on various parameters beside the integration variable, i.e. functions of the form where the data file includes integrand samples for multiple sets of values of the parameters. (In scuffcas3d, for example, we might compute Casimir forces between particles separated by various distances , so the integrand function may be thought of as a function of both distance and frequency.) In these cases you will generally want to evaluate separate integrals over for each set of parameter values represented in your data file.
For example, suppose your data file is called pxfgData
and
looks something like
p1 x1 f11 g11 p1 x2 f12 g12 .... p1 xN f1N g1N p2 x1 f21 g21 p2 x2 f22 g22 .... p2 xN f2N g2N .... pM xN fMN gMN
where p1,
p2,
..., pM
denote distinct values
of some parameter and fmn,gmn
are the numerical
integrand values .
In this case you can't simply say
freqColumn2 dataColumn 3 dataColumn 4,
because then
data for all parameter values will be mashed all together and
integrated as a single function of frequency, yielding nonsense.
Instead, you handle this situation by specifying the additional
commandline parameter tagColumn 1
to tell scuffintegrate
to interpret data lines with different values in column 1
as samples of different functions:
% scuffintegrate datafile pxfgData tagcolumn 1 freqColumn 2 dataColumn 3 dataColumn 4
In this case, the output file pxfgData.Integrated
will report
integrated values of and separately for each value of
.
If your integrands depend on multiple parameters ,
you may specify multiple tagColumn
options to specify
the columns in which values of the various parameters live.
Then each line of the .Integrated
output file will report
integrated values of all functions for a single tuple of
parameter values
2. Using scuffintegrate as a specialized integrator for scuffem data
As noted above, scuffintegrate has builtin knowledge of the structure of various data files produced by scuffem calculations. This streamlines calculations by allowing you you to feed those data files directly into scuffintegrate without needing to tell the code which column of the data file is which.
2A. Integrating scuffneq data
As discussed at the top of the page, the frequencyresolved
data reported by scuffneq
are generalized fluxes describing temperatureindependent
rates of energy and momentum transfer from each body
to each other body in your geometry. To turn these
into total heattransfer rates, forces, and torques
for a given set of object and environment temperatures,
we must (a) integrate over frequency with
BoseEinstein thermal weight factors appropriate for
the given temperatures, and (b) sum the
contributions of multiple source bodies to yield
the total rates of power and momentum transfer to
each destination body.
scuffintegrate already knows the
file format of the .SIFlux
and .SRFlux
frequencyresolved
data files produced by scuffneq,
so there is no need to specify FreqColumn
and DataColumn
options.
Specifiying temperatures
Instead, the only input you need to supply (besides
the .SIFlux
or .SRFlux
data file) is a specification
of the temperatures of the bodies in your geometry,
and of the surrounding environment. By default, all bodies
and the environment are at absolute zero, K; if
you do not modify this situation by setting a nonzero temperature
for at least one body (or the environment), all heattransfer
rates and forces/torques will be zero. The commandline option
for setting

Temperature N T
If , this sets the temperature of the th object/surface in the geometry to
T
Kelvin. (Here objects/surfaces are indexed using a 1based convention; to set the temperature of the first object/surface specified in the.scuffgeo
file to room temperature you would sayTemperature 1 300.
)If , this instead sets the temperature of the environment to
T
.
Specifiying multiple temperature sets
A bonus feature
of the separation between scuffneq and scuffintegrate
is that a single set of frequencyresolved flux data (in
an .SIFlux
or .SRFlux
file) can be used to obtain data on
heattransfer rates and forces and torques at multiple sets
of temperatures for the bodies and the environment, simply by
evaluating integral (2) multiple times with different temperatures
but the same flux data.
Spatiallyintegrated flux data (.SIFlux
files)
knows how to do this automatically
In this case, for a geometry containing bodies,
each line of the .SIFlux
output file is tagged with
a data field of the form (where and are
integers between 1 and ) to label the contributions
of sources in body to the power, force, and/or torque
(PFT) on body . (For example, lines for which this field reads
13
give contributions of body 1 to the PFT for body 3).
The actual data quantities reported in the
.SIFlux
file are the generalized fluxes
in equation (2) above, and to evaluate the integral
here we need to know the temperatures of the environment
and of all bodies in the geometry, which enter through
the BoseEinstein factors in (2).
To handle these complications, scuffintegrate supports the following additional commandline options:

sdColumn xx
Specifies that the indicator field appears on column
xx
of the data file. (The default issdColumn 3
, matching the default file format of the.SIFlux
files produced by scuffneq, so for those files this option may be omitted.)

TemperatureFile TFile
Specifies a file containing multiple temperature configurations at which to compute total PFTs. For an body geometry, each line of
TFile
should contain spaceseparated numbers in the same format as the arguments to theTemperature
option, i.e.TEnv T1 ... TN.
For example, to compute PFTs in a twobody geometry with the temperature of body 1 scanned from 10 to 300 Kelvin, the temperature of body 2 held fixed at room temperature, and the environment temperature fixed at 0,
TFile
would look like
0 10 300 0 20 300 ... 0 300 300
3. scuffintegrate CommandLine Reference
4. Miscellaneous notes
Only numerical data columns are counted as columns
There is one potentially confusing aspect of the way
scuffintegrate interprets column indices as specified
by commandline arguments such as FreqColumn
or DataColumn
.
This is that scuffintegrate treats nonnumerical data columns
as white space, and in particular does not include data columns
containing text strings when counting column indices.
Thus, for example, if your data file contains frequency and integrand data in the second and third columns, with the first column containing a character string, like this:
DEFAULT 0.1 3.45e5 DEFAULT 0.2 7.82e5 DEFAULT 0.3 1.10e4 ...
then scuffintegrate ignores the DEFAULT
column and considers
the first column with numerical data to be column 1, so here
you would say freqColumn 1 dataColumn 2.
In contrast, if your data file looks instead like this:
4.00000 0.1 3.45e5 4.00000 0.2 7.82e5 4.00000 0.3 1.10e4 ...
you would want to say freqColumn 2 dataColumn 3.