| thermo {CHNOSZ} | R Documentation |
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.
reset()
OBIGT(no.organics = FALSE)
thermo(...)
no.organics |
logical, load the database without data files for organic species (NOTE: CH4 is listed as an “inorganic” species)? |
... |
list, one or more arguments whose names correspond to the setting to modify |
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 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 (cm3 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) + 2S(Z) = 2S(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 12C) | ||
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 (cm3 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 | a1 * 10 (cal mol-1 bar-1) |
a2 | numeric | a2 * 10-2 (cal mol-1) |
a3 | numeric | a3 (cal K mol-1 bar-1) |
a4 | numeric | a4 * 10-4 (cal mol-1 K) |
c1 | numeric | c1 (cal mol-1 K-1) |
c2 | numeric | c2 * 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 (Cp = a + bT + cT-2 + dT-0.5 + eT2 + fTlambda).
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 | Temperature of phase transition or upper |
| temperature limit of validity of extrapolation (K) |
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 (cm3 g-1) |
b | numeric | b (cm3 K0.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()$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.
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; instead, they are tabulated in the database.
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 C1 and C2 organic substances in SI units. J. Phys. Chem. Ref. Data 11 (supp. 2), 1–392. https://srd.nist.gov/JPCRD/jpcrdS2Vol11.pdf
Other data files, including those supporting the examples and vignettes, are documented separately at extdata.
## 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()