affinity {CHNOSZ}R Documentation

Chemical Affinities of Formation Reactions


Calculate the chemical affinities of formation reactions of species.


  affinity(..., property = NULL, sout = NULL, exceed.Ttr = FALSE,
    exceed.rhomin = FALSE, return.buffer = FALSE, return.sout = FALSE,
    balance = "PBB", iprotein = NULL, loga.protein = 0, transect = NULL)



numeric, zero or more named arguments, used to identify the variables of interest in the calculations. For argument recall, pass the output from a previous calculation of affinity as an unnamed first argument.


character, the property to be calculated. Default is ‘⁠A⁠’, for chemical affinity of formation reactions of species of interest


list, output from subcrt


logical, allow subcrt to compute properties for phases beyond their transition temperature?


logical, allow subcrt to compute properties of species in the HKF model below 0.35 g cm-3?


logical. If TRUE, and a buffer has been associated with one or more basis species in the system, return the values of the activities of the basis species calculated using the buffer. Default is FALSE.


logical, return only the values calculated with subcrt?


character. This argument is used to identify a conserved basis species (or ‘⁠PBB⁠’) in a chemical activity buffer. Default is ‘⁠PBB⁠’.


numeric, indices of proteins in thermo$protein for which to calculate properties


numeric, logarithms of activities of proteins identified in iprotein


logical, force a transect calculation, even for three or fewer values of the variables?


affinity calculates the chemical affinities of reactions to form the species of interest from the basis species. The equation used to calculate chemical affinity (A), written for base-10 (decimal) logarithms, is A/(2.303RT)=\log (K/Q), where K is the equilibrium constant of the reaction, Q is the activity product of the species in the reaction, and 2.303 is the conversion factor from natural to decimal logarithms. The calculation of chemical affinities relies on the current definitions of the basis species and species of interest. Calculations are possible at single values of temperature, pressure, ionic strength and chemical activities of the basis species, or as a function of one or more of these variables.

The argument property can be changed to calculate other thermodynamic properties of formation reactions. Valid properties are ‘⁠A⁠’ or NULL for chemical affinity, ‘⁠logK⁠’ or ‘⁠logQ⁠’ for logarithm of equilibrium constant and reaction activity product, or any of the properties available in subcrt except for ‘⁠rho⁠’. The properties returned are those of the formation reactions of the species of interest from the basis species. It is also possible to calculate the properties of the species of interest themselves (not their formation reactions) by setting the property to ‘⁠G.species⁠’, ‘⁠Cp.species⁠’, etc. Except for ‘⁠A⁠’, the properties of proteins or their reactions calculated in this manner are restricted to nonionized proteins.

Zero, one, or more leading arguments to the function identify which of the chemical activities of basis species, temperature, pressure and/or ionic strength to vary. The names of each of these arguments may be the formula of any of the basis species of the system, or ‘⁠T⁠’, ‘⁠P⁠’, ‘⁠pe⁠’, ‘⁠pH⁠’, ‘⁠Eh⁠’, or ‘⁠IS⁠’ (but names may not be repeated). The names of charged basis species such as ‘⁠K+⁠’ and ‘⁠SO4-2⁠’ should be quoted when used as arguments. The value of each argument is of the form c(min, max) or c(min, max, res) where min and max refer to the minimimum and maximum values of variable identified by the name of the argument, and res is the resolution, or number of points along which to do the calculations; res is assigned a default value of 256 if it is missing. For any arguments that refer to basis species, the numerical values are the logarithms of activity (or fugacity for gases) of that basis species.

If ‘⁠T⁠’, ‘⁠P⁠’, and/or ‘⁠IS⁠’ are not among the vars, their constant values can be supplied in T, P, or IS (in mol kg^{-1}). The units of ‘⁠T⁠’ and ‘⁠P⁠’ are those set by T.units and P.units (on program start-up these are °C and bar, respectively). sout, if provided, replaces the call to subcrt, which can greatly speed up the calculations if this intermediate result is stored by other functions. exceed.Ttr is passed to subcrt so that the properties of mineral phases beyond their transition temperatures can optionally be calculated.

If one or more buffers are assigned to the definition of basis species, the logarithms of activities of these basis species are taken from the buffer (see buffer).

The iprotein and loga.protein arguments can be used to compute the chemical affinities of formation reactions of proteins that are not in the current species definition. iprotein contains the indices (rownumbers) of desired proteins in thermo$protein. This uses some optimizations to calculate the properties of many proteins in a fraction of the time it would take to calculate them individually.

When the length(s) of the variables is(are) greater than 3, the function enters the ‘⁠transect⁠’ mode of operation. In this mode of operation, instead of performing the calculations on an n-dimensional grid, the affinities are calculated on a transect of changing T, P, and/or chemical activity of basis species.

Argument recall is invoked by passing a previous result of affinity as the first argument. The function then calls itself using the settings from the previous calculation, with additions or modifications indicated by the remaining arguments in the current function call.


A list, elements of which are fun the name of the function (‘⁠affinity⁠’), args all of the arguments except for ‘⁠sout⁠’ (these are used for argument recall), sout output from subcrt, property name of the calculated property (‘⁠A⁠’ for chemical affinity), basis and species definition of basis species and species of interest in effect at runtime, T and P temperature and pressure, in the system units of Kelvin and bar, set to numeric() (length=0) if either one is a variable, vars the names of the variables, vals the values of the variables (a list, one element for each variable), values the result of the calculation (a list, one element for each species, with names taken from the species index in thermo$OBIGT). The elements of the lists in vals and values are arrays of n dimensions, where n is the number of variables. The values of chemical affinity of formation reactions of the species are returned in dimensionless units (for use with decimal logarithms, i.e., A/2.303RT).

Names other than ‘⁠T⁠’ or ‘⁠P⁠’ in vars generally refer to basis species, and the corresponding vals are the logarithms of activity or fugacity. However, if one or more of pe, Eh or pH is among the variables of interest, vals holds the values of the those variables as indicated.


Helgeson, H. C., Richard, L, McKenzie, W. F., Norton, D. L. and Schmitt, A. (2009) A chemical and thermodynamic model of oil generation in hydrocarbon source rocks. Geochim. Cosmochim. Acta 73, 594–695. doi:10.1016/j.gca.2008.03.004

See Also

ionize.aa, activated if proteins are among the species of interest, ‘⁠H+⁠’ is in the basis and thermo()$opt$ionize.aa is TRUE. equilibrate for using the results of affinity to calculate equilibrium activities of species, and diagram to plot the results. demo("saturation") for an example using the argument recall feature.


## Set up a system and calculate
## chemical affinities of formation reactions
basis(c("SiO2", "MgO", "H2O", "O2"), c(-5, -5, 0, 999))
# Chemical affinities (A/2.303RT) at 25 deg C and 1 bar
# At higher temperature and pressure
affinity(T = 500, P = 2000)
# At 25 temperatures and pressures,
# some are in the low-density region so we suppress warnings
suppressWarnings(affinity(T = c(500, 1000, 5), P = c(1000, 5000, 5)))
# Equilibrium constants of formation reactions
affinity(property = "logK")
# Standard molal Gibbs energies of species,
# in units set by E.units() (default: J/mol)
affinity(property = "G.species")
# Standard molal Gibbs energies of reactions
affinity(property = "G")
# A T,P-transect
# (fluid pressure from Helgeson et al., 2009 Fig. 7)
affinity(T = c(25, 110, 115, 215), P = c(11, 335, 500, 1450))

[Package CHNOSZ version 2.1.0 Index]