util.data: Functions to Work with the Thermodynamic Database

Description Usage Arguments Details Value Warning References See Also Examples

Description

Add species to or alter properties of species in the thermodynamic database or in the buffer definition table. Show references for sources of thermodynamic data in a web browser. Check internal consistency of individual entries in database.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  add.obigt(file = system.file("extdata/thermo/OBIGT-2.csv", 
    package = "CHNOSZ"), force = FALSE, E.units = "cal")
  mod.obigt(...)
  today()
  thermo.refs(key=NULL)
  checkEOS(eos, state, prop, ret.diff = FALSE)
  checkGHS(ghs, ret.diff = FALSE)
  check.obigt()
  obigt2eos(obigt, state, fixGHS = FALSE)
  RH2obigt(compound = NULL, state = "cr", 
    file = system.file("extdata/thermo/RH98_Table15.csv", package = "CHNOSZ"))

Arguments

file

character, path to a file

force

logical, force replacement of already existing species?

E.units

character, units of energy, cal or J

...

character or numeric, properties of species to modify in the thermodynamic database

key

character, numeric, or list, containing reference key(s) for which to show URL(s) in browser

eos

dataframe, containing equations-of-state parameters in the format of thermo$obigt

state

character, physical state of species

prop

character, property of interest (Cp or V)

ret.diff

logical, return the difference between calculated and tabulated values?

ghs

dataframe, containing G, H and S, in the format of thermo$obigt

obigt

dataframe, in the format of thermo$obigt

fixGHS

logical, calculate one of missing G, H, or S?

compound

character, name of compound(s) in group additivity calculation

Details

add.obigt reads data from the specified file and adds it to thermo$obigt. Set force to TRUE to replace species that exist in the thermodynamic database (each unique combination of a name and a state in the database is considered to be a unique species). force, if not specified, reverts to TRUE if the file is left at its default. Given the default setting of E.units, the function does not perform any unit conversions. If E.units is set to J, then the thermodynamic parameters are converted from units of Joules to calories, as used in the CHNOSZ database.

add.obigt affects the order of entries in thermo$obigt; therefore, it should be called before any basis or species definition. Also, there is no attempt made to keep the order of physical states in the database (aq-cr-liq-gas); the function simply adds new rows to the end of thermo$obigt. As a result, retrieving the properties of an added aqueous species using info requires an explicit state="aq" argument to that function if a species with the same name is in one of the cr, liq or gas states.

mod.obigt changes one or more of the properties of species or adds species to the thermodynamic database. These changes are lost if you reload the database by calling data(thermo) or if you quit the R session without saving it. The name of the species to add or change must be supplied as the first argument of ... or as a named argument (named name). When adding new species, a chemical formula should be included along with the values of any of the thermodynamic properties. The formula is taken from the formula argument, or if that is missing, is taken to be the same as the name of the species. An error results if the formula is not valid (i.e. can not be parsed bymakeup). Additional arguments refer to the name of the property(s) to be updated and are matched to any part of compound column names in thermo$obigt, such as z or T in z.T. Unless state is specified as one of the properties, its value is taken from thermo$opt$state. When adding species, properties that are not specified become NA (except for state). The values provided should be in the units specifed in the documentation for the thermo data object, including any order-of-magnitude scaling factors.

today returns the current date in the format adopted for thermo$obigt (inherited from SUPCRT-format data files) e.g. 13.May.12 for May 13, 2012.

change is a wrapper function to mod.obigt and mod.buffer. The name provided in the argument refers to the name or numeric index of the species to update or add using mod.obigt, unless the name begins with an underscore character, in which case the remaining part of the name (after the underscore) is passed to mod.buffer. The arguments in ... are sent without change to the subordinate function.

thermo.refs with default arguments uses browseURL to display the sources of thermodynamic data in thermo$refs, with the URLs in that table showing as hyperlinks in the browser. Otherwise, if key is character, the citation information for those reference keys (including URLs) are returned. If key is numeric, the values refer to the species in those rows of thermo$obigt, and the citation information for each listed reference (thermo$obigt$ref1, thermo$obigt$ref2) is returned. If key is a list, it is interpreted as the result of a call to subcrt, and the citation information for each species involved in the calculation is returned.

checkEOS compares heat capacity and volume calculated from equation-of-state parameters with reference (tabulated) values at 25 °C and 1 bar and prints a message and returns the calculated value if tolerance is exceeded. The Helgeson-Kirkham-Flowers equations of state parameters are in eos, which is a data frame with columns (and column names) in the same format as thermo$obigt. The property can be one of Cp or V. The code only distinguishes between states of aq and all others. The default tolerances, given in thermo$opt$Cp.tol and thermo$opt$V.tol, are 1 cal/K.mol for Cp and 1 cm3/mol for V. If ret.diff is TRUE, the differences are returned irrespective of their values, and no messages are printed.

