---
title: "OBIGT thermodynamic database"
output:
  html_vignette:
    mathjax: null
vignette: >
  %\VignetteIndexEntry{OBIGT thermodynamic database}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: OBIGT.bib
# So that these appear in the bibliography
nocite: | 
  @SPRONS92, @SLOP98, @SLOP07, @SLOP16, @JOH92, @WP02, @CWM89, @PRPG97, @TH88, @Kul06, @Sho09, @HKF81
csl: elementa.csl
link-citations: true
---
<style>
/* https://css-tricks.com/hash-tag-links-padding/ */
a.anchor::before {
  display: block;
  content: " ";
  margin-top: -220px;
  height: 220px;
  visibility: hidden;
  pointer-events: none;
}
</style>
<script>
function ToggleDiv(ID) {
  var D = document.getElementById("D-" + ID);
  if (D.style.display === "none") {
    // close all divs then open this one
    CloseAllDivs();
    OpenDiv(ID);
  } else {
    // close all divs
    CloseAllDivs();
  }
}
function OpenDiv(ID) {
  // open the div
  var D = document.getElementById("D-" + ID);
  D.style.display = "block";
  // style the button
  var B = document.getElementById("B-" + ID);
  var Btext = ID.split("-")[1];
  B.innerHTML = "<b>" + Btext + "</b>";
  B.style.color = "red";
}
function CloseDiv(ID) {
  // close the div
  var D = document.getElementById("D-" + ID);
  D.style.display = "none";
  // style the button
  var B = document.getElementById("B-" + ID);
  var Btext = ID.split("-")[1];
  B.innerHTML = Btext;
  B.style.color = "black";
}
function OpenAllDivs() {
  OpenDiv("aqueous-H2O");
  OpenDiv("aqueous-inorganic");
  OpenDiv("aqueous-organic");
  OpenDiv("solid-inorganic");
  OpenDiv("solid-organic");
  OpenDiv("solid-Berman");
  OpenDiv("gas-inorganic");
  OpenDiv("gas-organic");
  OpenDiv("liquid-organic");
  OpenDiv("optional-SUPCRT92");
  OpenDiv("optional-SLOP98");
  OpenDiv("optional-AD");
  OpenDiv("optional-DEW");
  OpenDiv("optional-Testing");
  // change the footer message
  document.getElementById("footer").style.display = "none";
  document.getElementById("all-open").style.display = "block";
}
function CloseAllDivs() {
  CloseDiv("aqueous-H2O");
  CloseDiv("aqueous-inorganic");
  CloseDiv("aqueous-organic");
  CloseDiv("solid-inorganic");
  CloseDiv("solid-organic");
  CloseDiv("solid-Berman");
  CloseDiv("gas-inorganic");
  CloseDiv("gas-organic");
  CloseDiv("liquid-organic");
  CloseDiv("optional-SUPCRT92");
  CloseDiv("optional-SLOP98");
  CloseDiv("optional-AD");
  CloseDiv("optional-DEW");
  CloseDiv("optional-Testing");
  // change the footer message
  document.getElementById("footer").style.display = "block";
  document.getElementById("all-open").style.display = "none";
}
</script>

```{r CHNOSZ_reset, include=FALSE}
library(CHNOSZ)
reset()
```

