thermo function

Thermodynamic Database and System Settings

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. UTF-8

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

Arguments

• no.organics: logical, load the database without data files for organic species (NOTE: 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 ) [100]
  Cp.tol	numeric	Difference in Cp above which check.EOS produces a message (cal K mol ) [1]
  V.tol	numeric	Difference in V above which check.EOS produces a message (cm mol ) [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 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 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 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 and 1 bar (cal K mol )
  n	numeric	Number of atoms of the element in its stable
  		compound at 25 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 for a complete description of the sources of data.

  The identifying characteristics of species and their standard molal thermodynamic properties at 25 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 )
  H	numeric	Standard molal enthalpy of formation
  		from the elements (J|cal mol )
  S	numeric	Standard molal entropy (J|cal mol K )
  Cp	numeric	Standard molal isobaric heat capacity (J|cal mol K )
  V	numeric	Standard molal volume (cm mol )

  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	* 10 (cal mol bar )
  a2	numeric	* 10 (cal mol )
  a3	numeric	(cal K mol bar )
  a4	numeric	* 10 (cal mol K)
  c1	numeric	(cal mol K )
  c2	numeric	* 10 (cal mol K)
  omega	numeric	* 10 (cal mol )
  Z	numeric	Charge

  Columns 15-22 for crystalline, gas and liquid species ( = $a$ + $bT$ + $cT$ + $dT$ + $eT$ + $fT$ ). 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 mol )
  b	numeric	$b$ (J K mol )
  c	numeric	$c$ (J K mol )
  d	numeric	$d$ (J K mol )
  e	numeric	$e$ (J K mol )
  f	numeric	$f$ (J K mol )
  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 equation (see 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 )
  b	numeric	$b$ (cm K g )
  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 and 1 bar are apparent values that are consistent with given values of enthalpy of transition (where available) at the transition temperature ($Ttr$). See the 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.

See Also

Other data files, including those supporting the examples and vignettes, are documented separately at extdata.

Examples

## 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()

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