8 PhreePlot Guide

2.4 INSTALLING GHOSTSCRIPT AND GSVIEW

As of 2018, PhreePlot optionally comes with Ghostscript installed but it is possible to install
it yourself in the normal way. If you want to use your installed version, you must point the
pdfMaker setting to the appropriate path (see pdfMaker). It is also useful to install a native ps
viewer such as GSview.
GSview 5.0 is available from Ghostgum Software Pty Ltd at http://www.ghostgum.com.au/
software/gsview.htm. After downloading, run GSview and under Options|Advanced Config-
ure|Ghostscript DLL enter <%PHREEPLOT_PATH%>\gsdll<nn>c.dll where <%PHREEPLOT_-
PATH%> is the long-hand description of the folder containing pp.exe (GSview does not accept
environment variables here), <nn> is either 32 or 64 depending on which version of
PhreePlot you have installed. This should point to the folder that contains your pp.exe exe-
cutable. If this does not work, install Ghostscript in the usual way and use these settings for
GSview.
If PhreePlot has been installed correctly, typing
pp -v
from a console should show some information about the current version of PhreePlot includ-
ing its release date, whether the 32- or 64-bit versions is running and whether Ghostscript is
installed, and if so, its source and version.
Running the demo\test\test.ppi file will indicate whether your Ghostscript setup has been
successful. If successful, this should produce ps, pdf, png, eps and jpg plot files.

2.4.1 Launching PhreePlot from Windows Explorer or similar

If the ppi extension has been associated with the PhreePlot executable, then double clicking a
ppi input file in Widows Explorer or similar should launch PhreePlot. This is probably the
easiest way to run PhreePlot.

2.4.2 Specifying the input file name on the command line

PhreePlot expects an input file to be given on the command line following ‘pp’. The usual file
naming conventions apply in terms of the use of quotes, .. (parent directory). Windows file-
names are not case sensitive and respect both forward and backward slashes as separators. It
can get complicated when batch files and changes of directory are used and PhreePlot may
not be able to find the required input file. In such cases, launch from a console window and
use the full pathname. In Windows, the environment variable %PHREEPLOT_PATH% should
point to the folder containing the executables so “%PHREEPLOT_PATH%\pp.exe” should always
find the executable and provides a safe way of specifying it in a console and in batch files. Note
that the quotes are necessary here because of the space in the Program Files directory and the
possibility of command line arguments.

2.4.3 Specifying input and output filenames in PhreePlot input files

