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 source data are provided with CHNOSZ as *.csv files in the extdata/thermo and extdata/OBIGT directories of the package. These files are used to build the thermo object, which is described below.

Usage

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

Arguments

no.organics: logical, load the database without data files for organic species (NOTE: CH₄ is listed as an “inorganic” 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 4.184 J = 1 cal).

`E.units`	character	The user's units of energy ([`J`] or `cal`) (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 `check.GHS` produces a message (cal mol^-1) [100]
`Cp.tol`	numeric	Difference in Cp above which `check.EOS` produces a message (cal K^-1 mol^-1) [1]
`V.tol`	numeric	Difference in V above which `check.EOS` 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. “OrganoBioGeoTherm” is the name of a Windows GUI interface to SUPCRT92 that was produced in Harold C. Helgeson's Laboratory of Theoretical Geochemistry and Biogeochemistry at the University of California, Berkeley. The OBIGT database was originally distributed with that program, and was the starting point for the database in CHNOSZ.

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.

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 identifying characteristics 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)
`model`	character	Model for thermodynamic properties of the species
`E_units`	character	Units of energy: `J` for Joules or `cal` for calories
`G`	numeric	Standard molal Gibbs energy of formation
		from the elements (J\|cal mol^-1)
`H`	numeric	Standard molal enthalpy of formation
		from the elements (J\|cal mol^-1)
`S`	numeric	Standard molal entropy (J\|cal mol^-1 K^-1)
`Cp`	numeric	Standard molal isobaric heat capacity (J\|cal mol^-1 K^-1)
`V`	numeric	Standard molal volume (cm³ mol^-1)

model must be one of H2O, HKF, CGL, Berman, AD, or DEW. H2O is reserved for liquid water, the properties of which are calculated using one of several available models (see water). Most aqueous species use HKF (the revised Helgeson-Kirkham-Flowers model). Properties of aqueous species with model set to AD are calculated using the Akinfiev-Diamond model, and those with DEW are calculated using the DEW model. Many minerals in the default database use the Berman model (see Berman). All other species use CGL (general crystalline, gas, liquid model). Properties of these species are calculated using a heat capacity function with up to six terms; the exponent on the final term can be defined in the database (see below).

The meanings of the remaining columns depend on the model for each species. The names of these columns are compounded from those of the parameters in the HKF equations of state and general heat capacity equation; for example, column 13 is named a1.a. Scaling of the values by integral powers of ten (i.e., orders of magnitude; OOM) for the HKF parameters (this also includes the DEW model) is based on the usual (but by no means universal) convention in the literature.

Columns 15-22 for aqueous species (parameters in the revised HKF equations of state). NOTE: Most older papers use units of calories for these parameters, so cal is listed here; the actual units for each species are set in the E_units column.

`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 15-22 for crystalline, gas and liquid species (C_P = $a$ + $bT$ + $cT$^-2 + $dT$^-0.5 + $eT$² + $fT$^lambda). NOTE: As of CHNOSZ 2.0.0, OOM scaling for heat capacity coefficients has been removed, and new entries use units of Joules unless indicated by setting E_units to cal.

`a`	numeric	$a$ (J K^-1 mol^-1)
`b`	numeric	$b$ (J K^-2 mol^-1)
`c`	numeric	$c$ (J K mol^-1)
`d`	numeric	$d$ (J K^-0.5 mol^-1)
`e`	numeric	$e$ (J K^-3 mol^-1)
`f`	numeric	$f$ (J K^-lambda-1 mol^-1)
`lambda`	numeric	λ (exponent on the $f$ term)
`T`	numeric	Positive value: Temperature (K) of polymorphic transition or phase stability limit
`T`	numeric	Negative value: Opposite of temperature (K) limit of C_P equation (see FAQ for details)

Columns 15-17 for aqueous species using the Akinfiev-Diamond model. Note that the c column is used to store the $\xi$ parameter. Columns 18-22 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 polymorphic transitions of minerals, so individual polymorphs 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()$Bdot_acirc Values of ion size parameter (Å) for species, taken from the UT_SIZES.REF file of the HCh package (Shvarov and Bastrakov, 1999), which is based on Table 2.7 of Garrels and Christ, 1965. This is used in nonideal with the default Bdot method. Custom ion size parameters can be added to this vector; to override a default value for a species, either replace the numeric value for that species or prepend a named numeric value (for duplicated species, the first value is used). See demo("yttrium") for an example of adding and overriding 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.

Note on polymorphic transitions

To enable the calculation of thermodynamic properties of polymorphic transitions, higher-temperature polymorphs of minerals are listed in OBIGT with states cr2, cr3, etc. The standard thermodynamic properties of high-temperature polymorphs at 25 °C and 1 bar are apparent values that are consistent with given values of enthalpy of transition (where available) at the transition temperature ($T_{tr}$). See the FAQ question “How can minerals with polymorphic transitions be added to the database?” for details of the retrieval of standard thermodynamic properties of polymorphs used in OBIGT.

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

Garrels, R. M. and Christ, C. L. (1965) Solutions, Minerals, and Equilibria, Harper & Row, New York, 450 p. https://www.worldcat.org/oclc/517586

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\) (J K^-1 mol^-1)
`b`	numeric	\(b\) (J K^-2 mol^-1)
`c`	numeric	\(c\) (J K mol^-1)
`d`	numeric	\(d\) (J K^-0.5 mol^-1)
`e`	numeric	\(e\) (J K^-3 mol^-1)
`f`	numeric	\(f\) (J K^-lambda-1 mol^-1)
`lambda`	numeric	λ (exponent on the \(f\) term)
`T`	numeric	Positive value: Temperature (K) of polymorphic transition or phase stability limit
`T`	numeric	Negative value: Opposite of temperature (K) limit of C_P equation (see FAQ for details)

`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