thermo: Thermodynamic Database and System Settings

Description

Run reset() to reset all of the data used in CHNOSZ to default values. This includes the computational settings, thermodynamic database, and system settings (chemical species).

The system settings are changed using basis and species. To clear the system settings (the default, i.e. no species loaded), run basis(""); to clear only the formed species, run species(delete = TRUE)

The thermodynamic database is changed using add.OBIGT and mod.OBIGT. To restore the default database without altering the species settings, run OBIGT().

The computational settings are changed using water, P.units, T.units, E.units, and some other commands (e.g. mod.buffer).

All the data are stored in the thermo data object in an environment named CHNOSZ. thermo() is a convenience function to access or modify parts of this object, in particular some computational settings, for example, thermo("opt$ideal.H" = FALSE) (see nonideal).

The main data files provided with CHNOSZ, as *.csv files in the extdata/thermo and extdata/OBIGT directories of the package, are used to build the thermo object, which is described below.

Usage

reset()
  OBIGT(no.organics = FALSE)
  thermo(...)

Arguments

no.organics: logical, exclude data files for organic and biotic species?
...: list, one or more arguments whose names correspond to the setting to modify

Format

thermo()$opt List of computational settings. Square brackets indicate default values. Note that the units of G.tol and Cp.tol depend on the E_units for each species in thermo()$OBIGT. Therefore, species with E_units of J have a lower absolute tolerance for producing messages (because Joules are smaller than calories).

`cutoff`	numeric	Cutoff below which values are taken to be zero [1e-10] (see `makeup`)
`E.units`	character	The user's units of energy ([`cal`] or `J`) (see `subcrt`)
`T.units`	character	The user's units of temperature ([`C`] or `K`)
`P.units`	character	The user's units of pressure ([`bar`] or `MPa`)
`state`	character	The default physical state for searching species [`aq`] (see `info`)
`water`	character	Computational option for properties of water ([`SUPCRT`] or `IAPWS`; see `water`)
`G.tol`	numeric	Difference in G above which `checkGHS` produces a message (cal mol^-1) [100]
`Cp.tol`	numeric	Difference in Cp above which `checkEOS` produces a message (cal K^-1 mol^-1) [1]
`V.tol`	numeric	Difference in V above which `checkEOS` produces a message (cm³ mol^-1) [1]
`varP`	logical	Use variable-pressure standard state for gases? [`FALSE`] (see `subcrt`)
`IAPWS.sat`	character	State of water for saturation properties [`liquid`] (see `util.water`)
`paramin`	integer	Minimum number of calculations to launch parallel processes [1000] (see `palply`)
`ideal.H`	logical	Should `nonideal` ignore the proton? [`TRUE`]
`ideal.e`	logical	Should `nonideal` ignore the electron? [`TRUE`]
`nonideal`	character	Option for charged species in `nonideal` [`Bdot`]
`Setchenow`	character	Option for neutral species in `nonideal` [`bgamma0`]
`Berman`	character	User data file for mineral parameters in the Berman equations [`NA`]
`maxcores`	numeric	Maximum number of cores for parallel calculations with `palply` [`2`]
`ionize.aa`	numeric	Calculate properties of ionized proteins when H⁺ is in basis species (see `affinity`) [`TRUE`]

thermo()$element Dataframe containing the thermodynamic properties of elements taken from Cox et al., 1989, Wagman et al., 1982, and (for Am, Pu, Np, Cm) Thoenen et al., 2014. The standard molal entropy ($S$(Z)) at 25 °C and 1 bar for the “element” of charge (Z) was calculated from $S$(H2,g) + 2$S$(Z) = 2$S$(H+), where the standard molal entropies of H2,g and H+ were taken from Cox et al., 1989. The mass of Z is taken to be zero. Accessing this data frame using mass or entropy will select the first entry found for a given element; i.e., values from Wagman et al., 1982 will only be retrieved if the properties of the element are not found from Cox et al., 1989.

`element`	character	Symbol of element
`state`	character	Stable state of element at 25 °C and 1 bar
`source`	character	Source of data
`mass`	numeric	Mass of element (in natural isotopic distribution;
		referenced to a mass of 12 for ¹²C)
`s`	numeric	Entropy of the compound of the element in its stable
		state at 25 °C and 1 bar (cal K^-1 mol^-1)
`n`	numeric	Number of atoms of the element in its stable
		compound at 25 °C and 1 bar

thermo()$OBIGT

