[CHNOSZ-commits] r883 - in pkg/CHNOSZ: . R demo vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Apr 23 11:21:23 CEST 2025
Author: jedick
Date: 2025-04-23 11:21:23 +0200 (Wed, 23 Apr 2025)
New Revision: 883
Modified:
pkg/CHNOSZ/DESCRIPTION
pkg/CHNOSZ/R/util.affinity.R
pkg/CHNOSZ/demo/buffer.R
pkg/CHNOSZ/vignettes/anintro.Rmd
pkg/CHNOSZ/vignettes/vig.bib
Log:
Add adjusted and non-standard Gibbs energy to anintro.Rmd
Modified: pkg/CHNOSZ/DESCRIPTION
===================================================================
--- pkg/CHNOSZ/DESCRIPTION 2025-04-21 12:25:48 UTC (rev 882)
+++ pkg/CHNOSZ/DESCRIPTION 2025-04-23 09:21:23 UTC (rev 883)
@@ -1,6 +1,6 @@
-Date: 2025-04-21
+Date: 2025-04-23
Package: CHNOSZ
-Version: 2.1.0-54
+Version: 2.1.0-55
Title: Thermodynamic Calculations and Diagrams for Geochemistry
Authors at R: c(
person("Jeffrey", "Dick", , "j3ffdick at gmail.com", role = c("aut", "cre"),
Modified: pkg/CHNOSZ/R/util.affinity.R
===================================================================
--- pkg/CHNOSZ/R/util.affinity.R 2025-04-21 12:25:48 UTC (rev 882)
+++ pkg/CHNOSZ/R/util.affinity.R 2025-04-23 09:21:23 UTC (rev 883)
@@ -181,7 +181,8 @@
X.reaction <- function(ispecies, X) X.species((ispecies+nbasis), 1, X) + X.basis(ispecies, X)
# To get logK or subcrt props or other values into the dimensions we are using
dim.fun <- function(x, idim = NULL) {
- if(is.null(idim)) {
+ # For working Eh in transect mode, always assign idim <- 1 with transect = TRUE 20250421
+ if(transect) idim <- 1 else if(is.null(idim)) {
if(is.null(grid)) {
# One of T, P, IS
ivar <- which(vars %in% c("T", "P", "IS"))
@@ -194,8 +195,6 @@
idim <- ivars(ivar2, ivars(ivar1))
}
}
- # For working Eh in transect mode, this should not be nested in the above if(is.null(idim)) 20250421
- if(transect) idim <- 1
return(aperm(array(x, mydim[idim]), idim))
}
# Properties of all species
Modified: pkg/CHNOSZ/demo/buffer.R
===================================================================
--- pkg/CHNOSZ/demo/buffer.R 2025-04-21 12:25:48 UTC (rev 882)
+++ pkg/CHNOSZ/demo/buffer.R 2025-04-23 09:21:23 UTC (rev 883)
@@ -12,7 +12,7 @@
basis(b.species, b.state, b.logact)
xlim <- c(0, 350)
thermo.plot.new(xlim = xlim, ylim = c(-4, 4), xlab = axis.label("T"), ylab = axis.label("H2"))
-# Method 1: in affinity(), assign name of buffer to basis species
+# Method 1: in buffer(), assign name of buffer to basis species
bufferline <- function(buffer, ixlab) {
basis("H2", buffer)
a <- affinity(T = xlim, P = 300, return.buffer = TRUE, exceed.Ttr = TRUE)
Modified: pkg/CHNOSZ/vignettes/anintro.Rmd
===================================================================
--- pkg/CHNOSZ/vignettes/anintro.Rmd 2025-04-21 12:25:48 UTC (rev 882)
+++ pkg/CHNOSZ/vignettes/anintro.Rmd 2025-04-23 09:21:23 UTC (rev 883)
@@ -65,8 +65,6 @@
knit_hooks$set(warning = color_block('magenta'), error = color_block('red'), message = color_block('blue'))
```
-# CHNOSZ: An Introduction to Thermodynamic Calculations in R
-
This vignette introduces CHNOSZ, an R package for thermodynamic calculations relevant to geochemistry and geobiochemistry. CHNOSZ provides functions and a thermodynamic database for calculating properties of reactions involving minerals, aqueous species, and gases across a range of temperatures and pressures.
## Getting Started
@@ -194,12 +192,14 @@
# Calculate affinities on an Eh-pH grid
a <- affinity(pH = c(0, 14), Eh = c(-0.8, 1.2))
# Create an Eh-pH (Pourbaix) diagram
-diagram(a, fill = "terrain")
+diagram(a, col = 4, col.names = 4, italic = TRUE)
```
+Note that `diagram()` automatically adds shading to represent where water is not stable with respect to O2 or H2.
+
For more sophisticated diagrams involving speciation of basis species, use the `mosaic()` function:
-```{r mosaic, fig.cap = "Cu-S-Cl-H2O mosaic diagram"}
+```{r mosaic, fig.cap = "Mosaic diagram showing effect of aqueous S speciation on the relative stabilities of Cu minerals and aqueous species"}
# Create a mosaic diagram for Cu-S-Cl-H2O system
basis(c("Cu", "H2S", "Cl-", "H2O", "H+", "e-"))
basis("H2S", -6)
@@ -213,6 +213,8 @@
water.lines(m$A.species, lty = 3, col = 8)
```
+Here we've added dotted lines to help visualize the water stability limits.
+
## Equilibrium Calculations
Calculate equilibrium distributions of species:
@@ -713,24 +715,136 @@
3. No balancing constraint (`balance = 1`).
This just shows the affinity of each reaction as given (that is, per mole of formed species), which is how the results were presented by Shock and Canovas (2010).
-### 14. Calculate Gibbs energy of reaction (opposite of affinity) with subcrt()
+### 14. Calculate adjusted and non-standard Gibbs energy with subcrt()
+
+In normal use, `subcrt()` returns *standard* molal properties (G, H, S, Cp, and V) for species in their standard states, referenced as unit activity or fugacity.
+Two deviations from this default setting are possible: *non-standard* properties for specified activity, and *adjusted* properties for activity coefficients.
+
+First let's look at how *adjusted* properties depend on activity coefficients.
+This example uses a particular nonideality model based on @Alb03:
+
+```{r subcrt_nonideal, results = "show"}
+# Set the nonideality model
+old_ni <- nonideal("Alberty")
+# Calculate standard and adjusted Gibbs energy at 25 °C
+species <- c("MgH2ATP", "MgHATP-", "MgATP-2")
+subcrt(species, T = 25, IS = c(0, 0.25), property = "G")$out
+# Restore the original nonideality model
+nonideal(old_ni)
+```
+
+Notice how logarithms of the activity coefficients (loggam) are more negative for the higher-charged species.
+The activity coefficients have a stabilizing effect: *adjusted* Gibbs energies (at *I* > 0) are less than the *standard* Gibbs energies (at *I* = 0).
+
+Now let's change the activities to get *non-standard* properties.
+
+```{r subcrt_affinity, results = "show"}
+species <- c("Mg+2", "ATP-4", "MgATP-2")
+coeffs <- c(-1, -1, 1)
+T <- c(25, 50, 100)
+# Drop some columns for more compact output
+idrop <- c(2:4, 6:9)
+# Unit activity: affinity is opposite of standard Gibbs energy
+subcrt(species, coeffs, T = T, logact = c(0, 0, 0))$out[, -idrop]
+# Non-unit activity: affinity is opposite of non-standard Gibbs energy
+subcrt(species, coeffs, T = T, logact = c(-5, -4, -3))$out[, -idrop]
+```
+
+Note that:
+
+- The logK, G, H, S, V, and Cp columns in the output of subcrt() always correspond to *standard* or *adjusted* thermodynamic properties, not non-standard ones.
+- Columns for logQ and A are added if the `logact` argument is provided.
+- The `logact` argument specifies the activities of species in the same order as the first argument.
+- A in the output of subcrt() has the same units as G (J/mol by default); this differs from the output of affinity(), which uses dimensionless values (A/2.303RT).
+
+The first call above specifies unit activities of all the species in the reaction.
+
+- Only for the case of unit activities of all species, the affinity values (A in the output) are the opposite of the standard Gibbs energy (G in the output).
+
+The second call specifies non-unit activities of the species.
+
+- The result shows that affinity values in general are *not* the opposite of the standard Gibbs energy.
+- Instead, they are the opposite of the *non-standard* (or overall) Gibbs energy.
+
### 15. Use the output of subcrt() to format reactions for diagrams
### 16. Extract lines and image data from the output of diagram()
-### 17. On-demand database updates with mod.OBIGT() and logK.to.OBIGT()
+### 17. Counting elements and summing and writing formulas with makeup() and as.chemical.formula()
### 18. A brief introduction to buffers
-### 19. A brief introduction to proteins
-### 20. More use cases for mosaic()
+### 19. A brief introduction to proteins and groupwise relative stabilities
## Further Resources
+### Help Pages
+
- Browse the package documentation with `help(package = "CHNOSZ")`
- See function-specific help: `?info`, `?subcrt`, etc.
-- Explore demos with `demo(package = "CHNOSZ")`
+### Demos
+
+Explore demos with `demo(package = "CHNOSZ")`.
+You can also use `demos()` to run all the demos or just one (e.g. `demos("mosaic")`).
+
+*More use cases for `mosaic()`*
+
+ - `mosaic`: Speciating more than one set of basis species
+ - `sum_S`, `uranyl`: Using summed activities of speciated basis species
+ - `comproportionation`: Gibbs energy of reaction with speciated basis species
+ - `arsenic`, `copper`: More examples of Eh-pH diagrams
+ - `sphalerite`, `contour`, `minsol`: Solubility calculations with speciated basis species
+
+*Solubility contours with `solubility()`*
+
+ - `Pourbaix`: Isosolubility lines for various metals (try Fe, Cu, Mn)
+ - `contour`: Solubility contours for gold
+ - `minsol` Solubility contours for multiple minerals
+ - `solubility`: CO2 and calcite
+
+*Other contour plots*
+
+ - `saturation`: Saturation lines (where affinity = 0) and labels for activity ratios
+ - `ionize`: Protein ionization properties
+ - `TCA`: Citric acid cycle energetics
+ - `comproportionation`: Using a color scale (image map)
+
+*Activity buffers*
+
+ - `buffer`: Plotting buffers as a function of temperature
+ - `DEW`: Applying calculated values of logfO2 in `affinity()`
+ - `gold`: Settting pH and fO2 buffers in `basis()` for solubility of gold
+ - `protbuff`: Using proteins as buffer species
+
+*Other thermodynamic models*
+
+ - `DEW`: Deep Earth Water model (extension of HKF to high pressures)
+ - `AD`: Akinfiev-Diamond model for aqueous nonelectrolytes
+
+*Calculations with proteins*
+
+ - `Shh`: Affinities of transcription factors
+ - `carboxylase`: Predicted rank abundance with varying temperature and redox
+ - `rank.affinity`: Affinity ranking for groupwise stability comparisons
+
+## Other Vignettes
+
Additional vignettes cover:
+### Frequently asked questions
+
+The [FAQ](FAQ.html) is a non-comprehensive collection of questions and answers about CHNOSZ.
+Please use the [Discussions forum on GitHub](https://github.com/jedick/CHNOSZ/discussions) for new questions.
+
### OBIGT thermodynamic database
+The [OBIGT](OBIGT.html) vignette is generated from reference information in the database and lists all literature citations for species arranged by default and optional data files.
+
+### Customizing the thermodynamic database
+
+The [custom_data](custom_data.html) vignette describes `add.OBIGT()` for adding data from files, `mod.OBIGT()` for updating or adding parameters of particular species, and `logK.to.OBIGT()` for generating parameters from logK values.
+
+### Fitting thermodynamic data
+
+The [EOSregress](EOSregress.html) vignette shows how to fit experimental data (volume and heat capacity) using constructed equation-of-state models.
+
### Creating multi-metal diagrams (aside: why affinity?)
The idea for creating stability diagrams in CHNOSZ came from Harold Helgeson's geochemistry course.
@@ -741,17 +855,16 @@
The grid-based method, used in CHNOSZ, looks at reactions to compose individual species from the basis species (let's call them formation reactions), then selects the most stable species according to their affinity values.
Affinity is just the opposite of non-standard Gibbs energy of reaction.
-"Standard Gibbs energy of reaction" and "Gibbs energy of reaction" - which are two very different things - have unfortunately similar names except for an optional [depending on the author, e.g. @AL19;@STK19] "overall" or "non-standard" in front of the latter.
+"Standard Gibbs energy of reaction" and "Gibbs energy of reaction" - which are two different things - have unfortunately similar names except for an optional [depending on the author, e.g. @AL19;@STK19] "overall" or "non-standard" in front of the latter.
"Non-standard Gibbs energy of reaction" doesn't lend itself to a short, unambiguous function name, which is why its opposite, "affinity", is used in CHNOSZ.
-In the reaction-based method, transformation reactions are "balanced on" a metal, while in the grid based method, formation reactions are normalized on that metal.
-The grid-based method in CHNOSZ is called the "maximum affinity method" for making relative stability diagrams and produces equivalent resuls to the reaction-based method.
-It also has the same limitations: every mineral or other formed species must have that "balanced on" (or "conserved") metal in their formula.
+In the reaction-based method, transformation reactions are said to be "balanced on" a metal.
+The grid-based method implements this balancing constraint by dividing the affinities of formation reactions by the coefficients of a basis species.
+CHNOSZ uses these normalized affinities for making relative stability diagrams, referred to as the *maximum affinity method*.
+Both the reaction- and grid-based method have the same limitation: every candidate species must have non-zero stoichiometry of a given metal (or of a basis species with that metal).
-The multi-metal vignette has some techniques for overcoming this limitation of balancing reactions on a single metal.
+The [multi-metal](multi-metal.html) vignette has some techniques for overcoming this limitation of balancing reactions on a single metal.
-### Customizing the thermodynamic database
-
## References
The CHNOSZ package incorporates data and methods from various sources. To view citation information for data sources:
@@ -764,6 +877,8 @@
thermo.refs(info("CH4", c("aq", "gas")))
```
+For citing CHNOSZ itself, see "How should CHNOSZ be cited?" in the [FAQ](FAQ.html).
+
## Document history
- 2010-09-30 First version, titled "Getting started with CHNOSZ".
Modified: pkg/CHNOSZ/vignettes/vig.bib
===================================================================
--- pkg/CHNOSZ/vignettes/vig.bib 2025-04-21 12:25:48 UTC (rev 882)
+++ pkg/CHNOSZ/vignettes/vig.bib 2025-04-23 09:21:23 UTC (rev 883)
@@ -4,7 +4,7 @@
title = {{T}hermodynamics of {B}iochemical {R}eactions},
year = {2003},
address = {Hoboken, New Jersey},
- url = {https://www.worldcat.org/oclc/51242181},
+ url = {https://search.worldcat.org/title/51242181},
}
@Article{AH00,
More information about the CHNOSZ-commits
mailing list