Side effects of functions in CHNOSZ
Some functions in the package access thermodynamic data and system definitions contained in the
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).
When the package is loaded,
.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
The CHNOSZ environment is not (as of CHNOSZ 1.0.0)
attached, rather the
thermo object is accessed in functions by e.g.
assign("thermo", thermo, "CHNOSZ") and occasionally
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 (
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
Some functions modify the thermodynamic database or system definition in
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
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.
|| || ||thermodynamic database|
|| || ||basis definition|
|| || ||species definition|
|| || ||units|
||--|| ||formulation for properties of water|
||--|| ||reference temperature and pressure|
||--|| ||physical state|
|| ||--||graphical parameters|
Beginning with CHNOSZ version 1.0.0, the “superassignment” operator (
<<-) 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
<<- 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
A discussion on “What does the "<<-" operator mean?” appeared on the R-help mailing list, https://stat.ethz.ch/pipermail/r-help/2011-April/275905.html.
1 2 3 4 5 6