```{r setfile, include=FALSE}
# Assign the file name to the parent frame and return the name and number of species
setfile <- function(csvfile, dat=NULL) {
  # Assign csvfile outside this function
  assign("csvfile", csvfile, parent.frame())
  if(csvfile == "testing") {
    # Deal with testing optional data files as a group
    testing_files <- dir(system.file("extdata/OBIGT/testing", package = "CHNOSZ"), full.names = TRUE)
    testing_list <- lapply(testing_files, function(file) {
      dat <- read.csv(file, as.is = TRUE)
      source <- gsub(".csv", "", basename(file))
      cbind(source = source, dat)
    })
    dat <- do.call(rbind, testing_list)
    state <- "Optional "
    class <- "Testing"
  } else {
    # Deal with individual optional data files
    file <- system.file(paste0("extdata/OBIGT/", csvfile), package="CHNOSZ")
    dat <- read.csv(file, as.is=TRUE)
    ## Exclude entries for high-T polymorphs
    #dat <- dat[!dat$state %in% c("cr2", "cr3", "cr4", "cr5", "cr6", "cr7", "cr8", "cr9"), ]
    # The state and class of substance (used as section header), followed by number of species
    basename <- gsub(".csv", "", csvfile)
    class <- strsplit(basename, "_")[[1]][1]
    substr(class, 1, 1) <- toupper(substr(class, 1, 1))
    state <- strsplit(basename, "_")[[1]][2]
    if(identical(state, "aq")) state <- "Aqueous "
    else if(identical(state, "cr")) state <- "Solid "
    else if(identical(state, "gas")) state <- "Gas "
    else if(identical(state, "liq")) state <- "Liquid "
    else state <- "Optional "
  }
  paste0(state, class, " (", nrow(dat), " species)")
}
```

```{r filerefs, include=FALSE}
filerefs <- function(csvfile, dat=NULL, message=FALSE) {
  # With dat, look for ref2 in dat
  whichref <- "ref2"
  # Without dat, look for ref1 in csvfile
  if(is.null(dat)) {
    if(csvfile == "testing") {
      # Deal with testing optional data files as a group
      testing_files <- dir(system.file("extdata/OBIGT/testing", package = "CHNOSZ"), full.names = TRUE)
      testing_list <- lapply(testing_files, function(file) {
        dat <- read.csv(file, as.is = TRUE)
        source <- gsub(".csv", "", basename(file))
        cbind(source = source, dat)
      })
      dat <- do.call(rbind, testing_list)
    } else {
      file <- system.file(paste0("extdata/OBIGT/", csvfile), package="CHNOSZ")
      dat <- read.csv(file, as.is=TRUE)
    }
    whichref <- "ref1"
  }
  ## Exclude entries for high-T polymorphs
  #dat <- dat[!dat$state %in% c("cr2", "cr3", "cr4", "cr5", "cr6", "cr7", "cr8", "cr9"), ]
  # Count number of times each reference is used
  tab <- table(dat[, whichref])
  # In case there are not references (previously for H2O_aq.csv) we return the species here
  if(length(tab)==0) return(paste(dat$name, dat$state))
  # The reference keys
  keys <- names(tab)
  # Warn if any keys aren't in thermo()$ref$key
  ikey <- match(keys, thermo()$ref$key)
  ina <- is.na(ikey)
  if(any(ina)) cat(paste("**WARNING: key(s)", paste(names(tab)[ina], collapse=" "), "not found in `thermo()$ref$key`**\n\n"))
  # Put the table in chronological order, according to thermo()$ref
  ikey <- order(match(keys, thermo()$ref$key))
  tab <- tab[ikey]
  keys <- keys[ikey]
  xxx <- lapply(seq_along(tab), function(i){
    thiskey <- keys[i]
    # Read thermo()$ref$note
    iref <- match(thiskey, thermo()$ref$key)
    note <- thermo()$ref$note[iref]
    # Show the note in italics
    if(!identical(note, "")) note <- paste0(" *", note, "* ")
    # Use bullets for ref2
    if(whichref=="ref2") bullet <- "- " else bullet <- ""
    # Convert key with subreference (e.g. LD12.2) to reference in OBIGT.bib (e.g. LD12)
    thisref <- gsub("\\..*$", "", thiskey)
    # Replace SLOP98 with slop98.dat, etc.
    # (we don't actually cite them here to keep the year from showing -- it's annoying to see e.g. "slop98.dat (1998)")
    citemark <- "@"
    if(thisref=="SLOP16") { thisref <- "slop16.dat"; citemark <- "" }
    if(thisref=="SLOP07") { thisref <- "slop07.dat"; citemark <- "" }
    if(thisref=="SLOP98") { thisref <- "slop98.dat"; citemark <- "" }
    if(thisref=="SPRONS92") { thisref <- "sprons92.dat"; citemark <- "" }
    if(thisref=="OBIGT") { thisref <- paste0("OBIGT (", thermo()$ref$year[iref], ")"); citemark <- "" }
    cat(bullet, citemark, thisref, " -- ", tab[i], note, "\n\n", sep="")
    # Get ref2 if we're in the outer list
    if(whichref!="ref2") filerefs(dat=dat[dat$ref1==names(tab)[i], ])
  })
  # Return all the species listed
  paste(dat$name, dat$state)
}
```