Various file paths can be specified in PhreePlot input files but somewhat stricter requirements
than above apply when specifying these file paths.
File paths should not contain a ‘+’ sign even though this is legal in Windows. PhreePlot uses a
system shell command to copy various files and your system may interpret an unquoted + sign
as the beginning of another file to copy.
File paths can in principle contain any characters that are compatible with normal operating
system rules (Windows disallows / ? < > \ : * | "). In order to avoid having to escape
characters, it is wise to also ignore parentheses, brackets and the ampersand. Other characters
including the + sign, comma, semi-colon, percent sign and space are best avoided. In other
words, keep it simple for an easy life!
File paths are not case sensitive in Windows so any mixture of cases will do. However, what-
 Installation 9

ever is entered is preserved in PhreePlot. PhreePlot itself tends to use lowercase filenames
with the exception that chemical elements follow their normal notation.

2.4.4 Setting the PhreePlot environment variable

The environment variable, PHREEPLOT, must be set before PhreePlot will work. The installer
should set this to the PhreePlot directory that you specify during installation, i.e. the root
directory containing the system, demo and doc directories. In Windows, this could be your
AppData directory (default) or a location that you chose during installation such as
C:\PhreePlot. Note that there is no trailing backslash.

The environment variable, PHREEPLOT_PATH, is also set to the location of the PhreePlot exe-
cutable, pp.exe, e.g. C:\Program Files\PhreePlot.
You can check that this has been done correctly by typing ‘set PhreePlot’ in a console win-
dow. This will return the two directories currently set.

Once set, the ‘demo directory’ for example could be referred to as “%PHREEPLOT%”\demo in
batch files.

2.4.5 Adding the path to PhreePlot to the Windows PATH setting

The installer should automatically add the path to the PhreePlot executable (pp.exe) to your
PATH during installation if requested. Otherwise it can be done through the Settings menu or
Control Panel. These can be accessed in different ways with different versions of Windows but
typing ‘Environment variables” in the run box works for Windows 10.

2.4.6 Search path for files

The search path for all input and data files is, in order of checking: (i) the specified filepath;
(ii) the current directory; (iii) the PhreePlot ‘system’ directory and its sub-directories, and (iv)
the path, if any, defined by a <file> tag.
If in doubt, include the full path to be sure. Put in quotes if there is a space in the name.

2.4.7 Ensuring that the correct databases are found

The database keyword points to the location of the thermodynamic database file to use. This
should be a standard Phreeqc-format database file. Several of these are included in the normal
Phreeqc distribution and have been copied to the PhreePlot system directory for conveni-
ence. Check the Phreeqc website (http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/) for
the latest files. Several other public-domain databases are also provided here (see Appendix 2).
Providing that the database files are kept in the system directory, they should be able to be
located by PhreePlot from their filenames alone, e.g. wateq4f.dat, since the system directory
is automatically included in the search path. Some demo examples specify other freely-availa-
ble databases that are not included in the PhreePlot distribution. This is usually because
obtaining them requires some form of registration.
The correctness of the results of geochemical calculations is directly related to the quality of
the associated thermodynamic databases. It is entirely your responsibility to make sure that the
databases used are adequate for the purposes for which you are using them - caveat emptor.
Keeping a critical eye on the quality of the databases used is an important part of geochemical
modelling. Other caveats, notably that thermodynamic equilibrium is not always, even rarely,
achieved should also be borne in mind. This is particularly true for many dissolution and pre-
cipitation reactions.

2.5 OTHER USEFUL SOFTWARE

Each to their own, but we have found the following software to be useful when working with
10 PhreePlot Guide

PhreePlot:

Notepad++ a free and highly capable text editor that includes syntax highlighting for a
large number of file types. The normal Phreeqc installations now come
with a file to colour Phreeqc keywords in pqi and ppi files (http://note-
pad-plus-plus.org/).
7-zip free file compression utility that is efficient and easy to use (http://www.7-
zip.org/).
xplorer2 dual pane Windows Explorer that makes a great way for launching
PhreePlot files and for viewing the graphical and text files produced (plus
many of the other things you have to do for file management) (http://zab-
kat.com/index.htm).
CoPlot Flexible and powerful scientific plotting package (http://
www.cohort.com/coplot.html).
R Powerful and well-supported open-source working environment for data
processing including flexible, high quality graphics (http://www.r-pro-
ject.org/).
Inkscape Open-source vector graphics editor capable of manipulating Postscript
files and exporting SVG-format files (http://www.inkscape.org/).

It is useful to have access to software that can edit native ps files so that other features can be
added and label positions etc changed. You will need a vector graphics editor for this. Inks-
cape mentioned above is one such editor.
Although PhreePlot does contain some plotting functionality, it is quite limited in what it can
do and is not intended to replace a proper scientific plotting package. The ASCII-format out-
put files are designed to be read by more powerful plotting and data analysis packages includ-
ing those mentioned above.

2.6 TROUBLE-SHOOTING

File conversions

File conversions from ps to other formats can be automatically carried out by Ghostscript
under the control of PhreePlot. If this is not working, make the following checks. If all else
fails, read in the ps file into GSview and make the required conversions in the normal GSview
way.
Once installed correctly, the demo examples should run (see Section 3.2).

Problem and bug reporting

Contact David Kinniburgh ([email protected]).

 Getting started 11

3 Getting started

3.1 THE COMMAND LINE INTERFACE AND BATCH PROCESSING

Like the batch version of Phreeqc, PhreePlot can be run from a console or executed via a
shortcut providing the following format is given:

pp input_filename [otherpp.set]

where input_filename is the name of a valid input file (see Section 5.2). If only a partially
qualified filename is given, care must be taken to ensure that it is sufficient for the file to be
found (Section 2.4.2). We have adopted the convention of using the ppi extension for input
filenames. The optional otherpp.set is the name of a settings file to use instead of the default
pp.set from the system directory. Normally this second parameter is left blank and the default
used.
Output will be sent to the screen and to various output files. If input_filename contains
blanks, embed it in quotes.
If the ppi extension is associated with PhreePlot, as recommended, then the easiest way of
running a PhreePlot input file is to double click it in an Explorer window.
Collections of the above-type statements may be collected together in a batch file and run as
one job. The demo.bat file included in the distribution is one such example. This is the mech-
anism for plotting multiple curves from different runs in a single custom plot – the output
files are created in the initial runs and then the last run does all the plotting using the extradat
keyword to load the output from the earlier runs.
Using the override.set file with calculationMethod 2 can make global changes to the output
from a set of already-calculated files without changing the individual ppi files.
Input files should be prepared with a standard text editor. Notepad will do but many better
editors exist. It is useful to have an editor that automatically checks for and loads updated files.
PhreePlot is not interactive (no GUI) but with a little effort in setup, it can be made to work
quite efficiently.
Most ordinary Phreeqc input files can be run by just adding the line CHEMISTRY to the begin-
ning of the input file (otherwise PhreePlot will interpret this input as PhreePlot keywords).
Adding all T or debug 2 just before this will cause the *.all file to be created which will con-
tain a copy of all the Phreeqc output.

3.2 RUNNING THE DEMO EXAMPLES

Providing the paths have been set correctly as described above, launching the demo1.bat file
from the \demo directory should begin the calculations. This can be done either by double
clicking on the demo1.bat file in a Windows Explorer-type window, or by opening a console
and executing it from there (as below).
This demo is an example of using the ‘hunt and track’ algorithm for producing a predomi-
nance diagram for an Fe-Cl system. It also creates pdf, eps, epsi and jpg files if Ghostscript is
installed and so can be used to test that installation.
The output looks something like:
*** PhreePlot 1 (x64) 11:41:57 31 Mar 2020
Incorporating the iPhreeqc library (3.6.2-15100-x64)
12 PhreePlot Guide

by DL Parkhurst, SR Charlton (USGS), & CAJ Appelo (Amsterdam)

Hunt & Track by DG Kinniburgh, and DM Cooper (CEH, NERC)
Fitting by MJD Powell and others
Postscript plotting by KE Kohler

Input filename: D:\PhreePlot\demo\test\test.ppi.

Main species = "Fe"

Calculating... 1
1 2.0000 -85.0000 -11 H2(g) > 1 a Fe+2 0.9044 -2.0195
2 2.0000 -81.6000 11 Fe+2 FeCl+ -2.0196 -3.3583
3 2.0000 -83.3000 -11 H2(g) > 1 a Fe+2 0.0544 -2.0196
4 2.0000 -81.6000 11 Fe+2 FeCl+ -2.0196 -3.3583
5 2.0000 -82.4500 11 Fe+2 FeCl+ -2.0196 -3.3583
6 2.0000 -82.8750 11 Fe+2 FeCl+ -2.0196 -3.3583
7 2.0000 -83.0875 11 Fe+2 FeCl+ -2.0196 -3.3583
8 2.0000 -83.1937 -11 H2(g) > 1 a Fe+2 0.0013 -2.0196
9 2.0000 -83.0875 11 Fe+2 FeCl+ -2.0196 -3.3583
10 2.0000 -83.1406 11 Fe+2 FeCl+ -2.0196 -3.3583
11 2.0000 -83.1672 11 Fe+2 FeCl+ -2.0196 -3.3583
12 2.0000 -83.1805 11 Fe+2 FeCl+ -2.0196 -3.3583
13 2.0000 -83.1871 11 Fe+2 FeCl+ -2.0196 -3.3583
14 2.0000 -83.2828 -21 H2(g) > 1 a Fe+2 0.0458 -2.0196
15 2.0000 -82.4242 22 Fe+2 FeCl+ -2.0196 -3.3583
16 2.1010 -82.4242 23 Fe+2 FeCl+ -2.0196 -3.3583
17 2.1010 -83.2828 -24 H2(g) > 1 a Fe+2 0.0458 -2.0196

The screen output provides feedback on progress. The columns are: (i) iteration number; (ii)
x-axis variable (automatically generated); (iii) y-axis variable (automatically generated); (iv) the
type of step being taken; (v) truncated name of the predominant species (most abundant); (vi)
truncated name of the sub-dominant (second most abundant) species; log concentrations of
the dominant and sub-dominant species (mol/kgw) when solution species or log partial pres-
sures when gases. Where one or more constraints are operating, these are elevated to the top-
most position(s) and the values given are determined by the type of species as outlined above.
The above example makes use of the ht1.inc include file. This determines exactly what values
are returned to PhreePlot.
The code returned for the type of step taken is determined as follows:

the first digit is 1 while hunting for boundaries along an edge or 2 while tracking an
internal boundary;
the second digit is either the side number or the cell corner (1-4, counted clockwise
from bottom left. 1 is the left-hand y axis, 2 is the top x axis...);
a negative sign indicates that a constraint is operating;
00 is a special code for a non-tracking move (as used by a ‘grid’ plot).

The above example indicates that PhreePlot starts by hunting for boundaries along the left-
hand y axis. It then starts tracking along an internal boundary at iteration 14. It will finish by
tracking along the remaining boundaries to check that there are no more intersections to start
tracking from. This example takes 1226 iterations to complete.
The demo.bat file included contains many more examples including many ‘custom’ plots
which use the selected output from Phreeqc to generate a plot. This includes the standard set
of examples distributed with Phreeqc. Each example will take from a few seconds up to sev-
eral minutes or more to calculate. Most of the time in these examples is spent running
Phreeqc.
Note that the demo examples are based on the pp.set file provided. If changes to this file are
made, it may be necessary to change the input files. For example, pp.set sets the commonly
used tag <log_H> to -<x_axis> so that the x-axis limits can be specified in terms of pH directly
rather than as the log (H+) activity.

3.3 THE ‘PP.LOG’ FILE

Providing, pplog is set to TRUE, a log of every PhreePlot run is written to a file called pp.log
 Getting started 13

which is created in the PhreePlot system directory. This can be checked at the end of the run
to make sure that all has run as expected and is especially useful for checking the results of
multiple runs from a batch file.
Each run normally gives rise to two lines on the pp.log file. The first line indicates the time
started and the second line gives the completion status. The absence of a second line indicates
a crash. Normally, an ‘OK’ status should be returned for each input file if all has run well.
Time Date Input_file Type Method n Time(min) Status
9:24:38 15_June_2010 C:\PhreePlot\demo\test\test.ppi ht1 calculate 0 0.000 Started
9:24:44 15_June_2010 C:\PhreePlot\demo\test\test.ppi ht1 calculate 1539 0.092 OK
9:24:44 15_June_2010 C:\PhreePlot\demo\Phreeqcexamples\ex1\ex1.ppi custom calculate 0 0.000 Started
9:24:44 15_June_2010 C:\PhreePlot\demo\Phreeqcexamples\ex1\ex1.ppi custom calculate 1 0.004 OK
9:24:44 15_June_2010 C:\PhreePlot\demo\Phreeqcexamples\ex2\ex2.ppi custom calculate 0 0.000 Started
9:24:45 15_June_2010 C:\PhreePlot\demo\Phreeqcexamples\ex2\ex2.ppi custom calculate 1 0.018 OK
...

This log file will accumulate output from every run and so should be periodically emptied or
erased. It will be automatically recreated or appended to as necessary.
If there has been a failure of Phreeqc such that no selected output was produced, then a ‘?’ is
appended to the right of the number of speciation calculations, n. Details of the offending
output will be written to the log file if that was active.
If debug is set to 1 or stopOnFail is set to 1, then PhreePlot will stop at the first failure. If
PhreePlot has had to adjust the resolution of a ‘hunt and track’-generated predominance plot
for various reasons then a ‘*’ is printed next to the number of speciation calculations.
If there has been an error reading one of the data input files, e.g. while reading an extraSym-
bolsLines file, then an exclamation mark (‘!’) is appended to the status. Check the log file for
details. The error may stop PhreePlot from running or may continue by skipping the errone-
ous data.
Other possible variations of the logged status on termination are:

Error an error occurred somewhere in the calculations

Input_error an error occurred reading input
Plotting_error an error occurred during plotting
GS_error an error occurred while Ghostscript was converting the ps file
No_plot no plot was specified
Interrupted the <Esc> interrupt was used to halt execution
Started still running (or crashed while running)

Setting pplog to FALSE will prevent anything being written to the pp.log file.

3.4 EXAMINING THE RESULTS OF THE RUN

Various output files will be written to the input file directory. The formats of these files are
described more fully elsewhere (Section 5). The file plot.ps is always a copy of the last Post-
script plot file produced. The log file if written should give a more detailed summary of the
calculations undertaken.

3.5 MAKING A WORKING DIRECTORY

It is best to keep all your working files in a directory that is quite separate from the setup direc-
tories. Since each run can produce a large number of files, it is best to make a new directory
for each ‘problem’. It is usually best to copy an existing similar working input file to this direc-
tory and edit that as needed.
Running the file should be straightforward providing the PhreePlot environment variable has
been set properly (see Section 2.4.1), e.g.

C:\projects\PhreePlot>md FeS2
14 PhreePlot Guide

C:\projects\PhreePlot>cd FeS2
C:\projects\PhreePlot\FeS2>pp FeS2

3.6 GETTING FAMILIAR WITH THE OPTIONS

The calculations and plotting are controlled by the various keyword-value pairs and lists
which are read from various input files. There is also usually some Phreeqc-format appended
to the end of the main input file. There are many options, some of which are more important
than others, and it is difficult in the beginning to know where to start.
The best way to learn is to run the demo examples. Pick an example that is closest to what you
are interested in and run it. If one of the keywords in the input file looks interesting, look it up
to see what it does and experiment by changing it.

3.7 USING BATCH FILES TO RUN A SET OF RUNS

PhreePlot is designed to produce a series of plots by varying one of the looping variables
(main species, loop parameter or the x- and y parameters). However, it is not designed to do
more than one independent type of plot in one run. To do this, it is necessary to run
PhreePlot multiple times and then combine the results. The overlay feature enables plots
from earlier runs to be combined with the current plot to produce complex page layouts con-
taining multiple plots.
Multiple independent plots can be executed in batch mode by preparing a batch file. This is
surprisingly powerful. The results from PhreePlot can even be intercepted, modified by
another program and returned to PhreePlot for plotting. Many programs exist to convert
images to other image formats, for example. Even a rudimentary understanding of Windows
batch scripting can be useful when processing large numbers of files.
The demo.bat file illustrates how a set of runs can be run in batch mode. This has obvious
advantages for repeatedly running a set of examples. On multi-processor machines, it may be
advantageous in terms of speed to split the batch files into two or more to take full advantage
of the separate processors.
It is possible to intersperse other batch commands in a batch file of PhreePlot runs in order to
rename, copy or delete files etc between runs.
It may be necessary to change the current working directory to that of the input file if a short-
ened file name is given.
The start command can be used to launch individual batch files simultaneously from within
this file (see demo2.bat). Alternatively, use call to run a batch file from within a batch file.
This will run the batch files sequentially.
The override.set file can be a useful place to add settings that will apply to all files run from
a batch file. For example, to generate png files for all the plots add
calculationMethod 2
png t

to the override.set file and re-run.

3.8 STOPPING A RUN

You can usually stop a run using the Esc key followed by ‘s’ for stop.
Stopping a batch file or script completely is a bit different. In Windows, Cntrl-c will always
abort the current run and when it is a Windows batch file, you will be given the opportunity
to exit the entire batch file.
 Phreeqc basics 15

4 Phreeqc basics

4.1 ONLINE PHREEQC DOCUMENTATION

Since the CHEMISTRY section of PhreePlot input files is itself essentially Phreeqc code, it is
necessary to be familiar with the way that Phreeqc input files are set up. This is described in
detail in the Phreeqc manual (pdf ). This manual is also available online in browser format.
Changes and corrections added since the initial release are given in the ‘Release notes’ on the
USGS website.

4.2 HOW PHREEQC INTERACTS WITH PHREEPLOT

PhreePlot uses Phreeqc for all geochemical calculations and runs only slightly modified
Phreeqc input files. Phreeqc calculations are controlled by an input file, a database file and
the program itself. The input can include one or more simulations. These need not be related
but they usually are. In many cases, only a single simulation is all that is needed to generate the
output required but sometimes more than one simulation is necessary, or it may be desirable
to split a simulation into two or more for the sake of efficiency (see Example 61).
A Phreeqc input file consists of a series of keyword data blocks separated into ‘simulations’ by
the END keyword. This file is read sequentially. When an END is found or the end of file is
reached, the statements accumulated since the last END are executed. We call this a ‘run’.
This execution triggers the specified calculations and the writing of results to the normal out-
put and selected output ‘files’ (if active). A number of data structures including the composi-
tion of various SOLUTIONS, EQUILIBRIUM_PHASES etc are also created or updated.
Many of these data structures persist across simulations but some of them can be explicitly
saved and re-used with the SAVE and USE keywords. The PUT and GET Basic statements also
enable user-defined numeric variables to be stored in, and retrieved, from global storage.
Phreeqc does not provide any explicit means of looping around specific lines of the input file
although some of the keywords such as REACTION and TRANSPORT implicitly involve a user-
defined set of iterations. This lack of general looping capability means that the input files
required for some calculations, including those often required for plotting, can become large
and repetitive.
PhreePlot attempts to overcome this by providing a framework for iterating across sections of
the Phreeqc input file while requiring minimal changes to the Phreeqc input file itself. It does
this by defining a set of four nested ‘DO’ loops which iterate over certain sections of the
Phreeqc code.
These loops, from the outside (least rapidly changing) in, are known as: (i) the ‘main species’
loop; (ii) the ‘z’- or ‘main’ loop; (iii) the y-axis loop, and (iv) the x-axis loop. The main species
loop iterates over a list of character variables while the remaining loops all iterate on numeric
variables. Not all loops need to be used all of the time. Indeed, you do not need to use any of
the loops.
Setting the iteration parameters for these various loops and providing instructions describing
which parts of the input file to loop over, plus many other PhreePlot settings, are either inher-
ited from the default settings (a file) or specified at the top of the PhreePlot input file.
Phreeqc input is at the bottom. A line containing the word CHEMISTRY separates these two sec-
tions.
16 PhreePlot Guide

Special tags – character strings between angled brackets – are used within the Phreeqc input
to act as placeholders which are substituted at run time by values generated by the various
PhreePlot looping mechanisms, and by other means. Phreeqc never sees these tags, just the
substituted values. Tags can also be used in the upper (PhreePlot) section of the input file.
These tags serve as global variables that enable transfer between different Phreeqc simulations
(somewhat like the Basic PUT/GET mechanism) but they also enable communication between
Phreeqc and the plot, and can be used to dynamically control such things as labelling, scaling
or sizing the plot.
Tags can be defined in a PhreePlot input file but can also be automatically generated from the
output of earlier simulations, or from reading an external data file. PhreePlot maintains a
table with the current values of all these tag variables ready for substitution at the appropriate
time. However, note that dynamic tags generated during execution will not be available during
replots (calculationMethod 2 or 3).
The sections of Phreeqc code iterated over are always based on contiguous blocks of one or
more simulations. The default is that the main species and z- loops iterate over all the simula-
tions while the x- and y-axis loops only iterate over the last n simulations where n is one by
default.
Communication of results between Phreeqc and PhreePlot is via the selected output.
Phreeqc’s in-built Basic interpreter gives you a great deal of flexibility in controlling what is
sent to the selected output.
Each simulation normally produces one or more lines of selected output although this can be
turned on or off at will. Where no output has been requested, a blank line is produced. This
output typically consists of the results of one or more initial solution etc calculations followed
by one or more lines giving the results of a reaction.
It is often the results on this last line that are wanted. PhreePlot only reads the last k lines of
the selected output where k by default is again normally one (in the cases where Phreeqc itself
does iterations, a whole block of results may need to be read and so k can be set to be greater
than one). This output is accumulated in a special file, called the ‘out’ file, which has a tabular
format ready for plotting.
PhreePlot has limited plotting capabilities though the output that is available is normally of
high quality (the native format is Postscript). The aim is to be able to get a reasonably quick
visual feel of the output, and once satisfied, to be able to generate plot files later, if necessary in
an automated (batch) fashion. All of the data files used to generate plots are well-structured
text files so can be readily imported into other plotting programs.
The ability to use tag variables in Phreeqc input files means that it is straightforward to keep
re-running a set of simulations with a different set of values. This is the basis of the model fit-
ting that is built into PhreePlot.

4.3 THERMODYNAMIC DATABASES

The standard databases distributed with Phreeqc and PhreePlot include a varied range of ele-
ments and ligands. The scope of these databases in terms of the elements defined are given in
Appendix 2. Check the appropriate web sites for updates.
It is straightforward in PhreePlot to change the database used using the database keyword.
Bear in mind that the same minerals and gases may have different names in the different data-
bases. This must be reflected in the use of such names in the Chemistry section of a PhreePlot
input file.

4.4 TYPES OF OUTPUT PRODUCED BY PHREEQC

Phreeqc can create two types of output files:

(i) normal output file: the PRINT and USER_PRINT data blocks control the output to the main
 Phreeqc basics 17

output file. This consists of a well-structured but verbose log of the speciation calculations
split into various blocks corresponding to each stage of the calculations. It also includes any
user-defined ouput defined by PRINT statements in the USER_PRINT or USER_PUNCH data blocks.
In PhreePlot, this output is directed to the Phreeqc.0.out and *.all files. The
Phreeqc.0.out file is only written if the Phreeqc.0.out keyword is ‘T’, or ‘auto’ and debug >0.
The *.all file is only written if the all keyword is ‘T’, or ‘auto’ and debug >1. The name of the
*.all file can be changed by adding the new filename as the second parameter on the all key-
word line.
(ii) selected output file: the SELECTED_OUTPUT n and USER_PUNCH n data blocks control tabular
output to the selected output file(s). The main selected output file (n = 1) is the file normally
used by PhreePlot for generating plots and it is normally this file that has to be manipulated
to give the required output. Certain rows of data from this file are accumulated in the ‘out’ file
which is often used to generate plots. Therefore familiarity with the ways of controlling out-
put to the SELECTED_OUTPUT file is a prerequisite for running PhreePlot. This is described in
detail in the Phreeqc manual (Parkhurst and Appelo, 1999).
In general, a single line of selected output is produced for each Phreeqc calculation – “after
each initial solution, initial exchange-composition, initial surface-composition, or initial gas-
phase-composition calculation and after each step in batch-reaction or each shift in transport
calculations”. If no USER_PUNCH variables have been defined, a blank line is output or if the
selected output has been turned off with the PRINT statement or -active FALSE setting, a
header line but no output is produced.
The Phreeqc library used by PhreePlot has switches to control whether the selected output is
written to a physical file or to memory. In PhreePlot, this is controlled by the value of the
debug setting with debug = 0 normally writing only to memory and greater values writing
increasing amounts to ‘disc’ (this could be a solid-state drive).

4.5 THE SELECTED_OUTPUT AND THE USER_PUNCH DATA BLOCKS

All output communications between Phreeqc and PhreePlot are sent via the selected output.
Therefore it is necessary to ensure that the correct output is sent to this ‘file’ (it may be just a
piece of memory or a ‘virtual’ file) and to tell PhreePlot what the format of the selected out-
put file is in relation to what PhreePlot has to do. This is done with a combination of the
SELECTED_OUTPUT/USER_PUNCH Basic statements in Phreeqc and selectedOutputLines key-
words in PhreePlot.
Phreeqc now supports multiple SELECTED_OUTPUT/USER_PUNCH blocks. These are numbered
with a user number, n, e.g. SELECTED_OUTPUT n/USER_PUNCH n where n is an integer which if
not specified is given the value 1. Within a given simulation, the SELECTED_OUTPUT n/
USER_PUNCH n numbers should be the same. Unlike with the batch and interactive versions of
Phreeqc, the default for the iPhreeqc library as used in PhreePlot is for the selected output
not to be written to a file. Rather, the selected output values are expected to be read directly
from memory and there are facilities to do this. This is in principle faster as it involves less
input/output. So in order to get arbitrary selected output files actually written, it is necessary
to switch them on first. The selectedOuptutFile keyword has a switch for doing this. This
switch combined with the SELECTED_OUTPUT/USER_PUNCH blocks determines if a selected out-
put file will be created or not.
There is one more important factor: the SELECTED_OUTPUT block must be executed in a simu-
lation before the simulation triggering the selected output, i.e. the selected output switch must
be set ‘on’ before the simulation generating the output is executed. In PhreePlot’s modus oper-
andi, this means that the selected output block(s) should either be placed in a pre-loop simula-
tion or for main loop simulations, the ‘one simulation at a time’ approach should be adopted
(see mainLoop) with the selected output block placed in a simulation preceding the simula-
tion that triggers the wanted selected output.
PhreePlot only transfers data from one selected output block to the ‘out’ file, the structured-
18 PhreePlot Guide

output file that is used for plotting. The block chosen is always the one with the highest user
number. This is not necessarily in the last simulation to be executed. Therefore judicious
numbering of the blocks provides a straightforward way of selecting the simulation which will
provide the output data.
selectedOutputLines is a number giving the number of lines from the chosen SELECTED_OUT-
PUT/USER_PUNCH block to transfer to the ‘out’ file, counting from the bottom of the output
upwards. This setting does not affect the data that will be sent to other files specified with the
SELECTED_OUTPUT; -file identifier.

Selected output will only be generated if both the SELECTED_OUTPUT and USER_PUNCH data
blocks are both present somewhere in the Phreeqc part of the input file. By default they are
active from the point of definition downwards. Selected output will be triggered from all sim-
ulations with a defined SELECTED_OUTPUT n/USER_PUNCH n pair each time an initialization,
reaction or timestep occurs. These can be selectively turned off/on with the -selected_out-
put identifier in the PRINT block and the -active and -user_punch identifiers in the SELECT-
ED_OUTPUT block. There will have to be a reason to emit some output so usually at least one
SOLUTION/REACTION block is needed (it can be empty).

It may also be useful to include the -reset FALSE and -high_precision TRUE identifiers to
suppress unnecessary headers and to retain maximum precision in the output numbers. The
system variables like SIM_NO are only produced without being explicitly defined when n = 1 in
SELECTED_OUTPUT n/USER_PUNCH n.

While the ‘out’ file is the principal data file used for plotting, other files can be used to supply
data for plotting by specifying them with the extradat keyword.
The built-in BASIC interpreter in Phreeqc provides a very flexible approach for defining the
selected output. The interpreter provides access to most of the fundamental system variables
such as species concentrations and activities. It also includes various summary functions such
as TOT(), SURF() and SYS(). The data sent to the selected output from various stages of
Phreeqc calculations can be controlled in the USER_PUNCH n data block(s) by checking the
STEP_NO and jumping over any PUNCH statement(s) for which the output is not wanted.

4.5.1 The SELECTED_OUTPUT filename and forcing the file to be written

The default name of the SELECTED_OUTPUT file in PhreePlot is ‘selected_1.0.out’ but this
can be changed using the SELECTED_OUTPUT -file identifier, as normal in Phreeqc. As men-
tioned above, the selected output in PhreePlot is normally written to a ‘virtual’ file (a block of
memory) and is not necessarily written to a ‘physical’ or disc file. The writing of the physical
file is controlled by a switch set by the selectedOutputFile keyword. This setting applies to all
selected output files created during the run.
For debug > 1 a physical file will always be produced with the given file name so that the out-
put can be inspected. There will be small performance penalty because of the file writing.
It can be useful to force a physical file to be written with multi-simulation input files. Data
from each simulation could be sent to a different file and plotted accordingly using the extra-
dat keyword to define the data files to be searched for plot data.
If the -selected_out identifier of the USER_PUNCH data block is set to FALSE, no lines are writ-
ten to the selected output file. However, a selected output file will still be produced but it will
be blank. This will be translated to a set of variable values all given zero values, i.e. all output
variables will be reported as 0.000000000000E+00 in the log file.
If a change in the structure of the selected output is wanted, make sure the simulations
involved are executed as separate blocks (see mainLoop).

4.5.2 Scope of Phreeqc keywords

Each Phreeqc simulation consists of a series of keyword data blocks which define the calcula-
tions for that simulation. The order of these keywords within a simulation is normally not
 Phreeqc basics 19

important other than if a keyword is replicated, the last instance overrides earlier ones. An
exception is that the position of the -reset in USER_PUNCH keyword blocks can be important.
Also the position of the units and numberOfFitParameters keywords can be important in rela-
tion to the related settings that follow.
The simulations are separated from one another by an END keyword. Each END can therefore be
interpreted as ‘Calculate!’.
Other keywords such as SELECTED_OUTPUT and USER_PUNCH have a broader scope and operate
from their point of insertion forward.
For example, the following input defines four Cd solutions and does an ‘initial solution’ calcu-
lation (speciation) for each one. The four simulations are essentially unrelated.

SOLUTION 1 # Simulation 1
Cd 1.0
END
SELECTED_OUTPUT #Simulation 2
high_precision true
reset false
USER_PUNCH
headings Cd+2
10 punch mol("Cd+2")
SOLUTION 2
Cd 0.1
END
SOLUTION 3 #Simulation 3
Cd 0.35
END
SOLUTION 4 #Simulation 4
Cd 0.6
END

This produces the following output in the selected_1.0.out file when the wateq4f.dat data-
base is used:
Cd+2
9.992072733798e-005
3.497329579806e-004
5.995528842616e-004

Note that no output has been produced for the first initial solution calculation since it is in a
simulation that precedes the definition of the SELECTED_OUTPUT data block. The SELECT-
ED_OUTPUT file is ‘turned on’ in simulation 2 and the output appears from this point forward,
hence the three lines of output representing output from simulations 2 to 4. Additional PUNCH
statements within a simulation result in more output columns. The ‘headings’ line in the
USER_PUNCH data block controls the header used for the column in the selected output file.

Therefore, for as long as the selected output file is turned on, at least one line of output is pro-
duced by each simulation providing that a USER_PUNCH block has been defined. The output for
the whole job accumulates in the selected output file. PhreePlot accumulates ‘selected data
from the main selected output file’ into a single output file called the ‘out’ file or outfile. The
default is to accumulate only the last line from the last simulation here the 5.995528842616e-
004.

The scope of many other Phreeqc ‘structures’ is global in the sense that once created in a sim-
ulation they persist for the remainder of the run unless overwritten. For example, solutions
defined by the SOLUTION keyword are automatically preserved across simulations. These solu-
tions can be used in subsequent simulations providing that the solution number is not reused
or redefined by a reaction. The same is true of PHASES, SOLUTION_SPECIES etc.

4.5.3 What is sent to the SELECTED_OUTPUT file?

Both numeric variables and text strings can be sent to the SELECTED_OUTPUT file by defining
them in a USER_PUNCH data block. The column headings should reflect each entry on a one to
one basis. If the list of headings is shorter than the list of variables output, the missing head-
20 PhreePlot Guide

ings are given the value ‘no_heading’.

The names of the column headings take on especial importance in PhreePlot since they are
used to automatically generate the names of new tags (see Section 6.4.2) and can ultimately be
used to label plots.
The number of significant figures sent to the SELECTED_OUTPUT file is controlled by the -
high_precision identifier in Phreeqc. It is normally safest to set this to TRUE, i.e. output at
high precision (12 decimal places, 13 significant figures). Normal precision is 4 decimal places
(5 significant figures). The default is FALSE so the high_precision identifier needs to be set
explicitly as above if high precision output is wanted. The high precision option is definitely
preferable when fitting data to models and when calculating predominance diagrams.
The sequence of columns sent to the SELECTED_OUTPUT file is set by the following rules:
(i) one column for each of the SELECTED_OUTPUT data item switches (simulation, state,
solution...) that is set to TRUE. The column headers for these switches, and their order, is given
by: sim, state, soln, dist_x, time, step, pH, pe, reaction, temp, Alk, mu, mass_H2O, charge
and pct_err. The default value for the first eight of these is TRUE and for the remainder is
FALSE. It is normally advisable to use the -reset false option at the top of the SELECT-
ED_OUTPUT data block to turn all of these off. Then the ones that are wanted can be turned on
by explicitly defining them as TRUE.
(ii) one column for each variable defined in the list data items such as -totals, -activities
etc. output in the sequence specified.
(iii) one column for each item PUNCHed within the USER_PUNCH data block in the cumu-
lative order in which they are specified by the BASIC statements. There can be one or more
items per PUNCH statement.
An example is:

SELECTED_OUTPUT
high_precision true
reset false
USER_PUNCH
headings pH Ca Mg
10 punch -la(“H+”), tot(“Ca”), tot(“Mg”)

4.6 SETTING UP THE SELECTED_OUTPUT FILE FOR INPUT TO PHREEPLOT

4.6.1 Possibilities for looping of Phreeqc input files

The structure of Phreeqc input files is very flexible in terms of the number of simulations
within a file and the relation between the various simulations. These are executed sequentially
until the end of file is found. Phreeqc does not contain any mechanism to enable looping of
the various simulations. This is what PhreePlot attempts to do without impinging unduly on
the overall structure of the Phreeqc input. PhreePlot expects a certain Phreeqc structure in
order to control this looping. This structure depends on the calculationType and certain other
keyword settings.
The general philosophy in preparing PhreePlot/Phreeqc input files should be to (i) keep the
input file as simple as possible; (ii) put any preliminary calculations that only need to be exe-
cuted once in one or more ‘pre-loop’ simulations at the beginning of the file; (iii) finish with
the simulation, or range of simulations, that need to be repeated many times with minor
changes (the ‘main loop’).
PhreePlot also recognises two types of looping: (i) a ‘continuous’ type of looping which
focuses on the ‘resolution’ of the calculations, (ii) a ‘discontinuous’ type of looping which gen-
erates a list of discrete values to be used. The x- and y-axis loops belong to (i), and the main
species and z-loop belong to (ii). These differences are reflected in the way that the iterations
are specified: (i) is specified in terms of a minimum value, a maximum value and a ‘resolution’
while for (ii) the main species loop uses a list of character variables and the z-loop uses a mini-
 Phreeqc basics 21

mum value, a maximum value and an increment value. An irregular list of z-loop values can
also be supplied.
Typically, the x- and y-axis loops are used to control the smoothness of generated curves for
plotting while main species repeats calculations over a range of chemical elements and the z-
loop controls the spacing between curves based on a range of discrete values of some impor-
tant variable.
It is only the ‘main loop’ simulations that are repeated under the x- and y-axis looping mecha-
nisms. The pre-loop simulations should be used for ‘one-off’ calculations such as initial solu-
tion calculations or database definitions that do not need to be varied during the main loop
but which might need to be used recalculated for each of the main species and z- loops. More
details about PhreePlot looping and the structure of multi-simulation input files is given in
Section 6.2.

Predominance plots
mainspecies loop
z-loop

simulation 1 selected output

USER_PUNCH tags
END (last line only)

selected output
simulation 2 USER_PUNCH tags
pre-loop

(last line only)

END

selected output
simulation 3 USER_PUNCH tags
END
(last line only)

simulation 4 selected output

USER_PUNCH tags
(last line only)
END
<y_axis>
<x_axis> simulation 5 USER_PUNCH selected output tags
main
loop

END always select last line which must have

the special structure as e.g. defined by the
ht.inc file
out file

Figure 4.1. Flow during the execution of a multi-simulation file generating a predominance plot (calcula-
tionType ‘ht1’ or ‘grid’). Simulations 1–4 are ‘pre-loop’ simulations used for initial solution etc calculations.
The <x_axis> and <y_axis> tags are only present in the 5th or ‘main loop’ simulation. It is this one which is
repeatedly called while tracking or traversing the specified domain. It is always the last line of the selected output
generated by this main loop simulation that returns the predominant species for PhreePlot to process. The
selected output file has a special structure and is normally generated by including the ht1.inc file or some variant
of it in the input file. Note that this flow diagram refers to a single value of the main species and z-loop variables.

The structure of the input file to generate a predominance diagram typically consists of two
simulations (Figure 4.1). It could all be done with one simulation but it executes more rapidly
if the initialization parts (the ‘pre-loop’ calculations which only need to be executed once) are
separated from those calculations that vary and that need to be calculated repeatedly (the
‘main loop’ calculations). The number of the first main loop simulation is identified with
mainLoop.
The first simulation usually pulls in the ht1.inc file which defines the Fix_H+ phase and sets
up the selected output ‘file’ and the required USER_PUNCH definitions that transmit the pre-
dominant species to PhreePlot. It also includes a SOLUTION data block which defines the total
quantities of all elements in the system of interest.
The second simulation uses the chemical system defined above and subjects it to control by
the x axis and y-axis variables.
A simple example for generating an Fe predominance diagram is:

# the first simulation defines the total quantities involved

include 'ht1.inc'
SOLUTION 1
pH 1.8
units mol/kgw
22 PhreePlot Guide

Fe(3) 1e-2
Na 1e-1
Cl 1e-1
END

# the second simulation carries out the reaction to the desired endpoint
USE SOLUTION 1
EQUILIBRIUM_PHASES 1
Fix_H+ <x_axis> NaOH 10
-force_equality true
O2(g) <y_axis> 1
Fe(OH)3(a) 0 0
END

Note that solution 1 is titrated with NaOH and O2(g) to achieve the required endpoints. The
initial pH of solution 1 should be less than the minimum pH of interest so that adding
NaOH can be guaranteed to achieve the full range of pH’s required.
If the <mainspecies> tag has more than one variable associated with it or if the <loop> varia-
ble has been set up to perform more than one z-loop, then the entire input file is run each
time one of these loop variables changes value. This can be used to prepare a set of predomi-
nance plots for several elements each with the its total concentration, for example, varying by
some amount. The ...\demo\loop_ht1 examples produce Fe predominance diagrams for a
range of total Fe concentrations. If an irregular sequence of z-loop values is required use the
loopFile keyword to read the values from a file.
If the main loop contains more than one simulation, then by default all of these simulations
are executed in a single run of Phreeqc. This means that tags will not be updated between
simulations. If this is needed, it is necessary to run the main loop simulations one at a time.
This is done by setting the selectedOutputFile switch to TRUE.

Data-led calculations

simulation 1 selected output

USER_PUNCH tags
END (last line only)

selected output
simulation 2 USER_PUNCH tags
pre-loop

(last line only)

END

selected output
simulation 3 USER_PUNCH tags
END
(last line only)

simulation 4 selected output

USER_PUNCH tags
(last line only)
END
selected output
simulation 5 USER_PUNCH tags
main
loop

(last line only)

END

The simulation(s) used for each data point depend on the value
or range of values specified in the column defined by the
blockRangeColumn of the data file. The pre-loop/main
loop division is determined by the value in the mainLoopColumn.

Figure 4.2. Flow during the execution of data-led calculations (‘simulate’ or ‘fit’ calculation types) in which the
simulation used is specified in the fit data file (or is simulation 1 by default).

The ‘fit’ and ‘simulate’ calculation types both read in certain parameters from a fit data file. In
order that the global optimization can include data calculated by different chemical models,
each data point can point to a different chemical model (Figure 4.2). Each chemical model is
defined by one or more simulations in the Phreeqc input code. These are specified by a data
column in the fit data file - the column used for this is defined by the blockRangeColumn.
The default value for the simulation is 1 which is the value assumed if no blockRangeColumn
 Phreeqc basics 23

is present in the fit data file. In this case, all values are calculated by the same chemical model.
If more than one simulation is needed, then a contiguous range can be entered, e.g. “1–2” (or
equivalently “1_2”) to indicate that simulations 1 and 2 will be used. There should be no
spaces in the string.

Custom plots

The ‘custom’ calculation type can be used to generate data for a variety of Phreeqc-type calcu-
lations especially where repetition is required that is not covered under the normal Phreeqc
options (Figure 4.3).
A custom calculation generally consists of zero or more pre-loop simulations which calculate
various initializations and then one (or more) simulations which are iterated using PhreePlot’s
x- and y-looping mechanisms. Normally it is the last line from the selected output generated
from the last simulation that is accumulated in the ‘out’ file and used in any subsequent plot-
ting.
If a z-loop variable is included, the whole input file is re-run for each z-value including any
pre-loop simulations.
The following input first defines a 1 mmol/kgw solution of CdCl2 and then equilibrates this

mainspecies loop
z-loop

simulation 1 selected output

USER_PUNCH tags
END (last line only)

selected output
simulation 2 USER_PUNCH tags
pre-loop

(last line only)

END

USER_PUNCH selected output

simulation 3 tags
END
(last line only)

simulation 4 selected output

USER_PUNCH tags
(last line only)
END
<y_axis>
<x_axis> simulation 5 USER_PUNCH selected output tags
Main
loop

END
selectedOutputLines
= 1 (for last or 'auto' for all)
mainLoop = 'last' (= 5)
out file

mainspecies loop
z-loop

simulation 1 selected output

USER_PUNCH tags
END (last line only)
pre-loop

selected output
simulation 2 USER_PUNCH tags
(last line only)
END

selected output
simulation 3 USER_PUNCH tags
END
(last line only)
main loop

END <x_axis>
<y_axis>
USER_PUNCH selected output tags
simulations 4 & 5
END
selectedOutputLines
= 1 (for last or 'auto' for all)
mainLoop = 4
out file

Figure 4.3. Normal flow during the execution of a multi-simulation input file for custom calculations. The out-
put depends on various settings including whether each simulation is executed in turn with just the final simulation
contributing to the ‘out’ file (upper figure) or whether the has been set to point to an earlier simulation (lower fig-
ure). Only simulations from that number forward are repeated during any ‘looping’ and are by default used to pop-
ulate the ‘ out’ file.
24 PhreePlot Guide

with carbon dioxide at a PCO2 partial pressure of 10-3.5 atm. Solution 1 is carried forward to
the second simulation. This simulation fixes the pH at 8.0 by titrating with NaOH and allows
amorphous cadmium hydroxide to precipitate if its solubility product is exceeded (which it is).
Note that a maximum of 1 mol NaOH is allowed to be used to prevent very high ionic
strengths from being created (the Pitzer option would have to be used for very high ionic
strength solutions).

SELECTED_OUTPUT #Simulation 1
high_precision true
reset false
USER_PUNCH
headings Cd+2 SI_Otavite
10 punch mol("Cd+2"), SI("Otavite")
SOLUTION 1
Cd 1.0
Cl 2.0 charge
END

USE SOLUTION 1 #Simulation 2

PHASES
Fix_H+
H+ = H+
log_k 0.0
EQUILIBRIUM_PHASES
Otavite 0 0 #Otavite is CdCO3
CO2(g) -3.5 10
Fix_H+ -8 NaOH 1
END

The selected output for this looks like this:

Cd+2 SI_Otavite
4.409910346467e-007 0.000000000000e+000

This output is from the second (final) simulation. It gives the Cd2+ concentration after otavite
has precipitated most of the Cd. These data are also transferred to the ‘out’ file.
Defining a pure phase to consist of a single species and then using the EQUILIBRIUM_PHASES
keyword to define its saturation index (SI), as here to fix the pH, is the Phreeqc way of fixing
a species activity. This simply forces the log activity to be numerically equal to the SI since SI
= log(IAP/SP) = log(aH+/log_k) = log(aH+) where IAP is the ion activity product and SP is
the solubility product.
In this example, the first simulation sets up the initial Cd solution and the second simulation
performs the reaction. The same effect could have been achieved by reducing the whole file to
a single simulation by removing the END and USE keywords. The selected output then looks
like:
Cd+2 SI_Otavite
8.738892163591e-004 -9.999000000000e+001
4.409910346467e-007 0.000000000000e+000

with the first line of output being derived from the initial solution calculation and the second
line having been derived from the second (reaction) simulation.
Another way of running both simulations together would be to set mainLoop to 1 so that
both simulations are run together as ‘main loop’ simulations. By default, the ‘out’ file only
picks up the last line of the selected output but if all three lines are wanted, selectedOutput-
Lines for the simulation should be set to 3 or ‘auto’. ‘auto’ will always transfer all the data
lines to the ‘out’ file.
If only the final concentration is wanted and the two simulations are run separately, then it is
also possible to omit the output from the first simulation by turning the selected output off
then on again in the second simulation using the -selected_output identifier of the PRINT
data block, e.g.

SELECTED_OUTPUT #Simulation 1
 Phreeqc basics 25

-high_precision true
-reset false
PRINT
-selected_output false
SOLUTION 1
Cd 1.0
Cl 2.0 charge
EQUILIBRIUM_PHASES
Otavite 0 0 #Otavite is CdCO3
CO2(g) -3.5 10
Fix_H+ -8 NaOH 10
SAVE solution 2
END

USE SOLUTION 2 #Simulation 2

PRINT
-selected_output true
EQUILIBRIUM_PHASES
Otavite 0 0 #Otavite is CdCO3
CO2(g) -1.5 10
Fix_H+ -8 NaOH 10
END

gives the selected output as:

Cd+2 SI_Otavite
4.409910346467e-007 0.000000000000e+000

Knowing which minerals might form using the given database

Phreeqc has no simple way of automatically inserting a valid set of minerals into an EQUILIB-
RIUM_PHASES keyword block such that any mineral that is predicted to form does form. This
normally has to be done manually. The mineral names will depend on the database used and
the solution composition. The printphases.inc include file extracts a list of all possible min-
erals by using the SYS() function. This include file can be added to an input file to get the
mineral names printed to the file Phreeqc.out. These can then be pasted back into the input
file as needed.
An alternative and slightly simpler approach for ht and grid plots is to just set the resolution to
1. This automatically inserts the printphases.inc code directly into the Phreeqc input
stream just ahead of the first (and hopefully only) SOLUTION keyword block. It also ensures
that the Phreeqc.out file is written and that all the PRINT settings are reset to TRUE. This will
only work properly for single simulation input files and providing that there are no
USER_PRINT blocks following the SOLUTION keyword block (these would override the inserted
code).
With these provisios, a single iteration is performed with all loop variables set at their initial
values and the names of all possible mineral species are written to Phreeqc.out.
It is possible to use Phreeplot to automatically generate a list of all possible mineral species in
one simulation, write them to a tag, and then to retrieve this tag in the EQUILIBRIUM_PHASES
data block of a subsequent simulation. This approach is used in demo\minstab\allminer-
als.ppi to generate a predominance diagram that automatically adds all of the minerals in the
database to the list of potentially precipitating minerals. This must be used with caution since
many minerals, while thermodynamically stable, do not form in a reasonable timescale.

4.6.2 Setting up a loop file

The z-loop or loop variable is used for discontinuous variables and will result in a separate cal-
culation and associated curve (or plot) for each value of the loop variable. This contrasts with
the x- and y-variables which are designed for ‘continuous’ variables in which the resolution
defines the number of calculations per curve.
<loopmin>, <loopmax> etc can be used to define a regular sequence of values for the loop vari-
able but if an irregular sequence is required or if more than one variable has to be carried in
parallel for each iteration, then a loop file must be created.
26 PhreePlot Guide

The loop file is an ASCII file which is read in free format. This file is primarily intended to
contain numeric data but it can also include character data. It can optionally contain a header
row with column names and an initial column with loop names. The format is deduced from
the first two columns and first two rows of the file. Columns are either numeric or character.
The first two columns of the first row determine if it is a header row (if both are character var-
iables). The first column of the first two rows determine if loop names are present (if both are
character variables). The remaining columns can be either numeric or character – this is deter-
mined by the type of data in the first non-header row. It may be necessary to introduce a
dummy numeric column as column 1 or 2 to force the correct interpretation of the file.
The four possible formats are shown in Figure 4.4.
(a) (b) (c) (d)

no header no header header header

no loop names loop names no loop names loop names

num num char num char char char char

num num char num num num char num

num = numeric value

char = character value

Figure 4.4. The format of fit data files is determined by the type of data in the first two rows and
first two columns of data.

The column headers if present are used to make the tag names, e.g. Na will make the tag <Na>.
Make sure that the column headers, if present, give rise to unique tag names.
If the header line is absent, then the tag names will be automatically set to <loop1>, <loop2>
for numeric column 1, 2 etc. These tags can be used in the input file. <loop1> is also known
simply as <loop>.
The loop names, if present, are used in exactly the same way as the loop names read in with
the labels keyword. Names in the loop file takes precedence.
A blank line in the loop file forces a blank line to be written to the ‘out’ file in the correspond-
ing position. This is useful for creating line breaks in plots.
A loop file is used to generate a set of discrete tag values that can be used in the Phreeqc code.
Each row of values is picked off in turn during an iteration of the z-loop, i.e. the number of
rows determines the number of iterations.

4.7 RUNNING PHREEQC WITHOUT ANY PLOTTING

The looping facilities in PhreePlot make it useful for some types of repetitive Phreeqc calcu-
lations which do not require a plot. Setting calculationMethod <0 will suppress any plotting,
as will setting plotFactor = 0. If data are to be read from a data file, as in fitting, then the cal-
culationType = “simulate” setting should be used to avoid calling the fitting routine. The
“simulate” setting can also be used to make a set of simulations after fitting, e.g. to plot a sim-
ulated curve.
The input data file, which is probably most conveniently prepared in a spreadsheet or database
and exported in csv or tab format, contains the data to be used. Tags are created from the
headers.
The SIs.ppi file gives an example of the use of ‘simulate’ for calculating saturation indices. It
contains a translation table that assists in converting non-standard headings in the text data
file to standard Phreeqc format. PhreePlot is used to loop one-by-one through a data file con-
taining analyses of groundwater chemistry. It runs a small Phreeqc include file which contains
 Phreeqc basics 27

the USER_PUNCH code necessary to calculate various saturation indices and other parameters.
This can be readily modified. The results are accumulated in the ‘out’ file.
The use of a data file for passing on information is somewhat similar to the use of a loop file
(Section 6.2.1).

4.8 INCLUDE FILES

4.8.1 Use of ‘include’ files

The input files can contain INCLUDE statements to pull in other files, e.g.

INCLUDE ht1.inc

The text following the INCLUDE statement, here ht1.inc, is the name of a file. The filename
can be optionally embedded in quotes. The normal rules apply for the search path when look-
ing for include files (Section 2.4.6).
All of the statements in this file will be inserted line by line at the insertion point. This substi-
tution occurs when the input file is initially read, before any code execution. This makes it
possible to have a library of commonly-used pieces of code. The include statement is recursive
– an include file can itself contain references to other include files.
The BASIC program runs strictly in the order of the BASIC line numbers not necessarily the
sequence of lines in the file. If a line number is repeated, the last one read is used. This means
that it is possible to add edits to an include file by including an ‘edit file’ after the main file (see
e.g. ht1s.inc).
Using include files can reduce repetition of commonly-used code and make it easier to manage
such code. It also can increase the readability of input files.
Phreeqc3 contains its own version of ‘include’ in the form of the INCLUDE$ keyword. This
is a more powerful form of include than PhreePlot’s since it is ‘dynamic’ (dollar for dynamic!):
the include file is read anew each time the directive is encountered. Therefore an earlier piece
of Phreeqc code within the same run may write or modify the contents of the include file
using PUNCH statements for example. In contrast, PhreePlot only reads the include file once –
at the beginning, before the Phreeqc code has been executed. Conclusion – use INCLUDE$
if you want to read a file that is generated during a Phreeqc run. And if in doubt, use
INCLUDE$. Remember that if the file is not found in the current directory, PhreePlot’s
INCLUDE automatically checks the system directory whereas INCLUDE$ does not.

4.8.2 Supplied include files

Several include files are provided for commonly-used functions. These will be found in the
system sub-directory. The uses of some of them are summarised in Table 4.1.

ht1.inc can be used to calculate a predominance diagram. If adsorbed species are present,
then their concentration is considered on a species by species basis just like solution species.
ht1combined.inc is similar except that all adsorbed species of one element and one surface are
combined into a single species (a ‘superspecies’) for the purposes of the predominance calcula-
tions (ranking) and for plotting. Other include files are variations on these. See the examples
in the \demo directory for their use.

4.9 USING PHREEQC’S _RAW AND _MODIFY KEYWORDS

Phreeqc (Version 3) introduced new keywords to retrieve and modify various existing data
structures. These are based on existing keywords with the suffixes _RAW and _MODIFY.
They are intended to provide more flexibility in the ways that the chemical system can be
defined and modified, and provide ways of reading in data structures sent to a file by DUMP.
These new keywords are not expected to be widely used.
28 PhreePlot Guide

Table 4.1. Some of the supplied include files and their functions

file function
ht1.inc for calculating predominance plots
as above but combines all adsorbed fields for a common surface
ht1combined.inc into a single field; also gives an option of using the mineral stabil-
ity criterion for identifying boundaries
ht1cCO3.inc as above but includes an additional total CO3 constraint
ht1cStability.inc as above but includes the stability criterion
ht1s.inc as ht1.inc but also adds ‘(s)’ to the labels for mineral names
as ht1.inc but also writes a list of all precipitating and poten-
ht1minerals.inc
tially precipitating minerals to the log file (needs out = TRUE)
as ht1.inc but also adds the mineral formula below the min-
ht1_phase_formula.inc
eral name when labelling the plot
minstab1.inc used for calculating traditional mineral (only) stability diagrams
as ht1.inc but automatically adds all possible minerals as
ht1allminerals.inc
potentially precipitating mineral phases
used to print the possible mineral phases to the Phreeqc.out
printphases.inc
file
speciesvspH.inc used for making species-pH plots
logspeciesvspH.inc used for making species plots with log y-scale

They enable the updating of concentrations to be simplified and maybe speeded up. For
example, the SOLUTION keyword always does an initial solution calculation whereas
SOLUTION_MODIFY does not. It may also be possible to avoid initial exchange and initial
surface calculations in an analogous way.
 PhreePlot input and output files 29

5 PhreePlot input and output files

5.1 INPUT/OUTPUT FILES

5.1.1 Use

PhreePlot uses a number of files for input and output. The default ‘settings’ file, pp.set, is
used to read in default values for all keywords. These are modified, and the Phreeqc chemistry
part is added in the ‘normal’ input file (usually with a ppi extension), and finally keyword val-
ues can be overridden with the override.set file.
All of these input files are in ASCII text format and so can be read and written with a normal
text editor. The input files determine the calculations that will be carried out. The extension is
stripped from the input filename and this is used as the ‘root’ for automatically naming the
output files. Many of the output files are optional and their production is set by a series of log-
ical switches which can be set to TRUE or FALSE.
In ‘Safe’ mode (the way PhreePlot has currently been set), all the necessary files needed to
produce the specified plots, and to be able to replot them, will be created even if their logical
switches have been set to FALSE. Where file switches are specified to be FALSE, the correspond-
ing files will be deleted at the end of the run if present, even if they were created from an ear-
lier run.
Any existing files with the same name as the files to be created/deleted will be overwritten or
deleted without warning.

5.1.2 Difference in execution of input files between PhreePlot and Phreeqc

Aside from the substitution of tags with values in PhreePlot input files, the CHEMISTRY part of
a PhreePlot input files looks very like a Phreeqc input file, and in fact, it is often easiest to
test small pieces of code using Phreeqc or Phreeqc Interactive. When there is only one simu-
lation in a file, there is essentially no difference in terms of execution.
However, where there is more than one simulation, PhreePlot has greater flexibility in the
way that individual simulations are run. There are two key features here: (i) a separation
between ‘pre-loop’ simulations and ‘main loop’ simulations, and (ii) the way that the main
loop simulations are executed.
The modus operandi of PhreePlot is that some simulations may be required to set up the data-
base, define other fixed things, prepare initial solutions etc and these need only be done once.
These are called ‘pre-loop’ simulations. Following this in terms of layout and execution, there
may be one or more ‘main loop’ simulations which are iterated or ‘looped’. Normally there
will be one or more tags in the ‘main loop’ part which will be altered during each iteration,
thus varying the output, and ultimately preparing a set of data for fitting or plotting.
Phreeqc necessarily runs all simulations consecutively and without user intervention. Data
structures are carried from simulation to simulation and some between-simulation user data
can be transmitted via the Basic PUT(), GET() functions, but there are few other opportunities
for dynamically altering values given in the input file.
PhreePlot has greater opportunities since it has the option to control the way that a multi-
simulation input file is executed. As indicated above, there is the basic division between pre-
loop and main loop simulations. There is another important option. PhreePlot feeds the
input file that it has read into the Phreeqc calculator, line by line. Calculations are only begun
30 PhreePlot Guide

when a whole simulation has been read in (defined by an END statement) but PhreePlot
decides when to look at the results of each simulation by exiting Phreeqc and looking at the
output, updating the tag dictionary, making new substitutions etc.
These two options: (i) ‘one simulation at a time’ mode or (ii) ‘all at once’ mode. (i) cedes con-
trol to PhreePlot after every simulation has been executed which gives some opportunity to
alter values for subsequent execution. (ii) is faster in execution but Phreeqc only returns to
PhreePlot after all simulations have been executed. This means that there is no opportunity to
intervene.
PhreePlot has somewhat arbitrarily made the decision that:
(i) all pre-loop simulations will be run ‘one at a time’ (being executed just once, speed is not
such an issue while the added flexibility can be useful).
(ii) there is the option or running main loop either ‘one at a time’ or ‘all at once’.
These two features are controlled by the mainLoop keyword. e.g.
mainLoop 3 false
means that the main loop simulations start at simulation 3 (simulations 1 and 2 are therefore
‘pre-loop’) and that ‘one simulation at a time’ is false, i.e. all main loop simulations will be run
together in one block.
The default in pp.set is
mainLoop auto false
where auto normally refers to the last simulation, i.e. the looping will only occur over the last
simulation. For calculationType’s fit and simulate, auto is set to 1.
Using debug equal to 2 or greater will log the details of how the simulations are executed to
the log file.

5.2 INPUT FILES

5.2.1 Different types of input file

There are three main types of input files: (i) those that define certain keyword values or set-
tings plus the chemical definition of the problem and dictionary files (‘main input files’); (ii)
those auxiliary files that provide additional data such as data for fitting and additional data or
text for plotting (‘data input files’), and (iii) those that contain chunks of Phreeqc code to be
included in one of the main input files (‘Phreeqc input files’).
This section describes the first of these while the separators used for parsing input files is
described in Section 5.2.7.

User
Input file Override file
defaults file
Run
PhreePlot
pp.set *.ppi override.set
defaults

'Esc'
interrupt

Figure 5.1. Diagram showing the sequence of setting of the keywords.

PhreePlot runs in response to the settings of various keyword-value pairs and lists. The values
associated with these keywords can be defined in various ways (Figure 5.1). In running order,
these are:
 PhreePlot input and output files 31

1. PhreePlot program defaults: set by PhreePlot internally; usually provide

minimal functionality;
2. the pp.set file: user-defined default values read from a file; contains gen-
eral preferences;
3. the main input file, the one given on the command line. It defines values
for the particular problem of interest and normally contains the line
‘CHEMISTRY’ somewhere in it. This must be on a line by itself. It divides
the input files into two with PhreePlot keywords in the upper section and
Phreeqc-format chemistry, if any, in the lower section. It is best if this
main input file is given the ppi file extension so that it can be associated
with the PhreePlot program;
4. the override.set file: useful for overriding one or more settings without
having to edit the main input file(s);
5. input made during interrupts during execution of PhreePlot: emergency
redefinitions, e.g. changing the debug level (see Section 6.6).

The last defined keyword value or list of values is always used from its point of definition for-
wards.
The full list of keywords is normally given in the default pp.set file in the system subdirec-
tory. The pp.set and override.set files should be in the system sub-directory if present. The
pp.set file should be modified to set commonly-used attributes that remain constant between
runs, including system-specific features such as the filepath for Ghostscript as well as a wide
range of plotting parameters including the preferred units of length.
The override file (override.set), if present, is read after the input file and can be used to
override any previously-defined values. It is especially useful for temporarily changing attrib-
utes for a whole series of files called via a batch file, e.g. changing the plot method, a font, a
colour or turning the beep off.

5.2.2 Structure of the main input files

These files are the problem file (*.ppi), the pp.set file and the override.set file.
Although PhreePlot input files are rather unstructured, they logically divide into the follow-
ing four sections:

SPECIATION Details of the speciation calculations

FIT Details of any fitting
PLOT Controls the plotting parameters
CHEMISTRY Contains the Phreeqc code.

The first three of these four sections headings may be included anywhere in the input files.
These section headings are only included for improving the legibility of the files and are not
used by PhreePlot. If present, the CHEMISTRY keyword signals the beginning of Phreeqc-type
input and, must appear as the last entry in the PhreePlot section, i.e. the main input file must
always end with the CHEMISTRY section if it is expected to do any chemical calculations.
The structure of a typical input file is therefore:

...
<PhreePlot section heads and keywords that define various keyword settings and tag values.
This section also defines the looping parameters and what type of plot, if any, will be pro-
duced>
...
CHEMISTRY
32 PhreePlot Guide

...
<Phreeqc-format chemical input which is normal Phreeqc code but can include optional
PhreePlot tags for substitution during execution>
...

There is essentially no limit to the number of lines in the PhreePlot or Phreeqc parts. The
CHEMISTRY line, which should be on a line of its own, defines the divide between the two sec-
tions and instructs PhreePlot to interpret the input accordingly.
The CHEMISTRY section includes the Phreeqc code. This can only be included in the main
input file and any ‘include’ files called by the main input file. This determines what is calcu-
lated and has almost the same format as a normal Phreeqc input file. The principal difference
is that it can contain special tags (‘<...>’) that are substituted with appropriate values before
running Phreeqc.
Results from Phreeqc calculations are communicated to PhreePlot via the SELECTED_OUTPUT
‘file’ which itself is generated in response to the Phreeqc USER_PUNCH and SELECTED_OUTPUT
blocks.
Therefore the CHEMISTRY section is essentially a Phreeqc input file with tags. The tags provide
placeholders for substituting variable values generated by PhreePlot and give PhreePlot the
ability to loop, fit data to models etc. The PhreePlot section defines how the tag values are
generated and other aspects of the calculations including the plotting of results. The keyword
values can be floating point, integer, character or logical.

5.2.3 The input file pre-processor

Where a simulation is repeated many times with the only change being an increment in one or
more numbers, the simulations can be replaced with a single ‘template’ simulation which has
tags indicating the start and end of the sequence to be repeated, the increment and where to
substitute the generated number. This part of the code is executed before the input file is pro-
cessed. The input file pre-processor is described in detail in Section 13.

5.2.4 Exceptions to the ‘latest keyword definition overrides earlier ones’ rule

Normally when a keyword and its settings are read, these settings will override all previous
ones for this keyword. The exceptions are for numericTags, characterTags and overlay where
multiple instances will add to the list of tags or overlay files to be processed.

5.2.5 The colour dictionaries and other files

There are two colour dictionaries which store the colours used for the lines, points and fills: (i)
line colour dictionary for plots based on a custom plot, and (ii) the fill colour dictionary for
predominance diagrams. Contour plots do not use the dictionaries.
These files can be edited to change any colours. For fill colours, this is all that need be done.
For line and point colours, it is necessary to set useLineColorDictionary to 1 or 2 to force the
use of the dictionary.
There are also data files for loop variables and for data to be used in simulations or fits.

5.2.6 Format of all input files

Physical and logical lines

All input files including data files have a similar structure. The input format conventions are
similar to those used for standard Phreeqc input files. The maximum length of input lines is
only limited by memory but most strings and character expressions are limited to 10000 char-
acters.
 PhreePlot input and output files 33

A physical line is a text string ending with a normal line ending which for the Windows oper-
ating system is <CR><LF>. Each physical line appears as a distinct line of text in a text editor. It
can consist of less than one, one or more than one logical lines.
A logical line is a string which is interpreted as a single block of data by PhreePlot. The key-
word-value(s) combination of PhreePlot input files must always be present on a single logical
line.
Strings containing spaces (or more specifically, separators) should be enclosed in quotes,
paired single or double. One or more separators must precede and follow these quotes for it to
be recognised.
Any input following a comment character (#) is ignored for the rest of that logical line. This
includes ; and \ (see below). Blank lines and lines which are entirely made up of a comment
are not counted as logical lines and are ignored. So
pdf TRUE \
<BLANK LINE HERE>
png TRUE
will fail because the continuation will ignore the blank line and join the other two lines to give
pdf TRUE png TRUE

Logical lines are terminated by a normal line ending, or by a semi-colon (;). A comment char-
acter takes precedence over ‘;’. For example, the comment in
# PHASES; Fixed_H+; H+ = H+; log_k 0.0
will comment out all four logical lines.
The above rules for # and ; even apply when embedded in quotes. Their special behaviour
takes precedence over quotes. Therefore it is not possible to use these characters even in
quoted text strings, i.e. “Sample #76” and “Bloomington; Rochester” would produce errors.
This is not true in Phreeqc where the quotes take precedence.
A logical line may be split across two or more physical lines by using a continuation character.
A continuation character is a backslash (\) providing it is present as the last non-whitespace
character on a physical line after comments have been removed. So unlike Phreeqc, this is true
even when the \ is followed by spaces and a comment character, i.e.

numericTags <logH> = -<x_axis> \ # comment

<pH> = -<logH> # -pH

is valid as is

#pdf \
T

is not.
Tabs, being whitespace, are ignored by Phreeqc but can be significant in data files. Consecu-
tive tabs signify a blank fields. However, a line consisting only of tabs is treated as a blank line.
Data files prepared by pasting from a spreadsheet into a text editor can contain tabs, including
trailing tabs. Such files should be read using the tab as a separator. This is done by adding “\t”
after the filename. An alternative to this way of reading null values is to explicitly use the
‘missing data’ code, namely -99999.

Specifying keyword-value pairs and keyword-lists

Keywords and their values are separated by any number of separators on a logical line.
Quotation marks should always be used when there is a space or tab embedded within a char-
acter variable. A null character variable is entered as a pair of quotation marks with or without
34 PhreePlot Guide

one or more blanks, e.g. ‘’, ‘ ‘, ““ or “ “. It is necessary to use this format when entering a blank
value for a character variable.
The following are some examples of valid input lines:

jobTitle Iron
jobTitle “Iron hydrolysis”
jobTitle ‘Iron hydrolysis’
calculationType ht1;
calculationType ht1
calculationType ht1 #This is a comment
pxmin 0; pxmax 10; pymin -10; pymax 20
pxmin 0pxmax 10 pymin 10 pymax 20

Format of keywords and their associated values

Most keywords are followed by a single value of a specified type, either an integer, a floating
point number, a character string or a logical. Case is not significant except within character
strings and tags. Some keywords are followed by a list of variable length, e.g. mainspecies.
An integer is any set of digits with or without a sign. A number is any set of digits with or
without a valid exponent (in E format), decimal point or sign and includes all integers. A char-
acter string is any set of valid characters (see below), and is optionally placed within a pair of
delimiters (a pair of single or double quotes). A logical value can be entered as TRUE or FALSE
or T or F, irrespective of case. Examples are given below, each value being separated by a
comma:

Integers: 0, 12345
Numbers: 1, 2., 3.1, 4e0, 5E0, 6d0, 7D0
Character expressions: PhreePlot, “PhreePlot”, “PhreePlot program”, ““, “ “, ‘This is
“PhreePlot”’, “This is ‘PhreePlot’”
Logical: t, T, true, TRUE, True, f, F, false, FALSE

5.2.7 Data separators and parsing input files

All of the input files consist of a set of logical lines with a collection of zero or more ‘words’ on
a line. The difference between physical and logical lines is described above. In many cases, the
first logical line of a file is used as a ‘header’ to describe the data that follows. In some cases,
these header names are converted to variable (tag) names for the columns. All of the input files
are read in ‘free format’, i.e. the column position of the entry on the line is not important.
The words on a line are separated by ‘data separators’, sometimes called delimiters. The pars-
ing of input files (separating the words) depends on the structure of the input file and the data
separator(s) specified. You have to ensure that the two match so that the file can be parsed cor-
rectly.
Commonly-used separators are spaces, (horizontal) tabs and commas.
The main input files are read in ‘very free format’ in which case all of the three main separators
– a blank, tab or comma – are treated as valid separators and consecutive separators of any sort
are treated as a single separator.
Quotes should be used to specify character strings containing these separators (Section 5.2.6).
A quoted string should always be followed by a separator or an end-of-line marker. If not, the
text after the closing quote is added to the quoted part of the string and an additional quote
added to the end of the string.
Spaces and other special characters (other than ; and #) enclosed within quotes (single or dou-
ble) are treated as part of a character string and will not be split.
Since data files such as those used for fitting (datafile) or plotting (e.g. extradat) can come
from many sources and can include blank fields, a somewhat more rigid type of ‘free format’ is
required for this type of file. The default data separator is always taken from the first entry in
dataSeparators but this can be overridden by appending a format string after the filename.
 PhreePlot input and output files 35

Valid entries for this format string are:

“\w” signifies whitespace (one or more blanks or tabs)
“\b” signifies one or more blanks
“\t” signifies a single tab (often found in files derived from spreadsheets)
“,” signifies a single comma (for csv files)
“\” or “” (null string) signifies whitespace or one or more commas (if at
the end of a line, make sure that \ is embedded in quotes otherwise it will
be interpreted as the line continuation character). This is the ‘very free
format’ option that is used to read the input files and will read many of
the most-common types of formatted files.
“char” where “char” signifies any valid single character.

Note that when a single tab, comma or character are used as separators, consecutive separators
will define a blank field. This means that blank fields can be preserved when reading files
based on single character separators such as those produced by Microsoft Excel and OpenOf-
fice Calc.

5.2.8 Case sensitivity of input

Most of the text in the main input files is case insensitive. This includes all keywords. The
only exceptions are the names of tags (anything between angle brackets) including text within
tags (e.g <input...>) and the names of column headings used to define columns in a data file
– these are case sensitive. File names under Windows are not case sensitive.
In general terms, things that have been defined by PhreePlot are not case-sensitive whereas
things that you have defined are case sensitive.

5.2.9 Reporting of errors in input files

PhreePlot stops if it detects errors in one of the keyword input files. These errors include syn-
tax errors as well as any errors based on ‘compile time’ inconsistencies in the settings. These are
signalled with an error message to the screen and to the log file if open, e.g.

File: test.ppi:6
Keyword: xmax
Input: xmax 1x2
Error: Expecting a number.

The message indicates the file involved and the position in the file where the error was
detected in terms of the physical line (here line 6). The keyword involved (if known), the line
of text where the error was detected, and an error message are also given. These may not iden-
tify the location or prime source of error exactly but should be sufficient to help to identify it.
Where an error occurs within a section where continuations (\) are being used, then the phys-
ical line indicated will be the end of the position of the offending section and the word will be
a negative number indicating the number of words to count back to the offending input
(roughly).
The whole input file is checked before reporting the error and exiting. Where several errors
occur on the same logical line, only the first error will be reported.
Errors in other input files are signalled in a similar way.
36 PhreePlot Guide

5.3 TAGS

5.3.1 What are tags used for?

Tags are special symbols which have values associated with them (i.e. variables). Each tag has a
name which is a text string embedded within angle brackets, e.g. <x_axis> is the tag that
holds the current value of the x-axis variable.
When tags are used within a file, they are essentially place markers which indicate where vari-
ous substitutions are to be made at a later time. Tags can be used to define ‘global’ variables
that retain their values between simulations. Some tags are automatically created by PhreePlot
in order to make their values available for subsequent use.
Tags come in two flavours. Tags can be either numeric or character depending on the type of
value that they represent.
Each tag has a tag expression associated with it. These are evaluated before running Phreeqc
and the derived tag values substituted in the appropriate places within the script. The tag
expressions for numeric tags can include simple arithmetic expressions as well as more com-
plex expressions using other previously-defined tags.
If the substitutions are not made correctly within the Phreeqc code section, e.g. because a tag
is not recognised or not defined, Phreeqc will normally fail because of the illegal characters
found at run time.
Tags can be placed anywhere in an input file and in the optional extraText and extraSymbol-
sLines files. There is no limit to the number of tags used.
Tags, combined with the looping facilities within PhreePlot, are used to vary the calculations
made by Phreeqc in a dynamic way. Some tags are defined by PhreePlot, others are defined
by the user. They provide a simple way of defining variables and of giving Phreeqc some basic
looping capabilities without changing the format of the Phreeqc input file greatly.

5.3.2 Rules for choosing tag names

Tag names should always start and finish with open and closed angle brackets, e.g. <tagname>.
Tag names should preferably be restricted to upper and lower case letters, numbers and the
underscore. Other characters can be included although they will be temporarily replaced by a
full stop (‘.’) and so tag names with multiple characters such as +, - etc. can become degener-
ate. This also applies to tag names automatically created from the selected output and fit data
files and from the fit parameter names so the parent names should also follow this advice.
The first character of a tag name must be alphabetic, i.e. in the sets a-z or A-Z. Tag names
should not contain any spaces
System tag names are ‘reserved’ names and should not be redefined. These are: <x_axis>,
<y_axis>, <loop>, <logloop>, <mainspecies>, <timedate>, <nexecute>, <systime>,
<Phreeqc_status_0>, <pxmin>, <pxmax>, <pymin>, <pymax>, <p2ymin> and <p2ymax>.

Case is significant in tag names. There is no length limitation to tag names.

5.3.3 Tag expressions

Tag expressions are the text on the right-hand side of a tag equation. These are stored as char-
acter strings and can contain any valid combination of numbers, character strings and other
tag names (see below). The tag expression can be any length. Long expressions can be subdi-
vided and saved as separate sub-expressions.
Numeric tags can represent variable values; character tags always refer to constant string
expressions.
 PhreePlot input and output files 37

5.3.4 Numeric tag expressions and available functions

Numeric tag expressions can be simple numbers such as 1, 1.2, 1.2e2, 1.2d-4 or arithmetic
expressions such as 2*4, log10(3.5), 2+(3*4) etc. The arithmetic operators available are: +, -,
* , / and ^ (exponentiation).
The following functions are also allowed: abs, exp, log10, log, sqrt, sinh, cosh, tanh, sin,
cos, tan, asin, acos, atan, rand and nrand.

The random number generators, rand and nrand, return a single pseudo random value gener-
ated from the uniform (range = (0,1)) or normal (mean = 0, standard deviation = 1) distribu-
tions, respectively. Both functions take a single integer argument which acts as a seed. If the
seed is positive this value is used to start the distribution. Using the same seed on different
runs means that the same pseudo random sequence will be generated. Using 0 or a negative
integer value for the seed means that the system date and time are used to generate the start of
the random sequence. This will ensure that a different sequence is started for each run.
Parentheses are used for specifying precedence in the normal way. All numeric tags are stored
and evaluated with high precision (double precision).
Tag expressions can also include other tag variables providing that they have already been
defined. The sequence in which the tags are evaluated is controlled by the order in which they
are defined.
Undefined numeric tags have the value UNDEFINED which is stored internally as -99999.
Valid tag expressions are:

log10(<loop>)
2*<x_axis>

When tag values are substituted, they are rounded and then trimmed of leading and trailing
spaces. Therefore

-<x_axis>

should work providing that the value of <x_axis> is not negative.

5.3.5 Tags for character variables

These tags are substituted at the indicated positions. If the tag expression contains spaces,
enclose in quotes. Quotes are always removed before substitution and so they may need to be
used to surround the tag expression, e.g. “<mainspecies>” so that the substituted expression is
correctly parsed.

5.3.6 System tags

Certain tags are automatically created and updated by PhreePlot. These are:

<x_axis> the value of the x-axis variable (numeric)

<y_axis> the value of the y-axis variable (numeric)
<loop> the value of the z-loop variable after being exponentiated (10^x) if
necessary (numeric)
<logloop> log10 of the value of the z-loop variable (numeric)
<mainspecies> the name of the main species (character)
<nexecute> the number of times that Phreeqc has been called
<timedate> a time (hr:min:sec.millisec)/date string with the format
23:30:45.123 23 September 2004 (character)
<systime> uses the system clock to get the elapsed time (in sec) since the
38 PhreePlot Guide

beginning of PhreePlot execution (this reflects ‘wall time’ not cpu

time). Resolution about 1 msec.
<Phreeqc_status_0> returns the exit status from the last Phreeqc run: 0 = OK, >0 =
error
<pxmin> the value of pxmin (numeric)
<pxmax> the value of pxmax (numeric)
<pymin> the value of pymin (numeric)
<pymax> the value of pymax (numeric)
<p2ymin> the value of p2ymin (numeric)
<p2ymax> the value of p2ymax (numeric).

These tags are known as ‘system’ tags and are updated throughout a run. They have reserved
names, effectively making them ‘read-only’. They should not appear on the left-hand side of a
tag expression.
There are also some additional tags which are created on start-up or after fitting:

<command_linen> the values of the n command line arguments (n=0 gives the name
of the pp.exe file, n= 1 gives the name of the ppi file, n=2, 3, 4, ...
give any additional arguments) (character)
<R2> the value of R2 after a successful fit, see Section 5.3.7 (numeric)
<RMSE> the RMSE after a successful fit (numeric)
<nFit> the number of ‘observations’ in a fit (numeric)
<fitMethod the fitMethod (char)
<objectiveFunction> the objective function, “L1”, “L2” etc (char).

If a loop file is read, then a separate tag value is automatically created for each column. These
are named <loop1>, <loop2>, ... for column 1, 2, ... . They will also be named after their col-
umn header names, if present.
Other tag names are reserved for formatting text (Section 7.6.3). These are:

_and

^and
<i> and </i>
<b> and </b>
<g> and </g>
<subsup> and </subsup>
<br>

Other tags are automatically defined by the user or automatically created during the course of
calculations (Section 12.12) and can be used in the extraText file.

5.3.7 User-defined tags

User-defined tags are defined in one of the input or data files using the numericTags or charac-
terTags keywords. The order of definition is important since once defined, these tags can
themselves be used to define new tag values in subsequent tag expressions. Ultimately every
numeric tag will need to be evaluated to provide a numeric value ready for substitution in an
input file.
 PhreePlot input and output files 39

The order of evaluation of numeric tags is given in Section 5.3.8.

Examples of numeric tag expressions are:

<log_H> = 7.5
<log_H> = -<x_axis>
<pH> = -<log_H>
<H> = 10^(-<pH>)
<Cu2x> = “TOT(“Cu”) * 2”

Substitution takes place on each iteration just before the Phreeqc calculations are performed.
Tag types cannot be mixed in an expression. Numeric tag expressions can include other
numeric tags but character tags must not be used in numeric tag expressions neither must
numeric tags be embedded in character expressions. For example

<x> = “4 + <x_axis>”
<y> = “6 + <y_axis>”
<z> = <x>+<y>

where <x>, <y> and <z> are all valid numeric tags. Note the use of quotes where the tag expres-
sions contain spaces. The tag expression appear as a single text string.

<c1> = “Title”+<x>
<c2> = <mainspecies>+6.3
<c3> = <x>+<c1>

where <c1>, <c2> and <c3> are character tags, are invalid tag definitions because the addition
mixes character and numeric tags.
Numeric and character tags can be defined in extradat files in much the same way that they are
defined by selected output.

5.3.8 The scope of tags, their initial values and their order of evaluation

Each tag is defined by a tag expression. Since these expressions can themselves contain tags, it
is important to understand the order in which they are evaluated in order to avoid a tag refer-
ring to an as-yet undefined tag or getting an out-of-date value for a tag.
Tags can be defined in a number of ways: by PhreePlot itself (system tags), from user-defined
tags in an input file, from reading a loop file or fit data file, from the selected output file, or as
a result of fitting.
The tags, their expressions and their current values are stored in a tag dictionary. This is used
to substitute the values of any tags found in the input files before carrying out the next simu-
lation. The whole tag dictionary is available for all simulations.
Tags can also be used in any text strings that are used in plotting: plotTitle, xtitle, points and
lines and their 2y equivalents, customXcolumn and in text lines and extraText files. Tags used
in the 'lines' and 'points' lists can themselves be lists.
The initial value of all numeric tags is set to UNDEFINED (-99999) but can be set to another
value with the initialValue keyword. This same value is applied to all undefined numeric tags.
The initial value of character tags is set to the null or empty string.
It is also possible to set the initial value of an individual tag by using a pre-loop simulation,
e.g.
SOLUTION
SELECTED_OUTPUT
-reset FALSE
USER_PUNCH
-heading z
10 PUNCH 0.0
END

will set the initial value of the <z> tag to 0.0. SOLUTION ensures that the selected output is
actually written. A pre-loop simulation is only executed once.
40 PhreePlot Guide

After a block of one or more simulations has been computed by Phreeqc, new tags are formed
if appropriate and all tag values are updated. This updating only occurs after all the simula-
tions within the block have been completed. Phreeqc has complete control during this execu-
tion phase. Therefore tag values cannot be passed from one simulation to another when they
are part of the same execution block since execution does not leave the Phreeqc module and
so the tags cannot get updated by PhreePlot. This has implications on how the input file is set
up.
Tags can be used in the ‘upper’ part (the part before CHEMISTRY) of an input file as well as the
in Phreeqc section (the part that follows CHEMISTRY). Tags can also be in extraText and extra-
SymbolsLines files which, if present, are updated during the plotting.
Once set, tag values retain their values until reset. Tags provide a simple mechanism for pass-
ing a numeric value from one Phreeqc simulation to another as well as for providing the val-
ues of certain system variables which can be used for looping and other tasks. Tags can also be
used during the plotting phase to control text input and its positioning.
The order of evaluation of numeric tags (first to last) is:

system tags defined internally by PhreePlot (<x_axis>, <y_axis>,

<loop>, ...);

independent variables from the column headers in a loop or data file;

extradat file tags tags defined by a two-line (header and data) extradat file;
USER_PUNCH tags the names of the tags defined in the header line of the
SELECTED_OUTPUT file created in a Phreeqc USER_PUNCH data block within
the Chemistry Section. The values are those that were ‘PUNCHED’;
fit parameters from fitParameterNames and fitParameterValues as defined
in one of the input files, or after fitting (<R2> etc);
user-defined tags from numericTags in one of the input files defined in the
order the files and tags are read.

The input files are read in the order:

(i) the user-defaults file (pp.set)

(ii) the main input file (*.ppi)
(iii) the override file (override.set).

The tags should not be used until after they have been defined, e.g. if a tag is defined in the
second simulation, it should not be used until the third or later simulations). Substitution of
all tags takes place before execution of a simulation and so the values of tags created during an
execution cannot be used to update other tags that depend on the values created during that
execution. For example, USER_PUNCH tag definitions cannot refer to other USER_PUNCH tags
defined in the same simulation.
The input files can contain tag expressions which may themselves refer to other tags whereas
the system, user punch, and fit tags are generated automatically by PhreePlot and simply have
numeric values associated with them. In that sense, only the order of tags defined in the vari-
ous input files is of significance.
Tags can be used to pass numeric values from one simulation to a later one (this is also possible
using Phreeqc’s PUT/GET mechanism). For example, it may be wanted to subtract the initial
value of a calculated variable such as the pH from all subsequently generated pH values to find
the change in pH. This can be done by first generating the initial pH in a simulation. Send
this pH to the selected output using a USER_PUNCH data block and a column name such as
‘pHorig’. This will automatically generate a tag <pHorig> with the desired value which will be
stored for the duration of the run. In subsequent simulations, either write the new pH to the
selected output using a new column name such as ‘pH’ or generate the change in pH directly in
 PhreePlot input and output files 41

the USER_PUNCH data block (e.g. la(“H+”) - <pHorig>) and output this difference directly to
the selected output. In the first case, this will create a <pH> tag with a new value each time the
simulation is run. Use numericTags to subtract the two.
In order to see which tags have been defined and their values, set debug=1, 2 or 3 and enable
the log file (log TRUE). A list of the tags defined at each iteration and the values of all tags used
will then be written to the log file. These tables can be used to identify undefined tags.

5.3.9 Examples of the use of tags

The following example shows how user-defined tags can be used to manipulate the Phreeqc
input file when there are multiple simulations (ENDs) and when the early simulations prepare
for looping on the final simulation.
Adsorption is defined with the SURFACE data block and in one of its forms requires values for
the number of adsorption sites (in moles), the specific surface area (in m2 per gram) and the
mass of adsorbent (in grams).

SURFACE
surface binding-site name, sites, specific_area_per_gram, mass

In order to see how the amount of metal adsorption might vary in a system as the specific sur-
face area changes, it is reasonable in the first instance to assume a constant surface site density
(i.e. a constant number of sites per m2). For the weak sites of HFO, we have

isite = sdm/gfa

and

sdm = isite/isa

where

isite = initial number of sites (mol)

sdm = density of sites per mol HFO (mol/mol),
gfw = gram formula weight of HFO,
isa = initial specific surface area (m2/g),
sd = site density of sites (mol/m2)

and

m = mass (g).

So for any other specific surface area, sa, the number of sites (mol) is

site = sa*sdm*m.

This can be implemented by defining a series of numeric tags as follows:

<initial_site_density_w_per_mol> = 0.2 mol/mol Fe \
<gfw> = 89 g/mol \
<initial_site_density_w_per_g> = <initial_site_density_w_per_mol>/<molecular_wt> \
<initial_specific_area_per_g> = 600 m2/g

Note the structure is

<tag> = <tag_expression>

where the tag has a unique name (case significant), followed by an equal sign (spaces
optional), followed by an expression. The expression can contain other tag values provided
42 PhreePlot Guide

they have already been assigned a value.

Therefore

<site_density_w_per_m2> = <initial_site_density_w_per_g>/(<initial_speci-
fic_area_per_g>) \

and for any surface area and mass, we have

<surface_area> = 300 m2/g \

<mass> = 1 \
<sites> = <surface_area>*<site_density_w_per_m2>*<mass>

The final tag defines the number of sites as required by Phreeqc. The density of strong sites
can be defined similarly.
The Phreeqc input is therefore given as:

SURFACE 1
-equilibrate with solution 1
Hfo_w <sites> <surface_area> <mass>

In order to create a plot of the amount adsorbed vs surface area, <surface_area> must be
replaced by <x_axis> or redefined as such, and the amount adsorbed must be written to the
selected output file. An example that implements this procedure is given in Example 63.

5.4 OUTPUT FILES

The various output files are used internally for storing intermediate data as well as the data
actually used for plotting (and later replotting). The output files can be used to examine in
detail the Phreeqc output, the intermediate results generated by PhreePlot, or to export data
to other packages for further analysis or plotting. If the structure of the Phreeqc input file is
relatively straightforward, PhreePlot provides a quick way of looping through Phreeqc calcu-
lations that would otherwise be rather tedious to set up (see Section 6.2 and Example 71).
Phreeqc-type calculations can be made without generating any plot files by setting plotFactor
to 0.

5.4.1 Output files produced

The output is sent to a variety of files, most of which derive their names from the root of the
input filename with an added extension. For example, if the main input file for a ht1 or grid
calculation is C:\PhreePlot\demos\amd\amd.ppi, then the root is taken as
C:\phreeplot\demos\amd\ which will then produce a series of files with the general format

root_[mainspecies][loopIndex].ext

where root is the root, mainspecies is the name of the main species and is only included
when the number of main species is greater than one, loopIndex is the index value (1...nz) of
the loop variable and is only included when number of loop values is greater than one. ext is
the output file extension. Possible extensions are:

log log file (filename is simply <root>.log)

pts points file (boundary points, species distribution)
trk tracking file with output from each Phreeqc iteration
vec vector file for predominance and contour plots including the boundaries
pol polygon file for predominance and contour plots defining each field
ps Postscript graphics file, potentially multi-page (not eps)
eps encapsulated Postscript (eps) graphics file with bounding box suitable for
embedding in documents (single page only)
 PhreePlot input and output files 43

epsi encapsulated Postscript (epsi) graphics file with bounding box and a plat-
form device independent preview suitable for embedding in documents
(single page only)
pdf pdf (portable document format) file
png png (portable network graphics) graphics file
log log file containing details of run
lab editable labels file giving the position and orientation of labels in a pre-
dominance diagram. Edit and replot with calculationMethod 2 or 3.
out tabular output file with accumulated results from the SELECTED_OUTPUT
file used as input by some of the plotting routines.
all cumulative output from Phreeqc

All files are output as space or tab-delimited ASCII files. The first five of these files are mainly
for PhreePlot’s internal use and for debugging while the latter ones provide graphical and text
output for further analysis. The output from each file can be turned on or off using one of the
logical keywords assigned to the file type (Section 5.4.2).
Looping of the main species variable always produces a separate ‘out’ file for each value of the
main species variable.
With custom and fit calculations, looping of the z-loop variable produces a single ‘out’ file
with, by default, a blank line separating each value of the loop variable. This blank line can be
suppressed by setting the fourth entry in dataSeparators to the null string, “”.
Whether the corresponding plots are in separate files or not depends on the multipageFile set-
ting.
For example, assuming the multipageFile setting is set to FALSE and ps is set to TRUE, if there
are two main species, Fe and Zn, and two iterations of the z-loop variable, then the following
four files will be produced:

C:\phreeplot\demos\amd_Fe1.ps
C:\phreeplot\demos\amd_Fe2.ps
C:\phreeplot\demos\amd_Zn1.ps
C:\phreeplot\demos\amd_Zn2.ps

Other extensions are generated as appropriate. The log file in the example above will be called
C:\phreeplot\demos\amd.log.

If multipageFile is set to TRUE, a single file will be produced:

C:\phreeplot\demos\amd.ps

and it will contain all four plots in the order given above.
With custom and fit plots, only one plot file is produced even when the <loop> variable is
used. The results from the various loops are all plotted on the same plot with the labelling
(from the selected output file column headings or the labels keyword) appended with an
underscore and the loop number. This file has the same name as the multipage file above.
The file plot.ps is a copy of the last Postscript file generated and is always produced if a plot
is generated. It is also the name of the file generated as the temporary tracking plot file when
the ‘p’ key is pressed during predominance calculations (Section 6.6), or when the calcula-
tions are interrupted (‘Esc’) and then terminated (‘s’). Derivatives of the ps file under such
circumstances will be given the corresponding names such as plot.pdf, plot.eps etc.

5.4.2 The logical switches

Each output file has a logical switch associated with it (TRUE or FALSE). These are designed to
give the user some control over the number of files produced. In general, the output data
44 PhreePlot Guide

(text) files that are needed for plotting will be created whatever the value of their logical switch
and they will not be deleted by PhreePlot at the end of a run. This ensures that plots can be
edited and replotted without recalculating the underlying data. The most important switches
for the user to control are for the log and track files which can both be large and are informa-
tive rather than being essential for the plotting (except that the track file is used to replot a grid
plot).
Providing plotFactor is greater than zero, the following files will definitely be produced and
retained during the following types of plots: ht1 – points, vectors, polygons and labels; grid –
track; custom and species – output; fit and speciate – points and output. If any of these
files are deleted manually, then it will not be possible to carry out a ‘replot’; it will be necessary
to recreate them. Sometimes the files are created but nothing is written to them. This will
result in zero byte files.
The primary output data file produced by the ht1 method is the points file. The vector, poly-
gon and labels files are generated from this. These four files are all used to create the ps plot
file during plotting and replotting. If the ‘reprocess and replot’ method (calculationMethod 3)
is requested, then the calculations start with a pre-existing points file and recreate the other
files anew. This will regenerate all the label positions and if appropriate, rewrite the labels file.
This setting should be used when the yscale is changed. Replotting alone (calculationMethod
2) starts with all the existing data files including the labels file and then regenerates the plot
files. With this setting, editing the labels file can be used to move the labels.
The grid plot uses the track file as the primary data file. The custom and fit plots use the out-
put file. The fit plot also uses the points file.
Unlike the ‘data’ files, the plot files are all optional and the logical switch determines whether
they are created or not, or more specifically, whether they are retained at the end of a run.
There are some interactions amongst the various plot file type because the ps file is the pri-
mary plot file and is required in order to produce all the other graphic files using Ghostscript,
e.g if the settings are ps FALSE and pdf TRUE then the ps file will be created because it is neces-
sary in order to produce the pdf file but it will be deleted at the end of the run because the ps
switch was set to FALSE.

5.4.3 ‘log’ file (log)

The log file provides a log of the calculations performed and for monitoring progress. It is
most useful for debugging. The amount of information sent to the log file can be very large. It
increases as the debug parameter increases from 0 (small) to 3 (large). A copy of the main
input file (i.e. the file specified on the command line) is written to the log file. This includes
any comments. If the writeInputFiles switch is set to TRUE, then all input files are written to
the log file. This means all ‘include’ files plus the override.set file.

5.4.4 ‘out’ file (out)

The ‘out’ file accumulates the selected lines of output from the main selected output file (n =
1) and is used by custom plots for plotting. The format of the ‘out’ file depends on the task
being undertaken. In general, the output file contains the accumulated information sent by
Phreeqc to PhreePlot via the SELECTED_OUTPUT [1] file. This does not include all the lines in
the selected output but only those chosen by. By default, this is just the last line of the last sim-
ulation (assuming that this contains the chosen selected output block). It is assumed that ear-
lier lines are from unwanted intermediate calculations such as initial solution calculations.
No output file is created during a replot (or resimplify).
In fit mode, the output file is an accumulation of the selected output from each call to
Phreeqc, one line per data point. The order of the headings is dictated by the way in which
the SELECTED_OUTPUT data block was written but should definitely contain the dependent var-
iable (fitted value) and probably the independent variables (see the -headings line in the
USER_PUNCH block).
 PhreePlot input and output files 45

In ‘grid’ and ‘ht1’ calculations, the ‘out’ file contains a cumulative version of the data sent to
the selected output using a PUNCH statement. After a header line, the ‘out’ file has the following
format:
an ordered list of species name, species value pairs for each of the five species types
given below. The lists run consecutively one after the other. If there are no entries for a species
type, then nothing is written. The line ends with five integers which serve as counters for each
of the five lists. The five counters tell PhreePlot how many name-value pairs of each type have
been PUNCH’ed. They are used by PhreePlot to read the data and construct a predominance
diagram. The name-value pairs can be seen being set in the ht1.inc and ht1c.inc include
files.
In summary, the five counters are:

nout1 the number of candidate predominant solution/adsorbed/exchanged/

mineral species and their ‘concentrations’ PUNCH’ed. This can be any num-
ber but, after PhreePlot sorts them by concentration, only the largest
three at most are passed on for further consideration. At present, only the
largest two – the dominant and sub-dominant species – are actually used
by PhreePlot.
nout2 the number of mineral species and their concentrations PUNCH’ed – if one
or more minerals is actually stable and present, then when the stability cri-
terion is used. these will be sorted in terms of ‘concentration’ and the one
with the largest concentration will take precedence over all solution spe-
cies. This can be any number but, after PhreePlot sorts them by concen-
tration, only the largest three at most are passed on for further
consideration.
nout3 the number of constraints PUNCH’ed as name-value pairs – these may over-
ride the nout1 species (e.g. they can be used to impose the ‘water limits’).
This can be any number.
nout4 the number of ‘carry’ variables PUNCH’ed as name-value pairs – these are
numeric values that are not used in predominance calculations but which
you might want to examine for some other reason. These ‘species’-value
pairs are sent to the ‘out’ and ‘trk’ output files for viewing and are sum-
marised in the log file. The values are also added to the tag dictionary.
This can be any number.
nout5 the number of ‘system’ variables returned. This must be 5! Always in the
order: pH, pe, PO2(g), PH2(g), temperature (oC).

More details about the expected format of the selected output are given in Section 4.5.
With predominance and contour plots, a blank line is written to the ‘out’ file when no
selected output is produced when it should have been – e.g. when the speciation has failed or
when a calculation has been skipped because it is not in the calculation domain.

5.4.5 ‘track’ file (trk)

This records the results of each speciation calculation as performed for a predominance plot
(both ht1 and grid). It is generated from the selected output after species coding. The header
line and the first data line look like this:
n x y pe T step species1 isp1 species2 isp2 c1 c2
1 -12.0000 -85.0000 -12.4518 25.0000 -11 "H2(g) > 1 atm" -4 "Fe(OH)3-" 1 0.90370 -2.0100

n is the sequential number of the speciation calculation; x and y are the x- and y-values, pe is
the calculated pe, T is the temperature, step is the type of step being taken (see Section 3.2),
then the dominant and sub-dominant species (after any overrides have been applied) with
their names (species.), species code number and concentration (mol/kgw). These data are
46 PhreePlot Guide

normally echoed to the screen during execution.

The track file can also be turned on during fitting. It will contain a copy of the convergence
monitoring with the number of the function evaluation, value of the objective function (RSS)
and its logarithm, and a list of the current parameter values. If multiple fitting methods are
chosen, then the headers to the track file are subscripted with the names of the method, e.g
RSS_nlls, log10(RSS)_bobyqa, logK_nlls etc. This differentiates the results from different
algorithms for the purpose of plotting.

5.4.6 ‘points’ file (pts)

The format of the points file depends on what task created it.

Predominance plot calculations (ht1 only)

This records the results of calculating boundary positions (see Section 8.3.2). These points are
the raw data for calculating predominance diagrams. The number of points can be very large
(even while tracking a straight line) and so these data are subjected to simplification to reduce
the size of the file and to improve the appearance of the diagram. It is these simplified lines
that are written to the vectors file and then to the polygon file.

Other calculations

This is an ASCII file in space-delimited format. It is created by a ‘species’ plot and contains a
table of species suitable for plotting. This variables in this file are automatically added to the
search list of variables and so can be used explicitly for plotting.

5.4.7 ‘vectors’ file (vec)

This file is generated from the points file and it stores the boundaries of the fields in a ‘ht1’
predominance diagram as a series of vectors. The order of the vectors is determined by the
order of tracking. The individual polygons are assembled from this file, and coloured accord-
ingly. These vectors divide two fields. They are not drawn for the domain boundary. The file
looks like this:

250 1190 3562 16 25.00000000000 -0.9995420904108 0.2499810326136 20.79331349261

-12.00000000000 -83.30000000000 4 1 1 -12.04377661614
-12.00000000000 -83.12734375000 4 1 1 -12.00061311406
-10.74000000000 -83.13000000000 4 1 1 -10.74144424834
-10.74000000000 -83.13000000000 3 1 2 -10.74144424834
-10.74000000000 -81.77000000000 3 1 2 -10.40145620289

The first line contains the values of various system parameters that were in force when the file
was created: the resolution, the number of points in the points file, the number of times that
the speciation program was executed, the number of species recorded as dominant or sub-
dominant, the temperature of the last speciation and three numbers defining the relationship
between pe and the x- and y-axis variables.
The subsequent lines have the following columns:

x-value y-value species1 species2 vector_sequence_number pe

where x- and y-value are the x and y values, species1 and species2 are the integer codes for the
two species at the boundary, vector_sequence_number is the sequential number assigned to
the vector and pe is the calculated pe returned by Phreeqc. In a contour plot, the pe is
replaced by a distance parameter – this is a scaled distance reflecting the relative distance of the
point from the drawn line. It is a measure of the influence or importance of the point – large
distance means large influence.
A species code of 99 indicates a domain boundary.
This file is used in ‘ht1’ plots to draw the outlines of the predominance fields. Commenting
 PhreePlot input and output files 47

out or deleting lines from this file combined with calculationMethod = 2 can be used to omit
specific lines from the plot. This can be useful for removing domain boundaries (those that
include a 99 code) in a pe-pH plot.
A ‘vec’ file is also produced by a contour plot. It has a different header line but again the file
contains all the vectors needed to draw the contours and to assemble the polygons used for
colouring. It contains information about the type of boundary, normally the fields (class 1 and
class 2) differ by one but if they are the same, then this indicates a non-intersecting contour
(with the domain boundary) or ‘island’.
With contour plots, the order of the vertices is always written with ‘the high side to the right’
when reading down the file.

5.4.8 ‘polygon’ file (pol)

This file is generated from the vectors (‘ht1’ and ‘contour’) or track (‘grid’) files and is used to
colour-fill the polygons. It is also used to determine a default labelling position near the poly-
gon centre in predominance plots. It is assembled from the vectors file (‘ht1’ and ‘contour’) by
selecting the appropriate set of vectors for each field based on the ‘species’ involved and match-
ing the ends until polygon closure has been achieved. In grid plots, ‘pixel aggregation’ is used
to determine the polygon boundaries.
The header line includes the x- and y- resolution, the species code to which the polygon corre-
sponds (see the labels file for the full species name in predominance plots), the number of
points represented by each polygon segment, and the pe at each point. A species code of 99
stands for the domain boundary.
The pol keyword can be used to omit specified fields from a predominance plot.
Commenting out all the lines for a polygon can also be used to omit a particular polygon from
the plot providing calculationMethod = 2 is used. In ‘ht1’ and ‘contour’ plots, the lines out-
lining each field are drawn using the vectors file but in a ‘grid’ plot these outlines are drawn
using the polygon file.
If the value of sp (the species number) for all the points making up a particular polygon in the
‘pol’ file are less than or equal to zero, the field will not be drawn. It is necessary to edit the
‘pol’ file and replot (calculationMethod = 2) for this to work.

5.4.9 ‘labels’ file (labelFile)

This file is generated by predominance plots. It provides the dictionary to connect the species
number in the vector and polygon files with a species name. It also includes the angle of the
text. Editing this file provides the means of rotating a label.

This file is used to tell the plot where to centre the labels as well as providing a list of the spe-
cies names. It also includes other attributes of the label such as rotation (theta in degrees from
the horizontal measured clockwise). The pe is carried so that the labels can be placed properly
if the y axis is changed to pe or a derivative of that. This file can be edited manually to reposi-
tion or rotate the labels. A labels file looks something like this:
sp x y       pe angle   %area Species
#! -.999962564643800 .249990833525500 20.7964049901900 .999997920415700
5 -8.300 -32.338 4.406 0 61.62 Fe(OH)3(a)
1 -11.541 -81.218 -11.054 0 0.41 Fe(OH)3-
6 -4.789 -61.095 0.735 0 32.10 Fe+2
10 -2.371 -12.279 15.333 0 2.10 Fe+3
11 -2.854 -11.174 15.15 0 0.49 Fe2(OH)2+4
3 -10.189 -81.442 -9.75 0 0.25 FeOH+
9 -2.783 -22.242 12.454 0 0.00 FeOH+2
4 -6.990 -83.939 -7.177 0 2.49 H2(g) > 1 atm
13 -7.000 -0.212 13.745 0 0.50 O2(g) > 0.21 atm

The #! line gives the results of the estimated fit used to estimate pe when it is not available.
The fourth parameter is the goodness-of-fit (R2).Label size and colour are determined by the
48 PhreePlot Guide

labelSize and labelColor keywords. Individual labels and the colouring of their associated pol-
ygons can be removed by commenting out the appropriate lines in the labels file. Alternatively,
making the species number (sp) negative means the label will not be plotted. Setting the spe-
cies number to zero will plot the label and field but will not colour it. In order to not plot the
field or its label at all, use pol to exclude the polygon (see above) or edit the polygon file to
give negative species numbers. The minimumAreaForLabelling setting and editing of the area
field in the labels file can be used to omit a label, e.g. make the area negative and set minimu-
mAreaForLabelling to 0.1, say.
If labelColor is set to ‘nd’ or labelSize is set to 0.0, no labels will be plotted.
A species can have more than one label if it occupies more than one distinct field. The order of
the labels is important and corresponds with the order that the polygons are read from the pol-
ygon file. This should not be changed.
Species names may be changed by editing this file and replotting with calculationMethod 2.
Species names are assumed to be in Phreeqc formula format and numbers will be sub- and
super-scripted accordingly. The species names can be appended with an identifier which will
not be sub- or super-scripted. This should follow the species name and be preceded by an
underscore. In order to allow surface species to still be interpreted correctly, the following rules
apply: the identifier will not be subscripted if it is 3 or less characters long, or if at least one
other underscore precedes it, e.g. the numbers in the identifiers for Cd+2_1 or Cd+2__A2014
(two underscores) will not be subscripted whereas the charge in Hfo_Cd+2 will be super-
scripted.
Possibly the easiest way of moving labels is to use a ‘nudge file’. This can be used for all plots.

5.4.10 Other output files

Various other files are produced, some of which are temporary files and normally deleted, oth-
ers are left in the file system for perusal.

plot.ps this is always a copy of the last ps file produced (and the
name of the tracking file optionally produced during calcu-
lations)
selected_1.0.out this is the default name of the file containing the last
SELECTED_OUTPUT returned by Phreeqc when ABS(debug)>0
(it is continually being overwritten with new data). Other
file names can be set using the SELECTED_OUTPUT -file
identifier in the CHEMISTRY section.
Phreeqc.out this is the normal PRINT output from Phreeqc for the last
iteration when ABS(debug)>0
*.all this is an accumulation of the normal PRINT output from
Phreeqc for all iterations and is only produced when
ABS(debug)>1 or when the all keyword is set to TRUE. It con-
tains end-of-file (Control-z) characters at the end of each
iteration’s output. This file can be very large which may
prove problematic when opening with some editors.

Whether the latter two files are produced or not is controlled by the debug keyword and pos-
sibly the value of resolution.
If the two colour dictionary files are undefined and needed, then the files lineColor.dat and
fillColor.dat will be automatically created in the working directory, i.e. the same directory
as the main input file. Note that since the label positions are recorded in the line colour dic-
tionary, it may be important that each problem run from the same directory is given a differ-
ent dictionary name.
Some other temporary files may be produced during a run. These are normally deleted at the
 PhreePlot input and output files 49

end of the run.

5.5 INSERTING PLOT FILES INTO MICROSOFT WORD, POWERPOINT AND OTHER
SOFTWARE

The information given below is likely to vary with the version of the software being used, and
will in any case age quickly, so treat this as a starter and experiment yourself. Amazingly, the
situation in 2017 has not improved much and you really will have to see what works for you.
Unfortunately, the eps format seems a moving feast and generally does not transfer well. If you
can afford Adobe Illustrator, then this is a good way of editing ps/eps files, and saving to a
format which will be able to be imported into most documents. At the moment, probably the
simplest approach to import a diagram into a document without resorting to other software is
to export from PhreePlot in the png format, and then clip it.
Graphic files in various formats can in principle be imported into office software such as
Microsoft Word and Open Office/LibreOffice. The filters available depend on the versions
used. With Word 2002 and later versions of Word, Postscript (ps) and Encapsulated Post-
script (eps and epsi) files can be imported with Insert|Picture|From file. You will have to
change the ps and epsi files to have the eps extension for this to work or prepare an eps file
directly (this will be clipped tightly to the image’s bounding box). They must be single page ps
files of course. These files all have a preview when viewed in Word.
png and jpg files can also be imported directly into most Office-type documents in the same
way but they will not normally be of such good quality as the Postscript files since they are bit
maps rather than vector-based and so will not scale so well.
The eps and epsi files will be cropped, the other formats will not be. These other format files
can either be cropped with image editing software such as IrfanView, or the cropping done
directly on the imported file in Word by specifying the crop parameters (Format|Picture).
If all else fails, the ps or epsi files can be converted to high resolution jpg files using GSview -
you will have more control over the resolution this way than is available when these files are
generated in PhreePlot.
Rather than importing the files into Word on a one-off basis, the ‘pictures’ can be linked to a
particular file using the ‘Link to file’ option available on the Insert drop-down menu. This
inserts an INCLUDEPICTURE field code into the document and reduces the document size since
the actual code for the image is no longer included in the file. The file is automatically
updated in the Word document when the file is reopened or when the fields are updated
(Cntrl-F9). The link file name can be viewed by viewing the field codes (Alt-F9).
Using the ‘Insert and Link’ option when importing will insert the code for the picture and link
it to the file for updating. This results in a larger document size than linking alone.
Probably the best format for importing into Word in terms of quality, size and convenience is
the eps format but you will have to experiment.
Powerpoint is not able to render Postscript files. Probably the best format for inserting into
Powerpoint is png. If all else fails use high resolution jpg. If the default resolution of the png
file produced by PhreePlot (300 dpi) is not what is wanted, change the resolution using the
second png parameter.
Many of the graphic formats exported by PhreePlot can also be imported into Open Office/
LibreOffice documents. For example, Insert|Graphics|From File will import eps. png, jpg
files. These files can also be either imported into the document or linked to it, as in Word.
Cropping is also possible. png files are often the easiest to import and of reasonable quality.
Open Office/LibreOffice does not provide a preview for eps files and the output needs to be
printed using a printer with a Postscript interpreter otherwise only the placeholder will be
printed. If you do not have a Postscript printer available and do not already have a generic
Postscript printer driver installed, install such a printer driver (e.g. in Windows 7, Control
Panel | Hardware and Sound | Add a printer | Add a local printer | Use an exist-
50 PhreePlot Guide

ing port: FILE | Lexmark | C935 PS (MS)) (or any other good coloured Postscript printer
driver). Then select this ‘printer’ when printing, and name the file as a ps file. This will pro-
duce a ps file that can then be read, converted and printed to paper with GSview etc.
If the graphic files need to be edited, Adobe Illustrator or Inkscape or other suitable vector-
based software can be used. Inkscape is vector-based (based on the SVG format) and is versa-
tile, modern and free. Many software suites (e.g. Microsoft Office and Open Office/LibreOf-
fice) can now import pdf files. GIMP is free and powerful but is raster-based. There are also
many ways of merging pdf files including use of Adobe Acrobat and Cloud-based methods
(e.g. http://www.mergepdf.net/). Slideshows can also be prepared using Adobe Acrobat which
means that pdf files can be used directly for presentation.
The vector-based quality of Postscript files should be retained for as long as possible and text
should be kept as text rather than bit-mapped. Software that allows insertion of eps/pdf files
directly will normally retain the highest quality.

5.6 SPEED OF COMPUTATIONS AND PLOTTING

The speed with which calculations and plotting take place clearly depends on the processing
power available and the number of computations undertaken. It also depends on certain set-
tings that are under user control. Normally most of the time is taken up within Phreeqc so
particular attention should be taken to the Phreeqc setup.
The following tips might help speed up computations:

reduce the number of species considered: the speed of Phreeqc computations depends
strongly on the number of pure phases present. These are defined in the EQUILIBRIUM_PHASES
keyword block. Reducing the number of phases being considered will reduce the computation
time required. For example, phases that are obviously not going to feature in the calculations
can be removed from consideration. The same is probably true to a lesser extent for the num-
ber of solution species. Reducing these will involve either changing the database used, or not
including them as species in the EQUILIBRIUM_PHASES keyword block. With predominance
diagrams, the ht1minerals.inc file (Section 8.1.6) can be used to monitor the saturation
indices (SI’s) of all the possible minerals using the ‘carry variables’ approach. The summary
statistics for these SI’s are written to the log file. If the maximum value is zero or very close to
it, then this indicates that the mineral has precipitated somewhere in the calculations.
reduce the resolution of the plot: this will reduce the number of calculations under-
taken at the expense of the smoothness and maybe the accuracy of the plot. Once the plot is
what is wanted, the resolution can be increased for a final, production plot.
alter the KNOBS settings: these do not normally need to be adjusted but they can
affect the speed with which Phreeqc converges (and even if it does converge) and so may be
important in certain cases (see Section 6.5.5 and Section 8.12). Their impact may vary with
the different versions of Phreeqc due to changes in the solution finding strategy.

The structure of the Phreeqc library used by PhreePlot has not be optimised for carrying out
the types of calculations often done with PhreePlot. For example, successive calculations are
often similar to each other with just a minor difference. However, Phreeqc starts from essen-
tially the same starting point each time. Sometimes ‘setup’-type calculations can be taken ‘out-
side the loop’ by making use of the END keyword to separate setup code from the looping code.
 Running PhreePlot 51

6 Running PhreePlot

6.1 CONVENTIONS FOR DATA INPUT

6.1.1 Types of variables

Each keyword has an associated value or list of values associated with it. These can be of four
types as given in Table 6.1

Table 6.1. Examples of how a Phreeqc column heading will be interpreted during plotting

Input Graphical output Examples

Integer (I) Integer -1, 0 1, 123
Floating point num- Non-integer numbers. Range allowed depends
ber (F) on storage type: usually stored as IEEE ‘dou-
–1.0, 1.23, 1e–5
bles’ (=xxx to +***) but plotting parameters are
stored as ‘singles’, *** to +**
Logical (L) Logical value TRUE, FALSE, true, false, t, f, T, F
Alphanumeric (A) Strings consisting of the following characters:
(0–9, a–z, A–Z, (space),!”%^&*()_+[]:;<>?/
Enclose strings in single or double quotes if
1, A, abc, “two words”, ‘three small
they include a space. If the string is enclosed in
words’, “C:\Program Files\PhreePlot\Sys-
square brackets, these are removed and the rest
tem\color.dat”, “” (null string)
of the string is taken literally, i.e. not inter-
preted.
The following are not allowed: £$¬!|\@

6.1.2 Phreeqc notation for chemical formulae

Phreeqc has a super/subscript-free way of specifying chemical formulae (Table 6.2) and this is
used by PhreePlot to interpret formulae strings when labelling plots.

Table 6.2. Examples of various chemical formulae in Phreeqc format

Conventional formula or name Phreeqc format PhreePlot

B B B
Br– Br– Br–
SO42– SO4-2 SO42–
Ca 2+ Ca+2 Ca2+
CaSO4.2H2O CaSO4:2H2O CaSO4.2H2O
FeS1.7 FeS1.7 FeS1.7
(CH3)2COOH (CH3)2COOH (CH3)2COOH
Hg 0 Hg0 Hg0
Phenanthroline Phenanthroline Phenanthroline
HFO_s Hfo_s Hfo_s
Fe(3) Fe(3) Fe(3)
18 O [18O] 18O
As(V) [As5] As5
52 PhreePlot Guide

PhreePlot assumes that some of the character strings (e.g. species and labels) used in
PhreePlot may represent formulae in Phreeqc format and attempts to translate them accord-
ingly. The places where this occurs are listed elsewhere (Section 10.1).
This interpretation of strings as formulae can be turned off by setting convertLabels to FALSE.
This setting applies to all strings. A second, optional logical switch to convertLabels controls
the conversion of colons when the Phreeqc conversion is true. This controls whether
ZnCO3:H2O is converted to ZnCO3.H2O (TRUE) or to ZnCO3:H2O (FALSE).

6.2 PHREEPLOT LOOPING

6.2.1 Loop variables and their use

Looping, or iteration, is at the centre of PhreePlot. The other important feature is the separa-
tion of Phreeqc simulations into pre-loop and main loop simulations (see Section 4.6.1).

There are four loop variables available in PhreePlot and these operate in a nested fashion with
the outer loop going round most slowly. These loops and their tag names are as follows:
Outer loop: main species loop (<mainspecies>)
z-loop (<loop>)
y-axis loop (<y_axis>)
Inner loop: x-axis loop (<x_axis>) (most rapidly changing)

The ‘main species loop’ loops on a list of character strings (each up to 30 characters), typically
element names, but it can be any character string that requires substitution.
The y-axis loop and x-axis loops are set internally to loop over the specified y- and x-axis
ranges, ymin to ymax and xmin to xmax, respectively, with the intervals of both controlled by
the same resolution keyword. The resolution gives the number of Phreeqc iterations used. So
if calculations are wanted over an x-range from 0 to 10 inclusive in steps of 1 then xmin = 0,
xmax = 10 and resolution = 11. If xmax = xmin then no looping is undertaken. resolution = 1
signals some special behaviour. The y-variables are defined in exactly the same way. The pre-
loop simulations are executed once and only the main loop simulations are looped.
The z-loop is controlled in several ways, most simply by the keywords loopMin, loopMax,
loopInt and loopLogVar. These generate a regular sequence of numeric values for the <loop>
variable. Alternatively the <loop> variable can be set to any discrete set of values, including an
irregular series, using loopFile. The loop file approach also provides a mechanism for carrying
varying values of other variables in parallel for each z-loop iteration including character varia-
bles. The z-loop iterates on both the pre-loop and main loop simulations.
Note that the x- and y-axis tag names use underscores not hyphens. The x- and y-axis loops are
used in predominance plots where movement along both axes is required. The resolution in
both dimensions is always the same in these types of plot. This arrangement is rarely useful in
custom plots. Here it is more common to use the x-axis loop to drive the principal independ-
ent variable, like pH, and the z-loop to alter some other factor or ‘level’ in a systematic way.
The main species loop produces a new plot for each species. These may or may not be in the
same file depending on the multipageFile setting.
The z-loop either produces a new plot for each value or introduces a blank line in the ‘out’ file
every time its value changes. This gives a break in the plotted line at each of these changes.
Whether or not a new file is produced or a blank line is introduced depends on the type of
plot and the customLoopManyPlots setting. A new plot file will always be produced for spe-
cies plots.
In plots other than predominance plots, the y-loop should normally be left undefined and
unused.
In summary, by default, a blank line is inserted in the output files for each iteration of the
 Running PhreePlot 53

<loop> variable. This results in a break in the plotted curve. This does not happen with the
<x_axis> or <y_axis> variables. The <x_axis> and <y_axis> variables are primarily designed for
continuous variables whereas the <loop> variable is primarily designed to loop over discrete
values of a variable. This difference is not rigid but there are some differences in the output
that reflect this motivation.
For example, in predominance plots, the z-loop can be used to loop over a discrete range of
concentrations of the main species. The z-loop variable can be specified with the loopMin,
loopMax, loopInt and loopLogVar keywords. The loopLogVar keyword is used to signal
whether to loop over a linear (0) or log (1) range of z-values.
z-looping can be used to repeat Phreeqc calculations in which just one or two parameters are
changed between runs, such as the pH. The custom plot option is used for this.
These built-in looping mechanisms always generate a regular sequence of values. If an irregu-
lar sequence of loop values is needed, or if more than one loop variable needs to be changed on
each iteration, use loopFile with calculationType = ‘custom’ or a data file with calculationType
= ‘simulate’. If a non-blank loop file name is set, the values in this file take precedence over
the loopMin etc keyword settings. An important difference between these two approaches is
that the loopfile approach will repeat the pre-loop iterations whereas the simulate approach
does not.
Phreeqc also has its own internal looping mechanisms, for example with the REACTION and
KINETICS blocks, and also to some extent with SOLUTION_SPREAD.

An example of the simulate approach is given below and in the calculation of saturation indi-
ces for a batch of water samples (see the SIs example in the \demo\SIs directory).

6.2.2 Looping over a list of character variables

The 3-parameter z-looping mechanism discussed above is designed to loop over a range of
numeric values. If you want to loop over a list of character variables, either use a loopFile with
character columns or in simple one-variable cases, use the mainspecies loop (even if the varia-
bles involved are not actually ‘species’).

6.2.3 An example of the use of various looping mechanisms

A series of examples described below shows how the various looping mechanisms can be used
to calculate the solubility of iron oxide as a function of pH in a fluoride-rich medium. These
examples highlight the different setups that can be used to implement looping in PhreePlot.
These examples can all be found in the demo\FeSolubility directory.

Using the <x_axis> tag

The first example uses the <x_axis> variable. The input file (FeSolubilityXaxis.ppi) is:
SPECIATION
calculationType “custom"
calculationMethod 1
xmin 2
xmax 12
resolution 101
numericTags <log_H> = -<x_axis>
PLOT
plotTitle "Fe(OH)3(a) solubility vs pH"
xtitle "pH"
ytitle "log₁₀ Fe_T (mol/kgw)"
pymax 0
customXcolumn 1
lineColor blue
useLineColorDictionary 0
legendTextSize 0
label 0

CHEMISTRY

PHASES
Fix_H+; H+ = H+; log_k 0
54 PhreePlot Guide

Fe(OH)3(a) solubility vs pH
(using a x_axis tag)

-2

log10 FeT (mol/kgw)

-4

-6

-8
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Fesolubility\Fesolubilityxaxis.ps

Figure 6.1. Amorphous iron oxide solubility as a function of pH calculated using the
<x_axis> loop variable.

SELECTED_OUTPUT
reset false

USER_PUNCH
headings pH FeT_
10 PUNCH -la("H+"), log10(TOT("Fe"))

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
Na 1e-1
F 1e-1
EQUILIBRIUM_PHASES 1
Fix_H+ <log_H> NaOH 10
-force_equality true
O2(g) -0.677
Fe(OH)3(a) 0 0
END

The range of the <x_axis> variable is given by xmin and xmax. The span in pH is 10 units and
the resolution is 101 so calculations will be made at <x_axis> values of 2.0, 2.1, 2.2...12.0.
The <y_axis> variable has been left undefined (here and in the other input files) and so is
unused.
The <log_H> tag is defined as the negative of the <x_axis> variable so that it can be substituted
on the Fix_H+ line. This is the only tag used within the CHEMISTRY section.
The plot produced from this file is shown in Figure 6.1. Exactly the same plot can be pro-
duced by using the <y_axis> variable in place of <x_axis>.
The useLineColorDictionary setting of 0 means that the line colour dictionary is ignored as a
source of line and point colours or label coordinates, even if they are present in the dictionary.
Rather auto colouring is used starting with the colours given in the lineColor setting (here set
as blue). The colour dictionary is always created if absent or updated if present with the latest
colours and coordinates.
 Running PhreePlot 55

Using the <loop> tag

Exactly the same plot can be produced using the <loop> variable. This requires several changes
to the SPECIATION section but none to the sections following that. The modified input is
shown below:

SPECIATION
calculationType "custom"
calculationMethod 1
loopMin 2
loopMax 12
loopInt 0.1
numericTags <log_H> = -<loop>
dataSeparators "\" "\t" "\p" "" “\r” “”

The two main differences are that loopMin, loopMax and loopInt replace xmin, xmax and
resolution. The fourth data separator must also be redefined to remove the blank line that
would normally be placed after each iteration of the <loop> variable. It is set to the null sep-
arator which means that no new line (paragraph) is put between each iteration. Since blank
lines in the ‘out’ file are interpreted as line breaks when custom plotting, without this change
to the data separator, 101 separate lines would be plotted rather than a single curve.
This is why it is normally preferable to use the <x_axis> approach for continuous variables and
to leave the <loop> variable for defining discrete intervals or levels of a variable.

Using a loop file

It is also possible to read the 101 values from a loop file. The name of a loop file needs to be
given and the dataSeparators may need to be redefined. The input is:

SPECIATION
calculationType "custom"
calculationMethod 1
loopFile FeLoop.txt
numericTags <log_H> = -<loop>
dataSeparators "\" "\t" "\p" "" “\r” “”

The FeLoop.txt file looks like this:

#pH
2.0
2.1
2.2
2.3
...
12.0

It has 101 rows of data with a comment at the top which is ignored. This gives the same plot
as in Figure 6.1.

Using the ‘simulate’ calculationMethod

This method also reads the data from a file, this time the file specified by the dataFile key-
word. The relevant part of the input file looks like this:

SPECIATION
calculationType "simulate"
calculationMethod 1
dataFile FeSimulate.txt
logVariableIn 0
dependentVariableColumnCalc 2
numericTags <log_H> = -<pHin>
...
customXColumn 3

The FeSimulate.txt file looks like this:

56 PhreePlot Guide

pHin
2.0
2.1
2.2
2.3
...
12.0

Note that as for the loop file, this file has a header row which define a series of tags, one per
column. While the header row is optional for the loop file, it is compulsory for this data file.
Here the <pHin> tag is defined which is used in the definition of <log_H>. The logVariableIn
keyword (a list of 0, 1 or -1’s) must also be included to indicate the number of columns in the
data file and whether any data transformations are required. Here, a single 0 indicates one col-
umn without any transformation on input.
It is also necessary to define where the dependent variable (the calculated value) is to be found
in the main selected output file - this is done with the dependentVariableColumnCalc key-
word. The customXcolumn also has to be set. This is the only plot type that uses the ‘pts’
file rather than the ‘out’ file, for plotting and this file has a slightly different format from the
‘out’ file consisting of the line number from the input file, calculated values and all of the var-
iables read in from the data file - whether they were used or not.

Looping over two variables

It is also possible to plot several curves on the same plot by using two looping variables. a line
break is normally The following file (FeSolubilityXaxisLoop.ppi) does this:

SPECIATION
calculationType "custom"
calculationMethod 1
xmin 2
xmax 12
loopmin -4
loopmax -1
loopint 1
looplogvar 1
resolution 101
debug 0
numericTags <log_H> = -<x_axis>
PLOT
plotTitle "Fe(OH)3(a) solubility vs pH"
xtitle "pH"
ytitle "log₁₀ Fe_T \
(mol/kgw)"
labels "10^-4M F" \
"10^-3M F" \
"10^-2M F" \
"10^-1M F"
pymax 0
customXColumn 1
linecolor blue
useLineColorDictionary 0
legendTextSize 2
label 1.5

CHEMISTRY

PHASES
Fix_H+; H+ = H+; log_k 0

SELECTED_OUTPUT
reset false

USER_PUNCH
headings pH FeT_
10 PUNCH -la("H+"), log10(TOT("Fe"))

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
 Running PhreePlot 57

Fe(OH)3(a) solubility vs pH
(using x_axis and loop tags)

0
Fluoride
10-4M F
10-3M F
-2 10-2M F

log10 FeT (mol/kgw)

10-2M F
• 10-1M F

-4
•
10-1M F

-6 •
10-4M F
10-3M F•

-8
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Fesolubility\Fesolubilityxaxisloop1.ps

Figure 6.2. Amorphous iron oxide solubility as a function of pH and NaF con-
centration calculated using the <x_axis> and <loop> variables.

Na <loop>
F <loop>
EQUILIBRIUM_PHASES 1
Fix_H+ <log_H> NaOH 10
-force_equality true
O2(g) -0.677
Fe(OH)3(a) 0 0
END

This is similar to the other files but has the <x_axis> tag to drive the x axis (pH) and the
<loop> tag to drive the variable Na and F concentrations. The <loop> or z loop adds a blank
line at the end of each iteration. These are interpreted as line breaks by the custom plotting
routines which then plots them separately with different line colours (Figure 6.2). The labels
keyword provides a list of names to use for labelling the curves and producing the legend.
If a separate plot is wanted for each value of the z-loop variable in a multiple-z value custom
plot, set customLoopManyPlots to TRUE. There are also additional parameters to choose
whether to append the loop index to label names in order to enable curves to be distinguished
in multi-loop plots.

6.2.4 Looping in multi-simulation input files - pre-loop simulations and the main loop

Introduction

Decisions had to be made about how PhreePlot would deal with multi-simulation input files,
i.e. those with more than one END keyword (assuming the file finishes with an END). In princi-
ple these files can be of any degree of complexity and can include completely unrelated simu-
lations.
Two aspects had to be considered.
Firstly, which simulations are repeated and which are not. There is obviously a time and clut-
ter penalty in repeating invariant operations that do not have to be repeated such as reading in
a database. This led to the concept of pre-loop (once only) simulations and main loop
58 PhreePlot Guide

(repeated) simulations.
Further, when several simulations need to be run, should they be fed to Phreeqc one at a time
or all together. PhreePlot can only update tags and make substitutions to the input file when
control is returned to itself between runs.
Secondly, which results of the various simulations are picked up and sent to the various
PhreePlot files ready for fitting, plotting etc. Some simulations produce no useful output
while others produce one or more lines of useful output.
The format of the output produced by a given block of code can depend on whether the sim-
ulations are executed one-at-a-time or in a single run.
Controlling these aspects of the input and output is the key to running PhreePlot successfully.

Basic structure of a multi-simulation Phreeqc input file

Each Phreeqc simulation in an input file is numbered consecutively from the top down, 1, 2,
3, ... A multi-simulation input file can be viewed as a series of one or more contiguous simula-
tions or ‘blocks’ of simulations. A block of simulations is therefore defined by a range of simu-
lations.
In many cases, PhreePlot considers the input file to be a single block but it can also be treated
as a series of unrelated blocks. This is possible with the ‘fit’ and ‘simulate’ types of calcula-
tions where each line of data (each ‘observation’) in the associated data file can point to a dif-
ferent block of Phreeqc code.
Each block is itself treated as having two parts: (i) the top part consists of zero or more ‘pre-
loop’ simulations, and (ii) the lower part consists of one or more ‘main loop’ simulations.
The innermost two PhreePlot loops (the y- and x-axis loops) act only on the main loop simu-
lations. This division between the two is designated by the mainLoop setting which is the
number of the simulation in the block starting counting from the top of the block, i.e. the
starting point of the looping.
The default is ‘last’ which automatically sets mainLoop to the number of the last simulation
in the block. Setting mainLoop to 1 would mean that all the simulations in that block are
treated as main loop simulations.
Much of this behaviour is hidden when running PhreePlot in normal mode but setting debug
to 1, 2 or 3 will cause more or less of the calculation trail to be written explicitly to the log file.
The following decisions were made based on the calculationType.
For custom, species and predominance-type calculations, it is assumed that the Phreeqc input
file is written to perform a single set of calculations and consists of zero or more initial simula-
tions to set up the database, do initial solution calculations, and to define other static settings.
This is then followed by one or more simulations which will be subject to the y- and x axis
PhreePlot looping mechanisms. Any simulation which contains a tag which is expected to
change on each iteration must be in this latter block. This division into ‘pre-loop’ and ‘main
loop’ simulations is specified with the mainLoop keyword which specifies the number of the
Phreeqc simulation at which the main loop starts.
In a multi-simulation input file, PhreePlot looping only applies to the simulations numbered
from mainLoop onwards. The simulations before this are assumed to be ‘pre-loop’ simula-
tions. Each of these pre-loop simulations is run individually and the tag dictionary updated
between runs (Figure 6.3). This means that tag variables can be passed from one simulation to
the next in these pre-loop simulations.
The ‘main loop’ iterates as rapidly as possible over the y-axis and x-axis loops. This loop runs
with minimum overheads and is intended for the most repetitive calculations. All simulations
in this main loop are run as a single Phreeqc run so there is no possibility of using tags created
in one simulation in the next. The tags are updated just once then the whole block of simula-
tions is executed.
 Running PhreePlot 59

loopSimulationStartNumber = 3 loopSimulationStartNumber = 4

mainspecies loop

z-loop
#Simulation 1 #Simulation 1
'Pre-loop' simulations ... ...
Run these simulations END* END*
separately for each combination
of the z- and mainspecies loops #Simulation 2 #Simulation 2
'Pre-loop' simulations
... ...
Run these individually
END* END*

#Simulation 3 #Simulation 3
'Main loop' simulations ... ...
Run these simulations together END END*
as one 'run' for each
combination of the #Simulation 4 #Simulation 4
x- and y-axis variables ... 'Main loop' simulation ...
END* END*

* = write selected output and update tags here

Figure 6.3. Two examples to illustrate how the mainLoop defines the division between ‘pre-loop’ simulations and the
‘main loop’ simulations in which the x- and y-axis variables operate. In this example, the difference controls the number of
times simulation 3 is run and consequently when selected output is normally written to the ‘out’ file and the tags updated.
The default (‘last’) is for the mainLoop to only loop over the last simulation, as illustrated on the right. The ‘pre-loop’
simulations are each run separately and sequentially. In contrast, the ‘main loop’ simulations are run as a single block with
no updating of tags between simulations.

The earlier (‘pre-loop’) simulations are re-run for each value of the main species and z-loop.
The default value for mainLoop is ‘auto’ which sets mainLoop to the number of simulations
found in the input file, i.e. it means that looping will only take place over the last simulation.
Care needs to be taken with the selected output when looping over more than one simulation.
A USER_PUNCH data block entered in simulation 1 say will remain active in subsequent simula-
tions unless specifically turned off with the -selected_output identifier in the PRINT data
block. If the USER_PUNCH data block is redefined in later simulations then the output may
become confusing since a new header line is not written to the ‘out’ file.
With multi-simulation input files, selectedOutputLines controls the amount of selected out-
put actually sent to the ‘out’ file. The number specified refers to the number of lines sent from
the SELECTED_OUTPUT in the chosen simulation (the SELECTED_OUTPUT block with the highest
user number).
One advantage of arranging for a block of simulations to be in the main loop rather than in
the pre-loop is that it involves fewer overheads than calling Phreeqc separately for each simu-
lation. However, some calculations only need to be carried out once and so are best put in the
pre-loop section.
The ‘out’ file is often used directly for plotting and the challenge is to end up with a well-
formed file suitable for plotting. Normally this should be a rectangular table with a header row
and columns of data possibly with blank rows to signify breaks in the data.
The exception to the above behaviour is during fitting and simulations. The ‘fit’ and ‘simu-
late’ calculationTypes do not allow looping since they use multi-simulation files to allow for
the possibility of doing different calculations for each data point (observation) or set of data
points. Each data point can in principle choose its own range of simulations and its own
mainLoop parameter. This makes it possible to optimise over a number of different types of
calculations within the same fit (‘global optimization’). The simulation or range of simulations
to be used for each point is specified in a special column in the fit data file, the mainLoopCol-
umn. Weighting of the residuals becomes a particularly important consideration when mixing
60 PhreePlot Guide

‘apples and oranges’ in this way.

6.2.5 Dynamic switching between Phreeqc models (code)

It is sometimes necessary during looping to switch between different pieces of Phreeqc code
to obtain the required output. This switch may reflect the results of an earlier simulation or
the value of some tag variable.
The most flexible approach is to engineer for a tag to be the 'switch' tag and to then use this in
the USER_PUNCH code to calculate what is required and to send the required output to the
selected output. This can often be made possible using the 'one simulation at a time' mode
(see mainLoop) based on the fact that in this mode USER_PUNCH'ed output from intermediate
simulations is automatically turned into tags which can then be used in subsequent simula-
tions. Furthermore, this intermediate output does not get copied to the 'out' file and so will
not interfere with the output used for plotting or fitting. So a simulation can calculate some-
thing, punch a switch value to the selected output and then the next simulation can make the
switch accordingly, perhaps even repeating the previous simulation with slightly different
input or output.

6.2.6 Defining the expected output in the selected output file

Use selectedOutputLines to define the number of lines (rows) to be read from the output
defined by the targeted SELECTED_OUTPUT (n)/ USER_PUNCH (n) block, counting lines from
the bottom upwards. Set to 1 to pick just the last line, 2 to pick the last two line etc., or ‘auto’
to pick all lines. During fitting, the number of lines picked will automatically be set to 1 when
onePass is FALSE and to that given by the number of observations in the fit data file when one-
Pass is TRUE.
If the selectedOutputLines value is 0, no data transfer will take place. This option can be used
when PhreePlot is used to produce some other output file such as a print file.
In order to accumulate output from all the simulations in one input file into a single selected
output file (and ‘out’ file), set mainLoop to 1 and put the SELECTED_OUTPUT (n)/ USER_PUNCH
(n) block in the first simulation. This ensures that all the simulations will be run in a single
run and so forces the accumulation of all output data into a single output file. Don’t use any
other looping mechanism, i.e. just loop through the whole set of simulations once. However,
note that tags will only get updated and substituted once at the beginning of the run.
It may be necessary to define a ‘break variable’ to force the plotted curves to break between
simulations. This can be done with the sixth parameter of the dataSeparators keyword. When-
ever the break variable is encountered, a blank line is sent to the outfile.

6.2.7 Timing execution

It can be useful to see the difference between execution times for different iterations. This can
be done by making use of the <systime> system tag. This is initialised to zero at the beginning
of a PhreePlot run and returns the cumulative time in seconds for each iteration thereafter. It
can be accessed using this tag in the USER_PUNCH section. The time taken for each iteration can
be calculated by using the PUT/GET mechanism to save the time of the previous iteration and
subtracting it.
For example, in a custom plot add code something like
-headings nexecute time dt
100 IF (EXISTS(1)=0) THEN PUT(0,1)
200 dt = <systime> - GET(1)
300 PUNCH <nexecute>, <systime>, dt
400 PUT(<systime>,1)

and monitor in the ‘out’ file. For a predominance plot, add something like the following as
‘carry’ variables in the ht1.inc (or similar) file.
 Running PhreePlot 61

295 IF (EXISTS(1)=0) THEN PUT(0,1)

296 dt = <systime> - GET(1)
297 PUNCH "nexecute", <nexecute>, "time", <systime>, "dt", dt
298 PUT(<systime>,1)
299 nout4 = 3

and monitor in the ‘track’ file (trk T). If a plot of this timing is wanted, set up another ppi file
something like

PLOT
extradat hfo.trk
customxColumn nexecute
lines dt
labelsize 0
legendtextsize 0
xaxislength 150

and execute the two together with a batch file.

6.2.8 Speeding-up calculations

Sometimes calculations are noticeably slow because the initial solution calculation is a poor
estimate of the final solution. In these cases, it may be possible to speed-up calculations signif-
icantly by saving the result of the last calculation and using it as a starting point for the next
calculation. This makes use of one or more of the ‘_MODIFY’ Phreeqc keywords.
A typical scenario for preparing a predominance diagram would be:
# simulation 1 - preloop, once only
SOLUTION 1
....
EQUILIBRIUM_PHASES 1
Fix_H+ -7 NaOH
-force_equality true
O2(g) -45
-force_equality true
...
SAVE SOLUTION 2
SAVE EQUILIBRIUM_PHASES 2
END

# simulation 2 - main loop, iterate here

USE solution 2
USE equilibrium_phases 2
USE surface 2
EQUILIBRIUM_PHASES_MODIFY 2
-component Fix_H+
-si -<x_axis>
-component O2(g)
-si <y_axis>
SAVE solution 2
SAVE equilibrium_phases 2
SAVE surface 2
END

If other reactions such as surface reactions are involved, then these must also be SAVE’d and
USE’d in the same way. This approach makes most sense for grid-type calculations but can also
be used to speed-up ‘hunt-and-track’ style calculations. It makes little or no difference when
the chemistry is ‘simple’ and calculations are relatively fast, e.g. demo\Fe\hfo.ppi.
An example to demonstrate this approach, FeAsS(cd-music)-mod.ppi, is given in the
C:\PhreePlot\demo\FeAsS-cd-music\ folder.

A similar approach using RUN_CELLS is also possible.

6.3 POSSIBLE TYPES OF CALCULATIONS AND PLOTS

The types of calculations undertaken and the type of plot produced is controlled by the calcu-
62 PhreePlot Guide

lationType keyword (Table 6.3).

Table 6.3. Types of calculations undertaken by PhreePlot

calculationType Use
makes one or more predominance diagrams using the ‘hunt and track’ algorithm.
ht1 The scope of calculations is given by xmin, xmax on the x axis and ymin, ymax on
the y axis. The step size during hunting and tracking is controlled by resolution.
grid makes one or more predominance diagrams using the ‘brute force’ or grid algo-
rithm. The number of cells along each axis (nx = ny) is controlled by resolution.
custom any calculations requiring a series of straightforward iterations (default)
fit fitting model parameters to observations and plotting the resultant fit.
simulate like fit but only calculates the fitted values rather than adjusting parameter values
to get a good overall fit
species calculates the percentage or log concentration of all species present for a given ele-
ment in a well-defined system

The other critical keyword that should be included in each input file is that of calculation-
Method which has the following values:

0 = do calculations but do not plot anything

1 = do calculations and plot everything from scratch
2 = don’t re-speciate or reprocess data but replot using existing plot data files
3 = as for 2 but goes back one stage further and reprocesses the output from speciation.

6.4 PREPARING THE SELECTED OUTPUT FILE

6.4.1 Normal behaviour

PhreePlot receives output from Phreeqc via its selected output ‘file’ mechanism. Originally
Phreeqc had just one combination of SELECTED_OUPTUT and USER_PUNCH keyword blocks but
this has now been extended to any number of SELECTED_OUPTUT n and USER_PUNCH n blocks
where the integer n defines a specific combination. The main (default) selected output is n = 1,
and it is this file that provides the data that are extracted to the ‘out’ file.
Although the selected output file was originally a permanent file that could be accessed via the
operating system in the usual ways, one of the options with the Phreeqc library used in
PhreePlot is to make this transfer entirely in memory. Storing the results in memory reduces
I/O and speeds up execution. However, it does not leave a file to be inspected after execution
has finished. PhreePlot uses this memory approach when debug=0 but uses the permanent
file approach when ABS(debug)>0.
It is also often neater to turn off the default selected output using the -reset false option in
the SELECTED_OUTPUT keyword block. This minimises the transfer of unwanted data. If this
option is not used, default selected output variables, like ‘state’, ‘simulation’ etc. will be
included in the output files.
The selected output ‘file’ (physical or actual) is constantly being overwritten with the results of
the last iteration. The ‘out’ file (see Section 5.4.4) accumulates the relevant lines (see selected-
OutputLines) that are produced each time the selected output is ‘punched’ (once per iteration
of the USER_PUNCH block providing that it is not blank and that the output has not been turned
off with PRINT; -selected_output FALSE or SELECTED_OUTPUT 1; -active FALSE).

6.4.2 The use of the ‘headings’ identifier

The -headings line in the USER_PUNCH block defines the column labels that are output to the
first line of the selected output file. These column labels in turn are used to define the tag
 Running PhreePlot 63

names for the variables that are automatically produced from the selected output.
Because of the way that headers are used to define variable names in PhreePlot and because of
the limitations of the PhreePlot function parser, the choice of header names is somewhat
more restrictive in PhreePlot than in Phreeqc. In particular, the following special characters
+-/*()<>^\ can cause problems. Quotes are not treated specially. Therefore quoted strings
should not be used for headings and spaces are not allowed within an individual heading name
– spaces are used as separators.
If one or more of the special characters is found, PhreePlot will replace each of them with a
period (.). This means that “a+b” and “a-b” will both be translated to “a.b”, leading to an
error if both are present. Providing that such degeneracy is avoided, the use of special charac-
ters in headers should cause no problem. The reporting of tag values in the log file and the use
of column headers in defining plot variables is based on the original names.
The list of column headings are associated in turn with each of the punched variables:

SELECTED_OUTPUT
-high_precision true
-reset false
USER_PUNCH
-headings pH Zn Cd ZnOam
-start
10 sorbedZn=SURF("Zn","Hfo")
20 totZn=SYS("Zn")
30 sorbed1=100*sorbedZn/totZn
40 mineral=100*equi("ZnO(a)")/totZn
50 punch -la("H+") sorbed1
60 sorbedCd=SURF("Cd","Hfo")
70 totCd=tot("Zn")*tot("water")+sorbedCd
80 sorbed2=100*sorbedCd/totCd
99 punch sorbed2 mineral

pH will head the column containing values of -la("H+").

Zn will head the column containing values of sorbed1.
Cd will head the column containing values of sorbed2.
ZnOam will head the column containing the percentage of Zn in the mineral ZnO(a).

The column headings are used by PhreePlot in four specific ways:

(i) to generate tag names like <pH>, <Zn> etc

(ii) to label the curves plotted in the main plot area (suppress with labelSize<=0)
(iii) to label the legend to the plot (suppress with legendTextSize=0)
(iv) to control whether the data column is to be plotted as points, lines, both or not at all.

If convertLabels is TRUE, then column headings are checked by PhreePlot to see if they are
consistent with Phreeqc chemical formulae format and if so are interpreted accordingly when
used as in-plot labels for the curves and in the legend. This means that numbers within the
text string will normally be interpreted as a stoichiometry and subscripted. A check is made to
see if the numbers could be interpreted as valences rather than stoichiometries. This checking
is not particularly thorough and some strings may be interpreted as formula when in fact they
are not.
If certain characters are found in the heading which indicate that the string is not a formula
then this prevents the translation to Phreeqc formula format. These characters are:
¬~@?|!£$%^&*_’. Some of these (¬£) are non-plotting characters with ASCII encoding and
so they can be used to force interpretation as a non-Phreeqc formula on a one-off basis with-
out affecting the appearance in the plot, e.g. ¬Zn8 will plot as Zn8 rather than as Zn8. How-
ever, these non-plotting characters should be used with caution as their behaviour is non-
standard and may be unpredictable. They are plotted using the Latin-1 character set.
64 PhreePlot Guide

Starting a heading with a lowercase character will force it to not be interpreted as a formula.
The backslash has special behaviour in a heading since on printing Phreeqc strips out the \
and the following character from the name. It is therefore necessary to use \\\ if a backslash is
wanted. In PhreePlot, a backslash is also used to indicate that the next character is to be inter-
preted as a Greek character so \\\b in a heading would print the Greek character beta. Some
examples which demonstrate these rules are given in Table 6.4.

Table 6.4. Examples of how a Phreeqc column heading (label name) will be interpreted during plotting

Input Graphical output Interpretation

CH4 CH4 normal Phreeqc formula (first character is uppercase)
cH4 cH4 not a formula (first character is not uppercase)
C(-4)H4 C(-4)H4 Phreeqc formula but (-4) is a valence not a charge
C(-4) C(-4) Phreeqc formula as above
C-4 C4- Phreeqc formula but -4 is treated as a charge
Non-printing character at beginning prevents interpretation as a Phreeqc
¬CH4 CH4
formula (ASCII encoding)
Phreeqc removes backslash and first character after it and the remaining is
\C(-4) (-4)
interpreted literally (it is not a formula)
the first \ removes the second \ and the remainder is interpreted as in the
\\C(-4) C(-4)
first example above
the first two \’s are removed leaving a single \ which indicates that the
\\\C(-4)  next character should be treated as a Greek character (here chi). This
indicates that it is not a formula.

Remember that # and ; have special meanings in Phreeqc input files and should be avoided in
headings. Single and double quotes may also be interpreted in a special way in strings includ-
ing headings. Tags such as _... will always be interpreted as indicated and so can be
used to force certain behaviour, e.g. %Zn²⁺ will appear as %Zn2+.
Unpaired quotes should not be used in column names. Strings enclosed in square brackets will
be stripped of the brackets and then interpreted literally.

Controlling the plotting of individual columns

Data from the selected output are accumulated in one or more output files. These files may
then be used for plotting the data.
The points and lines keywords (and their 2y counterparts) control whether points and/or lines
are selected for plotting. Properties of these points and lines such as colour, size or width are
controlled by a series of keyword lists such as lineWidth, pointSize (and lineWidth2y and
pointSize2y). Each dataset selected to be plotted with points and lines has a corresponding
entry in a property list, or if the list is short, is either generated automatically (pointColor or
lineColor), or recycled from the existing list.
For example, if pointSize is set to 0.0 or the pointColor is set to ‘nd’ then no symbol will be
drawn for any of the selected point datasets. If pointSize is set to 5.0 3.0 and pointColor is set
to red blue then the symbols for the selected datasets will alternate red-blue-red-blue ... as
needed with sizes alternating 5, 3, 5, 3 ....
The six standard filled symbols can have a coloured rim with their colours and widths set by
the corresponding rimColor and rimFactor keyword lists.

Use of labels in a custom plot and the minimum text size

The labels are used for labelling the lines/points in a custom plot and its legend. The size of
the label text is given by labelSize. The minimum height of text is 0.01 inch and is reset to this
value if it is entered as a smaller positive value than this. 0.0 suppresses plotting of text alto-
 Running PhreePlot 65

gether.
The headings can contain super- or subscript tags, e.g. H₂O or Fe²⁺,
and Greek characters as per the normal rule (only to the first level – no superscripted Greek
characters are allowed).
Label headings must not be duplicated.

6.5 DEBUGGING

6.5.1 Types of problem

If a file has not run as expected or has crashed then some debugging is required. Providing that
the run has not returned an immediate error report giving the file:line:word location of a syn-
tax error, the input file must be syntactically correct and the problem must lie deeper. An audi-
ble low beep signifies a recognised calculation problem of some sort.
First check the screen and log files if present to see if there are any messages which might give
a clue to the problem. Then it is necessary to work out whether it is Phreeqc/chemistry prob-
lem or a Phreeplot problem.
If the problem has failed on its first iteration of Phreeqc, there is probably something wrong
with the input file, either the PhreePlot part or the Phreeqc part.
It may be helpful to get the Phreeqc code working first by pasting the chemistry code into a
standalone version of Phreeqc, Phreeqci or Phreeqc for Windows. It will be necessary to
substitute values for all the tags before running the code.
PhreePlot problems should be reported to the address given on www.phreeplot.com.
The flags for ancillary output files such as the track file in the case of a predominance diagram
should be set to TRUE. Also make sure that all Phreeqc output is sent to the various log files by
ensuring that

PRINT; -reset TRUE

has been set in the Phreeqc input (CHEMISTRY) section. If there are several PRINT data blocks in
the CHEMISTRY section, it is the value of the last one that is used. This is useful since several of
the include files use -reset false which means none of the normal Phreeqc output will be
printed. Therefore during debugging, providing the line above is included after the include
file, reset will be set to TRUE and the Phreeqc output will be sent to the Phreeqc output files
without needing to edit the include file.
One this has been set, you can use debug = 2 or debug =3 to get a listing of all the Phreeqc
output copied to the file *.all (see below). Examine this carefully making sure that all the
expected substitutions have been made properly. The values of all the tags just before execut-
ing Phreeqc can be found in the log file so it should be able to tell if it is a PhreePlot problem
or Phreeqc problem.
You may just need a few iterations run. You can interrupt a run by pressing Esc and entering
‘s’ for Stop.
When the run is crashing later on and the early runs look good, it is more likely to be a failure
to converge in Phreeqc. This is most likely to be due to a user error in setting up the Phreeqc
input file leading to extreme chemistry of some kind. Failure of Phreeqc on well-defined and
well setup problems is rare enough to be dismissed as the most likely explanation. However,
failure of Phreeqc to converge can be quite a common problem and is usually due to the cal-
culations straying into some region of ‘unrealistic’ territory. Occasionally the chemistry may be
too complex and Phreeqc struggles to find a solution – this can be tested by simplifying the
problem including reducing the number of PHASES.
The problem is usually solved by tweaking the convergence parameters. The FeAsS.ppi exam-
ple is an example in which Phreeqc fails to converge in one place with the default convergence
66 PhreePlot Guide

tolerance. Relaxing the criterion from 1e-12 to 1e-10 solves the problem.

6.5.2 Checking the return status of a Phreeqc run

It is possible to check the status of a Phreeqc run by outputting the status return using the
<Phreeqc_status_0> tag in a USER_PRINT or USER_PUNCH block. This system tag is automati-
cally created and updated after each run. The 0 reflects the thread number of the run. A status
return of zero indicates successful completion while a positive value gives the number of errors
detected.
In principle, it is possible to check the status of a run, take avoiding action if it has failed and
then rerun the simulation, all in one script. Fore example, it is possible to automatically switch
the chemical used to achieve the target value in an EQUILIBRIUM_PHASES block, see the
\demo\switch examples.

6.5.3 General approach to debugging

Debugging is an acquired skill and some general principles apply whatever the language.
David Agans has nine general rules for debugging. In a review of Agans’ book, David A.
Wheeler listed them as:

Understand the system: Read the manual, read everything in depth, know the fundamen-
tals, know the road map, understand your tools, and look up the details.
Make it fail: Do it again, start at the beginning, stimulate the failure, don't simulate the
failure, find the uncontrolled condition that makes it intermittent, record everything
and find the signature of intermittent bugs, don't trust statistics too much, know that
"that" can happen, and never throw away a debugging tool.
Quit thinking and look (get data first, don't just do complicated repairs based on guess-
ing): See the failure, see the details, build instrumentation in, add instrumentation on,
don't be afraid to dive in, watch out for Heisenberg, and guess only to focus the search.
Divide and conquer: Narrow the search with successive approximation, get the range,
determine which side of the bug you're on, use easy-to-spot test patterns, start with the
bad, fix the bugs you know about, and fix the noise first.
Change one thing at a time: Isolate the key factor, grab the brass bar with both hands
(understand what's wrong before fixing), change one test at a time, compare it with a
good one, and determine what you changed since the last time it worked.
Keep an audit trail: Write down what you did in what order and what happened as a
result, understand that any detail could be the important one, correlate events, under-
stand that audit trails for design are also good for testing, and write it down!
Check the plug: Question your assumptions, start at the beginning, and test the tool.
Get a fresh view: Ask for fresh insights (just explaining the problem to a mannequin may
help!), tap expertise, listen to the voice of experience, know that help is all around you,
don't be proud, report symptoms (not theories), and realize that you don't have to be
sure.
If you didn't fix it, it ain't fixed: Check that it's really fixed, check that it's really your fix
that fixed it, know that it never just goes away by itself, fix the cause, and fix the pro-
cess.

The ‘divide and conquer’ rule applies well for solving PhreePlot-type problems. Simplify the
failing example until it works and then work forward, narrowing the range of possibilities
until the source of the error is found.
Sometimes it is the data that is giving the problem and the ‘divide and conquer’ approach can
 Running PhreePlot 67

work well for that too. Split the data into two and see if both halves cause a failure. If only one
half does, keep dividing the failing half into two until the data giving the problem can be iden-
tified. Then work out what is special about those data.
Phreeqc rarely fails from programming errors or bugs but calculating predominance plots can
explore a large range of chemistries in terms of redox, acid-base, mineral stability, adsorption
etc. and only the best speciation programs are robust enough to complete such a challenging
set of calculations reliably.

6.5.4 Using the debug keyword

You often need to know exactly what is being computed especially when there appears to be a
problem. The higher the debug setting (0-3), the more information is returned to the screen
and log file. If there has been a failure in Phreeqc, the relevant Phreeqc output is normally
sent to the log file and echoed to the screen and so examining this output should be the first
thing to do. The exception to this is during the calculation of predominance plots with
debug=0 when PhreePlot will record a NA species and attempt to battle on. In this case, setting
debug=1 will induce PhreePlot to stop immediately it has detected an error.
In general, with the default (‘auto’) settings for the Phreeqc.0.out and all keywords, debug
works in the following way:

debug=0 minimal diagnostic output

debug=1 selected_1.0.out and Phreeqc.out produced
debug=2 selected_1.0.out, Phreeqc.out and *.all produced
debug=3 as for debug=2 except that the input is echoed to the screen on each itera-
tion and the Phreeqc output is also inserted into the log file.

selected_1.0.out is the SELECTED_OUTPUT file from the last iteration and if produced, will be
found in the working directory. Phreeqc.out contains the normal Phreeqc output from the
last iteration and is controlled by the Phreeqc PRINT keyword. A copy of this is also sent to the
log file and the screen.
Debug also controls the degree to which the input files are echoed to the log file. With debug
= 0, only the main input file is written. With higher debug levels, all include files and the
override.set file are also copied.

The file *.all file is generated with debug=2 or greater, or when the all keyword switch is set
to TRUE. This accumulates Phreeqc.out from all of the iterations. This can produce a very
large file but it is the definitive record of all that Phreeqc has done. It may be necessary to
change the -reset option in the PRINT keyword block to -reset TRUE to ensure that all of the
Phreeqc output is written to the output file.
The log file will also give the value of many of the PhreePlot settings, including all the tag val-
ues and loop variables that have been generated. It will also have a copy of input to Phreeqc
after substitution. In the case of a failure, this should be checked for errors to make sure that
Phreeqc is receiving valid code. This input can also be seen on the screen by setting debug=3.
If Phreeqc fails (usually because of syntax or setup errors), then the Phreeqc output is usually
written to the log file and echoed to the screen, and calculations stop. The exception to this is
that with debug=0 and when calculating a predominance or contour plot, or when stopOnFail
is set to 0, computations continue unless stopped manually with the Esc key.
The selected_1.0.out file will indicate whether the expected output is being sent from
Phreeqc to PhreePlot. If Phreeqc has failed to converge, this file may not be formed properly.

6.5.5 The most common reason for a failure to converge

As mentioned above, Phreeqc is a very reliable and well-tested program and rarely fails to con-
verge given ‘reasonable’ chemistry. We have run it through millions of iterations without prob-
68 PhreePlot Guide

lems. However, it can be easily be made to fail if it is forced to make calculations under
conditions for which it was not designed, namely very high ionic strengths (e.g. above 5 mol/
kgw). Such conditions can arise from rather benign starting conditions if the system is sub-
jected to extreme constraints. For example, at the extremes of pe, water decomposes leading to
small volumes of water remaining. This concentrates the initial solutes and Phreeqc may, not
unreasonably, then fail to converge. This is exacerbated at high temperatures. Therefore in
non-obvious cases of failure always check for high ionic strengths or diminishing volumes of
water.
A second common failure is when a phase is designated to adjust the activity of some species
but in reality cannot. In the present context, this most often arises when trying to fix the pH
by adding an acid or base but choosing the wrong one. For example, trying to change the pH
of a solution initially at pH 3 to pH 9 by adding HCl is impossible. Phreeqc attempts to do
this by adding negative concentrations of HCl (removing HCl) but if there is not enough Cl
in the system to do this, Phreeqc will fail. For example,

PHASES
Fix_H
H+=H+
log_k 0
SOLUTION 1
units mol/kgw
pH 3
Na 1e-3
Cl 1e-3
EQUILIBRIUM_PHASES
Fix_H -9 HCl
END

will fail. If the initial pH was 4, there is sufficient Cl available to be removed and Phreeqc
converges without difficulty. Of course, if NaOH is specified as the reactant, Phreeqc does
not fail even starting at pH 3.
Our problem is that it is neither always obvious what reactant should be used nor is it neces-
sarily possible to specify a single reactant to cover the entire range of conditions desired (this
can be very wide when constructing pe-pH diagrams). For example, redox reactions can pro-
duce or consume large amounts of acidity. So changing a sulphate-rich oxidising solution to a
reducing one at a higher pH may actually require acid not base to be added because of the
large amount of OH- released as a result of sulphate reduction.
One way around this problem is to try and arrange for it not to happen by starting at an
extreme pH such that addition of the specified acid/base will always succeed.

Alternatively, add a ‘large’ amount of the co-solute (here Cl-) such that the above balancing
reaction can always be used to withdraw negative quantities of HCl. More generally when
‘large’ is not known, add a relatively benign equilibrium phase such as NaCl such that it
always maintains a finite (but probably small) concentration of the co-solute to allow the
required removal to be achieved, e.g.
SOLUTION_MASTER_SPECIES
[Na] [Na]+ 0 23 23
[Cl] [Cl]- 0 35 35

SOLUTION_SPECIES
[Na]+ = [Na]+
log_k 0

[Cl]- = [Cl]-
log_k 0

PHASES
Salt
[Na][Cl] = [Na]+ + [Cl]-
log_k 0

Fix_H+
 Running PhreePlot 69

H+=H+
log_k 0

SOLUTION 1
units mol/kgw
pH 3
Na 1e-3
Cl 1e-3

EQUILIBRIUM_PHASES
Fix_H+ -9 H[Cl]
Salt -12 [Na][Cl] dissolve
END...

By defining [Na] and [Cl] as new ‘elements’, there will be no additional side-effects arising
from reactions in which Na and Cl are involved. These new notional ions will be included in
the calculation of the ionic strength though this can be avoided by making their atomic masses
0.0. Adding ‘dissolve’ means that this action is only taken when needed, i.e. when Na needs
to be added – this becomes more important when simple Na and Cl are used as it prevents the
disappearance or ‘precipitation’ of Cl. Of course this approach does not actually reflect a plau-
sible reaction path.
An alternative approach is to run a simulation, then in the following simulation check
whether Phreeqc has run properly by testing the <Phreeqc_status_0> tag, then using this
information either re-run the original simulation or change it in some way and then rerun,
e.g. change the chemical used in EQUILIBRIUM_PHASES.
Using the -force_equality TRUE option in the EQUILIBRIUM_PHASES keyword block may be
necessary to ensure that the target value for one of the axis variables, such as Fix_H+, is reached
exactly. This setting should only be used for phases that are definitely present, not for condi-
tional phases. It may be helpful to use it for CO2(g) at high pH but this can cause problems at
low pH.
There can be occasional lack of convergence to a reasonable solution brought about by exces-
sive mass transfers from one of the PHASES, e.g. of O2(g) or CO2(g). For example, the mass
transfers of O2(g) required to fix the pe in most systems is rather small, usually much less than
0.1 mol/kgw and so unless there are compelling reasons otherwise, include a limited reservoir
size as the second parameter in the definition of a the activity of a phase (the default is large,
10 mol), e.g. use

EQUILIBRIUM_PHASES
O2(g) <y_axis> 0.1

rather than

EQUILIBRIUM_PHASES
O2(g) <y_axis>

or

EQUILIBRIUM_PHASES
O2(g) <y_axis> 10.

Similar comments apply to CO2(g). High concentrations of carbonate (> 0.1 mol/kgw) can be
created when solutions above pH 10 are equilibrated with CO2(g) at atmospheric partial pres-
sures or above. Even at lower pH’s, it may be necessary to limit the size of the CO2(g) reservoir
to a value less than the default value of 10 moles. This can prevent rare problems in Phreeqc
convergence.
Limiting the reservoir in this way is part of the normal Phreeqc setup. No error is triggered by
Phreeqc when the target phase activity is not achieved because of insufficient reservoir size.
Therefore care is necessary with the setup to ensure that what is being calculated is what is
required.
70 PhreePlot Guide

6.5.6 Changing Phreeqc’s convergence parameters

It is occasionally necessary to alter the default KNOBS settings in Phreeqc to get convergence.
We have found the four most critical options to adjust are ­iterations, ­convergence_tol-
erance, step and ­pe_step_size. The ‘nuclear’ option for testing would be to set KNOBS as:
KNOBS
-iterations 1000
-convergence_tolerance 1e-10
-step 3
-pe-step_size 1.5

The -high_precision setting should be changed from TRUE to FALSE either in the ht1.inc file
or by redefining it later in the input file. Another KNOBS setting that can help convergence is:
KNOBS
-diag T

Note that KNOBS only applies to the simulation in which it is placed so if two simulations are
used, as is common in calculating predominance diagrams, KNOBS should be placed in the sim-
ulation which does the mass transfer calculations.
Another approach to solve the lack of non-convergence is to add the following fictitious spe-
cies:
SOLUTION_SPECIES
H2O + 0.01e- = H2O-0.01; log_k -9.0

This can help convergence (see the Phreeqc_3 manual, KNOBS p 117) as demonstrated in the
demo\Cuedta example.

6.6 INTERRUPTING EXECUTION AND CHANGING KEYWORD VALUES

PhreePlot can often be stopped or interrupted using the Esc key. This returns the following
prompt:

Press "s" to stop, "i" for input or <CR> to continue

<CR> (the Enter key) resumes execution, “s” stops the execution and “i” gives the following
prompt:

Enter keyword-value pairs/lists, "s" to stop or <CR> to continue:

at which keyword-value pairs or lists can be entered in the same way that they are entered for
input files. These new settings will take effect immediately on resumption of the calculations.
No checking on the reasonableness of the new settings is made and since it is clearly possible
to cause great confusion, this option should be used with care. A blank <CR> ends the input.
If the letter ‘s’ is entered, execution will be stopped as soon as possible. If a fit is being pro-
cessed, then execution will not stop until the calculations have been completed for a whole set
of data points. If a fit plot has been requested, a plot will be produced that reflects the best fit
up to that point. For other calculations, the stopping will be almost immediate.
If a run is stopped during the execution of a batch file, the next line in the batch file will be
executed. Control-break will enable execution of the whole batch job to be halted.
Pressing the ‘p’ key (case insensitive) during the execution of a ht1 or grid plot will write a plot
file, plot.ps, showing the progress of the calculations (this does not work for ‘grids’ plots).
This plotting can be automatically done on a regular basis by setting the plotFrequency key-
word to the frequency of the speciation calculations for which the automatic plotting is to be
done. The plot file will then be renewed every n’th iteration. A message, ‘File "plot.ps"
written’, is sent to the screen whenever this file is written. This option can only be used when
 Running PhreePlot 71

the multipageFile option is set to FALSE, i.e. a separate file is being created for each plot within
a run. This is because only one instance of the plotting routine can be in operation at any time
(a single thread) and multipage plots leave the plot file open between plots.

6.7 RUNNING THE STANDARD PHREEQC EXAMPLES

It is possible to run most of the Phreeqc example input files distributed with Phreeqc from
within PhreePlot.
These examples can usually be run using a minimal template such as:

calculationMethod -1 # calculate but don't attempt to plot

all T # accumulate output in *.all file

CHEMISTRY

include ".\examples\ex1"

The output will be sent to the directory from which the example is run and will include the
normal Phreeqc output in the *.all file.
The main challenge with these examples is to isolate the data that need plotting or tabulating
from that which does not. In most cases, the aim is to get a well-formed ‘out’ file. This can
usually be achieved with judicious use of PUNCH and the -selected_output switches in the
Phreeqc code, and the mainLoop, selectedOutputLines and dataSeparators in the PhreePlot
section.

6.7.1 Going round for just one iteration

In predominance plot calculations, it is useful to know the set of minerals that could theoreti-
cally form given the input chemistry and database used. Setting the resolution to 1, all to T
and ensuring that PRINT is TRUE in the Chemistry section automatically includes a commented
block of USER_PRINT statements in the cumulative Phreeqc output (*.all) that give a com-
mented list of all possible mineral species in the system being considered. This text can be
pasted back into an EQUILIBRIUM_PHASES data block and those which can realistically be
expected to form activated by un-commenting them.

6.8 RETURN STATUS AND EXIT CODES

PhreePlot will normally give a return status of 0 if it has run without errors. If it returns with
one or more errors, the return status is normally 1. This can be useful when constructing
sequences of runs in a batch file or script.
For example, the following Windows batch file script will only run the second input file if the
first one exited successfully:
pp file1.ppi
IF %ERRORLEVEL% EQU 0 (
pp file2.ppi
)
72 PhreePlot Guide
 Plotting basics 73

7 Plotting basics

7.1 INTRODUCTION

PhreePlot will normally attempt to produce a plot after a run. The type of plot produced is
determined by the plot type, currently grid, ht1, custom, species, fit or simulate. See the
appropriate Sections below for details.
The Chemistry section of the input file largely governs the type of data generated. What is
plotted and its appearance is governed by a series of keyword settings. A full list of these can be
found in the pp.set file and are described in more detail in Section 14.

7.2 TYPES OF PLOT

There are six options for generating potentially plottable output. These are controlled by the
calculationType setting:

grid ‘brute force’ method for making predominance or ‘pe-pH diagrams

ht1 hunt and track method for making predominance or ‘pe-pH diagrams
contour 2D contour plots
custom direct plotting of output from the SELECTED_OUTPUT file (the default)
species plotting species distribution plots, e.g. % species vs pH
fit calculating and plotting the fit of observations to a Phreeqc chemical
model. The observations and associated independent variables are read
from an external file.
simulate similar to fit but without the observations and so no fitting.
There are only two basic types of plots: (i) an x-y filled-area plot used for displaying predomi-
nance diagrams and contour plots, and (ii) an x-y plot with lines and points for displaying
other data. The two types of predominance diagrams use (i) while all the other types of calcu-
lations use (ii).
It is possible to overlay lines and points on predominance plots but not vice versa.
In order to suppress the generation of any plot file(s), set plotFactor to 0.0 or use a negative
calculationMethod.

7.3 SUMMARY OF BASIC PLOTTING

7.3.1 Introduction

A plot can be produced directly after the generation of the data or by replotting an existing
plot without generating the chemical data a second time. This is governed by the calculation-
Method keyword.

7.3.2 Setting up the plotting area

A plot is positioned on a notional piece of paper. The size of the paper is set with the paperSize
keyword. It can be either one of the ISO sizes (A0-A5, B4-B5), US sizes (Ledger, Letter or
Legal) or Note. This should be set to your preferred units in the pp.set file.
74 PhreePlot Guide

The pageOrientation can be set to 0 (portrait) or 1 (landscape).

It is simplest if all dimensions use the same units as defined by the units keyword. The units
can be ‘mm’, ‘inch’ or ‘pt’. The units used during plotting are determined by the last set value of
the units keyword as read from the various input files. This applies to any features defined in
the extraText or extraSymbolsLines files. This is best set in the pp.set file so that it is read in
first and does not need to be reset. All of the other default settings that use these units should
also be changed in the pp.set file.
The font can be set for the document as a whole but the font used cannot be changed for indi-
vidual text strings except through the extra text mechanism. It is best to set your default font
in the pp.set file.
The plot area is set on this piece of paper. The bottom left-hand corner (‘origin’) of the plot
area is offset by xoffset from the left and yoffset from the bottom of the paper. The length of
the x axis is given by xaxisLength and the y axis by yaxisLength.
The colorModel used is either ‘rgb’ for red-green-blue, ‘gray’ for grayscale, or ‘b&w’ for black
and white. Colours for text, lines, symbols and fills are specified on the rgb scale by colour
codes such as red4 and, if necessary, transformed to the other colour models.
The background colour of the plot area (within the axes) is given by backgroundColor(1).
This setting is less useful with predominance plots as they are normally completely filled with
colour (including ‘white’) anyway. The background colour of the whole page is given by back-
groundColor(2).
plotFactor can be used to rescale everything plotted by a given factor.

7.3.3 Setting up the axes scales, tick marks and grid lines

The axis scales are set up by minimum and maximum values of the axes on user coordinate x-
(pxmin, pxmax) and y- scales (pymin, pymax) with the ‘p’ standing for ‘plot’. The first tick
mark, a major tick, for both axes is placed at the plot origin (bottom left-hand corner) by
default but this can be modified by the optional second parameter to pxmin or pymin which
indicates the location of the first major tick mark (and label). Major tick marks are then added
at intervals of pxmajor and pymajor and minor ticks at pxminor and pyminor. By default,
minor axis ticks are plotted at the centre of each major tick interval. The minor ticks can be
turned off by setting pxmajor or pymajor to 0.
If any 2y lines or points have been specified, a second y axis (‘2y axis’) will be used on the
right-hand side of the plot with settings p2ymin, p2ymax, p2ymajor, and p2yminor. It shares
a common x-axis scale with the main y axis. It is used by specifying the lines2y or points2y
variables.
All or any of these settings can be set to ‘auto’ for automatic scaling based on the range of data
being plotted.
The colour of the axes is set with axisLineColor and the width with axisLineWidth. Four axes
will always be drawn, each with major and minor tick marks. Tick lengths are set with tickSize
and colour with tickColor. Separate tick sizes can be chosen for each of the major and minor x
axes, major and minor y axes, and major and minor 2y axes and up to six tick colours can be
similarly specified. The line width of the major tick marks is the same as the axis line width
while the width of the minor tick marks is half the axis line width. By default, the minor ticks
are half the length of the major ticks.
tickSize can also be used to specify the position of the ticks in relation to the axis – ‘inside’ or
‘outside’. Just add the ‘inside’ or ‘outside’ qualifier to the end of the list of ticksizes.
Grid lines can be plotted by setting the appropriate gridLines setting to TRUE or choosing a
very large tick size (more than half the length of the ‘other’ axis). These can be dashed if the
corresponding gridLineType style is greater than 1. Alternatively, a negative tick size can be
used. The appearance of the dashed line is also controlled by the gridColor and gridDashes-
PerInch settings.
 Plotting basics 75

7.3.4 Axis numbering and annotation

Axis numbers will be drawn at the major tick marks. The numbers of digits after the decimal
point are determined by pxdec, pydec and p2ydec. -1 means integer. These can be ‘auto’.
Very large and very small numbers automatically invoke scaling of the numbers using the
‘divide/multiply by a power of ten’ approach.
The size of the axis numbers is given by axisNumberSize and their colour by axisNumber-
Color.
Axis titles are given by xtitle and ytitle along with axisTitleSize and axisTitleColor. An
optional second string for the axis title is put after any ‘divide by a power of ten’ scaling so that
the units can be correctly placed to give dimensionless scales.
An overall plot title is given by plotTitle, plotTitleSize and plotTitleColor. This is centered
above the plot.

7.3.5 Adding fills, lines and points

Fills can only be added in predominance and contour plots. Lines and points (or symbols) can
be added to these plots or more commonly used to generate their own ‘custom’ plots. All this
plotting is controlled by reading data from files, either from files generated during the run or
from existing files. These files are all ASCII files and so can be viewed and edited with a text
editor. These files should normally be in a spreadsheet-type format in rows and columns. They
should have a header row which is used to name each column. The separators can be specified
as spaces, tabs or commas.
Predominance plots maintain a fillColorDictionary which holds the colour to use for each
species. If the dictionary is not initially present or a species not found, a sequence of pale fill
colours will be automatically generated and used. The fill colour dictionary will always be
updated with the colours used at the end. A labels file is also generated with the positions of
the labels used. This can be edited to move the labels.
Contour plots normally derive their properties from a series of lists, one value for each con-
tour, specified by settings such as contourFillColor. These lists are recycled if they are shorter
than required.
points, points2y, lines and lines2y are used to specify the lists of custom data series to plot.
The names used are the column names normally from the outfile though data series from extra
files can be added with extradat providing that they share a common x-axis name given by cus-
tomXcolumn name. Column numbers can also be used for specifying a column starting with
the outfile and then the extradat files in the order specified.
Points are plotted with symbols, some of which are ‘filled’ symbols which have separate fill and
rim colours. The filled colour can be white and so when combined with a coloured rim, can
give the appearance of open circles. Point size(s) are determined by pointSize and colour(s) by
pointColor. The colour(s) for points from data series for which the colour has not been
defined by pointColor are either automatically selected based on a rotating 15-colour pallette
or are taken from the line colour dictionary depending on the useLineColorDictionary set-
ting.
All lines are drawn with a thickness given by lineWidth. Negative values will give dashed lines.
The dash density is given by dashesPerInch. As with the points, the starting line colour(s) are
either determined by the lineColor setting and then automatically follow the default sequence,
or are taken from the line colour dictionary.
The line colour dictionary also contains information about the in-plot position of labels for
the lines and can be edited and replotted accordingly. labelSize and labelColor can be used to
adjust the appearance of the labels or turn them off completely. Label names for lines are auto-
matically generated from the column names but can be overridden with the labels keyword.
It is possible to synchronise the point and line color for the same data series with points-
76 PhreePlot Guide

SameColor.
A simple legend with an optional legendTitle and legendBox is automatically drawn to the
right of the plot. It can be turned off by setting legendTextSize to 0. The position of the leg-
end can be moved with a line of text or extraText file.
Additional lines, points, symbols and text can be added to a plot with extraLinesSymbols, text
and extraText as described in more detail below. Points or lines from additional files can be
added with extradat.

7.4 CONTROLLING THE STYLE OF LINES AND POINTS (SYMBOLS) IN CUSTOM

PLOTS

7.4.1 The default style and colour for lines and points (symbols)

Each lines variable has a lineType associated with it. This defines the line style and is specified
by a number from 1 to 20:
1 solid line
2-10 dashed line with an increasing proportion of space
11 dotted line
12-20 dot-dashed line with an increasing proportion of dash
The appearance of a line can also be changed with lineColor and lineWidth as described
below. There are 2y equivalents of these keywords.
Similarly, the symbol styles of points are defined by their respective pointType. See below for a
description of the symbols.
Each dataset (lines, points, lines2y, points2y) has its own list of 15 colours. These are picked
off one by one as needed. Specifying specific colours in an input file promotes that colour or
colours to the top of the list.
Each list starts with the same default list of colours. This is:
red
blue
green
orange
cyan
magenta
brown
sky
purple
gray
yellow
maroon
lawn
spring
black

So by default, the first colour to be used will be red, the second blue, etc. The default colour
density is 4, i.e. red4, blue4, ...
The various colour keywords such as lineColor provide a mechanism for promoting a colour
to the top of the list.
lineColor purple green

means that the line colour list becomes:

purple
green
red
blue
orange
cyan
magenta
 Plotting basics 77

brown
sky
gray
yellow
maroon
lawn
spring
black

Once the list is exhausted, it is recycled but the colour density may also be cycled 4, 6, 8, 2,
4... depending on the changeColor setting. Points are plotted after lines and may inherit the
same colour as the corresponding line by using the pointSameColor setting.

7.4.2 Lines

Line styles

The line style pattern is defined by a number in the range 1-20. These are shown in Figure 7.1
using a dash density of 5 dashes per inch. The demo file, \demo\linestyle\linestyle.ppi,
can be used to generate a figure similar to that below for a range of dash densities.

5 dashes per inch

line width = 0.02 inch

10

11

12

13

14

15

16

17

18

19

20

Figure 7.1. Examples of the 20 line style patterns available. These are specified
with the lineType, lineType2y, contourLineType or gridLineType settings. The
appearance can also be altered by varying the dash density (dashesPerInch), line
width (lineWidth) and line color (lineColor) settings, and their 2y and grid rela-
tives.
78 PhreePlot Guide

Automatic colouring of lines and points

The colour of lines and points are automatically selected based on the amended colour
sequence in effect (see above). The colour picked is determined by the position of the variable
being plotted in the input list (lines, lines2y, points, points2y) and the position of any colours
specified explicitly in the corresponding colour setting (colorLines, colorLines2y, colorPoints,
colorPoints2y) if necessary taking into account the recycling rules, e.g.
lines pH Ca Mg Na K
lineColor purple green

will give the following colours: pH = purple4, Ca = green4, Mg = purple4, Na = green4, K =

purple4.

Colours can be set multiple times to force a particular colour. Rims for open-filled symbols
also have their own colours that follow the same colouring rules.
Sometimes there are subsets of data with the same heading. This occurs where a line break
(blank line) in the data file has been found. The colour for all lines from this column will fol-
low the colour selected above but the colour density will change if the colour was specified
without a colour density (no number at the end, e.g. red) and if changeColor is TRUE. If the
colour is specified explicitly as red4 then this will always be used with no change in density.
‘auto’ can also be used as a colour. This will cause different colours to be used following the
colour sequence in effect. ‘nd’ (‘not drawn’) is also a colour that is distinct from the back-
ground colour.
When there are multiple plots/datasets per run, restartColorSequence controls whether the
line color sequence for auto-generated colours is restarted from the beginning of the sequence
for each plot/dataset.
Colours can also be controlled explicitly with the line colour dictionary (Section 7.9.4). All
points and line segments within a given sequence will have the same colour. If different attrib-
utes are wanted for each point or line segment, use an extraSymbolsLines file.
The selection strategy outlined above is followed for the colour of all lines and points, y and
2y.

7.4.3 Points (symbols)

Symbols can be plotted to represent the data points in a curve. The symbol used is specified
with the pointType keyword and can be specified by a number or a name. The available sym-
bols and their symbol codes are shown in Appendix 3 and Figure 7.5.
The six standard filled symbols and their code numbers are:

1 filled circle
2 filled square
3 filled triangle
4 filled upside down triangle
5 filled diamond
6 filled octagon

The list of symbols is recycled as needs be. The default symbol type is 1.
If pointsSameColor is FALSE, pointColor controls the colour of the symbols using the point
colour list as for the lines described above.
If pointsSameColor is TRUE and lines are plotted, the symbols will always have the same colour
as their corresponding lines irrespective of the pointColor setting.
 Plotting basics 79

There is no guarantee that all symbols will be centered exactly though the first six should be.
The size of symbols is specified by the pointSize keyword list.
Filled symbols can have a separate rim colour (rimColor) and rim width specified as a fraction
of the corresponding symbol size (rimFactor). This enables open circle symbols to be specified.
If these lists are short, the values are recycled.
The minimum size of positively-sized symbols is set to 0.01 inch. A size of 0.0 suppresses plot-
ting of symbols.

7.4.4 Order of plotting of lines and points (symbols)

The general order of plotting of lines and points (symbols) is controlled by the plotOrder key-
word. The default is lines then points. Within a given class, e.g. ‘lines’, the order of plotting of
individual lines is controlled by their order of definition in the keyword in the input file(s).
The order of plotting affects any overprinting - the last plotted will appear on top.
Although plotOrder does control the order of plotting of separate sets of lines and points,
when the same variable is plotted as both a line and a set of points, the line is always plotted
first. This means that the points will always overprint the line.

7.5 LABELLING PLOTS

Fields and lines in plots will normally be labelled, although the precise way this is done
depends on the type of plot and the various settings available.
Labelling of plots is important but it can be difficult to automate effectively. It is therefore
always possible to edit a ‘labels’ file to rename labels or to move their positions. Some details
on the choice of label names and their positioning is given below.

7.5.1 Label names and label position

Label names (up to 30 characters long) are automatically assigned a value depending on the
type of plot.
In ‘ht1’ and ‘grid’ plots, label names are derived directly from the species names and x- and y-
coordinates of the label positions are approximately centered in the field. The species name is
in turn derived from the database and any changes subsequently made by the ht1.inc or sim-
ilar file. The labels file can be edited to change the label positions and/or the label attributes
and the plot replotted (calculationMethod = 2). The plot should not be recalculated (calcula-
tionMethod = 3) as this will recalculate the label positions and return them to their original
positions.
The label position for predominance plots is, by default, placed near the centre of each field.
In custom and fit plots the positioning is more complex and an attempt is made to place the
labels in a legible place (Section 7.10.3). This can take a lot of effort to calculate – a brute
force (simulated annealing) approach is taken. The time taken is broadly controlled by the
labelEffort setting (0-3). The second parameter, if present, provides an upper limit to the time
taken (in sec).
In custom plots, the centre of the label position is stored in the line colour dictionary which
can be edited and the plot remade. The label name can be edited in the same way. Automatic
label positioning is affected by the labelEffort setting.
Label names for each of the ‘curves’ (including a set of points) can be overridden with a list of
names given by the labels keyword. ‘label’ names are simply picked from this list one by one as
required. Multiple curves generated in the same iteration because of the presence of line breaks
will be picked first, then multiple values of the loop or z-variable, then any more ‘outer’ itera-
tions. The list is recycled if necessary. Label names for custom plots can also be read from the
first column of the loopFile if present though the labels setting takes priority if not null.
80 PhreePlot Guide

When labels are derived from column headings, these may be set in the input file or in the case
of a simulate or fit plot, from the column headings of the fit data file.
Label names are automatically tested to see if they are plausible Phreeqc chemical formulae
and if so, subscripted and superscripted appropriately. Whether a label name is interpreted as a
formula or not depends on its format (Section 6.4.2). This conversion can be bypassed by set-
ting convertLabels to FALSE or by including a non-printing character in the label name (Sec-
tion 6.4.2).
Label names stored in the line colour dictionary and used as labels in plots and legends are
automatically appended with a special character when referring to the secondary (2y) axis. By
default this is a ‘*’ but this can be changed (see ytitle). This character should not be used as the
last character in undecorated label names.

7.5.2 Overriding calculated label positions and angles

Sometimes it is necessary to omit a particular label from a plot or move its position or change
its angle.
For predominance plots, removing a label can be done by changing the relevant species num-
ber in the labels file to a negative number, e.g. change 4 to -4.
This can also be achieved in other plots by editing the line colour dictionary as described
above.
The label positions and angles can be changed by ‘nudging’ them with the nudge or nudgeFile
keywords. A nudge file is simply a collection of nudges. These specify either an incremental
shift (‘diff’) or an absolute position (‘abs’) for x, y and angle for a label. The justification of
the label string can also be set for the absolute definition.
These files should have a single header line (e.g. to remind yourself of the column headings)
followed by 6 or 7 columns of data in free format as follows:
plot labelno species_name type xmm ymm angle pos
auto 1 "H2(g) > 1 atm" diff1.2-6 16 0 # left-justified
auto 2 "O2(g) > 0.21 atm" diff1.25.516 1 # centered
1 0 “Fe+3” diff 4 6 0 2 # right-justified

plot refers to the sequential plot number (as given by the info block) of the file for which this
override applies. ‘auto’ or 0 means that it applies to all of the plots. labelno refers to the
sequential label position (see the log file) and is necessary because the same label can be used
several times in a plot. ‘auto’ or 0 means that it applies to all of the labels with the given label
name.
If the type keyword parameter is ‘abs’, this sets a new value for x,y coordinates and angle. The
position set by the coordinates is for the centre of the label in the units used for plotting (mm,
inch, etc). This contrasts with the labels file where the x,y coordinates are specified in terms of
graph units and so a nudge labels file can be useful for automating shifts in batch processing
where different coordinate systems are used. x and y are for the anchor position of the label; y
is located at the vertical centre of the label (when horizontal), and the angle is in degrees from
the horizontal, rotated clockwise. The seventh column, pos, is only used for ‘abs’ shifts and
specifies whether the anchor position given is for the left end of the label (0), middle (1) or
right end (2).
If the type parameter is ‘diff’, then this does the same but specifies the shift in the position
and angle of the label from its calculated position. The pos column is not used.
The overrides only apply if the plot number and species name match that in a plot.
It is possible to delete a label from plotting by making the x-y coordinates off plot. A nudge
file can also be useful for rotating the labels for the water limits in predominance plots. The
angle for this is given in the log file.
 Plotting basics 81

7.5.3 Legend

A legend is automatically is automatically drawn for custom plots.

Normally a simple legend will be drawn to the right of the plot. This shows the colour of the
plotted lines and symbols against their label names. The size of the legend text is controlled by
legendTextSize and the line thickness is the same as in the plot. The colour of the legend text
is controlled by legendTextColor.
The order of items in the legend is controlled by the plotOrder setting and the orders specified
in the lines and points settings in the input file(s).
The legend will not be drawn if legendTextSize is 0.0 or if all of the lines or symbols have the
same colour.
The legend and all labelling can therefore be suppressed by setting both legendTextSize and
labelSize to zero. Individual labels can be suppressed by setting their colour to ‘nd’ in the line
colour dictionary and forcing the dictionary to be used by setting useLineColorDictionary >
0.
A legend box can be drawn around the legend using legendBox.
The placement of the legend can be changed by specifying its position in a text line or extra-
Text’ file using the special <legend> option. <legend> is not like a typical tag but rather acts as
a placeholder for the legend contents.
This approach can also be used to suppress the legend by specifying its coordinates to be out-
side of the page area.
A legend title can be also be added by preceding the <legend> tag with text, e.g.

auto 9 -20 “<b>Concentration</b><br> mg/L<legend>” 1.5 blue

auto in the line above means that the text will be applied to every plot. Any text after <leg-
end> but within the double quotes is ignored. The position of the legend can be automatically
controlled using the <pxmin> etc tags (see Section 7.12).

7.6 INPUTTING TEXT STRINGS

7.6.1 Available fonts and character sizes

Fonts from the Helvetica, Helvetica-Narrow, Bookman, Avantgarde, Times, Palatino,

NewCenturySchoolbook and Courier font families are available (see font). These are the
eight font families included in the 35 standard Postscript fonts. The regular, italic and bold
faces of these fonts can be specified with PhreePlot and should be able to be displayed and
printed by Postscript-conforming devices. The italicized ZapfChancery font is also available.
The symbol and dingbats fonts are also used for plotting Greek characters, symbols and vari-
ous icons.
All of these fonts are available with the standard Ghostscript distribution.
However, the fonts cannot be mixed. Only one of the font families can be specified for the
main text (in titles etc) although text enhancements such as bold and italic can be used. Text
in other fonts can only be written using the text or extraText mechanism.
The set of characters available within a font depends on the character encoding used. The
default is ‘Latin-1’ which includes many of the accented characters of Western European lan-
guages plus a few other symbols. The popular Windows-1252 character set adds a few extra
accented characters to this (plus the euro sign) but is not available here. The alternative,
‘Standard’ encoding, includes all 7-bit ASCII characters plus a smaller range of extended char-
acters which depend on the setup of your PC. This standard set was the default character set
in PhreePlot until January 2014. The ‘ASCII’ encoding only includes the 7-bit ASCII codes
(decimal 0-127) which includes all the numbers, lower and upper case Latin alphabet, punctu-
82 PhreePlot Guide

ation as well as some special characters (as found on most keyboards). This was used in earlier
(pre- 2014) versions of PhreePlot.
The size of characters can usually be specified by a character size parameter. These are nominal
character sizes and do not usually match the actual size of the characters as plotted. For exam-
ple, an uppercase ‘O’ in Helvetica font with a specified size (height) of 10 mm will actually be
about 12.8 mm high. Other fonts will differ somewhat from this.

7.6.2 Available characters and inserting ‘special’ characters

Text is required as input for various options such as the plot title, axes titles and extra text.
General features of text input are:
All standard ASCII characters (32-126) are available including numbers, alphabetic characters
and some special characters. These include: \|!ӣ$%^&*()_-+={}[]:;@~#<,>.?/. A space can
be included but when this is done, the entire text string must be included in single or double
quotes, e.g.
“Zinc concentration” or ‘Zinc concentration’
The two types of quote should not be mixed. If a single quote character itself needs to be
included as well as a space, embed the text string in double quotes; vice versa for including a
double quote character. A warning will be given if an unpaired quote is found without being
embedded in quotes. In this case, the string will not be plotted. Note that the quotes should
be of the simple vertical type, not the angled open/closing quote marks beloved of word pro-
cessors and their fancy fonts (as here, so be careful not to copy/paste these!)

“It’s easy”

and

‘A double quote (“) can also be used.’

are acceptable.

It’s easy

and

(“)

are not. If in doubt, include the text string in paired quote delimiters.
Ultimately the fonts available to the printer and display device will determine which charac-
ters are available. In principle, most devices are able to print the standard ASCII set of charac-
ters without a problem. Example 68 provides a view of many of the available characters. The
full range of characters is determined by the encoding and can include accented characters.
Text strings can contain system and user-defined tags. These should be assigned values using
the numericTags or characterTags keywords or have their values assigned by PhreePlot.
If the character is not readily available on your keyboard or input device, then any valid char-
acter can be added to a text string by using a backslash followed by the 3-digit octal code for
the character from the character set in force (\000-\377). For example, using the Latin-1
encoding, 20¢ (twenty cents) can be entered as 20\242 since 242 is the octal code for cent
(decimal 162). In order to avoid backslashes being misinterpreted when wanted as such rather
than being interpreted as part of the octal code, enter them as double backslashes. They will
print as single backslashes.

7.6.3 Text enhancements (bold, italic, subscript, superscript) and Greek characters

A certain degree of text enhancement is possible although the possible combinations are rather
 Plotting basics 83

limited. The following tags are available for modifying the appearance of text. Case is signifi-
cant. All text enhancement tags should be in lowercase.
Most of the tags are paired and should be turned ‘on’ and ‘off’ in their nested order otherwise
unpredictable output may result.

Bold: <b>This is bold text</b>

Italic: <i>This is italic text</i>

Italic: <b><i>This is text</i></b> # N.B. tags must be properly nested

Superscript: e = m c²

Subscript: Ca(NO₃)₂

Sub and superscript: Sum <subsup>under over</subsup>

over
Subscript first then the superscript separated by a space. This gives Sum .
under
Greek strings: <g>abcdef</g> gives .

The mapping of lower and uppercase Greek characters is:

abcde fghij klmno pqrst uwxy

abcde fghij klmno pqrst uwxyz

ABCDE FGHIJ KLMNO PQRST ¡WXY

ABCDE FGHIJ KLMNO PQRST UWXYZ

An alternative way of getting a single Greek character is to precede the corresponding letter
with a backslash:

\a gives 

\mg/L gives g/L

If a backslash itself is wanted and is immediately succeeded by a character, use two consecutive
backslashes or insert a blank enhanced string immediately after the backslash, e.g. \<i></i>p
will print \p.
Characters embedded in a Greek string for which there is no translation to a Greek character
will be replaced by a space.
Break: <br> produces a line break. Each line is treated as a separate text string. Therefore any
other tags such as <b> </b> must be properly paired tags before and after any <br> and may
need to be repeated, e.g. <b>bold1</b><br><b>bold2</b>.
All but <br> are paired tags. If one of the pair is missing or has been mistyped or the tag has
not been recognised, that part of the string will be printed as is.
In most cases, text enhancement tags (i.e. Greek, bold, italics, subscript, superscript, subsuper-
script) cannot be embedded within one another, e.g.

^{<i>this gives superscript but not italics</i>}

and

<b>this will not be bold<br>this will not be bold</b>

will not work and may produce incorrect output but

<b>bold</b><i>italics</i>
84 PhreePlot Guide

and

<b>bold</b><br><b>bold again</b>

will work. The exceptions are that bold can be used with other tags: <b><i>...</i></b> and
<i><b>...</b></i> will both produce the bold-italic font and <b>Cu_T</b> will
work as hoped. Note that the order of the ‘off’ tags is important to maintain the correct nest-
ing otherwise unpredictable results may occur. Illegally nested tags will be ignored or incor-
rectly translated.
It is not possible to define subscripted superscripts such as a 3+ by
Fe
a_Fe³⁺ (illegal)

or superscripted superscripts

a^Fe³⁺ (illegal)

or superscripted Greek characters.

It is not possible to enhance any Greek characters, e.g. Greek italics or Greek bold are not sup-
ported.
It is possible to embed many PhreePlot tags such as <loop> and <mainspecies> (but not
<input>) between text enhancement tags since the text substitution has already taken place
before being interpreted for plotting:

“As = 10^<loop>M”.

Ensure embedded spaces are enclosed using single or double quotes.

7.6.4 Accented and other ‘foreign’ characters - the Latin-1 encoding

The default or ‘Standard’ encoding is based on the ASCII 7-bit characters plus a variable num-
ber of characters from an ‘extended’ character set as found on many keyboards. Many Western
European languages have accented characters which are not in this set. These are found in the
ISO-8859-1 character encoding which is similar to the Windows 1252 (Western European)
character set minus a few characters.
The Latin-1 character encoding is supported in Postscript and in the Postscript fonts supplied
by Ghostscript and many other Postscript interpreters. The full character sets are shown in
Appendix 4.
There are two ways of entering accented and foreign characters not available directly from
your keyboard:
(i) most Windows text editors such as Notepad and Notepad++ support the Latin-1
encoding (and others) and accented characters can be entered by using Alt-num key codes.
This is done by holding the Alt key and then typing the decimal code for the character with
the numeric keypad including the leading zero, e.g. Alt-0200 for È. The editor must be con-
figured to view and export the text with the correct encoding (i.e. ISO-8859-1 or ANSI) which
may not be the default.
(ii) Postscript interprets 3-digit numeric strings preceded by a backslash as octal codes
and associates these with the appropriate characters according to the encoding in force, e.g.
\310 for È and \350 for è with Latin-1. So these octal codes can be included directly in text
strings, e.g. caract\350res europ\351ens for caractères européens.
The first method is probably better if the Latin-1 encoding is being used since this follows
closely the Windows encoding and so the text can be read and checked visually in the moni-
tor. The second method is less easily interpreted on-screen but avoids any problems with
encoding of the text from editor/monitor to Postscript. Internally, the extended characters are
 Plotting basics 85

always replaced by their octal codes in the Postscript output.

The usual limit on the length of plotted text strings of 200 characters remains. This includes
the necessary replacement of the extended characters using their octal representation, i.e. each
extended character takes four ASCII characters. Long lines will either be truncated or any
translation aborted.
The default is to interpret text strings with the Latin-1 encoding. In order to enable the Stand-
ard encoding, use the font keyword
font Helvetica Standard

or to retain the current font

font Standard

The encodings for both ‘Standard’ and ‘Latin-1’ encodings are given in Appendix 4 . Alterna-
tively visit a website such as http://en.wikipedia.org/wiki/ISO/IEC_8859-1 for Latin-1.
As well as the accented characters, umlauts and inverted marks, Latin-1 includes some other
useful characters such as the degree (°), plus-minus (±) and some common fractions. On the
other hand, the standard encoding has some characters that Latin-1 does not, such as the per-
mil symbol and the oe ligature.

7.6.5 Non-printing characters

It is sometimes useful to add a non-printing character to the plotted output. Postscript inter-
preters usually just ignore these characters.
Whether a character (decimal code) will print or not depends on the font and its encoding.
With the ASCII encoding, the ¬ (‘Not sign’) character does not print and is found on many
keyboards. This does print with Latin-1 and Standard encodings so other characters are
required. Characters not available on keyboards can be entered with either of the two methods
discussed above, namely Alt-num key codes and octal codes. Characters with decimal codes
from 129 to 159 (octal codes 201 to 237) may not be defined and are not normally printable
but avoid those before decimal 138 (octal 212) as these are used internally by PhreePlot.

7.6.6 Justification

This can usually be specified as either left, centre or right justified horizontally. The text is also
aligned on the text baseline (bottom of the letter a) though the exact position can depend on
the particular characters and font. Where a <br> is included, the x and y coordinates refer to
the bottom of the first (top) line.
For accurately centered symbols, use the extraSymbolsLines symbols rather than the extraText
symbol font.

7.6.7 Angle

The text can be rotated. The angle of rotation is given in degrees from the horizontal, rotating
clockwise.

7.6.8 Tags in text strings

Tags can be added to text strings and their values, if known, substituted at plot time. Tags gen-
erated during a run are not stored and so will be UNDEFINED on replotting.

7.7 SPECIAL PHREEPLOT VARIABLES OR TAGS

7.7.1 Available tags

A number of special variables, or tags, can be included in a PhreePlot input file or extra text
file. These are substituted by values or specific operations at run time. These are:
86 PhreePlot Guide

<x_axis> The current value of the x-axis variable

<y_axis> The current value of the y-axis variable
<loop> The current value of the loop (z) variable
<logloop> The current log10 value of the loop (z) variable
<mainspecies> The name of the main species
<legend> The entire legend key as used in the current plot
<input...> Part of the input file (only in text lines or extraText files)
<pxmin> etc The value of pxmin etc at plot time
<command_line0> etc The values of the command line arguments

In addition, several special tags are automatically produced during a fit which contain infor-
mation about the fit.

7.7.2 System pH, system pe and system temperature

Internally, PhreePlot needs to know certain system variables to convert from one yscale to
another. Sometimes this information is passed through standard PUNCH output formats, e.g. for
predominance plots (ht1.inc etc), but sometimes it is not done automatically, e.g. for contour
plots. However, this information can be passed by PUNCH’ing the appropriate columns and
naming the columns in a particular way. These three variables, pH, pe and temperature (Cel-
sius) are recognised by the column headings, “pH”, “pe” and “TC” (case sensitive), respectively.

7.8 AXIS SCALING

7.8.1 Auto or user-defined axis scaling

Axis scaling is set with keywords such as pxmin, pxmax etc. Axis scaling can either be auto-
matic or manual. A keyword value of ‘auto’ means that PhreePlot attempts to choose the axis
scaling so that all valid data in the data file are included in the plot and the tick intervals are at
‘pretty’ intervals.
Manual scaling by setting pxmin etc gives more control over the minimum and maximum
range, the numbering of the axes and the positioning of tick marks. It also enables ‘zooming
in’ on particular parts of the plot without recalculation though this is often better done by
recalculating with the new domain settings. Automatic label placement for lines is only carried
out after a new calculation.
The first major tick mark for both axes is placed at the plot origin (bottom left-hand corner)
by default but this can be modified by the optional second parameter to pxmin or pymin
which indicates the location of the first major tick mark (and label). The x and y axes are then
labelled every pxmajor (or pymajor) graph units until xmax (or ymax) is reached. There is a
major tick mark at each label. There is not necessarily an axis label at the maximum value.
Additional tick marks are calculated according to the value of the pxminor and pyminor.
When a plot has a max-min range of 0–100, say and a lot of data are at or close to 0., then this
can create a lot of untidy plotting and labelling close to the lower x axis. This can be avoided
either by removing the offending columns completely from the plot or by shifting the y-axis
scale by a small amount, e.g. to 0.001 and 100.001, respectively. This will remove the col-
umns where all the data are below 0.001 from both the plot and from the key. Of course,
some information is lost in the process. It is also possible to eliminate lines by setting the min-
imumYValueForPlotting keyword at an appropriate value.
If the scope of a predominance plot calculation (set by xmin, xmax etc) is changed and the
plot is replotted rather than recalculated then the scale and positioning of the polygon label-
ling and axis scaling will reflect the selected data from the original files and may appear some-
what odd - not much of the original data may be selected if the plot area is a small proportion
 Plotting basics 87

part of the original area or if not many points are selected from the polygon file. The corre-
sponding polygon and label files should therefore be regenerated using ‘reprocess (labels) and
replot’ (calculationMethod = 3) or ‘Calculate and plot’ (calculationMethod =1) to ensure the
correct display of labels within the specified domain.

7.8.2 Secondary y axis (the 2y axis)

The left-hand vertical axis is the main y axis. The ticks on this axis are normally mirrored on
the right-hand y axis. It is also possible to define different scaling for the right-hand y axis (the
secondary or ‘2y’ axis) using keywords such as p2ymin, p2ymax, 2ytitle etc. Variables for this
axis are specified for this scale using points2y and lines2y keywords as for the main y-axis vari-
ables. An example in which the 2y axis is used as an expanded y-scale is shown in Figure 7.2.
Al solubility vs pH
(with 2y axis)

2 0.1

0 SIGibbs*
0.0
log concn (mol/kgw)

-2 -0.1

SIGibbs
Gibbsite
Al3+
-4 AlF2+
AlT -0.2
Al(OH)4-
-6 Al3+
-0.3
AlF2+
Al(OH)4-
-8 AlT
-0.4
Gibbsite
SIGibbs*
-10 -0.5
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Alvsph\Alvsph2y.ps

Figure 7.2.

The 2y title is plotted if any variables have been defined with points2y or lines2y. If 2ytitle is
set to ‘auto’, the first variable name from points2y or lines2y is used. If labels or a legend are
drawn, the names of any labels referring to the 2y axis have, by default, an asterisk (‘*’)
appended to their label name. This modified name is also stored in the line colour dictionary.
The asterisk can be replaced with any single character using the third parameter of the 2ytitle
setting.
There is no corresponding minimumYValueForPlotting for the 2y axis.

7.9 CONTROLLING THE PROPERTIES OF TEXT, SYMBOLS, POLYGON FILLS AND

LINES

7.9.1 Principles

Text, symbols, polygon fills and lines have various properties associated with them such as
type, size and colour.
88 PhreePlot Guide

Some of these are fixed by PhreePlot but many can be set in PhreePlot. However, the way
that this is done can depend on the type of plot involved – predominance plot, custom plot or
contour plot. These properties often take on default values specified in the pp.set file but
many of the colours, such as those for lines and symbols, can either be auto-generated or set
more explicitly.
Some properties such as the colour of the plot title only have a single value and these are usu-
ally set by a separate keyword, here plotTitleColor. Other properties, e.g. those of lines and
points (symbols) in custom and contour plots, have an array of values, one for each separate
line or set of symbols.
In custom plots, these array properties are set in two ways: line and point colours are automat-
ically picked from a sequence of 15 colours including black while other properties such as line
width, point size and where appropriate, rim colour and size, are recycled from the list associ-
ated with the various keywords such as lineWidth, pointSize, rimColor and rimFactor. The
principle here is that some properties such as lineWidth are often constant within a given plot
and so it would be tedious to specify them for each line. Hence properties such as these only
need to be specified once and are then recycled.
However, it is often desirable to colour each line separately (within reason) and so here a
longer list is recycled. There is always a default and ordered list of colours associated with the
plotted lines but specific colours can be promoted to the top of the list to ensure that they are
used first. Four of these colour lists or sequences are stored, one for points (symbols), one for
lines, and one each for their 2y counterparts.
Lines of a particular dataset are always plotted before the points. This ensures that the points
will overwrite the lines.
The ways that these colour sequences are used and their interactions are controlled by three
keywords: pointsSameColor (ensures points have the same colours as any associated lines),
changeColor (individual datasets are plotted with different colours as far as possible), and
restartColorSequence – if true, restarts the auto-generated color sequence for each new plot
and for each new plot type (lines, points).
Colours from custom plots are stored in the line colour dictionary. This can be edited to
change the line and symbol properties (see useLineColorDictionary).
With contour plots, the properties of each contour are derived from a corresponding list, e.g.
contourLineColor.
Fill colours used in predominance diagrams are also automatically selected from a colour
sequence but unlike line and point colours cannot be preset. They can however be changed by
editing the fill colour dictionary and replotting.
While the colours used are always stored with their Cohort colour names, the rendered colours
may be changed if the grayscale or black & white colour models are used.
Details about how to add additional text to a plot and how to format numbers is given in Sec-
tion 7.12.

7.9.2 The colour palette

Colours are defined using the Cohort rgb colour palette (Cohort Software, 2004). This has 14
base colours, each one with 10 shades of increasing colour density or darkness (Figure 7.3)
plus ‘black’, ‘white’ and ‘nd’ (for ‘not drawn’). The base colours are centered on number 4,
e.g. ‘red4’ is pure red. Numbers from 3 to 0 have increasing amounts of white in them while
numbers from 5-9 have increasing amounts of black in them. Therefore ‘red0’ is the palest red
(more like a pink) and ‘red9’ the darkest red. Colour names are not case sensitive.
A null colour string, ‘’, is interpreted as ‘take the next auto colour’ and so is different from
‘nd’.

If a colour name is not recognised, then black or white are used depending on the context
 Plotting basics 89

(black for text and lines; white for fills).

Figure 7.3. The Cohort colour palette used by PhreePlot (Cohort Software, 2004).

The actual colour of the plotted lines, fills and symbols will depend on the colorModel setting:
rgb for colour, gray for grayscale and b&w for black and white.

7.9.3 Automatic or explicit

The colour of text, symbols and lines can be explicitly specified in the input files. If this is not
done, PhreePlot will choose its own colours according to a set of rules. These are described
below. The colours used in the plots can be changed without recalculating the original plot.
This is done either by specifying or changing the relevant attribute in the input file or editing
one of the colour dictionaries and then re-running the problem with calculationMethod set to
2 (just replot) or 3 (reprocess and replot).

7.9.4 The colour dictionaries

There are two colour dictionaries which control the placement of labels and the colour of fills
and lines. The location of these is specified by the fillColorDictionary and lineColorDiction-
ary settings in the input files. Both files are automatically created and maintained by
PhreePlot but can be edited to change their settings, e.g. the colours, or in the case of the line
colour dictionary, the placement of the labels in a custom plot (repositioning/removing labels
in a predominance plot is achieved by nudging or editing the labels file).
The dictionaries are read in free format in the same way as the input files. The species name
can contain blank characters if embedded in single or double quotes. If the labels appear to be
chemical formula in Phreeqc format, sub- and superscripts are substituted as appropriate.
If the dictionaries are not present, then they will be automatically created with the name spec-
ified. Default names are ‘fillColor.dat’ and ‘lineColor.dat’.

Fill colours

The fill colours are used for the area fills of predominance plots and the line colours are used
for the lines in custom plots including fit plots. By default and in the absence of a fill colour
dictionary, or when the species is absent from the dictionary, the colour fill is chosen from a
sequence of pale colours (starting at sky1...). These default colours are overruled by settings in
the fill colour dictionary. The fill colour dictionary contains a list of the ‘species’ names (as
returned by Phreeqc) and their corresponding colours.
90 PhreePlot Guide

Line colours and auto line colouring

The line colour dictionary is used for custom and fit plots and contains a list of the label
name, x and y location (in graph coordinates) and colour of the various plotted lines. The col-
ours are only used if the line or symbol is plotted, and by themselves do not dictate whether
this is the case. For example, if a line has zero width or a symbol has zero size, it will not be
plotted.
The line colour dictionary is used or created whenever a custom plot is made. If the file
already exists, then it may be used to determine the line colour associated with a particular
‘species’ if it is present.
The line colour dictionary consists of seven columns of data containing: the label name, x-
and y- plotting positions in graph coordinates and three colours, the first applies to the line
colour, the second to the points colour and the third to the rim colour of filled symbols, for
each label. The last column is the code number for the type of symbol used (pointType), 0 for
no symbol. If a points colour has not been defined, it will be written as a blank field (“”). The
x-position refers to the horizontal centre of the label and the y-position refers to the baseline.
UNDEFINED refers to an undefined (‘not set’) coordinate, e.g. when labels are not plotted. An
empty string (“”) for a colour will force automatic selection of the colour, if necessary. This is
the default when the colour dictionary is rewritten and the when the point or line colour has
not been set.
An example of a line colour dictionary is:

# label x y lines points rims symbol

"Cd+2" 9.7065 48.624 green4 red4 “” 0
"Cd2OH+3" 9.3670 -3.5947 orange4 blue4 “” 1
"CdCl+" 8.1980 2.2705 cyan4 black “” 1
"CdCl2" 8.5480 -3.5722 magenta4 nd “” 0

Whether the settings in these dictionaries are used or overridden in a custom plot is deter-
mined by the useLineColorDictionary and changeColor settings. If useLineColorDictionary
is 0, then the labels and line colours are either taken from the lineColor setting in one of the
input files or are automatically generated. The line colour dictionary is ignored. If useLine-
ColorDictionary is 1 or 2 then the line colour dictionary will be searched for the species being
plotted and if found will use the colour (= 1 or 2) and label position (= 2) from the line colour
dictionary. changeColor determines whether all the curves have the same base colour (=
FALSE) or not (= TRUE). If changeColor is set to FALSE and useLineColorDictionary is 1, then
the line colour dictionary will take precedence.
If the species colour is not found or if useLineColorDictionary is 0, then a line colour will be
automatically selected according to the line colour sequence starting at the top of the list of
colours in effect at the time. The default sequence is:

red
blue
green
orange
cyan
magenta
brown
sky
purple
gray
yellow
maroon
lawn
spring
black

Yellow is not plotted by default as a line or point colour as it is often hard to see (it will be
included if explicitly given a colour density, e.g. yellow4). The sequence specified by this list is
modified by the lineColor settings which promotes the given colour(s) to the top of the 15-
long list. If the number of lineColor’s is greater than 15, the list is extended to accommodate
 Plotting basics 91

all of these. The default lineColor setting in pp.set is ‘auto’ which means the colour
sequence will be red, blue, green, ... as above. If lineColor setting is set to blue, then the
sequence would be: blue, red, green, ... . If the number of colours required is greater than the
length of the list, the list is recycled. If this is not wanted, use the colour dictionary to specify
colours.
Autocolours only consider the basic colors (colors without a number). If the lineColor setting
is red2, red6, black, the autocolour selected for the next (fourth) color would be blue4, the
next unused colour in the sequence.
If a dataset is not plotted because there is no valid data in the plotting domain, then the corre-
sponding auto-generated colour for that dataset is skipped.
If changeColor is set to FALSE and useLineColorDictionary is 0 then the colour(s) in the line-
Color list will be used first (unless this colour is ‘auto’). If there are several subsets of data for
the same variable the actual colour will rotate the colour density, 4, 6, 8, 2, 4..., e.g. red4,
red6, red8, red2, red4,... providing the colour was defined without a density, i.e. as ‘red’
rather than ‘red4’. If a density is given, this colour will always be used.
With calculationMethod 2 or 3 (replot), PhreePlot uses the dictionary coordinates if present
otherwise it omits the label. Use this to change the colour or position of labels, lines and mark-
ers. Use calculationMethod 1 to regenerate a fully populated dictionary.
When there are several plots produced per run, for example due to use of the loop variable,
there is an option of whether to restart the auto-generated colour sequence at the beginning
for each plot, or whether to continue where the colour sequence ended on the previous plot.
This is controlled by the restartColorSequence keyword. TRUE will restart it, FALSE will not.
If the trackSymbolSize is greater than zero and trackSymbolColor is not ‘nd’ then a coloured
track symbol or anchor point is drawn at the point on the line to which any automatically
positioned labels have been associated. This symbol is not drawn on replots.
The x,y position of the label placement is calculated by PhreePlot when calculationMethod 1
(calculate) although whether this position is actually used is determined by the various settings
described above. The position is always read from the file when calculationMethod 2 or 3
(replot) is used.
The line colour dictionary is always updated with the latest species and colours at the end of
each plot and the results written to the dictionary file at the end of each run.
If a record from a colour dictionary cannot be read properly, it is ignored.
Line widths are set by the lineWidth setting for each particular line (recycled as necessary).
Negative line widths indicate dashed lines. The appearance of dashed lines is controlled by
their respective dashesPerInch and lineType settings.

Point colours

Points are coloured in the same way as lines except that the initial colour is defined with point-
Color. If pointsSameColor is TRUE, then the points will always have the same colour as the
lines if defined. If the line colour dictionary is present, the second colour setting can be used
to override the automatic selections. Delete or rename the dictionary or set useLineColorDic-
tionary to 0 if this is not wanted.
The interactions between the changeColor and pointsSameColor settings for the automatic
selection of colours (useLineColorDictionary set to 0) are illustrated in Figure 7.4. These
examples can be found in the autocolorn.ppi files found in the demo\Phreeqcloooping
directory.

Filled symbols with a different rim colour

Normally points are plotted as simple symbols. However, there are six filled symbols which
can have a separate rim colour. The filled colour is controlled by the points, pointSize, point-