Standard input and output files¶
Besides optional other parameter files that are used within the C++
stand-alone version or the Python version, FastChem requires two
special input files, one for the element abundances and a second
describing the mass action law constant parametrisations. Both are
described in the following.
Element abundance file¶
This file should contain the element abundances for all chemical
elements that are used in FastChem. The location of this file is
usually supplied either within a separate parameter file or directly in
the constructor of the FastChem object class.
A note on element abundances¶
It is important to note that there are two different ways to define an element abundance. Both variants, denoted by \(x_j\) and \(\epsilon_j\), are related via:
or
In the \(x_i\) version, widely used in the astronomical literature, hydrogen has a value of 12 for solar element abundances, such that its \(\epsilon_i\) is unity.
FastChem uses the \(x_j\) notation, also
employed in the usual standard abundance compilations (e.g. Asplund et al. 2009).
For example, in the
\(x_j\) notation, the solar element abundance for oxygen is
\(x_\mathrm{O}\) = 8.69, whereas its value for
\(\epsilon_\mathrm{O}\) would be \(0.00048978\).FastChem converts the \(x_j\) from the input file
to the computationally more appropriate \(\epsilon_j\). This also
refers to all methods of the FastChem object class that are used
to interact with the element abundances: these will always refer
to \(\epsilon_j\).Thus, if one wants to change the oxygen element abundance in the input
file (which refers to \(x_j\)) to ten times its solar value, one
would need to use a value of \(x_\mathrm{O}\) = 1 + 8.69 = 9.69. If
one, on the other hand, uses one of the internal FastChem methods to
change element abundances on the fly, one would need to set it to a
value of \(\epsilon_\mathrm{O} = 10 \cdot 0.00048978 = 0.0048978\).
File structure¶
The element abundance file should have the following structure to be
readable by FastChem:
#Solar element abundances based on Asplund et al. (2009)
e- 0.00
Al 6.45
Ar 6.40
C 8.43
Ca 6.34
Cl 5.50
Co 4.99
Cr 5.64
Cu 4.19
F 4.56
Fe 7.50
Ge 3.65
H 12.00
He 10.93
K 5.03
Mg 7.60
Mn 5.43
N 7.83
Na 6.24
Ne 7.93
Ni 6.22
O 8.69
P 5.41
S 7.12
Si 7.51
Ti 4.95
V 3.93
Zn 4.56
The first line is always a header line that provides important
information for the user and is ignored by FastChem. All subsequent
lines contain each the symbol for an element and its element abundance.
Molecules that contain elements not present in this file are ignored.
The element abundance for the electron has an arbitrary value. It is
only present in the file to inform FastChem that the electrons (and
thus ions) should be included in the chemistry calculations. Its element
abundance \(\epsilon_e\) will internally be set to 0 because its
number density is determined by charge balance. The elements are not
required to be in any particular order.
Standard files¶
Together with FastChem, we provide several different element
abundance files, located in the input/element_abundances/ folder.
The folder includes three different sets of element abundances:
Asplund et al. (2009),
Asplund et al. (2021), and
Lodders (2003) .
The standard files provide the solar element abundances for species that
are at least as abundant as germanium. As alternative versions, we also
include additional files *_extended.dat for each compilation, that
includes more elements, up to uranium. These files can be used for the
extended set of ion species described in the next section.
Species data files¶
FastChem publication
Stock et al. (2018), we use the natural
logarithm of the dimensionless mass action constant of species
\(i\)\[\ln\bar{K}_i(T) = - \frac{\Delta_\mathrm{r} G_i(T)}{R\,T} \ , \label{eq:lnK}\]
FastChem, these mass action constants are fitted with the
expression\[\ln\bar{K}_i(T) = \frac{a_0}{T} + a_1\,\ln T + b_0 + b_1\,T + b_2\,T^2 \ , \label{eq:fit}\]
gas_phase/molecule_struct.cpp, while the one for condensates is
located in condensed_phase/condensate_struct.cpp.File structure for gas phase species¶
For FastChem, the species information file should have the following
structure:
#logK = a1/T + a2 ln T + a3 + a4 T + a5 T^2 for FastChem:
#includes elements with eps >= eps_Ge
#fit coefficients calculated from indicated data source.
Al1Cl1 Aluminum_Chloride : Al 1 Cl 1 # JANAF tables
6.01726e+04 -9.82181e-01 -5.80778e+00 1.65774e-04 -6.11197e-09
Al1Cl1F1 Aluminum_Chloride_Fluoride : Al 1 Cl 1 F 1 # JANAF tables
1.22295e+05 -1.60844e+00 -1.43675e+01 3.72486e-04 -1.98493e-08
Al1Cl1F2 Aluminum_Chloride_Fluoride : Al 1 Cl 1 F 2 # JANAF tables
1.93126e+05 -1.90100e+00 -3.00531e+01 6.68640e-04 -3.72957e-08
FastChem files, we use the
modified Hill notation for the formulas. Isomeric species would in
principle have the same formula in the Hill notation. For example, the
two species HCN and HNC would both be referred to as C1H1N1. To
distinguish the two in the standard set of FastChem, underscores
are used, such that C1H1N1_1 refers to HCN, while C1H1N1_2
represents HNC. The use of the Hill notation is not a requirement. In a
custom version of the species file, a different chemical notation
could be used.Aluminum Chloride. The name is read until the seperator
: is encountered. Note that there has to be a white space between
the last part of the species’ name and the :.:, FastChem expects the stoichiometric
information of the species, i.e. the elements and their stoichiometric
coefficients. The elements need to be present in the element abundance
file as well, otherwise the species will be discarded. They don’t need
to be in any specific order.# is required
between the stoichiometry and the reference.FastChem will read in as many coefficients as it can
find in that line but for its own parametrisation it will only use the first five.File structure for condensate species¶
For FastChem, the species information file should have the following
structure:
#logK = a1/T + a2 ln T + a3 + a4 T + a5 T^2 for FastChem:
#includes elements with eps >= eps_Ge
#fit coefficients calculated from indicated data source.
Al2O3(s,l) Aluminum Oxide, Corundum : Al 2 O 3 # JANAF tables
sl
2327.0 4000.0
3.68482e+05 -1.04194e+01 -2.79243e+01 1.17904e-02 -1.58786e-06
3.71349e+05 5.273685e+00 -1.35345e+02 1.68173e-03 -8.80259e-08
Al2SiO5(s) Aluminum Silicate, Kyanite : Al 2 O 5 Si 1 # JANAF tables
s
3000.0
5.91829e+05 -1.46795e+01 -5.53926e+01 1.428257e-02 -1.5322e-06
CO(l) Carbon Monoxide : C 1 O 1 # Goodwin, R. D., 1985.
l
132.85
1.298145e+05 2.919440e+00 -3.27363e+01 -1.57201e-02 -5.51055e-05
The second line contains the phase state information. FastChem
currently recognises three different states: s (solid), l
(liquid), and sl (solid and liquid).
Condensates can have multiple data fits attached to them. Phase changes can result in non-monotonic slopes within the Gibb’s free energy of formation. To allow for a better fit to the resulting mass action coefficients, it is therefore usually beneficial to fit each phase separately. Additionally, thermochemical data for condensates is often only tabulated over a restricted temperature range, which makes extrapolation to higher temperatures problematic.
The third line, thus, lists the temperature limits of the different fitted data sets in the order they appear below. For solids, the limit is usually the melting point, whereas for liquids this can typically be the critical point or the last tabulated data point.
FastChem will use these temperature limits of the phase states when
it calculates the activities of the condensates. By default,
FastChem will also not extrapolate the date fits beyond the last
listed temperature. The user can override this behaviour by setting a
special FastChem parameter. More information on this can be found here.
The following lines finally contain the fit coefficients for the different data fits. Their format is identical to the corresponding one for the gas phase species discussed above. The number of data fits has to be equal to the number of temperature limits discussed above.
Standard files¶
Together with FastChem, we provide two different files for gas phase
species, located in the input/logK/ folder. The file logK.dat
provides the standard set, discussed in
Stock et al. (2018) and
Stock, Kitzmann & Patzer (2022). This includes species for
all elements at least as abundant as germanium.
As an alternative version, we also provide an additional file
logK_extended.dat that includes more ions for elements up to
uranium. The data for this file is discussed in
Hoeijmakers et al. (2019).
For condensate species we provide the file logK_condensates.dat in
the input/logK/ folder that contains all species discussed in
Kitzmann, Stock & Patzer (2023). We note that these condensates
should only be used in combination with the standard logK.dat file
for the gas phase since it lacks condensate species for the additional
elements contained in the species listed in logK_extended.dat.
Basic element data file (optional)¶
FastChem also needs to have
additional basic data for the elements, such as their atomic weight to
calculate the molecular weights of molecules, for example. For most
elements up to uranium, this data is hard-coded in a standard set
located in the header file chemical_element_data.h. If you want to
change this standard set by removing or adding elements or add
isotopes, you can change it directly in the header file and re-compile
FastChem.FastChem also has the option to read an external
file with the required information.File structure¶
The optional file has the following, simple structure, starting with a header line that is ignored when reading in the file:
#Basic element data based on Meija et al. (2016)
e- Electron 5.4857990907e-4
H Hydrogen 1.008
He Helium 4.002602
Li Lithium 6.94
Be Beryllium 9.0121831
B Boron 10.81
C Carbon 12.011
N Nitrogen 14.007
O Oxygen 15.999
F Fluorine 18.998403163
Ne Neon 20.1797
Na Sodium 22.98976928
Mg Magnesium 24.305
Al Aluminium 26.9815385
Si Silicon 28.085
P Phosphorus 30.973761998
S Sulfur 32.06
Cl Chlorine 35.45
Ar Argon 39.948
K Potassium 39.0983
Ca Calcium 40.078
Sc Scandium 44.955908
Ti Titanium 47.867
Mn Manganese 54.938044
Fe Iron 55.845
Co Cobalt 58.933194
Ni Nickel 58.6934
Cu Copper 63.546
Zn Zinc 65.38
Ga Gallium 69.723
Ge Germanium 72.630
As Arsenic 74.921595
Se Selenium 78.971
Br Bromine 79.904
It contains three columns, where the first one lists the elements’
symbols, the second their names, and the third their atomic weights. An
example of this file can be found in the folder
fastchem_src/chem_input/.
FastChem parameter file (optional)¶
FastChem is able to load a specific parameter file when one of its
instances is created through the object class constructor. This
parameter file includes the most important parameters and options used
within FastChem. All of these quantities can also be changed during
runtime by using the appropriate methods listed here
for the C++ object class and here
for the Python module. Using the parameter
file in principle allows changing these options and parameters outside
of the code and, therefore, does not require the code to be recompiled.
The input/ folder of the FastChem repository contains two example files:
parameters.dat and parameters_py.dat. The former is to be used for the C++
version, while the latter is intended for the Python version. The only difference
between the two files are the relative locations of the other input files since the Python
scripts are called from within a separate folder.
File structure¶
The optional parameter file has the following structure:
#element abundance file
input/element_abundances/asplund_2009.dat
#species data files
input/logK/logK.dat input/logK/logK_condensates.dat
#accuracy of chemistry iteration
1.0e-4
#accuracy of element conservation
1.0e-4
#max number of chemistry iterations
80000
#max number internal solver iterations
20000
#element data file (optional)
input/basic_element_data.dat
The first two entries are the locations of the element abundance and gas
phase & condensate species data files. The condensate species data file
is optional and can be left out or also replaced by none. In that
case, FastChem won’t be able to perform calculations including
condensation, though.
The next parameter determines the convergence criterion of the chemistry iteration. This value is also used for the internal Newton’s method and the condensation calculation iteration. The latter ones can be adjusted within in the code by the methods listed here C++ version and here for Python. This is followed by the (relative) accuracy of the element conservation checks.
The maximum number of chemistry iterations is listed next. The value here is also used for the maximum number of condensation iterations and for the number of coupled gas and condensed phase iterations.
The next parameter sets the maximum numbers of iterations for the
different internal numerical methods employed within FastChem. This
includes the Newton, Nelder-Mead, and bisection methods. Using the
corresponding functions of the FastChem object class, this
number can be adjusted for each of these numerical methods individually.
The last parameter is optional and does not need to be present in the
file. It contains the path to the file for an alternative basic element
data file. If this parameter is not present, FastChem will use the
standard set that is directly located in the FastChem source code
(see previous section).
Output files¶
The C++ stand-alone version will produce two output files: a
detailed chemistry output and a monitor file with diagnostic
information. The file names of both files can be chosen in the config
file discussed in the previous section.
Gas phase chemistry output¶
The chemistry output is organised in columns. The first line of the file is a header that describes the content of each column.
The first and second column contain the pressure in bar and the temperature in K, respectively. The third column lists the total number density of all atoms \(j\), i.e. \(n_\mathrm{tot} = \sum_j \left( n_j + \sum_i \nu_{ij} n_i + \sum_c \nu_{cj} n_c \right)\), summed over their atomic number densities, as well as the ones contained in all other molecules/ions \(j\) and the fictitious number densities of the condensate species \(n_c\). This is usually only a diagnostic quantity and rarely used in other applications.
The fourth column is the number density of the gas in units of cm\(^{-3}\), derived from the ideal gas law. This is followed by a column of mean molecular weights of the mixture of species in units of the unified atomic mass unit. For all practical purposes, this can also be converted into units of g/mol.
All subsequent columns contain the number densities (in
cm\(^{-3}\)) or the mixing ratios of all species, depending on the
choice of output made in the config file. By default, elements will be
placed in the beginning, followed by molecules and ions. Note that in
its species data files, FastChem employs the modified Hill notation
as used in the JANAF thermochemical tables (Chase, 1986)
for the formulas of all
non-element species. If, for example, you are looking for the abundance
of carbon dioxide, you need to locate the C1O2 column rather than
CO2, whereas NH3 would be listed as H3N1.
Condensate species output¶
The output for the condensate species has a similar structure than the one for the gas phase discussed above. The first two columns again refer to the pressures and temperatures. The subsequent columns for the various elements contain the corresponding degrees of condensation.
The remaining columns for the condensate species are the fictitious number densities in units of cm\(^{-3}\). As discussed in Kitzmann, Stock & Patzer (2023), for a given temperature and pressure the total number of stable condensates that can be present is limited by the number of elements. Thus, most condensates will usually have a fictitious number density of 0 cm\(^{-3}\), which indicates that they are not present.
Monitor file¶
The monitor output file is a very important diagnostic output that provides crucial details on the outcome of the chemistry calculations. You should further investigate any chemistry calculations that shows problems in this file. It is, therefore, advisable to check this file after each calculation to verify that everything went fine. The first line of the file is a header that describes the content of each column.
The monitor output is organised in columns, where the first column contains a simple integer that refers to index of the input temperature-pressure structure. The second column lists the number of coupled gas-phase chemistry and condensed phase iterations that were required to solve the system. If the number is zero, then no condensates were stable and only a pure gas-phase chemistry calculation was required.
The third columns contains the total number of gas-phase chemistry iterations, while the fourth column lists the total number of iterations for the condensed phase.
The next columns contain information on the convergence of the chemistry
and on the status of overall element conservation. If the chemistry did
converge properly ok will be listed as output, whereas fail is
used when the chemistry failed to converge in the maximum allowed number
of steps. The same keywords are used for the element conservation
status: ok if all elements were conserved, fail if any element
was not conserved.
The next four columns contain basic chemistry output, that is also found in the chemistry output file: the pressure, temperature, total element density, gas number density, and mean molecular weight.
All remaining columns list the status of the element conservation for each element separately. The same keywords as for the overall element conservation status are used again in these columns. For the electrons, this status refers to the charge balance rather than element conservation.
Benchmark input and output files¶
The input folder contains a selected sample of atmospheric structures of
various objects, from AGB stars to exoplanets. The
pre-computed chemistry output of these benchmark structures can be found
in the folder output_benchmarks. This chemistry output has been
generated with the standard FastChem options and the standard solar
element abundance and equilibrium constants files. These benchmarks can
be used to validate that the FastChem installation works correctly.