```{r used, include=FALSE}
# Initialize the list of used species
used <- character()
# Initialize the list of used optional species
optused <- character()
```

This vignette, produced on `r Sys.Date()`, lists the references for thermodynamic data in the OBIGT database in CHNOSZ version `r sessionInfo()$otherPkgs$CHNOSZ$Version`.
Except for Optional Data, all data are present in the default database, which is loaded when the package is attached, or by running `reset()` or `OBIGT()`.

Each section below corresponds to one of the CSV data files in the `extdata/OBIGT` package directory.
Clicking on a button opens that section, which contains a list of primary references (from column `ref1` in the file) in chronological order.
Any secondary references (`ref2`) are listed with bullet points under the primary reference.
Each citation is followed by the number of species, and a note taken from `extdata/thermo/refs.csv`.
Additional comments (from this vignette) are present for some sections.

Abbreviations: T (temperature), P (pressure), GHS (standard Gibbs energy, enthalpy, entropy), Cp (standard heat capacity), V (standard volume), HKF (<abbr title="Tanger and Helgeson, 1988">revised</abbr> <abbr title="Helgeson et al., 1981">Helgeson-Kirkham-Flowers</abbr> equations).

<!-- All buttons at top -->

### Aqueous Species <button id="B-aqueous-H2O" onclick='ToggleDiv("aqueous-H2O")'>H2O</button> <button id="B-aqueous-inorganic" onclick='ToggleDiv("aqueous-inorganic")'>Inorganic</button> <button id="B-aqueous-organic" onclick='ToggleDiv("aqueous-organic")'>Organic</button>

### Solids <button id="B-solid-inorganic" onclick='ToggleDiv("solid-inorganic")'>Inorganic</button> <button id="B-solid-organic" onclick='ToggleDiv("solid-organic")'>Organic</button> <button id="B-solid-Berman" onclick='ToggleDiv("solid-Berman")'>Berman</button>

### Gases <button id="B-gas-inorganic" onclick='ToggleDiv("gas-inorganic")'>Inorganic</button> <button id="B-gas-organic" onclick='ToggleDiv("gas-organic")'>Organic</button> &nbsp;&nbsp;&nbsp;Liquids <button id="B-liquid-organic" onclick='ToggleDiv("liquid-organic")'>Organic</button>

### Optional Data <button id="B-optional-SUPCRT92" onclick='ToggleDiv("optional-SUPCRT92")'>SUPCRT92</button> <button id="B-optional-SLOP98" onclick='ToggleDiv("optional-SLOP98")'>SLOP98</button> <button id="B-optional-AD" onclick='ToggleDiv("optional-AD")'>AD</button> <button id="B-optional-DEW" onclick='ToggleDiv("optional-DEW")'>DEW</button> <button id="B-optional-Testing" onclick='ToggleDiv("optional-Testing")'>Testing</button>

<!-- Normal or "all open" footer message --> 

<div id="footer" style="display: block">
*Press a button above to show the citations in that data file.*
*Or, <a href = "#showall" onclick='OpenAllDivs()'>click here</a> to show all citations.*
</div>

<div id="all-open" style="display: none">
*Showing citations in all data files.*
*Press any button above to hide them.*
</div>

<!-- Aqueous species divs -->

<div id="D-aqueous-H2O" style="display: none">
## <a id="aqueous-H2O" class="anchor"></a> `r setfile("H2O_aq.csv")`
```{r reflist, results="asis", echo=FALSE}
used <- c(used, filerefs(csvfile))
```

