Thermodynamic Database and System Definition

Share:

Description

Please read the important Warning at CHNOSZ-package.

The core data files provided with CHNOSZ are in the data directory of the package. These *.csv files are used to build the thermo data object on loading the package. Additional (extra) data files, supporting the examples and vignettes, are documented separately at extdata.

The thermo object holds the thermodynamic database of properties of species, some thermodynamic constants and operational parameters for functions in CHNOSZ, the properties of elements, references to literature sources of thermodynamic data, compositions of chemical activity buffers, and amino acid compositions of proteins. The thermo object also holds intermediate data used in calculations, in particular the definitions of basis species and species of interest input by the user, and the calculated properties of water so that subsequent calculations at the same temperature-pressure conditions can be accelerated.

The thermo object is a list composed of data.frames or lists each representing a class of data. The object is created in an environment named thermo; see sideeffects for details. It is created upon loading the package, through a call to data(thermo) in .onAttach. At any time, the user can restore the data object to its initial state by calling data(thermo). This is sometimes a useful command to use during an interactive session, when previous definitions of basis species and species of interest are longer desired.

The function add.obigt is available to update the thermodynamic database in use in a running session. For example, one can run add.obigt("mydata.csv") after loading the package, and the data in that file will be added to the database. The format of this file must be the same as the OBIGT.csv file provided with CHNOSZ. Although changes made using add.obigt are lost when the current R session is closed, the data can always be restored the next time as long as the user has the mydata.csv (or other) file available.

The first example below shows how to find the installation locations of OBIGT.csv and other *.csv files. Making changes to these files is not recommended, because incompatible changes can leave the package unusable; also, the files will be overwritten whenver the package is installed (or updated). Instead, use these files as templates for creating your own database files.

Usage

1
data(thermo)

Format

