Stout Data Format

Stout data files are stored in the data/stout/<element>/<element>_<ionstage>/ directory. Here <element> is the usual chemical symbol, but in lower case (e.g., fe for iron) while <ionstage> is the ionization stage in the usual Cloudy notation (i.e., 1 for neutral, 2 for singly ionized, etc.). So as an example, the files for neutral silicon should be stored in the directory data/stout/si/si_1/.

The Stout data are separated into 3 files named <element>_<ionstage>.<extension>

The extensions for the various files are: nrg for the energy level file, tp for the transition probability file, and coll for the collision data file. So the energy level file in the example above would be the file data/stout/si/si_1/si_1.nrg.

A masterlist file is used to determine which Stout species are enabled. The default masterlist file is Stout.ini and is contained within the data/stout/masterlist/ directory. Other masterlists are specified with the command database stout "masterlist". The minimum number of energy levels for a given species can be set via the masterlist file. Add the number of levels to the line of the intended species. For example,

n_1   50

will include the lowest 50 levels of n_1 (assuming there are that many of course). The number of levels is still subject to the database stout levels command.

The first line of each Stout file is a set of three version numbers. This document describes the version of the Stout data files with version numbers "17 09 05".

Lines starting with # are considered comments. Comments can also be added after a line of data, also starting with #.

Data fields in each Stout file are tab/space delimited.

A field of stars (minimum 3), ********, marks the end of data in each file. The stars should start in the first column after the last line of data you want to be included.

All data files are case sensitive, but the masterlist file is not.

References for data sources

The lines following the field of stars document the data sources by reference to the ADS link to the paper. A second field of stars ends the bibliography and can be followed by user comments. The following is an example:

NIST 2016-05-30

Comments can go here.  Examples include,
First four levels match to NIST, rest are from the reference indicated.

The 'Reference' keyword is mandatory. When the keyword "NIST" appears the information following is reported as part of the NIST reference. If the line contains "http" then the reference should be to the papers on ADS.

Energy Level File

The energy level file, <element>_<ionstage>.nrg, has 3 or 4 data fields per energy level.

We use experimental energies, often from NIST, since they are used to derive observed wavelengths. The energies do not need to be in increasing order. The code will sort the level energies in the correct order, making sure the atomic data are correctly transposed as well.

Field 1: The energy level index. This may have any integer value, as long as it doesn't match the index of another level.

Field 2: Energy in wavenumbers (cm-1).

Field 3: Statistical weight (g). This must be an integral number larger than zero.

Field 4: State information (optional). This is a free-format string that needs to be enclosed in double quotes so that it can contain spaces. For atomic levels this will typically contain the electronic configuration followed by the term information. This information is saved in the comment section of each transition, and is therefore included in the save line labels output. So make sure something meaningful to the user is in there if the field is included.

Transition Probability File

Transition probabilities are cumulative. If more than one is given for a particular transition they are added together. This allows different contributors to the line, E1, M2, etc, to be specified independently.

The transition probability file, <element>_<ionstage>.tp, has 4 or 5 data fields per transition.

Field 1: A character which identifies the data type provided by Field 4. A for Einstein A values, G for gf values, or S for the line strength.

Field 2: Lower level index of the transition, referring to the energy level file.

Field 3: Same as Field 2, but for the upper level.

Field 4: Either Aul (in s-1), gf, or line strength depending on Field 1. This value must be non-negative.

Field 5: The transition type (E1, E2, E3, M1, M2, or M3). This field is optional. Entries like M1+E2 are also allowed if the data are already summed over those transition types. There are no spaces allowed around the '+' symbol. If the line contains line strength data (i.e., type S) supplying the transition type is mandatory as it is needed in the conversion to a transition probability. In this case summing the data over various transition types is not allowed as this would make conversion into a transition probability impossible.

Only one transition with the same set of level indices and the same transition type may be entered in a file. If the transition type is omitted, it will be treated as E1 in this check.