This file contains H<sub>2</sub>O, *e*<sup>-</sup>, and H<sup>+</sup>.
The properties of H<sub>2</sub>O are listed as NA; CHNOSZ calculates its properties using a Fortran subroutine taken from SUPRCT92 ([Johnson et al., 1992](https://doi.org/10.1016/0098-3004(92)90029-Q)) (default) or using the IAPWS-95 equations ([Wagner and Pruß, 2002](https://doi.org/10.1063/1.1461829)) or the Deep Earth Water (DEW) model ([Sverjensky et al., 2014](https://doi.org/10.1016/j.gca.2013.12.019)).

By convention, the standard Gibbs energy of formation, entropy, and heat capacity of the aqueous proton (H<sup>+</sup>) are 0 at all *T* and *P* ([e.g. Cox et al., 1989](https://www.worldcat.org/oclc/18559968)).
The formation reaction of the proton can be expressed as &frac12;H<sub>2,(*g*)</sub> + Z = H<sup>+</sup>, where Z is the "element" of positive charge.
Because the conventional standard Gibbs energy of this reaction is 0 at all *T*, the standard entropy of the reaction is also constrained to be zero (cf. Denbigh, 1981; Puigdomenech et al., 1997).
Therefore, the "element" of positive charge (Z) has zero thermodynamic properties except for an entropy, *S*°<sub>*T*<sub>r</sub></sub>, that is negative one-half that of H<sub>2,(*g*)</sub>.
The standard entropy of the aqueous electron, which is a solely a pseudospecies defined by *e*<sup>-</sup> = -Z, is opposite that of Z.

Likewise, [GEM-Selektor](http://gems.web.psi.ch/) defines "independent components" to be stoichiometric units usually consisting of elements and charge; the latter, [which is named Zz](http://gems.web.psi.ch/tests/TestNaCl-dep.html) and has a standard molal entropy of -65.34 J/mol/K and heat capacity of -14.418 J/mol/K (negative one-half those of gaseous hydrogen), is negated in the formula of the fictive "aqueous electron" ([Kulik, 2006](https://doi.org/10.1016/j.chemgeo.2005.08.014)).

Despite these considerations, the final column of the thermodynamic database (`thermo()$OBIGT`) lists a charge of "0" for both the aqueous proton and electron.
Data in this this column are used in CHNOSZ only to specify the charge that is input to the "*g*-function" ([Tanger and Helgeson, 1988](https://doi.org/10.2475/ajs.288.1.19); [Shock and Helgeson, 1988](https://doi.org/10.1016/0016-7037(88)90181-0)).
Setting it to zero prevents activation of the *g*-function, which would result in non-zero contributions to thermodynamic properties, conflicting with the conventions mentioned above.
All other calculations in CHNOSZ obtain the elemental makeup, including the correct charge for the species, by parsing the chemical formulas stored in the database.
</div>

<div id="D-aqueous-inorganic" style="display: none">
## <a id="aqueous-inorganic" class="anchor"></a> `r setfile("inorganic_aq.csv")`

**NOTE:** Aqueous U species from @SSB97 (with the exception of HUO<sub>4</sub><sup>-</sup>) have been moved to the SLOP98 optional data file due to incompatibility with more recent data [@MBA+24]. Because the latter source includes only uranyl species, the set of data for aqueous uranium species in the default database is currently incomplete.

```{r reflist, results="asis", echo=FALSE}
```
</div>

<div id="D-aqueous-organic" style="display: none">
## <a id="aqueous-organic" class="anchor"></a> `r setfile("organic_aq.csv")`
Charged amino acid sidechain groups have a Z parameter that is tabulated as zero; their chemical formulas indicate the correct charge.
Non-zero values of Z would yield derivatives of the omega parameter (&omega;) in the revised HKF equations of state for the cations and anions *that are not opposites of each other*.
This would be incompatible with group additivity of cations and anions to give a neutral species, for which the derivatives of &omega; are taken to be zero (cf. [Dick et al., 2006](https://doi.org/10.5194/bg-3-311-2006)).

```{r reflist, results="asis", echo=FALSE}
```
</div>

<!-- Solid species divs --> 

<div id="D-solid-inorganic" style="display: none">
## <a id="solid-inorganic" class="anchor"></a> `r setfile("inorganic_cr.csv")`

```{r reflist, results="asis", echo=FALSE}
```
</div>

<div id="D-solid-organic" style="display: none">
## <a id="solid-organic" class="anchor"></a> `r setfile("organic_cr.csv")`

```{r reflist, results="asis", echo=FALSE}
```
</div>

<div id="D-solid-Berman" style="display: none">
## <a id="solid-Berman" class="anchor"></a> `r setfile("Berman_cr.csv")`
This file gives the identifiying information for minerals whose properties are calculated using the formulation of [Berman (1988)](https://doi.org/10.1093/petrology/29.2.445).
Thermodynamic properties for these minerals are listed as NA in `thermo()$OBIGT`; the actual data are stored separately, as CSV files in `extdata/Berman/*.csv`.

```{r reflist, results="asis", echo=FALSE}
```
</div>

<!-- Gas species divs --> 

<div id="D-gas-inorganic" style="display: none">
## <a id="gas-inorganic" class="anchor"></a> `r setfile("inorganic_gas.csv")`

```{r reflist, results="asis", echo=FALSE}
```
</div>

<div id="D-gas-organic" style="display: none">
## <a id="gas-organic" class="anchor"></a> `r setfile("organic_gas.csv")`

```{r reflist, results="asis", echo=FALSE}
```
</div>

<!-- Liquid species divs --> 

<div id="D-liquid-organic" style="display: none">
## <a id="liquid-organic" class="anchor"></a> `r setfile("organic_liq.csv")`

```{r reflist, results="asis", echo=FALSE}
```
</div>

<!-- Optional species divs --> 

<div id="D-optional-SUPCRT92" style="display: none">
## <a id="optional-SUPCRT92" class="anchor"></a> `r setfile("SUPCRT92.csv")`
These minerals, taken from the SUPCRT92 database, were present in earlier versions of CHNOSZ but have since been superseded by data from @Ber88 (most minerals) or @RH95 (cassiterite).
The thermodynamic properties and parameters are kept here as optional data for reproducing published calculations and making comparisons with newer data.
The minerals here include all of the silicates and Al- and Ti-bearing minerals from @HDNB78, as well as calcite, dolomite, hematite, and magnetite.

Use `add.OBIGT("SUPCRT92")` to load the data.

**NOTE:** Other minerals from SUPCRT92, including native elements, sulfides, halides, sulfates, and selected carbonates and oxides that do not duplicate those in the Berman dataset, are still present in the default database (**inorganic_cr.csv**).

```{r optreflist, results="asis", echo=FALSE}
optused <- c(optused, filerefs(csvfile))
```
</div>

<div id="D-optional-SLOP98" style="display: none">
## <a id="optional-SLOP98" class="anchor"></a> `r setfile("SLOP98.csv")`
These species, whose parameters were listed in or are otherwise linked to slop98.dat (or later versions) and were present in earlier versions of CHNOSZ, have been replaced by or are incompatible with species currently in the default database.
The elements with updated data for at least some aqueous species include:
HCl [@TZA97],
Al [@TS01],
Au, Ag, and Cu(I) [@AZ01; @AZ10],
As [@NA03],
REE [@MWW09],
Cd [@BZA10],
Co [@LBT+11],
Pd [@TBZ+13],
Zn [@AT14],
Pt [@TBB15],
Nb [@AKK+20],
Ga and In [@HB24], and
U [@MBA+24].

Use `add.OBIGT("SLOP98")` to load the data.

**NOTE:** Other species listed in slop98.dat and later versions are still present in the default database.

```{r optreflist, results="asis", echo=FALSE}
```
</div>

<div id="D-optional-AD" style="display: none">
## <a id="optional-AD" class="anchor"></a> `r setfile("AD.csv")`
This file has parameters for aqueous nonelectrolytes in the Akinfiev-Diamond model [@AD03].
Use `add.OBIGT("AD")` to load the data; see `demo(AD)` for an example.

```{r optreflist, results="asis", echo=FALSE}
```
</div>

<div id="D-optional-DEW" style="display: none">
## <a id="optional-DEW" class="anchor"></a> `r setfile("DEW.csv")`
The Deep Earth Water (DEW) model extends the applicability of the revised HKF equations of state to 60 kbar.
Accuracy of the thermodynamic calculations at these conditions is improved by revised correlations for the <i>a</i><sub>1</sub> HKF parameter, as described by [Sverjensky et al. (2014)](https://doi.org/10.1016/j.gca.2013.12.019).
The thermodynamic parameters for species were taken from the May 2017 and January 2019 versions of the DEW spreadsheet.
The following species are present in the spreadsheet, but are not used here because the parameters are unchanged from the default database in CHNOSZ: B(OH)<sub>3</sub>, Br<sup>-</sup>, Ca<sup>+2</sup>, Cl<sup>-</sup>, Cs<sup>+</sup>, F<sup>-</sup>, H<sup>+</sup>, H<sub>2</sub>, He, I<sup>-</sup>, K<sup>+</sup>, Kr, Li<sup>+</sup>, Mg<sup>+2</sup>, Na<sup>+</sup>, Ne, O<sub>2</sub>, Rb<sup>+</sup>, Rn, SO<sub>4</sub><sup>-2</sup>.

Besides using `add.OBIGT("DEW")` to load these data, you should also run `water("DEW")` to activate the DEW equations in CHNOSZ.
See `demo(DEW)` for some examples.

Most of the comments below were transcribed from the DEW spreadsheet. Comments in parentheses were added by JMD.

```{r optreflist, results="asis", echo=FALSE}
```
</div>

<div id="D-optional-Testing" style="display: none">
## <a id="optional-Testing" class="anchor"></a> `r setfile("testing")`

These are optional data files used for testing purposes.
Load the data with e.g. `add.OBIGT("GEMSFIT")`.

<h3>SiO2</h3>

Aqueous SiO<sub>2</sub> from @AS04 and HSiO<sub>3</sub><sup>-</sup> modified to be consistent with it.
This file also has H<sub>4</sub>SiO<sub>4</sub> from an earlier publication [@Ste01] that is roughly consistent with the SiO<sub>2</sub> here.
See `demo(aluminum)` and the vignette [<span style="color:blue">*Regressing thermodynamic data*</span>](eos-regress.html) for examples.

<h3>GEMSFIT</h3>

Internally consistent dataset for aqueous species in the system Ca-Mg-Na-K-Al-Si-O-H-C-Cl obtained with the [GEMSFIT](https://doi.org/10.1016/j.apgeochem.2014.10.013) package [@MWKH16;@MWKL17].

<h3>IGEM</h3>

Updates for Au and Cu complexes and SO<sub>4</sub><sup>-2</sup>-bearing species from researchers at the Institute of Geology of Ore Deposits, Petrography, Mineralogy, and Geochemistry, Russian Academy of Sciences (IGEM RAS) [@AZ23;@TTA+23;@TAT+24;@TAZ24].

<h3>Sandia</h3>

Model for the Mg(OH)<sub>2</sub>-MgCl<sub>2</sub>-H<sub>2</sub>O system at 25 to 150 &deg;C from researchers at Sandia National Laboratories [@KBJ24].

<h3>Citations</h3>

```{r optreflist, results="asis", echo=FALSE}
```
</div>

<hr>

<b>Total count of species</b>: References were found for `r length(used)` of `r nrow(thermo()$OBIGT)` species in default data files and `r length(optused)` species in optional data files.

# References

<script>
// Open button corresponding to hash target in URL 20200703
// Keep this at the end of the body:
// https://stackoverflow.com/questions/9899372/pure-javascript-equivalent-of-jquerys-ready-how-to-call-a-function-when-t
  var url = window.location.href;
  if (url.indexOf("#") > 0) {
    var activeButton = url.substring(url.indexOf("#") + 1);
    if(activeButton == "showall") {
      OpenAllDivs();
      // hide the footer message
      document.getElementById("footer").style.display = "none";
    } else {
      OpenDiv(activeButton);
    }
    // https://stackoverflow.com/questions/3163615/how-to-scroll-html-page-to-given-anchor
    location.hash = "#" + activeButton;
  }
</script>

