Appendix A. Keyword Data Blocks for Programmers

A number of keywords are intended to be used when scripting or programming with an IPhreeqc module (Charlton and Parkhurst, 2011). The IPhreeqc module provides a set of methods that expose the full capabilities of PHREEQC to other programs and allows retrieval of specified values (as defined in SELECTED_OUTPUT and USER_PUNCH).

One use of an IPhreeqc module is to incorporate geochemical reactions into a transport model. The strategy is to specify reactants for a set of cells in an IPhreeqc module and perform geochemical reactions for a time step with the RUN_CELLS data block. The solution concentrations are retrieved from the module, transported by the transport model, and returned to the IPhreeqc module for renewed geochemical calculations. A series of keyword data blocks have been written that facilitate transferring and modifying concentration data. These data blocks end with the suffixes _MODIFY and _RAW . In this reactive-transport strategy, SOLUTION_MODIFY could be used to update solution concentrations in the IPhreeqc module after a transport step. SOLUTION_MODIFY is related to SOLUTION_RAW, which is an input data block that is written by the DUMP operation and contains a complete description of a solution composition. SOLUTION_MODIFY has the same format as SOLUTION_RAW and allows one or more data items of the solution composition to be modified and also allows new data items (moles of another element in solution, for example) to be added.

Keyword equivalents to SOLUTION_MODIFY and SOLUTION_RAW data blocks exist for equilibrium-phase assemblages, exchange assemblages, gas phases, solid-solution assemblages, surface assemblages, kinetic-reaction assemblages, stoichiometric reactions, reaction pressures, and reaction temperatures. A complete list of _MODIFY and _RAW data blocks is given in See List of keyword data blocks for scripting and programming.. There is no keyword MIX_RAW or MIX_MODIFY because the MIX data block can be used. Similarly, REACTION_TEMPERATURE_MODIFY and REACTION_TEMPERATURE_MODIFY data blocks are not needed; the REACTION_PRESSURE and REACTION_TEMPERATURE data blocks can be used to modify temperature definitions. The set of _MODIFY keywords provides capabilities to change any data item in any reactant. Although transport is expected to apply primarily to solutions, it would be possible to transport exchange assemblages analogously to solutions by transporting the elements that define the composition of exchangers and then updating the exchange composition of a cell by using EXCHANGE_MODIFY with the results of the transport calculations.

List of keyword data blocks for scripting and programming.
Keyword data block	Function
EQUILIBRIUM_PHASES_MODIFY	Modify the definition of an equilibrium-phase assemblage
EQUILIBRIUM_PHASES_RAW	Complete description of an equilibrium-phase assemblage as written by DUMP
EXCHANGE_MODIFY	Modify the definition of an exchange assemblage
EXCHANGE_RAW	Complete description of an exchange assemblage as written by DUMP
GAS_PHASE_MODIFY	Modify the definition of a gas phase
GAS_PHASE_RAW	Complete description of a gas phase as written by DUMP
KINETICS_MODIFY	Modify the definition of a kinetic reactant assemblage
KINETICS_RAW	Complete description of a kinetic reactant assemblage as written by DUMP
REACTION_MODIFY	Modify the definition of an irreversible reaction
REACTION_RAW	Complete description of a REACTION definition as written by DUMP
REACTION_PRESSURE_RAW	Complete description of a REACTION_PRESSURE definition as written by DUMP
REACTION_TEMPERATURE_RAW	Complete description of a REACTION_TEMPERATURE definition as written by DUMP
SOLID_SOLUTIONS_MODIFY	Modify the definition of a solid-solution assemblage
SOLID_SOLUTIONS_RAW	Complete description of a solid-solution assemblage as written by DUMP
SOLUTION_MODIFY	Modify the definition of a solution composition
SOLUTION_RAW	Complete description of a solution as written by DUMP
SURFACE_MODIFY	Modify the definition of a surface-assemblage composition
SURFACE_RAW	Complete description of a surface-assemblage composition as written by DUMP

The _RAW data blocks (and possibly MIX) are written by the DUMP operation and are intended to be used without modification. The DUMP operation can be used to save the state of a calculation. The _RAW data blocks that are written by DUMP can be read by PHREEQC and the entire chemical state of the calculation will be restored to the point where DUMP was executed. DUMP also can be used to transfer data among IPhreeqc modules by dumping the data in one module and reading the data in another.

The use of the _MODIFY data blocks is complicated and subject to errors. Any item of data can be changed, but some are used for internal calculations, and changing the value externally has no effect. Some items cannot be reasonably changed, and others are interrelated so that a change to one may require a change to another as well. In particular, the number of moles of elements, including H and O, and the charge balance should not be changed independently because doing so may cause unforeseen pe and (or) pH changes. Varying just the number of moles of a single element (sodium for example) would be equivalent to adding or removing sodium metal from solution, which also would produce unexpected redox and pH reactions.

The _MODIFY data blocks are not intended for general use, but can be used by program developers. As such, developers are largely responsible for their use, and only limited support is provided. In the following description of input for _MODIFY keywords, a subset of the complete set of data in the _RAW data blocks is presented. Each subset is somewhat arbitrary, but has, in principle, the data items that could reasonably be changed with appropriate care.