This dataframe is a thermodynamic database of standard molal thermodynamic properties and equations of state parameters of species. Note the following database conventions:

The combination of name and state defines a species in thermo()$OBIGT. A species cannot be duplicated (this is checked when running reset()).
English names of inorganic gases are used only for the gas state. The dissolved species is named with the chemical formula. Therefore, info("oxygen") refers to the gas, and info("O2") refers to the aqueous species.
Properties of most aqueous species (state = aq) are calculated using the revised Helgeson-Kirkham-Flowers (HKF) model (see hkf).
Properties of aqueous species with abbrv = AD are calculated using the Akinfiev-Diamond model (see AD).
Properties of most non-aqueous species (liquids, gases, and minerals) are calculated using a heat capacity polynomial expression with up to six terms (see cgl).
Properties of minerals with NA values of all heat capacity parameters are calculated using the Berman model (see Berman).

OrganoBioGeoTherm is the name of a GUI program to use SUPCRT in Windows, produced in Harold C. Helgeson's Laboratory of Theoretical Geochemistry and Biogeochemistry at the University of California, Berkeley. The OBIGT database was originally developed for that program, and was the original basis for the database in CHNOSZ.

Each entry is referenced to one or two literature sources listed in thermo()$refs. Use thermo.refs to look up the citation information for the references. See the vignette OBIGT for a complete description of the sources of data. The original OBIGT database was influenced by the SUPCRT92 (Johnson et al., 1992) and slop98.dat data files (Shock et al., 1998), and the references in those files are included here.

In order to represent thermodynamic data for minerals with phase transitions, the higher-temperature phases of these minerals are represented as phase species that have states denoted by cr2, cr3, etc. The standard molar thermodynamic properties at 25 °C and 1 bar ($T_r$ and $P_r$) of the cr2 phase species of minerals were generated by first calculating those of the cr (lowest-T) phase species at the transition temperature ($T_{tr}$) and 1 bar then taking account of the volume and entropy of transition (the latter can be retrieved by combining the former with the Clausius-Clapeyron equation and values of $(dP/dT)$ of transitions taken from the SUPCRT92 data file) to calculate the standard molar entropy of the cr2 phase species at $T_{tr}$, and taking account of the enthalpy of transition (${\Delta}H^{\circ}$, taken from the SUPCRT92 data file) to calculate the standard molar enthalpy of the cr2 phase species at $T_{tr}$. The standard molar properties of the cr2 phase species at $T_{tr}$ and 1 bar calculated in this manner were combined with the equations-of-state parameters of the species to generate values of the standard molar properties at 25 °C and 1 bar. This process was repeated as necessary to generate the standard molar properties of phase species represented by cr3 and cr4, referencing at each iteration the previously calculated values of the standard molar properties of the lower-temperature phase species (i.e., cr2 and cr3). A consequence of tabulating the standard molar thermodynamic properties of the phase species is that the values of $(dP/dT)$ and ${\Delta}H^{\circ}$ of phase transitions can be calculated using the equations of state and therefore do not need to be stored in the thermodynamic database. However, the transition temperatures ($T_{tr}$) generally can not be assessed by comparing the Gibbs energies of phase species and are tabulated in the database.

The identification of species and their standard molal thermodynamic properties at 25 °C and 1 bar are located in the first 13 columns of thermo()$OBIGT:

`name`	character	Species name
`abbrv`	character	Species abbreviation
`formula`	character	Species formula
`state`	character	Physical state
`ref1`	character	Primary source
`ref2`	character	Secondary source
`date`	character	Date of data entry (ISO 8601 extended format)
`E_units`	character	Units of energy: cal or J
`G`	numeric	Standard molal Gibbs energy of formation
		from the elements (cal mol^-1)
`H`	numeric	Standard molal enthalpy of formation
		from the elements (cal mol^-1)
`S`	numeric	Standard molal entropy (cal mol^-1 K^-1)
`Cp`	numeric	Standard molal isobaric heat capacity (cal mol^-1 K^-1)
`V`	numeric	Standard molal volume (cm³ mol^-1)

The meanings of the remaining columns depend on the model used for a particular species (see database conventions above). The names of these columns are compounded from those of the parameters in the HKF equations of state and general heat capacity polynomial; for example, column 13 is named a1.a. Scaling of the values by orders of magnitude is adopted for some of the parameters, following common usage in the literature.

Columns 14-21 for aqueous species (parameters in the revised HKF equations of state):

