retrieve: Retrieve Species by Element

In CHNOSZ: Thermodynamic Calculations and Diagrams for Geochemistry

Retrieve Species by Element

Description

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

Usage

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

Arguments

elements	character, combination of elements, or list, elements in a chemical system
ligands	character, elements present in any ligands
state	character, filter the result on these state(s).
T	numeric, temperature where \DG0 of species must be not NA
P	numeric, pressure where \DG0 of species must be not NA
add.charge	logical, add charge to the system?
hide.groups	logical, exclude groups from the result?

Details

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 \DG0 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; \viglinkanintro for a diagram made with retrieved species in the Mn-O-H system.

Examples

# Species index of Ti-bearing minerals
retrieve("Ti")
# Thermodynamic data for those minerals
info(retrieve("Ti"))

# All species that have Au
retrieve("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")

CHNOSZ documentation built on Feb. 12, 2024, 3 p.m.