Integrating frequency-dependent data with scuff-integrate
Many application codes in the scuff-em 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 scuff-em scattering problems at that frequency. For example,
- scuff-cas3d and scuff-caspol compute zero-temperature Casimir quantities by integrating contributions from imaginary frequencies :
Here is a zero-temperature Casimir energy/force/torque (scuff-cas3d) or Casimir-Polder potential (scuff-caspol) and is the spectral density of contributions to from fluctuations at imaginary frequency , which may be obtained by solving scuff-em scattering calculations at imaginary frequency .
- scuff-neq 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 heat-transfer rate, force, or torque) for body , is the Bose-Einstein 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 scuff-em scattering calculations at frequency .
The integrals over and are evaluated by numerical cubature---that is, as weighted sums of integrand samples. In a perfect world, it would be possible for scuff-em application codes to choose appropriate integration strategies automatically, hiding these details from the user and reporting just the frequency-integrated quantities . This is in fact the strategy that was adopted in early incarnations of the scuff-em 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 scuff-em to make intelligent automatic choices of integration strategies, and attempts to do so without user input may result in misleading or even flat-out incorrect data.
For this reason, the modern approach to frequency integration
in scuff-em is to ask users to define a
list of frequencies at which to sample the integrand; this
list is passed to scuff-em application codes using the
--OmegaFile command-line 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 post-processing step
using the information reported in the frequency-resolved
data files, and this is the task for which scuff-integrate
- scuff-integrate tutorial walkthrough
- scuff-integrate Command-Line Reference
- Only numerical data columns are counted as columns
scuff-integrate tutorial walkthrough
Integrating a single function of frequency
The simplest usage of scuff-integrate is to integrate
a single function of frequency
[where denotes either real or imaginary frequency].
Suppose we have a file called
fData in which
are tabulated numerical pairs , ,
x1 f1 x2 f2 ... xN fN
Then to compute we can just go like this:
% scuff-integrate --datafile fData --freqColumn 1 --dataColumn 2
This will produce a file named
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
--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
in the above snippet) is ignored.
Integrating multiple functions of frequency
More generally, frequency-resolved data files produced by scuff-em codes will contain data on multiple functions . (For example, in scuff-cas3d each line of the data file may contain data on both Casimir energy and Casimir force.)
You can integrate all of these
at once simply by specifying multiple
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
% scuff-integrate --datafile fgData --freqColumn 1 --dataColumn 2 --datacolumn 3
and the resulting output file
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
data 1, etc. If you want to give more
descriptive names, just follow each
For example, if your force and torque
integrands are respectively reported on columns 8 and 11
of your data file, 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 frequency. (In scuff-cas3d, 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.)
For example, suppose your data file is called
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
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
--tagColumn 1 to tell
to interpret data lines with different values in column 1
as samples of different functions:
% scuff-integrate --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
Integrating scuff-neq data
scuff-integrate incorporates special functionality
for handling the particular frequency-resolved data files
produced by scuff-neq.
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 (1) 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 Bose-Einstein factors in (1).
To handle these complications, scuff-integrate supports the following additional command-line options:
Specifies that the indicator field appears on column
xxof the data file. (The default is
--sdColumn 3, matching the default file format of the
.SIFluxfiles produced by scuff-neq, so for those files this option may be omitted.)
--Temperature N T
If , this sets the temperature of the th object/surface in the geometry to
TKelvin. (Here objects/surfaces are indexed using a 1-based convention; to set the temperature of the first object/surface specified in the
.scuffgeofile to room temperature you would say
--Temperature 1 300.)
If , this instead sets the temperature of the environment to
Specifies a file containing multiple temperature configurations at which to compute total PFTs. For an -body geometry, each line of
TFileshould contain space-separated numbers in the same format as the arguments to the
TEnv T1 ... TN.
For example, to compute PFTs in a two-body 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,
TFilewould look like
0 10 300 0 20 300 ... 0 300 300
scuff-integrate Command-Line Reference
Only numerical data columns are counted as columns
There is one potentially confusing aspect of the way
scuff-integrate interprets column indices as specified
by command-line arguments such as
This is that scuff-integrate treats non-numerical 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.45e-5 DEFAULT 0.2 7.82e-5 DEFAULT 0.3 1.10e-4 ...
then scuff-integrate 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.45e-5 4.00000 0.2 7.82e-5 4.00000 0.3 1.10e-4 ...
you would want to say
--freqColumn 2 --dataColumn 3.