retrieve {CHNOSZ}R Documentation

Retrieve Species by Element


Retrieve species in the database containing one or more chemical elements.


  retrieve(elements = NULL, ligands = NULL, state = NULL,
    T = NULL, P = "Psat", add.charge = TRUE, hide.groups = TRUE)



character, combination of elements, or list, elements in a chemical system


character, elements present in any ligands


character, filter the result on these state(s).


numeric, temperature where ΔG° of species must be not NA


numeric, pressure where ΔG° of species must be not NA


logical, add charge to the system?


logical, exclude groups from the result?


This function retrieves the species in the thermodynamic database (see thermo) that have the indicated elements. A character value of elements is interpreted as a combination of one or more elements that must be present in each species. A list value of elements is used to specify a chemical system – the species must contain one or more of the indicated elements, but no other elements. ligands, if present, gives the elements that may be present in any ligands; this can be used to retrieve all species in a system bearing the elements (usually a single metal).

The result includes charged species if add.charge is TRUE (the default) or the user supplies the “element” of charge (‘⁠Z⁠’). Results can be filtered on physical state by setting the state argument. Groups used in group-additivity calculations, which have names with square brackets (e.g. [-CH2-]), are excluded unless hide.groups is FALSE. A special argument value ‘⁠all⁠’ can be used to retrieve all species in the thermodynamic database, including filtering on state and hiding of the groups.

The return value is a named integer vector giving the species index (i.e. rownumber(s) of thermo()$OBIGT) with names corresponding to the chemical formulas of the species. If the electron is in the result, its name (‘⁠e-⁠’) is used instead of its chemical formula (‘⁠(Z-1)⁠’). An empty (length 0) integer value is returned if no elements are specified or no species are retrieved.

Set T (and optionally P) to require that species have non-NA values of ΔG° at this temperature and pressure. These values are passed to subcrt and therefore have the units set in T.units and P.units.

To speed up operation, the function uses a precalculated stoichiometric matrix for the default database, which is loaded with the package (see thermo). If the function detects a change to any chemical formulas in the database, it updates the stoichiometric matrix using i2A.

See Also

info for basic database searches; anintro for a diagram made with retrieved species in the Mn-O-H system.


# Species index of Ti-bearing minerals
# Thermodynamic data for those minerals

# All species that have Au
# All species that have both Au and Cl
retrieve(c("Au", "Cl"))
# Au-Cl system: species that have Au and/or Cl,
# including charged species, but no other elements
retrieve(list("Au", "Cl"))
# All Au-bearing species in the Au-Cl system
retrieve("Au", "Cl")
# All uncharged Au-bearing species in the Au-Cl system
retrieve("Au", "Cl", add.charge = FALSE)

# Minerals in the system SiO2-MgO-CaO-CO2
retrieve(list("Si", "Mg", "Ca", "C", "O"), state = "cr")

[Package CHNOSZ version 2.0.0 Index]