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 <tt>#</tt> are ignored.



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.


  • 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


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.


  • Output (spectra and Tex valuest) will be written to binary files (see also keyword prefix).



  • 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<sup>-3</sup>), 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


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



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


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



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


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


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



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


  • 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:
  1. density
  2. kinetic temperature
  3. fractional abundance
  4. macroturbulence
  5. velocity
  6. volume filling factor (only 3D)
  7. angular size of the cloud
  8. 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.


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


  • 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



  • Selects a quasi random number generator instead of a pseudo random number generator. Should give a more uniform distribution of random numbers (= less noice).



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


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


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


  • For continuum calculations: follow and count only scattered photons. (??)

seed float

  • Seed number for the random number generator.


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


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


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