thermo {CHNOSZ} | R Documentation |
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: CH4 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 ofG.tol
andCp.tol
depend on theE_units
for each species inthermo()$OBIGT
. Therefore, species withE_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 (cm3 mol-1) [1]varP
logical Use variable-pressure standard state for gases? [ FALSE
] (seesubcrt
)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 fromS
(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 ofZ
is taken to be zero. Accessing this data frame usingmass
orentropy
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
andstate
defines a species inthermo()$OBIGT
. A species cannot be duplicated (this is checked when runningreset()
).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, andinfo("O2")
refers to the aqueous species.
Each entry is referenced to one or two literature sources listed in
thermo()$refs
. Usethermo.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 (seewater
). Most aqueous species use ‘HKF’ (the revised Helgeson-Kirkham-Flowers model). Properties of aqueous species withmodel
set to ‘AD’ are calculated using the Akinfiev-Diamond model, and those with ‘DEW’ are calculated using theDEW
model. Many minerals in the default database use the ‘Berman’ model (seeBerman
). 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 +eT
2 +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 settingE_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 CP 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
(cm3 g-1)b
numeric b
(cm3 K0.5 g-1)c
numeric \xi
d
numeric XX1
NAe
numeric XX2
NAf
numeric XX3
NAlambda
numeric XX4
NAZ
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’ andMOD5.N
proteins of ‘YEAST’ denote the mitochondrial and nuclear isoforms of this protein. Seepinfo
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 theiprotein
argument inaffinity
. -
thermo()$basis
InitiallyNULL
, reserved for a dataframe written bybasis
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
InitiallyNULL
, reserved for a dataframe generated byspecies
to define the species of interest. The number of columns in “...” is equal to the number of basis species (i.e., rows ofthermo()$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. Seeretrieve
, and the first test ininst/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 innonideal
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). Seedemo("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 inBerman
.
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 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
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()