The program cppsimu is used to simulate radiative transfer of line emission in molecular clouds. The program can be obtained from the author. The versions available on the web contains the following limitations:
These manual pages are partly more up to date and may refer to options not available in the publicly available version.
Before running the program one must set up a parameter file and provide files containing molecular data and collision coefficients. It is better to keep all these files in the current working directory (at the moment a separate directory for molecular data etc. can be specified only at compile time). The following pages contain information about the input and output files and their formats.
The ‘ini-file’ contains various parameters that can be used to scale the cloud model (e.g., densities and temperatures), specify the molecule for which the radiative transfer problem is to be solved, set various options that affect the way calculations are carried out, and specify output files that are to be written. The name of the ini-file must be given on command line, e.g.,
Cppsimu my.ini
The file consists of lines which starts with a key word followed by one or more arguments. Comment lines starting with # are ignored.
A B C D E F G H I J K L M N O P Q R S T U V W X Y
abundance float1 float2
The lower and the upper limits for the fractional abundance of the
molecule (synonym for fraction). Linear scaling is applied to the
values originally read from a file. If float2<0 all read values are
multiplied directly with float1.
angle float
The size of the cloud in arc seconds. For 1d and 2d models the
radius of the cloud (in the direction perpendicular to the symmetry
axis). For 3d models the linear size of a single cell.
ascii
Output (spectra and Tex values) will be written to ascii files
(see also keyword prefix. Normally the header is commented out using
the character !. Using this keyword the header will be commented out
with character # and the files can be plotted with e.g. gnuplot
background float
When used together with the keyword montecarlo this specifies the
fraction (0.0-1.0) of the model photons that are to be emitted from
the background instead of from within the cloud.
bandwidth float
For both the simulation and the output spectra the width in km/s
of the calculated velocity intervals. In case of overlapping lines
this is the minimum velocity interval surrounding each individual line.
binary
Output (spectra and Tex valuest) will be written to binary files
(see also keyword prefix).
centreweight
For 1D clouds and direct simulation only. Normally the photon
packages are created in such a way that the density of packets
crossing any volume element is constant. With this keyword the packets
are directed preferentially towards the centre of the cloud (the
distribution of the impact parameters is uniform). This is useful when
the inner spheres in the model cloud are small and few photon packages
would otherwise hit them. With values below -10 an equal number of
packets will be sent towards each annulus as determined by the
gridding (which may well be the best thing to do) but positions within
each annulus are still random. If value is below -100 same number of
rays is sent towards each annulus, within each annulus the rays are
equidistant (that is, the impact parameters are also systematic) and
only directions of the incoming packages are random.
channels int
The number of velocity channels for the simulation and in the
calculated spectra. The number of channels in the spectra written to
output files can be overridden using the keyword spec_channels
changelimit float
Sets limits for the maximum allowed relative change in the level
populations i.e. the new population will be within
[1.0/changelimit,changelimit] times the old population. This kind of
limitation seems to be necessary ar least in case of some SiO maser
calculations…
clip float
Normally cells with densities below ~10.0 cm-3 are ignored during
the calculations. The limit can be changed with this keyword (unit
cm-3).
cloud[ 1d/2d/3d ] filename
The name of the file containing description of the
one-dimensional, two-dimensional or three-dimensional cloud.
cloud3dbin filename
Read the cloud model as a binary file. The file starts with cloud
dimensions (three integers) followed by the following data for each
cell: total density (cm-3), kinetic temperature (K),
turbulent linewidth (km/s), three components of the cell velocity
(km/s), and the fractional abundance of the species. In the file the
data for each cell is consecutive.
coolfile filename
The name of the binary file from which additional cooling rates
are read while calculating the kinetic temperatures in the cloud.
cooling filename
*Name of the binary file to which the cooling rates are saved
crtdust
Read dust emission from file crt.emission and dust opacity from
file crt.opacity. Both are binary files starting with two integers,
number of cells in the cloud and the number of transitions. File
crt.emission contains continuum emission as photons per velocity
channel per cm^-3, one number for each transition and each cell (that
is, for the frequencies of the line included in the simulation).
Values of different transitions of one cell are consecutive. File
crt.opacity contains continuum opacity per cloud radius (1d model) or
per cell length (3d model) for each cell and the frequencies of all
transitions. For each cell the values of different transitions are
again consecutive. Note that emission must be calculated using the
actual channel width used in the Cppsimu run. Usually the files would
be created using Python script CRT2Cppsimu.py and files created by the
program CRT: emitted.dat and the opacity file written using CRT option
[opacity|. Note: crtdust is currently implemented only in the
‘direct’ method (not with option) when the program is compiled using
-DWITH_CRT and without -DCORE_SATURATION.
custom int
Will run the simulation according to a specific scheme that may
include adjusting the number of levels, velocity channels, number of
photon packages and the number of cells in the cloud. The idea is to
do a number of fast iterations and increase the discretization only
when we have obtained an approximate solution. Under construction…
debug int
Sets the number of items printed to stdout during execution.
Valid values are 0,1,2..? Has little effect in practice.
density float1 float2 ...
Lower and upper limits for the density in the cloud: a linear
transform is applied to scale the density values specified by the
cloud model. If only one value is given (or the second value is
negative) the density values read from the file are multiplied with
the first parameter.
directions floats
This spectra are calculated as seen towards these directions. The
keyword is followed by pairs of floating point numbers: the first is
the angle between the z-axis (=the rotational axis for 1d and 2d
clouds) and the line-of-sight and the second the angle of rotation
from the direction of the positive x-axis towards the y-axis. Both are
given in degrees and the valid ranges are [0.0,180.0] and [0.0,360.0].
distance float
The distance to the cloud in parsecs.
dtkin float
Limits the calculated kinetic temperature to 1.0/dtkin … dtkin
times the value on the previous iteration.
dxfile prefix
Write Visualization Data Explorer files of the cloud, suffix n for
density and v for the velocity field.
emission
The emission (in units of antenna temperature) will be written to
files ’emission.1′ etc. with the suffix being the index of the
transition. The files consist of rows: index of the cell, index of the
velocity channel, the emitted intensity [K]
epsilon float
In optimization sets the stopping criterion: when the change is
for all parameters smaller than epsilon the optimization is finished.
In practice the limit must be set to a slightly smaller value than
what the desired accuracy is.
fileng integer
Perform Ng extrapolation of the level populations after each given
number of iterations. Computation is done as with the keyword ng
except that the level populations of the previous iterations are saved
to disk files and are not kept in the memory. If the normal save file
is file.save two additional files, file.save.1 and file.save.2, will
be written. Using fileng instead of ng can significantly reduce the
amount of needed RAM memory.
filling f k [ e ]
Change the filling factor of a 3D model cloud. The filling factor
is ‘f’ or if ‘e’ is given f*r^e where r is the distance from the cloud
centre (outer edge is at r=1). The density values of the other cells
are scaled by ‘k’ e.g. k=0 (i.e. f is the fraction of cells that is
NOT scaled by k)
fits
Output (spectra and Tex valuest) will be written to FITS files
(see also keyword prefix).
fraction float1 float2
The lower and the upper limits for the fractional abundance of the
molecule (synonym for abundance).
fwhm floats
In arc seconds, the FWHM of the beam used to convolve the
calculated intensity when the spectra are calculated. The given values
correspond to the transitions in the same order as they are given with
the keyword. If the number of given fwhm values is less than the number of
transitions the last given fwhm value is used for the rest of the
transitions. The values correspond to the order of transitions given
with the keyword . Note that also keyword samples must be specified
for fwhm to have any effect.
gnuplot
Output files written in ascii format (e.g. the spectrum files) may
contain a header. Normally the header is commented out using the
caharacter !. Using this keyword the header will be commented out with
character # and the files can be plotted with e.g. gnuplot
grid float
In a spectrum map the spacing between the computed spectra, given
in arc seconds.
heatfile filename
The name of the binary file from which heating rates will be read
while calculating the kinetic temperatures (see the separate section
on the cooling). The file should contain the heating rates for each
cell in units of 1.0e-25 Erg 1/s 1/(H2 molecule) and the four byte
floating point numbers should be given in the order corresponding to
the ordering in the files from which the cloud description is read.
(Note: the byte ordering is automatically changed so that the files
are interchangeble between e.g. Intel computers and Sun workstations.
In preparing the files on Intel the byte order of each floating point
number must be reversed i.e. 1234 => 4321)
heatobject name
Specifies the name of the object that provides the heating
information for Tkin calculations. Alternatively one can read heating
rates directly from a file (see heatfile).
INCLUDE filename
The contents of the the given file are interpreted as part of the
parameter file. If the molecule has not been given yet the included
file is taken as a continuation of the current file otherwise it is
assumed to contain parameters for another molecule. Simultaneous
calculation of several molecules can be carried out by using a
parameter file consisting of such include lines only – the actual
parameters of each molecule can be kept in separate files.
inside T R x y z [ | ISRF ]
Specify an isotropic source inside the model cloud with given
temperature T, and radius R (in cm). Optionally use ISRF instead of
black body. The coordinates of the source (x,y,z) are given in grid
coordinates (1D, 2D: radius 1 unit and centre at (0,0,0); 3D: cell one
unit and (0,0,0) at the corner of the cloud)
isotropic T dilution
Specify an isotropic background source with given temperature T
and a dilution factor. Optionally use ISRF instead of blackbody.
iterations int
The maximum number of iterations performed. The actual number
depends also on the value of ‘stop’.
itermax int
In optimization sets the maximum number of chi2 evaluations i.e.
the maximum number of different model clouds tested. The other
stopping criterion for optimization is given with the keyword epsilon
levels int
The number of energy levels included in the calculations. Note:
when the type of the molecule is ‘general’ the order in which the
levels are listed in the file *.mol defines the order in which the
levels are taken into calculations.
limit float
When using optimization the calculations are stopped once the chi2
value drops below the given limit. Since it is often difficult to say
what is a good chi2 value it is better to use only the keyword epsilon.
load filename
The name of the file from which the initial values of the level
populations are read (seed *.mol). The number of levels saved in the
file can be higher or lower than the current number of levels but the
dimensions of the clud must agree. If the density has been changed
since the values were saved this populations will be scaled
accordingly when the file is read.
lowmem
The optical depth of a cell remains constant during an iteration
and it they may be calculated only at the beginning of each iteration.
On the other hand, for 3D models a lot of space is needed for storing
these values (number of cells * number of transitions). If this
keyword is given the optical depth values are not stored at all. They
are instead calculated anew each time a model photon enters a cell.
This saves some memory but increases the run times by 5-10%.
make1d / make2d filename
This specifies a file from which instructions for creating the
cloud are read (as opposed to reading a cloud using cloud1d or
cloud2d). See separate section for the syntax of the files. THIS IS
NOW OBSOLETE: use cloud1d or cloud2d – the contents of the file will
be used to determine the file type (i.e. whether the file contains
data values or a prescription for calculating them)
molecule string
The name of the molecule: the molecular data will be read from
files string.mol and the collision coefficients from string.h2 and
(possibly) from string.he.
montecarlo
This selects ‘old fashioned’ Monte Carlo instead of the direct
simulation. May work or on the other hand it may not (this is not
tested).
NEXT
One file may contain several section which give parameters for
different molecules that are to be calculated simultaneously. This
keyword marks the beginning of a new section. Not all parameters given
for the previous molecule need to be repeated (e.g. the general
parameters of the cloud) but if given they will be ignored. Instead of
using this it may be more convenient to keep each molecule in its own
file and write a separate file consisting only of lines beginning with
the keyword include
ng int
Program will take an accelerated Ng step after every n:th
iteration as specified by the argument. Useful for optically thick
clouds. May lead to divergence if applied too soon. Requires the
saving of the level populations from a few previous iterations (a
problem with big 3D models…)
object string
During optimization the computed spectra are compared with spectra
that are read from files. The names of these files are composed of the
string given with this keyword, the name of the molecule and the
position in the map. For example, if the string is test, the name of
the molecule co, the transition J=2-1 and the observed position
(+1,-1) (irrespective of the value given with the keyword grid) the
name of the file will be test.co02-01.+1.-1.
onebyone
With this keyword the simulation step is performed separately for
each transition. This will slow down the computations but will reduce
the memory requirements since absorption counters of only one
transition and level populations of only two levels have to be kept in
memory at any given time. The equilibrium equations are also solved
one cell at a time using the disk files i.e. this does not increase
the memory consumption either. The simulation method used will be the
same as in normal runs when the keyword montecarlo is not given.
optimize tag1 value1 tag2 value2 ..
[Deprecated – better to embed Cppsimu calls to, for example, a Python
script that takes care of the optimization. Much more
flexible.]Selects the optimization. Each tag is an integer that refers
to a free variable and it is followed by the initial value given for
that variable. The possible free variables are: density kinetic
temperature fractional abundance macroturbulence velocity volume
filling factor (only 3D) angular size of the cloud cloud distance #-15
parameters of the model subroutine During the optimization the free
parameters 1-8 are used to multiply the original values and should
preferably be close to 1.0. If the density was set with the keyword
density to the range from 1.0e2 to 1.0e4 cm-3 and the initial value
given with optimize is 2.0 the optimization starts from a model with
densities in the range from 2.0e2 to 2.0e4 cm-3. The only exception is
the parameter number 6 which specifies the true volume filling factor.
Parameters 10 to 15 are passed directly to the model subroutine.
overlap
With this keyword the possible overlapping of different
transitions is taken into account. The overlap can be either between
different transitions of the same molecule or between transitions of
different molecules when they are calculated simultaneously.
packets int
The number of packets simulated during one iteration. For direct
simulation this should be large enough so that each cell of the cloud
is hit by at least 10 photon packages during each iteration. When
using normal Monte Carlo the number should be at least a factor of 10
higher (depends on the geometry, optical depths etc.).
points int1 int2
The number of positions in the computed spectrum maps: the first
integer is the number of positions in the RA direction the second the
number of points in the DEC direction.
pseudo
Selects internally implemented pseudo random number generator
(i.e. instead of a system generator or the quasi random number generator
prefix string
Prefix for the names of the output files
quasi
Selects a quasi random number generator instead of a pseudo
random number generator. Should give a more uniform distribution of
random numbers (= less noice).random
Selects a the random number generator provided by the system (i.e
instead of a internally implemented pseudo random and quasi random
number generators)
reference floats
This specifies for each transition the temperature of the
reference field. If number of given temperature values is less than
the number of transitions the last temperature is used from the rest
of the transitions. (For rotational transitions the order is that of
an increasing rotational quantum number; for molecules of the ‘general
type’ the ordering of the transitions is specified by the order in
which the transitions are listed in the file molecule.mol)
reset
This causes the random number generator to be reset after each
iteration. Using this keyword is generally a good idea when using
direct simulation. On the other hand, this should not be used with the
keyword weight.
restart ints
Gives a list of iterations on which the counters of absorption
events are restarted from zero i.e. is useful only when the keyword
weight is being used.
rho float
During optimization the algorithm finds a local minimum by
comparing the fit results at a few points at a given distance from the
initial point. New minima are searched for by moving to the minimum
and repeating the search with a smaller distance. The keyword rho
gives a factor in the range 0.0 to 1.0 that is used in decreasing the
search radius. With value much smaller than 1.0 the algorithm proceeds
quickly but is likely to miss the optimal points. If the value is very
close to 1.0 the convergence is slow but the optimization is likely to
succeed. It is probably best to keep the parameter within a range from
0.5 to 0.8. One might also start with a small value (~0.5) and check
the optimisation using a larger parameter value. Note that normally
rho is used also to set the initial search radius and e.g. if the
optimisation is continued after interruption it may be a good idea to
select a smaller radius using keyword inirho.
samples int
A number of samples over the beam area are computed when the
convolved spectra are being calculated. The number of samples in one
dimension is specified with this keyword i.e. the actual number of
samples is this raised to the power of two.
save filename
The name of the file to which the level populations are saved
after the calculations. Note: currently the level populations are
automatically save also on iteration number 4 and after that on every
third iteration
scatter
For continuum calculations: follow and count only scattered
photons. (??)
seed float
Seed number for the random number generator.
shortsave
Save level populations to save-file as (unsigned short)
integers i, such thatn = density*pow(0.9995, i). Normally populations
are saved as floating point numbers (4 bytes each). Short integers
take only 2 bytes so this reduces the size of the save-files to half
while the relative accuracy remains typically quite good (~0.05%).
sigma float1 float2
The lower and upper limit for the intrinsic linewidth
(microturbulence not including the thermal linewidth). Linear scaling
is applied to the values originally read from a file. If float2<0 all
read values are multiplied directly with float1.
size float
Specify the size of the model cloud in units of parsec (instead of
using angle to give the size in arc seconds). In 1D and 2D models the
size refers to the cloud radius, in 3D clouds to the size of an
individual cell.
smooth
This keyword is valid only for 3D clouds and direct simulation
(i.e. do not with the keyword montecarlo). In direct simulation one
must know for each cell what proportion of the photons emitted in the
cell are to be added to each passing photon package. This fraction is
calculated by comparing the distance the current package travels in
the cell with the total distance all packages travelled in the cell on
the previous iteration. The distances change randomly from cell to
cell and introduce noise in the absorption counters. With the keyword
smooth the fraction is replaced with an average fraction i.e. the
average distance one photon package travels within one cell divided by
the average distance photon packages travel within one cell during one
iteration. When the photon numbers are also weighted with the actual
number of photon packages passing the current cell divided by the
average number of photon packages passing a cell the noise gets
considerably lower. The only drawback is some loss of resolution: each
passing photon package is treated alike irrespective of the distance
travelled in the current cell (i.e. it does not matter whether the
package goes through the centre of the cell or just through a corner).
sources float
Fraction of all generated photon packages that are sent from
sources OTHER than isotropic external sources. External sources are
treated implicitly in direct simulation; in normal Monte Carlo the
keyword background determines the fraction of packages coming from
isotropic background.
spec_channels int
Number of velocity channels in the calculated spectra. If this is
not given the number of channels is that given with the keyword channels
spectra upper1 lower1 upper2 lower2 ...
The keyword is followed by pairs of integers giving the upper and
lower levels of the transitions for which spectra are to be written to
files at the end of a run. See the section on molecules for the
numbering of energy levels in connection with different types of
molecules.
spectra1 upper1 lower1 upper2 lower2 ...
As spectra but with levels numbered with indices starting with a
value of 1 instead of 0. (Added 2.12.2011)
store integer
Save level populations to disk files from given number of
iterations before the last one. If last level populations are saved to
file file.save the previous iterations will be saved to file.save.1,
file.save.2, … The files can be used with external programs to
extrapolate level populations before the next run (see also fileng).
stop float
On each iteration the maximum relative change in the level
populations in each cell is calculated for levels defined with the
keyword uppermost. The iterations will be stopped as soon as the
average over all cells of these changes is below the value given with
the keyword stop.
temperature lower upper...
Lower and upper limits for the kinetic temperatures in the cloud.
When the cloud is first read or made the temperatures are mapped to
the given range with a linear scaling. If only one value is given (or
the second value is negative) the sigma values of the initial model
are multiplied with the first parameter. This does not affect kinetic
temperatures read with the keyword tkinfile.
tkinfile filename.
The name from which the (current) values of the kinetic
temperature are read and to which they are written during Tkin
calculations.
tkinrange lower upper
The upper and lower limits for the allowed range of kinetic
temperatures (during reading, writing and calculations).
tkinupdate int
A flag controlling the calculations of kinetic temperatures. If
positive new Tkin values are calculated and updated only every n:th
iteration. If the number is negative updating is performed each time
the maximum relative change in the level populations is less than the
limit given with the keyword stop.
transitions upper1 lower1 upper2 lower2 ...
List of transitions for which the excitatin temperatures are to be
written to files at the end of a run. Transitions are specified in the
form of pairs of integers giving the indices for the upper and the
lower energy levels. See the section on molecules for the numbering of
energy levels in connection with different types of molecules.
transitions1 upper1 lower1 upper2 lower2 ...
As transitions but with levels numbered with indices that start
with a value of 1 instead of 0. (Added 2.11.2011)
turbulence value expo
Add macroturbulence to the model cloud: value(km/s) x R^expo where
R is the radius of the cloud. Makes absolutely no sense in the case of
1D models!
unisotropic T theta x y z dilution
Specify an isotropic background source with given temperature a
dilution factor. Optionally use ISRF instead of blackbody. The
direction towards the source is given by the vector (x,y,z) and theta
gives the angle in which the source is seen (angle corresponding to
the radius of the source).
uppermost int
Gives the index of the uppermost energy level that is to be
considered when the relative changes of the level populations are
compared with the limit given with the keyword ‘stop’.
velocity lower upper
Lower and upper limits for the macroscopic velocities in km/s. The
keyword is optional but when given the original velocities (read from
a file or calculated while creating the cloud) are mapped with linear
scaling to this range. If only one value is given (or the second value
is negative) the velocity values of the initial model are multiplied
with the first parameter.
verbose
Output will be directed to stout (not only to file cppsimu.err)
weight float
It is possible to calculate the absorption event counters as
averages of the past iterations and the results of the current
iterations. The parameter following the keyword is the relative weight
given for the previous iterations when the results of the current
iteration is given the weight 1.0. If the parameter value is negative
(e.g. -1.0) a cumulative average of the counters is used. Large weight
reduces the noice in the level populations but slows down the
convergence. It is not a good idea to use this together with the
keyword reset. This weight is currently used also in calculating the
average distance that packages travel in a cell during one iteration –
information that is used only in connection with ‘direct simulation’.xgauss filename
Use hfs structure given in filename to simulate pseudo-hfs (see
Keto et al. 2004). Gaussian line profile will be substituted with a
sum of gaussians with given frequencies and strengths. In the hfs
description file the first line for each transition should contain the
upper and lower levels of the transition (as with keyword spectra) and
the number of hfs components separated with whitespaces, e.g. 1 0 18.
Each following line must contain the offset of the hfs component from
the line central frequency (in units km/s) and the relative strength
of the component, e.g. -10.35 0.23. The sum of all relative strengths
of the components for a single transition should be 1(?). Several
transitions can be listed in a single file, separated with an empty
line.One-dimensional, spherically symmetric model cloud can be defined in two ways. The first is to specify analytical formulas for the various parameters. For example:
spheres 30
# models a + b * (radius^c); radius =
radius_of_the_sphere/radius_of_the_cloud
density 1.0 0.0 0.0
temperature 1.0 0.0 1.0
turbulence 1.0 0.0 0.0
radial 0.0 -1.0 1.0
rotation 0.0 0.0 0.0
fraction 1.0 0.0 0.0
expo 1.0
hole 0.1
The file can be called anything, e.g. sample.cloud. The first line gives the number of spheres. The following lines specify density etc. using three parameters a, b, and c listed on the line. The functional form of the distributions is a+b*r^c, where r is radius relative to the outer radius of the model cloud. The parameter expo determines how the cloud is divided into shells. Radiae are first calculated equidistantly and are then raised to the power given by expo. For example, if file contained line expo 0.33 the shells would have roughly equal volumes. The parameter hole specifies an empty innermost shell. The radius of the first, empty shell is adjusted to that radius.
Alternatively, the values can be listed shell by shell and the file looks like this:
read
7
4.000e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
6.179e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
7.082e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
7.775e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
8.359e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
8.873e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
9.339e+16 1.000e+05 1.000e+01 5.000e-09 1.500e-01 0.000e+00 0.000e+00
The first line indicates that values are read from the file directly (not computed) and the number of shells is given on the second line. The following lines list for each shell (starting from the centre) the values: outer radius, density cm-3, temperature K, fractional abundance, turbulent linewidth [km/s], radial velocity [km/s], and velocity of cloud rotation [km/s].
In both cases the ini-file should contain a line cloud1d sample.cloud (or whatever the previous files were called). All parameters can also be re-scaled using appropriate keywords in the ini-file : abundance, density, sigma, and velocity. The actual radius of the cloud is always determined by the keywords distance and angle (or the keyword size).
The 3D cloud consists of a Cartesian grid and the cloud is divided into Nx × Ny × Nz cubic cells. The cloud is defined by giving a file that lists the required parameters (density etc.) cell by cell. The cloud can be either a plain binary file or a FITS file.
This may be the simplest alternative. A binary file starts with three integers (3 x 4 bytes) that give the dimensions of the cloud: Nx, Ny, Nz. This is followed by floating point numbers (4 bytes each). The cloud is gone through cell by cell (x-coordinate runs fastest), and for each cell the file contains seven consecutive floating point numbers. These give for this cell the values of density [cm^-3], kinetic temperature [K], turbulent linewidth [km/s], three components of velocity vector [km/s], and the fractional abundance. Note that all these values can still be scaled using various keywords in the ini-file .
The 3D cloud can be given as a 4-dimensional FITS file. NAXIS1 equals
6 or 7, and the fields are the same (density etc.) as for the binary
file (NAXIS1=7) or the fractional abundance can be omitted (NAXIS1=6).
The three remaining axes correspond to cloud dimensions Nx, Ny, Nz.
New version of Cppsimu can read files in the format used by the Leiden Atomic and Molecular Database, Lamda . However, the input file must be modified to have after the number of collision temperatures on the same line a second number that gives the relative weight for collisions with that collision partner. The number must be always be included but its value is important only when the input file contains collisional coefficients for collisions with several partners. The filename is specified by the keyword molecule in the ini-file. The Lamda site contains files for a number of molecules.
Basic data. Cppsimu reads the molecular data (apart from the collision
coefficients) from a file molecule.mol where ‘molecule’ is the
name given in the parameter file using the keyword molecule. The
filename should contain lower case letters only. The file is in plain
ascii format. The file may contain any number of lines that are
commented out using the character ‘#’ or the character ‘!’ in the
first column. The type of the molecule is defined on the first line.
Valid values are “ro” (for rotational spectrum) and “generic”.
Any molecule can be described using the generic type. The energy
levels are numbered in arbitrary order starting from zero. The
energies are listed after keyword energies: each line contains the
number of the energy level followed by the energy in units of Hz. The
Einstein’s coefficients for spontaneous emission are listed after a
line containing the keyword A: each line contains indices of the upper
and lower level of the transition followed by the value of the
coefficient in units 1/s. Statistical weights are listed after a line
containing G with each line containing the index of the
level followed by the value of the statistical weight. For an example
see the file hcn.mol
.
If the type is ro energies can be given as above using the
energies keyword. Energies do not have to be listed if the rotational
constant of the molecule is given with the keyword B followed on the
same line by the value in units of MHz. Higher order correction
factors can be given with keywords D and H (see source code for the
exact formula). Einstein’s coefficient can be given as above or
alternatively the program can calculate the coefficients provided the
permanent dipole moment is given with the keyword dipole. See for
example file co.mol
. For molecule of the ro type
index of an energy level equals the quantum number J.
Keyword weight followed by numerical value defines the mass of the molecule in atomic mass units.
Collisional coefficients. Cppsimu needs the transition rates for the collisions between the studied molecule (X) and the major collision partners. Coefficients must exist at least for X-H2 collisions but the coefficients for collisions X-He may also be given.
The filenames are formed from the name of the molecule (as given in
the parameter file) and the name of the collision partner. For
example, the files used in CO calculations would be co.h2 and
co.he. The filenames should contain lower case letters only.
The files for the collision coefficients are in plain ascii format. The file may contain any number of lines that are commented out using the character ‘#’ or the character ‘!’ in the first column. The number of kinetic temperatures for which the coefficients are given is given on a line by itself and it is followed by the kinetic temperature values one per line. The rest of the file consists of lines where the indices of the initial and the final energy levels of a transition are followed by as many coefficients as there are kinetic temperatures. Note that the relations between energy level indices and the values of the quantum numbers are defined in the molecule file. If molecule type is ro the level index is the same as the rotational quantum number J.
If a collision coefficient is given in one direction only (e.g. for a downward transition) the coefficient for the reverse transition will be calculated from the equilibrium condition. Some coefficients are allowed to be missing although in that case warning messages will be generated.
For an example see the file co.h2 .
The parameter file determines what spectra are calculated and how they are saved. There are three possibilities for the output format: an ascii file, a binary file and a FITS-file.
Ascii spectra are written if the keyword ascii was given in the
parameter file and transitions were defined with keyword spectra. Each
spectrum is written into a separate file. The name of a file is formed
from the prefix given with prefix, the name of the molecule and the
transition. A file could be named e.g. test.co02-01.000.spe – test is
the given prefix, co the name of the molecule, transition is J=2-1,
000 is a running index for different spectra of the same transition
and .spe is the default suffix. The file itself contains two columns:
the velocity in km/s and the corresponding antenna temperature.
Binary files are written if the keyword binary was given in the parameter file. The file begins with a 4 byte integers giving the number spectra in the spectrum map and the number of channels in the file. This is followed by the velocity (km/s) of the first channel and the channel width (km/s) as 4 byte floating point numbers. This is followed by the spectra. For each spectrum the position in the map is given as two floating point numbers (4 bytes each), followed by the antenna temperature values for each channel. The spectra in a map are saved in an increasing order of RA and DEC with DEC changing fastest. In the case of the previous example all spectra would be saved into file test.co02-01.bin.
If keyword The files are named
according to the same scheme as the ascii files except for the suffix
which is ‘.s‘.fits is given (instead of ascii or binary) all
spectra are written into separate FITS-files.
The parameter file determines for what transitions the excitation
temperatures are calculated and how they are saved. There are three
possibilities for the output format: an ascii file, a binary file and
a FITS-file.
Tex files are written if keywords prefix and transitions are given in
the parameter file as well as one of the following: ascii, binary,
fits. The name of a file is formed from the prefix, the name of the
molecule and transition. A file could be named e.g. test.co02-01.tex –
test is the given prefix, co the name of the molecule, transition is
J=2-1 and spe is the default suffix.
The ascii files contains five columns: three indices of the cell, the excitation temperature in Kelvins and the distance from the cloud centre in centimeters. For 1D cloud the second and the third columns are all zeros; for 2D clouds only the third column is zeros.
Binary files are written if the keyword binary is given in the
parameter file. The file contains the excitation temperatures (4 byte
floats) for each cell. For 3D clouds the order is (x,y,z) with the
first coordinate running fastest; for 2D clouds from centre outwards,
one plane at a time; for 1D clouds the shells starting from the
centre. If cppsimu is compiled with the option DINTEL the byte order
is reversed (1234>4321) on writing. If keyword fits is given the
excitation temperatures are written into FITS-files. The naming
conventions are as above, the suffix is ‘.t’.
The file cppsimu.err contains all error messages from the latest run.
It contains also most of the output that is written to stout during
the program execution
For runs with a 1D cloud models the file scaled_cloud.dat contains
densities, kinetic temperatures etc. after they were scaled as
specified by the various keywords in the ini-file. The order of the
columns is the same as in the cloud description of a 1D model.