The transition type field can also be set to UT, which stands for "undefined transition type". This is sometimes used by NIST when they do not know if a forbidden transition is either of type M1 or E2. In the test for duplicate transitions this entry is treated as if it is both M1 and E2.

Collision Data File

The collision data file, <element>_<ionstage>.coll, has 2 possible types of data rows, Temperature rows and Collision Data rows.

Temperature rows start with the keyword TEMP, followed by the temperature data points in Kelvin, in monotonically increasing order. This is currently limited to a maximum of 100 points, but it is not clear whether that limit is really needed.

Collision Data rows start with two keywords (the first specifies the type of data, and the second the collider), followed by the lower the upper levels of the transition, and then the collision data values of the type specified by the keywords.

Example designation keywords are: CS ELECTRON if the collision data are electron collision strengths and RATE PROTON if they are proton rate coefficients. Available keywords are listed below. The first line of the collision data file after the version number and excluding comments must be a Temperature row. All collision data after that row will be assumed to be on that temperature scale. There should be the same number of temperature points and collision data points on associated lines.

Setting a new temperature scale is achieved by adding a new Temperature row followed by the associated Collision Data rows. Collision Data rows are associated with the closest Temperature row that appears above them. A second Temperature row may have a different number of temperatures than the first.


Field 1: Type of Data:

  • TEMP = Temperature Scale
  • CS = Collision Strengths (only for electron colliders)
  • RATE = Rate Coefficients

Field 2: Colliders (only allowed if Field 1 is CS or RATE):

  • ELECTRON = Electron
  • H = Atomic Hydrogen
  • PROTON = Proton
  • H+ = Proton
  • HE = Atomic Helium
  • HE+ = Singly Ionized Helium
  • HE+2 = Alpha particle
  • H2 = Molecular Hydrogen (both Ortho and Para)
  • H2ORTHO = Molecular Hydrogen (only Ortho)
  • H2PARA = Molecular Hydrogen (only Para)

Masterlist files

Stout uses masterlist files, saved in the data/stout/masterlist/ directory, to decide which species to model with this database. These files are modeled after the masterlist files in Chianti. The masterlist Stout.ini is used by default and other masterlist files can be selected with the database stout "masterlist" command.

The Stout masterlist file, as well as the data files themselves, are protected with checksums. The GoldVersionToDo page contains instructions on how to update the checksum file.

If the same species is requested from more than one database the priorities are to use Stout, then Chianti, then Lamda.

Conversion to Stout Format

Matt Lykins created two Python scripts to convert data to the Stout format from other formats as he was doing this paper. These require Python3.

ADF04, energy levels, transition probabilities, and collision strengths

The script to convert from the ADF04 format used in the Open-ADAS database can be found in scripts/ in the root directory, named A possibly out of date version may be found here.

The ADF04 standard requires that all upper and lower states be joined with a non-zero transition probability. In practice, something like 20% of the TP will have a value of 1e-30 s-1, the smallest value they use. Many of these transitions are completely forbidden and, if the line exists, Cloudy has to transfer the line, no matter how small the TP. We introduced the rule that we do not create emission lines when the TP is 1e-30 s-1 or smaller.

NIST, energy levels and transition probabilities

The source:trunk/scripts/NistExtractor/ script will pull energy levels and transition probabilities from NIST and save them into Stout format. Matt's original version is here. This version no longer works as the NIST web server has been updated since.

Stout Report and References

The following scripts parse the link to the ADS paper containing the data set to create a report of the data sources. The format of this reference is give above.

A summary of the references to the original sources of the Stout data can be produced with the aid of the Perl script, which resides in scripts/ under the root directory. These can then be converted to LaTeX format with the script

In addition, a summary of all the atomic species known to Cloudy (in the Stout and Chianti databases) can be produced with the script, also in the scripts/ directory.

Return to DeveloperPages

Return to main wiki page

Last modified 9 months ago Last modified on 2020-01-15T16:49:26Z