MOCASSIN 2.02 manual
autoPackets
Syntax
autoPackets real1 real2 integer3
Description
The number of energy packets to be used in the next iteration will automatically be increased by a factor of real2 whenever a convergence plateau (defined by real1) is reached, i.e. if the convergence level increase is less than the value specified by the user in real1. For example, autoPackets 0.10 5. 1e8 will cause the total number of energy packets to increase by a factor of 5. whenever the convergence level increase from one iteration to the other is less than 10%. This only occurs when the convergence level is less than 85% and is the maximum number of packets defined by integer3 (1e8 in this example) has not been reached.
Default value
.false.
continuumCube
Syntax
continuumCube real1 real2
Description
This keyword creates a 3D cube of the escaped continuum radiation in direction given by the inclination keyword and over all directions.
If no inclination is specified in the input the continuum cube
will include packets escaping in all directions. The continuum band wavelength limits are defined by real1 and real2 (given in μm). A negative value or the omission of this keyword will result in no continuum cube being written out.
Default value
-1.
contShape
Syntax
contShape string [real]
Description
The shape of the ionising continuum. The default value is 'blackbody', in which case the ionising stellar continuum is approximated by the Planck function for the stellar temperature defined by the keyword TStellar. If 'string' == 'powerlaw' then this must be followed by a real number indicating the index of the power law distribution such that Fν ∝ ν-index. E.g. contShape powerlaw 1. will generate an input spectrum following a ν-1 distribution. Note that the final result will be normalised to the luminosity entered. The power law keyword is not compatible with the LPhot keyword, but only with the LStar keyword. If a stellar atmosphere data file is to be used, the 'string' must specify the path of the external file containing the data. For example contShape "NLTE140lg65" tells the program to look for the nLTe140lg65 data file in the current directory. The stellar atmosphere files must be in a format consisting of two columns: the first listing the wavelength points in units of [A] and the second containing the corresponding wavelength-dependent stellar Eddington fluxes in units of [erg/cm^2/s/A/sr]. A set of stellar atmosphere flux tables have been compiled by Dr T. Rauch in a MOCASSIN-friendly format and are available from http://astro.uni-tuebingen.de/~rauch/ (but please manually remove the header from the flux tables).
Default value
blackbody
convLimit
Syntax
convLimit real
Description
This is the convergence limit for the variation of a given parameter, in each grid cell from one Monte Carlo iteration to the next (e.g. 0.05 means changes of 5% maximum). In the case of a pure-gas (or gas+dust) simulation the criterion is based on the rate of change of neutral hydrogen. In the case of dust-only the criterion is based on the rate of change of the dust temperatures.
Other convergence criteria can also be used, at the moment, this would require a simple editing of some source modules. If you would like to use a different convergence criterion please email me and I can do the editing for you.
Default value
0.05
debug
Syntax
debug
Description
Logical switch to enable the debugging mode. When this keyword is included MOCASSIN will calculate a number of extra quantities (see Output files), which will, of course, slow the process down and also require more memory.
In mocassin 2.02.70+ and possibly earlier, this keyword will give segmentation faults if used - the bug is being investigated
Default value
.false.
densityFile
Syntax
densityFile string
Description
The density structure of the nebula can be defined cell by cell by using an external density file. MOCASSIN knows that a density file is to be used when the densityFile string is included in the input file, where string contains the name and path of the file where the data is stored. This file must consist of four, five or six columns, with the first three columns containing the x-, y-, and z- coordinates of the grid cell in [cm] and the fourth columns containing the value of the hydrogen density by number in [cm-3] at the particular grid cell. The x, y and z axis do not to be equally spaced - irregular grids are perfectly acceptable by MOCASSIN and also the extent of each axis can vary (as long as this is consistent with the values given in the nx, ny and nz fields). The fifth column is optional. If the multiChemistry keyword is specified the fifth column must contain an integer number in the range [1, Ncomponents] which indicates what component this cell belongs to (so that MOCASSIN can assign the chemical abundances for this component).
It is possible to specify nx, ny and nz from within string - the first row of the file should then be
# nx ny nz
and the keywords can be omitted from input.in
Default value
none
densityLaw
Syntax
densityLaw real...
Description
This keyword is usually followed by a set of parameters which are to be fed into the density law routine, included in the grid_mod module. Any density law can be specified by editing the code in the setGrid subroutine. If the nebula is homogeneous, this keyword must be omitted and the Hdensity keyword included instead. Note that if neither of the two keywords is included, and an external density file is not specified with the densityFile keyword, the nebular density distribution is left undefined and the simulation halted with an error message being produced.
Default value
0. 0. etc..
diffuseSource
Syntax
diffuseSource real1 real2 'string1' integer1 integer2
Description
This keyword can be used in the case of a non-central source such as the heating by radioactive decay of 56Co in supernova remnants. real1 is the total luminosity of the diffuse source in [1e36 erg/s], and real2 is the temperature of the diffuse source. string1 is the shape of the source spectrum, with the same syntax as contShape.
integer1 is the number of diffuse photons to use at the start of the model (same use as nPhotons).
integer2 is the index of the grid in which the diffuse source emits, which allows control of the extent of the diffuse source. For example, a medium with clumps embedded could be represented by a mother grid (index 0) and subgrids (indices 1..n). To restrict emission to the inter-clump medium only, integer2 would be set to 0. If there are no subgrids, set integer2 to 0.
Currently, for compatibility reasons, a value of TStellar must still be specified (i.e. TStellar=0.) but nPhotons, LStar and contShape can be removed from the input.in file.
diffuseSource should not be used at the same time as symmetricXYZ.
Default value
*
dustFile
Syntax
dustFile string1 string2
Description
names dust data files -
string1 = grain species file
string2 = grain size info file
Default value
"none", "none"
dustMass
Syntax
dustMass real1
Description
By default, MOCASSIN calculates the total dust mass from the user-specified number densities, dust species and grain size distributions. If this keyword is specified, the specified number densities are scaled when read in, such that the total dust mass is equal to real1. real1 has units of [Msun]
Default value
.false.
echo
Syntax
echo real1 real2
Description
If one needs to account for light travel time effects, for example if the source luminosity is changing, then this keyword will cause the results in SED.out to be integrated only over grid cells lying between ellipsoids corresponding to light travel times of real1 and real2. real1 and real2 are in light days, and real1 must be less than real2. The ellipsoids open out along the z-axis, and so one should also specify inclination 1 0.0 -1 in input.in when using this keyword. A review of the geometries of light echoes can be found in Sugerman, 2003, AJ, 126, 1939, and a case of MOCASSIN modelling including light travel time considerations is described by Wesson et al, 2010, MNRAS, 403, 474.
Default value
.false.
edges
Syntax
edges real1 real2 real3
Description
Defines the grid edges (only to be used with automatic grids). real1 real2 and real3 are respectively the x, y and z edges in cm
Default value
-1., -1., -1. *must be given if automatic grids are used
fillingFactor
Syntax
fillingFactor real1
Description
real1 can assume all values from 0. to 1. to defines the gas volume (and/or dust) filling factor
Default value
1.
getEquivalentTau
Syntax
getEquivalentTau
Description
Logical switch to enable equivalent optical depth calculations
(see Ercolano et al. 2007) - useful for diffuseSource and multiPhotoSources cases. The last column in the output file equivalentTau.out gives the source SED in the same units as SED.out, which may be useful to the user as well.
Default value
.false.
getTau
Syntax
getTau
Description
Logical switch to enable optical depth calculations and output - may be time consuming for large grids
Default value
.false.
Hdensity
Syntax
Hdensity real
Description
This keyword specifies a constant hydrogen density, by number, throughout the nebular region The command Hdensity 300, for example, will set the hydrogen density, by number, to the constant value of 300 cm-3.
Default value
0.
home
Syntax
home string
Description
Specifies the main installation of MOCASSIN. This allows the user to put the executable in a sourced path (e.g. /usr/local/bin) and run it out of any directory. The runtime directory needs only contain the input/ and output/ directories, and the files explicitly mentioned in the input.in file. Everything else is expected to be in the "home" directory, e.g.:
home '/software/mocassin/'
Note that the trailing slash is required.
This keyword is not necessary in versions from 2.02.71 onwards, which locate the data files automatically.
Default value
.false.
inclination
Syntax
inclination integer real1, real2 ..... real{n1}, real{n2}
Description
This keyword controls the viewing angles at which the SED will be calculated as it will appear in the SED.out file. The number of viewing angles is given first (integer; in this version integer <= 2) and then the θ and φ inclination in radians. To turn off the φ dependence, real_2 must be set to to -1. (θ=0. when the line of sight coincides with the z-axis)
Default value
0
inputNe
Syntax
inputNe
Description
This indicates that the density distribution of the grid is in terms of electron densities instead of H density. This will cause the code to calculate at each iteration the values of H density from the local Ne values by taking into account the local ionisation structure.
Default value
.false.
isotropicScattering
Syntax
isotropicScattering
Description
This keyword activates the logical switch that turns off unisotropic scattering (implemented via the Heyney-Greenstein phase function - with <cos θ> calculated from the dielectric constants via Mie theory).
Default value
.false.
LPhot
Syntax
LPhot real
Description
This is the number of hydrogen-ionizing photons emitted by the source per unit time, which is generally referred to as Q(H0), in the literature, with units of [E36 sec-1]. If this is given then the stellar luminosity, LStar is automatically derived from it.
Default value
* if LStar not given
LStar
Syntax
LStar real
Description
This is the stellar luminosity in units of [E36 erg sec-1]. If this is given as an input, then the number of hydrogen- ionizing photons, Q(H0), is automatically derived from it and from the input spectrum.
Default value
* if LPhot not given
maxIterateMC
Syntax
maxIterateMC integer1 real1
Description
integer1 is the maximum number of Monte Carlo iterations to
be performed in the simulation. real2 is the minimum convergence level to be achieved before the end of a simulation. The program will however
stop after integer1 iteration even if real1% of convergence has yet to
be reached.
Default value
30 95.
MdMg
Syntax
MdMg string1 real1/string2
Description
Dust to gas ratio by mass. If string1 = 'constant' then it must be followed by real1, containing the value of MdMg to be applied homogeneously to all cells in the grid. If string1=file then it must be followed by string2, the name of the file defining the MdMg at each location. Note that MdMg, MdMh and Ndust are mutually exclusive.
This file must consists of four columns, with the first three columns containing the x-, y-, and z- coordinates of the grid cell in [cm] and the fourth columns containing the dust to gas mass ratio at the particular grid cell. The x, y and z axis do not to be equally spaces, irregular grids are perfectly acceptable by MOCASSIN and also the extent of each axis can vary (as long as this is consistent with the values given in the nx, ny and nz fields).
It is possible to specify nx, ny and nz from within 'string2' - the first row of the file should then be
# nx ny nz
and the keywords can be omitted from input.in
Default value
.false. 0./'none'
MdMh
Syntax
MdMh string1 real1/string2
Description
Dust to Hydrogen ratio by mass. If string1 = 'constant' then it must be followed by real1, containing the value of MdMh to be applied homogeneously to all cells in the grid. If string1=file then it must be followed by string2, the name of the file defining the MdMh at each location. Note that MdMg, MdMh and Ndust are mutually exclusive.
This file must consists of four columns, with the first three columns containing the x-, y-, and z- coordinates of the grid cell in [cm] and the fourth columns containing the dust to hydrogen mass ratio at the particular grid cell. The x, y and z axis do not to be equally spaces, irregular grids are perfectly acceptable by MOCASSIN and also the extent of each axis can vary (as long as this is consistent with the values given in the nx, ny and nz fields).
It is possible to specify nx, ny and nz from within 'string2' - the first row of the file should then be
# nx ny nz
and the keywords can be omitted from input.in
Default value
.false. 0./'none'
multiChemistry
Syntax
multiChemistry integer1 string(1) string(2) ..... string(integer1)
Description
This keyword must be used when a chemically inhomogeneous model is being performed. The integer1 value defined the number of components to be used. string(1), string(2) ... string(integer1) are the names of the files describing the abundances in each component. When the multiChemistry keyword is included the density distribution MUST be specified via the densityFile keyword. The fifth column of the density file must contain the index for the abundance file describing the chemical composition at each location.
Default value
.false.
multiDustChemistry
Syntax
multiDustChemistry integer1 string(1) string(2) ..... string(integer1) string2
Description
This keyword must be used when a chemically inhomogeneous dust model is being performed. The integer1 value defined the number of components to be used. string(1), string(2) ... string(integer1) are the names of the files describing the dust species in each component, and string2 is the name of the grain size distribution file. When the multiDustChemistry keyword is included, the density distribution must be specified via the densityFile keyword. The fifth column of the density file must contain the index for the file describing the dust composition at each location.
Default value
.false.
multiGrids
Syntax
multiGrids integer1 string1
Description
This defines a multiple grid environment. The integer1 is the total number of grids to be used (mother + subgrids) and string1 is the name of the file containing the subgrid information. Please see Running multiple spatial grids.
Default value
.false. 'none'
multiPhotoSources
Syntax
multiPhotoSources string1
Description
This keyword is used to define multiple (or single) ionising sources, that can be placed at any locations. 'string1' is the name of the file containing the central star parameters. This file must contain in the first line the number of sources to be included and then each source should be specified on successive lines providing (in this order) Teff [K], L* [E36erg/s], ContShape, x-, y-, z-position. Note that the location of the source must be given normalised to the length of the relative axis. As example is included in the example/ directory.
Default
.false.
nbins
Syntax
nbins integer
Description
The total number of points to be used in the frequency mesh.
Default value
600
Ndust
Syntax
Ndust string1 real1/string2
Description
Number density [cm-3] of dust grains. If string1='constant' then it must be followed by real1, containing the value of Ndust to be applied homogeneously to all cells in the grid. If string1=file then it must be followed by string2, the name of the file defining Ndust at each location. Note that MdMg and Ndust are mutually exclusive. This file must consists of four columns, with the first three columns containing the x-, y-, and z- coordinates of the grid cell in [cm] and the fourth columns containing the number density of dust in [cm-3] at the particular grid cell. The x, y and z axis do not to be equally spaced; irregular grids are perfectly acceptable by MOCASSIN and also the extent of each axis can vary (as long as this is consistent with the values given in the nx, ny and nz fields).
It is possible to specify nx, ny and nz from within string2 - the first row of the file should then be
# nx ny nz
and the keywords can be omitted from input.in
Default value
.false. 0./'none'
nebComposition
Syntax
nebComposition string
Description
This keyword specifies the path of the nebular composition data file. If the default 'solar' composition (defined in the file solar.dat) is to be used, this keyword can be omitted. However the solar.dat file includes all elements with Z<30: this will result in a more memory expensive simulation. It is therefore advised to set to zero those elements which are not needed in the simulation. Otherwise the nebular composition can be specified in the user-defined string file to be found in the current directory. All composition input files must be in a format consisting of one column containing the abundances by number and relative to hydrogen for the first thirty elements in order of ascending atomic number. The abundances of elements which are not to be included in the simulations must be set to zero (this will automatically exclude them by flagging them out throughout the program). If the multiChemistry keyword is specified the nebComposition keyword must be omitted.
Default value
* if gas is present and no multiChemistry
NeStart
Syntax
NeStart real
Description
Initial guess for the nebular electron density.
Default value
0.
noPhotoelectric
Syntax
noPhotoelectric
Description
When this keyword is included in the input file all procedures associated with the calculation of the grain charges and photoelectric yield are switched off as well as gas-grain collision processes.
Default value
.false.
nPhotons
Syntax
nPhotons integer
Description
This is the number of energy packets to be used in the Monte Carlo simulation and it has to be specified for each model.
Default value
*
nStages
Syntax
nStages integer
Description
This is the number of ionisation stages to be used in the model. Max allowed is currently 10. If you have the atomic data necessary and would like to use more than 10 ionisation stages please contact me, or if you are confident you can edit the data/fileNames.dat and include the new data files to the pool.
Default value
7
nuMax
Syntax
nuMax real
Description
High limit of the frequency mesh in units of [Ryd]
Default value
15.
nuMin
Syntax
nuMin real
Description
Low limit of the frequency mesh in units of [Ryd]
Default value
0.
nx
Syntax
nx integer
Description
Number of axial points in the x-direction. Can also be specified on the first row of densityFile, Ndust, MdMg and MdMh files, in the form of a row containing
# nx ny nz
The keywords nx, ny and nz can then be omitted.
Default value
30
ny
Syntax
ny integer
Description
Number of axial points in the y-direction. Can also be specified on the first row of densityFile, Ndust, MdMg and MdMh files, in the form of a row containing
# nx ny nz
The keywords nx, ny and nz can then be omitted.
Default value
30
nz
Syntax
nz integer
Description
Number of axial points in the z-direction. Can also be specified on the first row of densityFile, Ndust, MdMg and MdMh files, in the form of a row containing
# nx ny nz
The keywords nx, ny and nz can then be omitted.
Default value
30
output
Syntax
output
Description
When this keyword is included the output files will be written at the end of each iteration. If it is omitted no output will be created. However, if the grid files are being created the output files can easily be recovered using the mocassinOutput driver.
Default value
.false.
planeIonization
Syntax
planeIonization real1 real2
Description
This keyword is used when the ionisation source is from a plane and not from a point source. real1 must contain the value of the incident ionizing flux above υ = real2 [Ryd] (constant at each point on the plane) in units of [phot/s/cm2]. If real2 = 0. then the real1 is assumed to be the bolometric flux.
When this keyword is specified the density distribution must be defined via the densityFile option. The ionizing plane is the x-z plane. the energy packets are reflected when they hit the y-z and the y-x planes and can escape from the x-z planes. (This can be easily changed to suit. please contact me if your work requires it to be different)
Default value
.false.
quantumHeatGrain
Syntax
quantumHeatGrain real1 real2
Description
This keyword activated the temperature spiking routines (quantum grain heating). It is only valid for simulations including dust. real1 is the limiting size of grain radii [μm] that will be allowed to spike (i.e. grains with a < real1 will spike). real2 is the minimum convergence level for the spiking to occur. Please read the notes on Grain temperature spiking procedures.
Default value
1.e-3, 99.
quantumHeatGrainParameters
Syntax
quantumHeatGrainParameters real1 integer1 logical1
Description
This keyword provides controls over some internal parameters in the quantum grain heating procedures. They should not be modified unless you really know what you are doing. real1 is the max temperature to be considered in the grain temperature mesh of the spiking. integer1 is the number of temperature (and enthalpy) bins considered. logical1 switches on and off the writing out of a file containing all the probability functions for all the grains in every cell. The resulting file can be really gigantic and so this value should be set to .true. only for debugging purposes and used with care. Please read the notes on Grain temperature spiking procedures contained in this manual.
Default value
700., 300, .false.
Rin
Syntax
Rin real
Description
Inner radius of the ionised region, in units of [cm].
Default value
*
Rout
Syntax
Rout real
Description
Outer radius of the ionised region in units of [cm].
Default value
0.
recombinationLines
Syntax
recombinationLines
Description
If this keyword is introduced, recombination line intensity of astrophysically abundant ions will be computed and appended to the lineFlux.out file
Default value
.false.
resLineTransfer
Syntax
resLineTransfer real
Description
real tells at what level of grid convergence the resonance line photons escape fractions should be calculated. This should be included when both dust and gas are present.
Default value
101.
slit
Syntax
slit real1 real2
Description
This keyword will cause the results in lineFlux.out, temperature.out and ionratio.out (see output files) to be integrated over only those cell that fall under the projection of a slit aligned along the z-axis of the grid. The slit x and y dimensions (in [cm]) are defined by real1 and real2 respectively.
If real1 and real2 have value 0. or if they are omitted, no slit is used
and the results are integrated over the whole active volume.
Default value
0., 0.
symmetricXYZ
Syntax
symmetricXYZ
Description
When the nebula to be modelled shows axial symmetry in the x- y- and z-directions, this keyword can be used to enable the symmetric grid procedures. This will result in the ionizing source being put in a corner of the grid, instead of being put in the centre, meaning that only one eighth of the nebula will have to be computed.
symmetricXYZ should not be used in models illuminated by a diffuse source.
Default value
.false.
talk
Syntax
talk
Description
This switch enables the verbose version of the program.
Default value
.false.
TeStart
Syntax
TeStart real
Description
Initial guess for the nebular temperature.
Default value
10000.
traceHeating
Syntax
traceHeating
Description
Logical variable to switch on the thermal balance channel tracing. When this is included in the input file a file called thermalBalance.out will be written to the output/ directory. Be aware that depending on the size of your grid this may be quite a large file and time-consuming in the I/O phase.
Default value
.false.
TStellar
Syntax
TStellar real
Description
Temperature in [K] of the ionizing stellar source.
Default value
*
writeGrid
Syntax
writeGrid real
Description
real indicates the minimum grid convergence percentage after which the grid files will be written out.
Default value
0.