checkGHS compares G (standard molal Gibbs energy of formation from the elements) calculated from H (standard molal enthalpy of formation) and S (standard molal entropy) with reference (tabulated) values of G at 25 °C and 1 bar. A message is printed and the calculated difference is returned if it exceeds the value given in thermo$opt$G.tol, which has a default value of 100 cal/mol. The calculation requires that G, H and S, and the chemical formula of the species all be present. checkEOS and checkGHS are used by info when retrieving species parameters from the database.

check.obigt is a function to check self-consistency of each entry (with itself) in the thermodynamic database, using checkEOS and checkGHS. The function checks data in both thermo$obigt and extdata/thermo/OBIGT-2.csv. The output is a table listing only species that exceed at least one of the tolerance limits, giving the name of the database (OBIGT or OBIGT-2), the species index (rownumber in the database), species name and state, and DCp, DV and DG, for the calculated differences (only those above the tolerances are given). This function is used to generate the file found at extdata/thermo/obigt_check.csv.

obigt2eos takes a data frame in the format of thermo$obigt of one or more rows, removes scaling factors from equations-of-state parameters, and applies new column names depending on the state. This function is used by both info and subcrt when retrieving entries from the thermodynamic database. If fixGHS is TRUE a missing one of G, H or S for any species is calculated from the other two and the chemical formula of the species (used by subcrt when retrieving database entries).

RH2obigt implements a group additivity algorithm for standard molal thermodynamic properties and equations of state parameters of crystalline and liquid organic molecules from Richard and Helgeson, 1998. The names of the compounds and their physical state are searched for in the indicated file, that also contains chemical formulas and group stoichiometries; the names of the groups are stored in the column names of this file, and must be present in thermo$obigt. The default file (extdata/thermo/RH98_Table15.csv) includes data taken from Table 15 of Richard and Helgeson, 1998 for high molecular weight compounds in crystalline and liquid states. An error is produced if any of the compound-state combinations is not found in the file, if any of the group names for a given compound-state combination is not found in thermo$obigt, or if the chemical formula calculated from group additivity (with the aid of i2A and as.chemical.formula) is not identical to that listed in the file.

Value

The values returned (invisible-y) by mod.obigt are the rownumbers of the affected species.

Warning

Cautionary advice about the secondary database added by add.obigt (OBIGT-2.csv):

  • H4SiO4_Ste01, taken from Steffánson, 2001, is used in the vignette Regressing thermodynamic data for comparison with the H4SiO4 pseudospecies made in CHNOSZ (pseudo-H4SiO4). As with other species in OBIGT-2.csv, it is likely to be inconsistent with specific minerals and other species in the default database, so use it with care.

References

Richard, L. and Helgeson, H. C. (1998) Calculation of the thermodynamic properties at elevated temperatures and pressures of saturated and aromatic high molecular weight solid and liquid hydrocarbons in kerogen, bitumen, petroleum, and other organic matter of biogeochemical interest. Geochim. Cosmochim. Acta 62, 3591–3636. http://dx.doi.org/10.1016/S0016-7037(97)00345-1

Stefánsson, Andri (2001) Dissolution of primary minerals of basalt in natural waters. I. Calculation of mineral solubilities from 0°C to 350°C Chem. Geol. 172, 225–250. http://dx.doi.org/10.1016/S0009-2541(00)00263-1

See Also

The secondary thermodynamic database for add.obigt (extdata/thermo/OBIGT-2.csv) is used in some of the example calculations in the help page for diagram and also in anim.TCA.

mod.buffer for updating the list of available buffers.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
## modify an existing species with fake properties
ialanine <- mod.obigt("alanine", state="cr", G=0, H=0, S=0)
# we have made the values of G, H, and S inconsistent
# with the elemental composition of alanine so the following 
# produces a message about that
info(ialanine)
## add a species
iCl2O <- mod.obigt("Cl2O", G=20970)
info(iCl2O)
# add a species with a name that is distinct from the formula
mod.obigt("buckminsterfullerene", formula="C60", state="cr")

# citation information for Helgeson et al., 1998
thermo.refs("HOK+98")
# two references for alanine
thermo.refs(info("alanine"))
# three references for species in the reaction
s <- subcrt(c("O2","O2"),c("gas","aq"),c(-1,1))
thermo.refs(s) 
## Not run: 
## marked dontrun because it opens a browser
# show the contents of thermo$refs
thermo.refs()

## End(Not run) 

## calculate thermodynamic properties of organic compounds
## using group additivity, after Richard and Helgeson, 1998
RH2obigt()


Search within the CHNOSZ package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at ian@mutexlabs.com.

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.