Changes between Version 25 and Version 26 of StoutData


Ignore:
Timestamp:
2017-09-06T14:14:40Z (3 months ago)
Author:
peter
Comment:

update data file description to the latest version

Legend:

Unmodified
Added
Removed
Modified
  • StoutData

    v25 v26  
    11= Stout Data Format =
    22
    3 Stout data files are stored in the ''data/stout/<element>/<element>_#/'' directory.
     3Stout 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/''.
    44
    5 The Stout data are separated into 3 files named ''<element>_#.<extension>''
     5The Stout data are separated into 3 files named ''<element>_<ionstage>.<extension>''
    66
    7 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.
     7The 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''.
    88
    99A masterlist file is used to determine which Stout species are enabled.
    10 The default masterlist file is Stout.ini and contained within the ''data/Stout/masterlist/'' directory.
     10The default masterlist file is Stout.ini and is contained within the ''data/stout/masterlist/'' directory.
    1111Other masterlists are specified with the command
    12 '''atom stout "masterlist"'''.
     12'''database stout "masterlist"'''.
    1313The minimum number of energy levels for a given species can be set via the masterlist file.
    1414Add the number of levels to the line of the intended species.
    1515For example,
    1616{{{
    17 N_1   50
     17n_1   50
    1818}}}
    19 will include a minimum of 50 levels of N_1.
    20 The number of levels is still subject to the '''atom stout levels ''' command.
     19will include the lowest 50 levels of n_1 (assuming there are that many of course).
     20The number of levels is still subject to the '''database stout levels''' command.
    2121
    22 The first line of each Stout file is a version number.
     22The 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".
    2323
    24 Lines starting with '''#''' are considered comments
     24Lines starting with '''#''' are considered comments. Comments can also be added after a line of data, also starting with '''#'''.
    2525
    2626Data fields in each Stout file are tab/space delimited.
    2727
    28 A field of stars, '''********''', marks the end of data in each file.
    29 The stars should start in the first column after the last line of data.
     28A field of stars (minimum 3), {{{********}}}, marks the end of data in each file.
     29The stars should start in the first column after the last line of data you want to be included.
     30
     31All data files are case sensitive, but the masterlist file is not.
    3032
    3133== References for data sources ==
     
    5254== Energy Level File ==
    5355
    54 The energy level file, ''<element>_#.nrg'', has 4 data fields per energy level.
     56The energy level file, ''<element>_<ionstage>.nrg'', has 3 or 4 data fields per energy level.
    5557
    5658We use experimental energies, often from [http://www.nist.gov/pml/data/asd.cfm NIST], since they are used to derive observed wavelengths.
    57 The energies do not need to be in increasing order since code exists
    58 to resort the energy order and correct the indices for the energy, collision,
    59 and transition probability files.
     59The 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.
    6060
    61 Field 1: The energy level index
     61Field 1: The energy level index. These need to be strictly in increasing order, where the first level has index 1, the second index 2, etc.
    6262
    63 Field 2: Energy in wavenumbers
     63Field 2: Energy in wavenumbers (cm^-1^).
    6464
    65 Field 3: Statistical weight (g)
     65Field 3: Statistical weight (g).
    6666
    67 Field 4: State information (optional)
    68 
     67Field 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.
    6968
    7069== Transition Probability File ==
     
    7473This allows different contributors to the line, E1, M2, etc, to be specified independently.
    7574
    76 The transition probability file, ''<element>_#.tp'', has up to 5 data fields per transition.
     75The transition probability file, ''<element>_<ionstage>.tp'', has 4 or 5 data fields per transition.
    7776
    78 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.
     77Field 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.
    7978
    80 Field 2: Lower level of the transition
     79Field 2: Lower level index of the transition, referring to the energy level file.
    8180
    82 Field 3: Upper level of the transition
     81Field 3: Same as Field 2, but for the upper level.
    8382
    84 Field 4: Either Aul, gf, or line strength depending on Field 1
     83Field 4: Either Aul (in s^-1^), gf, or line strength depending on Field 1. This value must be greater than zero.
    8584
    86 Field 5: Transition type (E1, E2, E3, M1, M2, or M3). This field is required for line strength data.
     85Field 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.
    8786
     87Only 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.
    8888
    8989== Collision Data File ==
    9090
    91 The collision data file, ''<element>_#.coll'', has 2 possible types of data rows, '''Temperature''' rows and '''Collision Data''' rows.
     91The collision data file, ''<element>_<ionstage>.coll'', has 2 possible types of data rows, '''Temperature''' rows and '''Collision Data''' rows.
    9292
    9393'''Temperature''' rows start with the keyword ''TEMP'', followed by the temperature data points in Kelvin.
    9494
    95 '''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.
    96 
    97 There should be the same number of temperature points as collision data points.
     95'''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.
    9896
    9997Example designation keywords are: '''CS ELECTRON''' if the collision data are electron collision strengths and '''RATE PROTON''' if they are proton rate coefficients.
    10098Available keywords are listed below.
    101 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.
     99The 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.
    102100
    103 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.
     101Setting 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.
    104102
    105103'''Keywords:'''
    106104
    107 Type of Data:
    108   * CS = Collision Strengths (Only for Electron Colliders)
     105Field 1: Type of Data:
     106  * CS = Collision Strengths (only for electron colliders)
    109107  * RATE = Rate Coefficients
    110108
    111 Colliders:
     109Field 2: Colliders:
    112110  * ELECTRON = Electron
    113111  * PROTON = Proton
     
    116114  * HE+2 = Alpha particle
    117115  * HE+ = Singly Ionized Helium
    118   * H2 ORTHO = Molecular Hydrogen Ortho
    119   * H2 PARA = Molecular Hydrogen Para
    120   * H2 = Molecular Hydrogen
     116  * H2ORTHO = Molecular Hydrogen Ortho
     117  * H2PARA = Molecular Hydrogen Para
     118  * H2 = Molecular Hydrogen (both Ortho and Para)
    121119
    122120== Masterlist files ==
    123121
    124 Stout uses masterlist files, saved in data / stout / masterlist, to decide which species to model with this database.
     122Stout uses masterlist files, saved in the ''data/stout/masterlist/'' directory, to decide which species to model with this database.
    125123These files are modeled after the masterlist files in Chianti.
    126 The masterlist Stout.ini is used by default and other masterlist files can be selected with the '''species stout masterlist''' command.
     124The masterlist Stout.ini is used by default and other masterlist files can be selected with the '''database stout "masterlist"''' command.
    127125
    128 
    129 The Stout masterlist file is protected with magic numbers, contained in '''md5datafiles.dat''',  which must be updated if the contents change.
     126The Stout masterlist file, as well as the data files themselves, are protected with md5 sums, contained in '''md5datafiles.dat''',  which must be updated if the contents change.
    130127Make 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.
    131128