Cppsimu

Cppsimu – Monte Carlo radiative transfer for lines

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:

  • only one-dimensional (spherically symmetric) and three-dimension (cartesian grid) geometries
  • partial handling of overlapping lines
  • no calculation of cooling efficiencies or thermal balance

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 topics below include:

Cppsimu initialisation file

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

^

A

  • 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 caharacter !. Using this keyword the header will be commented out with character # and the files can be plotted with e.g. gnuplot

^

B

  • 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).

^

C

  • 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…

^

D

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

^

E

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

^

F

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

^

G

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

^

H

  • 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).

^

I

  • 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

^

J

^

K

^

L

  • 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%.

^

M

  • 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).

^

N

  • 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…)

^

O

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

^

P

  • 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

^

Q

  • 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).

^

R

  • 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 optimization using a larger parameter value. Note that normally rho is used also to set the initial search radius and e.g. if the optimization is continued after interruption it may be a good idea to select a smaller radius using keyword inirho.

^

S

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

^

T

  • 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!

^

U

  • 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’.

^

V

  • 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)

^

W

  • 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’.

^

X

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

^

Y

^

Z

Cloud description

Definition of 1D cloud model

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

Definition of a 3D cloud

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.

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

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

Molecular data

Lamda file format

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 keywoard molecule in the ini-file. The Lamda site contains files for a number of molecules.

The old file format

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

Output files

Spectra

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.spetest 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 fits is given (instead of ascii or binary) all spectra are written into separate FITS-files. The files are named according to the same scheme as the ascii files except for the suffix which is ‘.s‘.

Excitation temperature

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

cppsimu.err

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

scaled_cloud.dat

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.