add.OBIGT {CHNOSZ}R Documentation

Functions to Work with the Thermodynamic Database


Add or modify species in the thermodynamic database.


  add.OBIGT(file, species = NULL, force = TRUE)
  mod.OBIGT(..., zap = FALSE)



character, path to a file


character, names of species to load from file


logical, force replacement of already existing species?


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


logical, clear preexisting parameters?


Note: change made to OBIGT are lost if you reload the database by calling reset or OBIGT or if you quit the R session without saving it.

add.OBIGT is used to update the thermodynamic database (thermo$OBIGT) in the running session. The format (column names) of the specified file must be the same as the extdata/OBIGT/*.csv files provided with CHNOSZ. Note that this includes both the E_units and model columns, which were added in versions 1.3.3 and 2.0.0.

file is first matched against the names of files in the extdata/OBIGT directory packaged with CHNOSZ. In this case, the file suffixes are removed, so ‘⁠DEW⁠’, ‘⁠organic_aq⁠’, and ‘⁠organic_cr⁠’ are valid names. If there are no matches to a system file, then file is interpreted as the path a user-supplied file.

If species is NULL (default), all species listed in the file are used. If species is given and matches the name(s) of species in the file, only those species are added to the database.

By default, species in the file replace any existing species having the same combination of name and state. Set force to FALSE to avoid replacing species that are present in (thermo()$OBIGT).

When adding (not replacing) species, 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 present 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. The name of the species to add or change must be supplied as the first argument of ... or as a named argument (named ‘⁠name⁠’). Additional arguments to mod.OBIGT refer to the name of the property(s) to be updated and are matched to any part of compound column names in thermo()$OBIGT. For instance, either ‘⁠z⁠’ or ‘⁠T⁠’ matches the ‘⁠z.T⁠’ column. The values provided should also include order-of-magnitude scaling of HKF and DEW model parameters (see thermo).

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 occurs if the formula is not valid (i.e. can not be parsed by makeup). For new species, properties that are not specified become NA, except for ‘⁠state⁠’ and ‘⁠E_units⁠’, which take default values from thermo()$opt. These defaults can be overridden by giving a value for ‘⁠state⁠’ or ‘⁠E_units⁠’ in the arguments.

⁠model⁠’, if missing, is set to ‘⁠HKF⁠’ for state == "aq" or ‘⁠CGL⁠’ otherwise. When modifying some existing minerals in OBIGT, model = "CGL" should be explicitly given in order to override the Berman model.

When modifying species, the parameters indicated by the named arguments of mod.OBIGT are updated. Use zap = TRUE to replace all prexisting parameters (except for state and model) with NA values.


The values returned (invisible-y) are the indices of the added and/or modified species.


Apps, J. and Spycher, N. (2004) Data qualification for thermodynamic data used to support THC calculations. DOC.20041118.0004 ANL-NBS-HS-000043 REV 00. Bechtel SAIC Company, LLC.

Bazarkina, E. F., Zotov, A. V., and Akinfiev, N. N. (2010) Pressure-dependent stability of cadmium chloride complexes: Potentiometric measurements at 1-1000 bar and 25°C. Geology of Ore Deposits 52, 167–178. doi:10.1134/S1075701510020054

Kitadai, N. (2014) Thermodynamic prediction of glycine polymerization as a function of temperature and pH consistent with experimentally obtained results. J. Mol. Evol. 78, 171–187. doi:10.1007/s00239-014-9616-1

Shock, E. L., Helgeson, H. C. and Sverjensky, D. A. (1989) Calculation of the thermodynamic and transport properties of aqueous species at high pressures and temperatures: Standard partial molal properties of inorganic neutral species. Geochim. Cosmochim. Acta 53, 2157–2183. doi:10.1016/0016-7037(89)90341-4

Stefánsson, A. (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. doi:10.1016/S0009-2541(00)00263-1

Sverjensky, D. A., Shock, E. L., and Helgeson, H. C. (1997) Prediction of the thermodynamic properties of aqueous metal complexes to 1000 °C and 5 kbar. Geochim. Cosmochim. Acta 61, 1359–1412. doi:10.1016/S0016-7037(97)00009-4

See Also

thermo (description of OBIGT), mod.buffer (modify buffer definitions), (fit thermodynamic parameters to formation constants)


## Modify an existing species (not real 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 
# now produces a message about that

## Add an aqueous species (default) with Gibbs energy given in J/mol 
## (the same as the default) and today's date
date <- as.character(Sys.Date())
iCl2O <- mod.OBIGT("Cl2O", date = date, E_units = "J", G = 87738)

## Add a solid species with a name that is different from the formula
mod.OBIGT("lorem-ipsum", formula = "C123", state = "cr", G = -12345678)
# Retrieve the data for this species using either name or formula
# reset database

## Using add.OBIGT():
# Compare stepwise stability constants of cadmium chloride complexes
# using data from Sverjensky et al., 1997 and Bazarkina et al., 2010
Cdspecies <- c("Cd+2", "CdCl+", "CdCl2", "CdCl3-", "CdCl4-2")
P <- c(1, seq(25, 1000, 25))
SSH97 <- lapply(1:4, function(i) {
  subcrt(c(Cdspecies[i], "Cl-", Cdspecies[i+1]),
    c(-1, -1, 1), T=25, P=P)$out$logK
file <- system.file("extdata/adds/BZA10.csv", package="CHNOSZ")
BZA10 <- lapply(1:4, function(i) {
  subcrt(c(Cdspecies[i], "Cl-", Cdspecies[i+1]),
    c(-1, -1, 1), T=25, P=P)$out$logK
matplot(P,, SSH97), type="l")
matplot(P,, BZA10), type="l", add=TRUE, lwd=2)
legend("topleft", legend=c("", "", "Sverjensky et al., 1997",
  "Bazarkina et al., 2010"), lwd=c(0, 0, 1, 2), bty="n")
# Make reaction labels
y <- c(1.8, 0.2, -0.5, -1)
invisible(lapply(1:4, function(i) {
  text(800, y[i], describe.reaction(subcrt(c(Cdspecies[i], "Cl-",
    Cdspecies[i+1]), c(-1, -1, 1), T=25, P=1)$reaction))
# Restore default database

# Another use of add.OBIGT()
# Compare Delta G of AABB = UPBB + H2O
# (Figure 9 of Kitadai, 2014)
# Default database has values from Kitadai, 2014
Kit14 <- subcrt(c("[AABB]", "[UPBB]", "H2O"), c(-1, 1, 1), T = seq(0, 300, 10))
# Load superseded parameters for [UPBB] from Dick et al., 2006
mod.OBIGT("[UPBB]", G = -21436, H = -45220, S = 1.62)
DLH06 <- subcrt(c("[AABB]", "[UPBB]", "H2O"), c(-1, 1, 1), T = seq(0, 300, 10))
xlab <- axis.label("T"); ylab <- axis.label("DG", prefix="k")
plot(Kit14$out$T, Kit14$out$G/1000, type = "l", ylim = c(10, 35),
     xlab = xlab, ylab = ylab)
lines(DLH06$out$T, DLH06$out$G/1000, lty = 2)
legend("topleft", c("Dick et al., 2006", "Kitadai, 2014"), lty = c(2, 1))
title(main = "AABB = UPBB + H2O; after Figure 9 of Kitadai, 2014")
# Restore default database

# Another use of add.OBIGT(): calculate Delta G of
# H4SiO4 = SiO2 + 2H2O using various sources of data for SiO2.
# First, get H4SiO4 from Stefansson, 2001
add.OBIGT("AS04", "H4SiO4")
T <- seq(0, 350, 10)
s1 <- subcrt(c("H4SiO4", "SiO2", "H2O"), c(-1, 1, 2), T = T)
# Now, get SiO2 from Apps and Spycher, 2004
add.OBIGT("AS04", "SiO2")
s2 <- subcrt(c("H4SiO4", "SiO2", "H2O"), c(-1, 1, 2), T = T)
# Plot logK from the first and second calculations
plot(T, s1$out$G, type = "l", xlab = axis.label("T"),
  ylab = axis.label("DG"), ylim = c(-500, 2500))
lines(T, s2$out$G, lty = 2)
# Add title and legend
title(main = describe.reaction(s1$reaction))
stxt <- lapply(c("H4SiO4", "SiO2", "SiO2"), expr.species)
legend("top", c("Shock et al., 1989", "Apps and Spycher, 2004"),
  title = as.expression(expr.species("SiO2")), lty = c(1, 2))
legend("topright", "Stef\u00e1nsson, 2001",
  title = as.expression(expr.species("H4SiO4")))
abline(h = 0, lty = 3, col = 8)
# Take-home message: SiO2 from Ste01 is compatible with H4SiO4 from Ste01
# at low T, but SiO2 from Shock et al., 1989 (the default in OBIGT) isn't

[Package CHNOSZ version 2.0.0 Index]