wiki:StoutData

Version 24 (modified by Gary J. Ferland, 3 weeks ago) (diff)

tidy up Stout python scripts description

Stout Data Format

Stout data files are stored in the data/stout/<element>/<element>_#/ directory.

The Stout data are separated into 3 files named <element>_#.<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.

A masterlist file is used to determine which Stout species are enabled. The default masterlist file is Stout.ini and contained within the data/Stout/masterlist/ directory. Other masterlists are specified with the command atom 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 a minimum of 50 levels of N_1. The number of levels is still subject to the atom stout levels command.

The first line of each Stout file is a version number.

Lines starting with # are considered comments

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

A field of stars, , marks the end of data in each file. The stars should start in the first column after the last line of data.

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:

**************
Reference:
NIST 2016-05-30
http://adsabs.harvard.edu/abs/2014A%26A...567A..18D
**************

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>_#.nrg, has 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 since code exists to resort the energy order and correct the indices for the energy, collision, and transition probability files.

Field 1: The energy level index

Field 2: Energy in wavenumbers

Field 3: Statistical weight (g)

Field 4: State information (optional)

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>_#.tp, has up to 5 data fields per transition.

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

Field 2: Lower level of the transition

Field 3: Upper level of the transition

Field 4: Either Aul, gf, or line strength depending on Field 1

Field 5: Transition type (E1, E2, E3, M1, M2, or M3). This field is required for line strength data.

Collision Data File

The collision data file, <element>_#.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.

Collision Data rows start with a designation keyword, followed by the lower the upper levels of the transition, and then the collision data values of the type specified by the designation keyword.

There should be the same number of temperature points as collision data points.

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. The number of data points specified on the Temperature row must be the number of temperature points and the number of collision data points for all 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.

Keywords:

Type of Data:

  • CS = Collision Strengths (Only for Electron Colliders)
  • RATE = Rate Coefficients

Colliders:

  • ELECTRON = Electron
  • PROTON = Proton
  • H = Atomic Hydrogen
  • HE = Atomic Helium
  • HE+2 = Alpha particle
  • HE+ = Singly Ionized Helium
  • H2 ORTHO = Molecular Hydrogen Ortho
  • H2 PARA = Molecular Hydrogen Para
  • H2 = Molecular Hydrogen

Masterlist files

Stout uses masterlist files, saved in data / stout / masterlist, 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 species stout masterlist command.

The Stout masterlist file is protected with magic numbers, contained in md5datafiles.dat, which must be updated if the contents change. Make sure md5datafiles.dat is up to date. To do this run ../scripts/generate_md5sums.sh in the root of the data directory. This requires the executable ../source/md5datafile.exe which is built alongside cloudy.exe by the make script.

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 adf042stout.py. A possibly out of date version may be found here.

NIST, energy levels and transition probabilities

The docs/NistExtractor.py script will pull energy levels and transition probabilities from NIST and save them into Stout format. Matt's original version is here.


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 db-ref-bib2json.pl, which resides in scripts/ under the root directory. These can then be converted to LaTeX format with the script db-ref-json2tex.pl.

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


Return to DeveloperPages

Return to main wiki page