thermo data object, as well as modify the object. This help topic should help users understand the major side effects, but does not contain a comprehensive description of these interactions (the code is the ultimate reference).
.onAttach creates a list object named thermo that is placed in an environment named CHNOSZ.
Some functions in CHNOSZ have side effects that modify the contents of thermo; all such changes can be reverted, and the object restored to its original state, by calling data(thermo).The CHNOSZ environment is not (as of CHNOSZ 1.0.0) attached, rather the thermo object is accessed in functions by e.g. get("thermo"), assign("thermo", thermo, "CHNOSZ") and occasionally with(as.environment("CHNOSZ"), ...).
In the functions in the package, the greatest number of accessions are to the thermodynamic database (thermo$obigt), followed by the basis and species definitions (thermo$basis and thermo$species).
For example, info can be used to look up thermodynamic data in thermo$obigt by the name or chemical formula of a species.
As another example, subcrt attempts to balance unbalanced chemical reactions with the user-defined basis species in thermo$basis.
Some functions modify the thermodynamic database or system definition in thermo.
These are “side effects”, since the functions have an effect on the state of the program that persists beyond the lifetime of the objects returned by the functions.
In the code, side effects can be recognized by assignment to the thermo object in the CHNOSZ environment, i.e. assign("thermo", thermo, "CHNOSZ") (the unquoted thermo here refers to the object that was manipulated internally by a function and is now being assigned to the environment).
Side effects are not highly desirable in functional programming languages such as R.
The reason this design is adopted in CHNOSZ is that interactive use of basis and species appeared to the author, in the early stages of developing the package and of learning R, to be facilitated by not requiring users to assign the results of these functions to objects.
Instead, using side effects, the program “remembers” the results of these function calls.
Experience has shown that this design is usable (especially for new users), and is adaptable to many usage scenarios, but the dependence on side effects probably should be eliminated in the future.
The two major side effects, that most users will encounter, are the basis and species definitions. These functions and a few other modifications (writing) and accessions (reading) of data objects are listed below. The names of objects in this table refer to the components of the thermo object; for example, one can type thermo$opt at the command line to access all of the contents of the opt component, including those not listed in the table.
| object | writer | reader |
| notes |
obigt |
mod.obigt |
info |
thermodynamic database |
basis |
basis |
species, subcrt |
basis definition |
species |
species |
affinity |
| species definition |
opt$T.units |
T.units |
convert |
units |
opt$water |
| -- | water |
formulation for properties of water |
opt$Tr, Pr |
-- | GHS |
| reference temperature and pressure |
opt$state |
-- |
info |
physical state |
opar |
thermo.plot.new |
-- | graphical parameters |
Beginning with CHNOSZ version 1.0.0, the “superassignment” operator (<<-< a="">) is no longer used in functions.
However, if you wish to alter something in thermo in an interactive session, it is recommended to use the <<-< a=""> operator, instead of <-.
This way, your changes to the thermo object occur in the CHNOSZ environment, which is where the functions in CHNOSZ expect to find it, rather than being saved to the global environment.
An example of changing thermo$opt$water in this manner can found in the help page for water.
data(thermo) # side effect: reset the system definition
basis() # NULL
basis("CHNOS") # side effect: define the basis species
basis() # not NULL
data(thermo) # side effect: reset the system definition
basis() # NULL
Run the code above in your browser using DataLab