retrieve {CHNOSZ} | R Documentation |
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 ΔG° of species must be not NA |
P |
numeric, pressure where ΔG° 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 Δ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 retrieve
d 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")