`a1`	numeric	a₁ * 10 (cal mol^-1 bar^-1)
`a2`	numeric	a₂ * 10^-2 (cal mol^-1)
`a3`	numeric	a₃ (cal K mol^-1 bar^-1)
`a4`	numeric	a₄ * 10^-4 (cal mol^-1 K)
`c1`	numeric	c₁ (cal mol^-1 K^-1)
`c2`	numeric	c₂ * 10^-4 (cal mol^-1 K)
`omega`	numeric	ω * 10^-5 (cal mol^-1)
`Z`	numeric	Charge

Columns 14-21 for crystalline, gas and liquid species ($Cp$ = $a$ + $bT$ + $cT$^-2 + $dT$^-0.5 + $eT$² + $fT$^lambda)

`a`	numeric	$a$ (cal K^-1 mol^-1)
`b`	numeric	$b$ * 10³ (cal K^-2 mol^-1)
`c`	numeric	$c$ * 10^-5 (cal K mol^-1)
`d`	numeric	$d$ (cal K^-0.5 mol^-1)
`e`	numeric	$e$ * 10⁵ (cal K^-3 mol^-1)
`f`	numeric	$f$ (cal K^-lambda-1 mol^-1)
`lambda`	numeric	λ (exponent on the $f$ term)
`T`	numeric	Temperature of phase transition or upper
		temperature limit of validity of extrapolation (K)

Columns 14-21 for aqueous species using the Akinfiev-Diamond model. Note that the c column is used to store the $\xi$ parameter, and that Z must be NA to activate the code for this model. The remaining columns are not used.

`a`	numeric	$a$ (cm³ g^-1)
`b`	numeric	$b$ (cm³ K^0.5 g^-1)
`c`	numeric	$\xi$
`d`	numeric	$XX1$ NA
`e`	numeric	$XX2$ NA
`f`	numeric	$XX3$ NA
`lambda`	numeric	$XX4$ NA
`Z`	numeric	$Z$ NA

thermo()$refs References for thermodynamic data.

`key`	character	Source key
`author`	character	Author(s)
`year`	character	Year
`citation`	character	Citation (journal title, volume, and article number or pages; or book or report title)
`note`	character	Short description of the compounds or species in this data source
`URL`	character	URL

thermo()$buffers

Dataframe which contains definitions of buffers of chemical activity. Each named buffer can be composed of one or more species, which may include any species in the thermodynamic database and/or any protein. The calculations provided by buffer do not take into account phase transitions of minerals, so individual phase species of such minerals must be specified in the buffers.

name character Name of buffer

species character Name of species

state character Physical state of species

logact numeric Logarithm of activity (fugacity for gases)

thermo()$protein Data frame of amino acid compositions of selected proteins. Most of the compositions were taken from the SWISS-PROT/UniProt online database (Boeckmann et al., 2003) and the protein and organism names usually follow the conventions adopted there. In some cases different isoforms of proteins are identified using modifications of the protein names; for example, MOD5.M and MOD5.N proteins of YEAST denote the mitochondrial and nuclear isoforms of this protein. See pinfo to search this data frame by protein name, and other functions to work with the amino acid compositions.

`protein`	character	Identification of protein
`organism`	character	Identification of organism
`ref`	character	Reference key for source of compositional data
`abbrv`	character	Abbreviation or other ID for protein
`chains`	numeric	Number of polypeptide chains in the protein
`Ala`...`Tyr`	numeric	Number of each amino acid in the protein

thermo()$groups This is a dataframe with 22 columns for the amino acid sidechain, backbone and protein backbone groups ([Ala]..[Tyr],[AABB],[UPBB]) whose rows correspond to the elements C, H, N, O, S. It is used to quickly calculate the chemical formulas of proteins that are selected using the iprotein argument in affinity.

thermo()$basis Initially NULL, reserved for a dataframe written by basis upon definition of the basis species. The number of rows of this dataframe is equal to the number of columns in “...” (one for each element).

`...`	numeric	One or more columns of stoichiometric
		coefficients of elements in the basis species
`ispecies`	numeric	Rownumber of basis species in `thermo()$OBIGT`
`logact`	numeric	Logarithm of activity or fugacity of basis species
`state`	character	Physical state of basis species

thermo()$species Initially NULL, reserved for a dataframe generated by species to define the species of interest. The number of columns in “...” is equal to the number of basis species (i.e., rows of thermo()$basis).

`...`	numeric	One or more columns of stoichiometric
		coefficients of basis species in the species of interest
