Cloud Files¶
File Structure¶
DESPOTIC cloud files contain descriptions of clouds that can be read
by the cloud
or zonedcloud
classes, using either the class
constructor or the read method; see cloud for
details. This section contains a description of the format for these
files. It is recommended but not required that cloud files have names
that end in the extension .desp
.
Each line of a cloud file must be blank, contain a comment starting
with the character #
, or contain a key-value pair formatted as:
key = value
The line may also contain comments after value
, again beginning
with #
. Any content after #
is treated as a comment and is
ignored. DESPOTIC keys are case-insensitive, and whitespace around
keys and values are ignored. For the full list of keys, see
Cloud file keys and their meanings. All quantities must
be in CGS units. Key-value pairs may be placed in any order, with the
exception of the key H2opr
, which provides a means of specify the
ratio of ortho-to-para-\(\mathrm{H}_2\), instead of directly
setting the ortho-and para-\(\mathrm{H}_2\) abundances. If this
key is specified, it must precede the key xH2
, which gives the
total \(\mathrm{H}_2\) abundance including both ortho- and para-
species. Not all keys are required to be present. If left unspecified,
most quantities default to a fiducial Milky Way value (if a reasonable
one exists, e.g., for the gas-dust coupling constant and
ISRF strength) or to 0 (if it does not, e.g., for densities and
chemical abundances).
Key | Units | Description |
---|---|---|
Physical Properties | ||
nH | \(\mathrm{cm}^{-3}\) | Volume density of H nuclei |
colDen | \(\mathrm{cm}^{-2}\) | Column density of H nuclei, averaged over area |
sigmaNT | cm \(\mathrm{s}^{-1}\) | Non-thermal velocity dispersion |
Tg | K | Gas temperature |
Td | K | Dust temperature |
Dust Properties | ||
alphaGD | erg \(\mathrm{cm}^3\) \(\mathrm{K}^{-3/2}\) | Gas-dust collisional coupling coefficient |
sigmaD10 | \(\mathrm{cm}^2\) \(\mathrm{H}^{-1}\) | Dust cross section per H to 10 K thermal radiation |
sigmaDPE | \(\mathrm{cm}^2\) \(\mathrm{H}^{-1}\) | Dust cross section per H to 8-13.6 eV photons |
sigmaDISRF | \(\mathrm{cm}^2\) \(\mathrm{H}^{-1}\) | Dust cross section per H averaged over ISRF |
betaDust | Dimensionless | Dust IR spectral index |
Zdust | Dimensionless | Dust abundance normalized to Milky Way value |
Radiation Field Properties | ||
TCMB | K | CMB temperature |
TradDust | K | Temperature of the dust-trapped IR radiation field |
ionRate | \(\mathrm{s}^{-1}\) | Primary cosmic ray / x-ray ionization rate |
chi | Dimensionless | ISRF strength, normalized to Solar neighborhood |
Chemical composition | ||
emitter | See Emitters |
Emitters¶
The emitter
key is more complex than most, and requires special
mention. Lines describing emitters follow the format:
emitter = name abundance [noextrap] [energySkip] [file:FILE] [url:URL]
Here the brackets indicate optional items, and the optional items may appear in any order, but must be after the two mandatory ones.
The first mandatory item, name
, gives name of the emitting
molecule or atom. Note that molecule and atom names are case
sensitive, in the sense that DESPOTIC will not assume that co
and
CO
describe the same species. Any string is acceptable for
name
, but if the file or URL containing the data for that species
is not explicitly specified, the name is used to guess the
corresponding file name in the Leiden Atomic and Molecular Database
(LAMDA) – see Atomic and Molecular Data. It is therefore generally advisable
to name a species following LAMDA convention, which is that molecules
are specified by their chemical formula, with a number specifying the
atomic weight preceding the if the species is not the most common
isotope. Thus LAMDA refers to \(^{28}\mathrm{Si}^{16}\mathrm{O}\)
(the molecule composed of the most common isotopes) as sio
,
\(^{29}\mathrm{Si}^{16}\mathrm{O}\) as 29sio
, and
\(^{12}\mathrm{C}^{18}\mathrm{O}\) as c18o
. The automatic
search for files in LAMDA also includes common variants of
the file name used in LAMDA. The actual file name from
which DESPOTIC reads data for a given emitter is stored in
the emitterData class – see emitterData.
The second mandatory item, abundance
, gives the abundance of that
species relative to H nuclei. For example, an abundance of 0.1 would
indicate that there is 1 of that species per 10 H nuclei.
The optional items noextrap
and energySkip
change how DESPOTIC
performs computations with that species. If noextrap
is set,
DESPOTIC will raise an error if any attempt is made to calculate a
collision rate coefficient between that species and one of the bulk
components (H, He, etc.) that is outside the range tabulated in the
data file. If not, DESPOTIC will instead handle temperatures outside
the tabulated range by substituting the closest temperature inside the
tabulated range. Note that this behavior can be altered within a
DESPOTIC program by using the extrap
property of the
emitterData
class – see Full Documentation of All DESPOTIC Classes and Functions.
The optional item energySkip
specifies that a species should be
ignored when computing heating and cooling rates via the
cloud.dEdt
method, and by extension whenever thermal equilibria or
thermal evolution are computed for that cloud. However, line emission
from that species can still be computed using the cloud.lineLum
method. This option is therefore useful for including species for
which the line emission is an interesting observable, but which are
irrelevant to the thermal balance and thus can be omitted when
calculating cloud thermal properties in order to save computational
time.
Finally, the optional items file:FILE
and url:URL
specify
locations of atomic and molecular data files, either on the local file
system or on the web. This capability is useful in part because some
LAMDA files do not follow the usual naming convention, or because for
some species LAMDA provides more than one version of the data for that
species (e.g., two versions of the data file for atomic C exist, one
with only the low-lying IR levels, and another including the
higher-energy UV levels). File specifications must be of the form
file:FILE
with FILE
replaced by a file name, which can include
both absolute and relative paths. If no path or a relative path is
given, DESPOTIC searches for the file first in the current directory,
and then in the directory $DESPOTIC_HOME/LAMDA
, where
$DESPOTIC_HOME
is an environment variable. If it is not specified,
DESPOTIC just looks for a directory called LAMDA relative to the
current directory.
The url:URL
option can be used to specify the location of a file
on the web, usually somewhere on the LAMDA website. It must be
specified as url:URL
, where URL
is replaced by an absolute or
relative URL. If an absolute URL is given, DESPOTIC attempts to
download the file from that location. If a relative URL is given,
DESPOTIC attempts to download the file from at
http://$DESPOTIC_LAMDAURL/datafiles/URL
, where
$DESPOTIC_LAMDAURL
is an environment variable. If this environment
variable is not specified, DESPOTIC searches for the file at
http://home.strw.leidenuniv.nl/~moldata/URL
.