species {CHNOSZ} | R Documentation |
Define the species of interest in a system; modify their physical states and logarithms of activities.
species(species = NULL, state = NULL, delete = FALSE, quiet = TRUE)
species |
character, names or formulas of species to add to the species definition; numeric, rownumbers of species to modify or delete. |
state |
character, physical states; numeric, logarithms of activities or fugacities. |
delete |
logical, delete the species identified by numeric values of species (all species if that argument is missing)? |
quiet |
logical, make less output to the screen? |
After defining the basis
species of your system you can use this function to identify for the program the species of interest. A species is operationally a combination of a name
and state
, which are columns of the thermodynamic database in thermo$obigt
. The function operates on one or more character values of species
. For each first match of species
(optionally restricted to a state
among aq, cr, gas, liq) to the name of a species or a formula or abbreviation in the thermodynamic database, a row is added to thermo$species
.
Some species in the thermodynamic database are duplicated, i.e., they have the same name
and state
but are from different sources in the literature. In this case, species
takes the n'th one in the order they appear in thermo$obigt
, where n=thermo$opt$level
.
The dataframe in thermo$species
holds the identifying characteristics of the species (including the logarithms of their activities or fugacities) as well as the stoichiometric reaction coefficients for the formation of each of the species from the basis species. The default values for logarithms of activities are -3 for aqueous (aq) species and 0 for others. If the basis species do not contain all the elements in any of species
, a message to this effect is generated but the species is nevertheless added with its incomplete stoichiometric definition, even if all zeros.
If state
is NULL
(the default), species in any state can be matched in the thermodynamic database. If there are multiple matches for a species, the one that is in the state given by thermo$opt$state
is chosen, otherwise the matching (or n'th matching duplicate) species is used. Note that the state
s of species representing phases of minerals that undergo phase transitions are coded as cr1, cr2, cr3, ...
(phases with increasing temperature). If state
is cr when one of these minerals is matched, all the phase species are added.
To modify the logarithms of activities of species (logarithms of fugacities for gases) provide one or more numeric values of species
referring to the rownumbers of the species dataframe, or species
NULL, to modify all currently defined species. The values in state
, if numeric, are interpreted as the logarithms of activities, or if character are interpreted as states to which the species should be changed. If species
is numeric and delete
is TRUE
, the rows representing these species are deleted from the dataframe; if the only argument is delete
and it is TRUE
, all the species are removed.
With no arguments, the value of thermo$species
. Successful addition of species returns the rownumbers of the species added to thermo$species
; for every species that is not located in the thermodynamic database a warning is generated, and if no species are found the value of thermo$species
(which is NULL
at program start-up) is returned. A successful deletion returns the number of species remaining after deletion, or NULL
if no species remain.
Use info
to search the thermodynamic database without adding a species to the system. basis
is a prerequisite for species
. affinity
depends on the definitions made using species
, but subcrt
, used to calculate standard molal properties, does not.
## add, modify, delete species basis("CHNOS") species(c("CO2","NH3")) # aqueous species species(c("CO2","NH3"),"gas") # gases # delete the first couple of species species(1:2,delete=TRUE) # modify the logarithms of activities (actually # fugacities) of the remaining species species(1:2,c(-2,-5)) # set the species to aqueous species(1:2,"aq") # delete all the species species(delete=TRUE) ## add and delete species basis(c("CaO","CO2","H2O","SiO2","MgO","O2")) # a species with Fe (faylite) can be loaded, # but its initial logarithm of activity is NA to # indicate that it falls outside the basis definition species(c("dolomite","quartz","calcite","forsterite","fayalite")) # changing the elements in the basis definition # causes species to be deleted basis(c("CO2","H2O","O2")) species() # NULL