`ispecies`	numeric	Rownumber of species in `thermo()$OBIGT`
`logact`	numeric	Logarithm of activity or fugacity of species
`state`	character	Physical state of species
`name`	character	Name of species

thermo()$stoich A precalculated stoichiometric matrix for the default database. This is a matrix, not a data frame, and as such can accept duplicated row names, corresponding to chemical formulas of the species. See retrieve, and the first test in inst/tinytest/test-retrieve.R for how to update this.

rownames character Chemical formulas from thermo()$OBIGT

... numeric Stoichiometry, one column for each element present in any species
thermo()$Berman A data frame with thermodynamic parameters for minerals in the Berman equations, assembled from files in extdata/Berman and used in Berman.

References

Cox, J. D., Wagman, D. D. and Medvedev, V. A., eds. (1989) CODATA Key Values for Thermodynamics. Hemisphere Publishing Corporation, New York, 271 p. https://www.worldcat.org/oclc/18559968

Johnson, J. W., Oelkers, E. H. and Helgeson, H. C. (1992) SUPCRT92: A software package for calculating the standard molal thermodynamic properties of minerals, gases, aqueous species, and reactions from 1 to 5000 bar and 0 to 1000°C. Comp. Geosci. 18, 899--947. tools:::Rd_expr_doi("10.1016/0098-3004(92)90029-Q")

Shock, E. L. et al. 1998 SLOP98.dat (computer data file). tools:::Rd_expr_doi("10.5281/zenodo.2630820")

Thoenen, T., Hummel, W., Berner, U. and Curti, E. (2014) The PSI/Nagra Chemical Thermodynamic Database 12/07. Paul Scherrer Institut. https://www.psi.ch/en/les/database

Wagman, D. D., Evans, W. H., Parker, V. B., Schumm, R. H., Halow, I., Bailey, S. M., Churney, K. L. and Nuttall, R. L. (1982) The NBS tables of chemical thermodynamic properties. Selected values for inorganic and C₁ and C₂ organic substances in SI units. J. Phys. Chem. Ref. Data 11 (supp. 2), 1--392. https://srd.nist.gov/JPCRD/jpcrdS2Vol11.pdf

Examples

Run this code

## Where are the data files in CHNOSZ?
system.file("extdata", package="CHNOSZ")
# What files make up OBIGT?
# Note: file names with _aq, _cr, _gas, or _liq
# are used in the default database
dir(system.file("extdata/OBIGT", package = "CHNOSZ"))

## Exploring thermo()$OBIGT
# What physical states are present
unique(thermo()$OBIGT$state)
# Formulas of ten random species
n <- nrow(thermo()$OBIGT)
thermo()$OBIGT$formula[runif(10)*n]

## Adding an element
old <- thermo()$element
# Element symbol, state, source (can be anything),
# mass, entropy, and number in compound
Xprops <- data.frame(element = "X", state = "cr",
  source = "user", mass = 100, s = 100, n = 1)
new <- rbind(old, Xprops)
thermo(element = new)
# Now "X" is recognized as an element in other functions
mass("X10")
# Restore default settings to remove X
reset()

Run the code above in your browser using DataLab

`a`	numeric	\(a\) (cal K^-1 mol^-1)
`b`	numeric	\(b\) * 10³ (cal K^-2 mol^-1)
`c`	numeric	\(c\) * 10^-5 (cal K mol^-1)
`d`	numeric	\(d\) (cal K^-0.5 mol^-1)
`e`	numeric	\(e\) * 10⁵ (cal K^-3 mol^-1)
`f`	numeric	\(f\) (cal K^-lambda-1 mol^-1)
`lambda`	numeric	λ (exponent on the \(f\) term)
`T`	numeric	Temperature of phase transition or upper
		temperature limit of validity of extrapolation (K)

`a`	numeric	\(a\) (cm³ g^-1)
`b`	numeric	\(b\) (cm³ K^0.5 g^-1)
`c`	numeric	\(\xi\)
`d`	numeric	\(XX1\) NA
`e`	numeric	\(XX2\) NA
`f`	numeric	\(XX3\) NA
`lambda`	numeric	\(XX4\) NA
`Z`	numeric	\(Z\) NA

`name`	character	Name of buffer
`species`	character	Name of species
`state`	character	Physical state of species
`logact`	numeric	Logarithm of activity (fugacity for gases)

`rownames`	character	Chemical formulas from `thermo()$OBIGT`
`...`	numeric	Stoichiometry, one column for each element present in any species