The items in the thermo object are documented below.

  • thermo$opt List of operational parameters. Square brackets indicate default values.

    Tr numeric Reference temperature (K) [298.15]
    Pr numeric Reference pressure (bar) [1]
    Theta numeric Theta in the revised HKF equations of state (K) [228]
    Psi numeric Psi in the revised HKF equations of state (bar) [2600]
    R numeric Value of the gas constant (cal K-1 mol-1) [1.9872]
    cutoff numeric Cutoff below which values are taken to be zero (see makeup) [1e-10]
    E.units character The user's units of energy ([cal] or J)
    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]
    water character Computational option for properties of water ([SUPCRT] or IAPWS)
    online logical Allow online searches of protein composition? Default [NA] is to ask the user.
    G.tol numeric Difference in value of G above which checkGHS produces a message (cal mol-1) [100]
    Cp.tol numeric Difference in value of Cp above which checkEOS produces a message (cal K-1 mol-1) [1]
    V.tol numeric Difference in value of 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 H2O ([liquid], vapor, or ) for saturation properties (see water.IAPWS95 and 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]
  • thermo$element Dataframe containing the thermodynamic properties of elements taken from Cox et al., 1989 and Wagman et al., 1982. 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. OBIGT is an acronym for OrganoBioGeoTherm, which refers to a software package produced by Harold C. Helgeson and coworkers at the Laboratory of Theoretical Geochemistry and Biogeochemistry at the University of California, Berkeley. (There may be an additional meaning for the acronym: “One BIG Table” of thermodynamic data.)

    As of CHNOSZ version 0.7, the data in OBIGT.csv represent 179 minerals, 16 gases, and 294 aqueous (largely inorganic) species taken from the data file included in the SUPCRT92 distribution (Johnson et al., 1992), an additional 14 minerals, 6 gases, and 1049 aqueous organic and inorganic species from the slop98.dat file (Shock et al., 1998), and approximately 50 other minerals, 175 crystalline organic and biochemical species, 220 organic gases, 300 organic liquids, 650 aqueous inorganic, organic, and biochemical species, and 40 organic groups taken from the recent literature. Each entry is referenced to one or two literature sources listed in thermo$refs. Use browse.refs to display the references in a browser window.

    Note the following additional modifications:

    • Use corrected values of a2 and a4 for [-CH2NH2] (were incorrectly listed as zero in Table 6 of Dick et al., 2006).

    • The standard molal thermodynamic properties and equations of state parameters of the aqueous electron are zero except for the standard molal entropy at 25 °C and 1 bar, which is the opposite of that for the element of charge (Z, see above).

    • The properties and parameters of some reference unfolded proteins used by Dick et al., 2006 are included here. Their names have dashes, instead of underscores, so that they are not confused with proteins whose properties are generated at runtime.

    • The standard molal Gibbs energies and enthalpies of formation of the elements and entropies at 25 °C and 1 bar of aqueous metal-amino acid (alanate or glycinate) complexes reported by Shock and Koretsky, 1995 were recalculated by adding to their values the differences in the corresponding properties between the values for aqueous alanate and glycinate used by Shock and Koretsky, 1995, and those used by Amend and Helgeson, 1997b and Dick et al., 2006.

    • The standard molal properties and equations-of-state parameters of four phase species (see below) of Fe(cr) were generated from heat capacity data given by Robie and Hemingway, 1995.

    These modifications are indicated in OBIGT.csv by having CHNOSZ as one of the sources of data. Note also that some data appearing in the slop98.dat file (Shock et al., 1998) were corrected or modified as noted in that file, and are indicated in OBIGT.csv by having SLOP98 as one of the sources of data.

    In order to represent thermodynamic data for minerals with phase transitions, the different phases of these minerals are represented as phase species that have states denoted by cr1, cr2, etc. The standard molar thermodynamic properties at 25 °C and 1 bar (Pr and Pr) of the cr2 phase species of minerals were generated by first calculating those of the cr1 phase species at the transition temperature (Ttr) 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 Ttr, and taking account of the enthalpy of transition (DeltaH0, taken from the SUPCRT92 data file) to calculate the standard molar enthalpy of the cr2 phase species at Ttr. The standard molar properties of the cr2 phase species at Ttr 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 DeltaH0 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 (Ttr) 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 12 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 (formatted as in SUPCRT92)
    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^3 mol^-1)

    The meanings of the remaining columns depend on the physical state of a particular species. If it is aqueous, the values in these columns represent parameters in the revised HKF equations of state (see hkf), otherwise they denote parameters in a general equations for crystalline, gas and liquid species (see cgl). The names of these columns are compounded from those of the parameters in each of the equations of state (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 13-20 for aqueous species (parameters in the revised HKF equations of state):

    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 omega * 10^-5 (cal mol^-1)
    Z numeric Charge

    Columns 13-20 for crystalline, gas and liquid species (Cp = a + bT + cT^-2 + dT^-0.5 + eT^2 + fT^lambda).

    a numeric a (cal K^-1 mol^-1)
    b numeric b * 10^3 (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^5 (cal K^-3 mol^-1)
    f numeric f (cal K-lambda-1 mol^-1)
    lambda numeric lambda (exponent on the f term)
    T numeric Temperature of phase transition or upper
    temperature limit of validity of extrapolation (K)
  • thermo$source Dataframe of references to sources of 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)
    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. Many 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 iprotein 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$water The properties calculated with water at multiple T, P points (minimum of 26) are stored here so that repeated calculations at the same conditions can be done more quickly.

  • thermo$Psat The values of Psat calculated with water.SUPCRT at multiple T points (minimum of 26) are stored here.

  • thermo$water2 The properties calculated with water.SUPCRT at multiple T, P points (minimum of 26) are stored here.

References

Amend, J. P. and Helgeson, H. C. (1997b) Calculation of the standard molal thermodynamic properties of aqueous biomolecules at elevated temperatures and pressures. Part 1. L-alpha-amino acids. J. Chem. Soc., Faraday Trans. 93, 1927–1941. http://dx.doi.org/10.1039/a608126f

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

Dick, J. M., LaRowe, D. E. and Helgeson, H. C. (2006) Temperature, pressure, and electrochemical constraints on protein speciation: Group additivity calculation of the standard molal thermodynamic properties of ionized unfolded proteins. Biogeosciences 3, 3110–336. http://www.biogeosciences.net/3/311/2006/bg-3-311-2006.html

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. http://dx.doi.org/10.1016/0098-3004(92)90029-Q

Shock, E. L. and Koretsky, C. M. 1995 Metal-organic complexes in geochemical processes: Estimation of standard partial molal thermodynamic properties of aqueous complexes between metal cations and monovalent organic acid ligands at high pressures and temperatures. Geochim. Cosmochim. Acta 59, 1497–1532. http://dx.doi.org/10.1016/0016-7037(95)00058-8

Shock, E. L. et al. 1998 SLOP98.dat (computer data file). http://geopig.asu.edu/supcrt92_data/slop98.dat, accessed on 2005-11-05. Current location: http://geopig.asu.edu/sites/default/files/slop98.dat.

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. http://www.nist.gov/data/PDFfiles/jpcrdS2Vol11.pdf

See Also

add.obigt for thermodynamic data from local .csv files.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
## where are OBIGT.csv and the other data 
## files on your installation?
system.file("data",package="CHNOSZ")

## exploring thermo$obigt
# what physical states there are
unique(thermo$obigt$state)
# formulas of ten species at random
n <- nrow(thermo$obigt)
thermo$obigt$formula[runif(10)*n]

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.