i




 
 
  







 "
*
% $%+


$

,.
$

$
#

%%




'

(&

  
$
!"




&$$


&

,.
%



  %$&
%

 "

$
%


&$


&$




 ,.
" ) 

 

  % &
$%

   
 %%
 $


 
  $  ,.


$&
( 
"

 $  ,.


 % $
 




&
,%

  (& $% 
$ $&
+-
)

&
 ' $ /
%
"

$ %% '
 $ $$
  "
*


& %+
 



%
$


  $



 %

 
$( 




  %




  
PhreePlot

Creating graphical output with PHREEQC

David G Kinniburgh
http://www.phreeplot.org

David M Cooper
Centre for Ecology and Hydrology, Deiniol Road, Bangor, Gwynedd, LL57 2UW, UK

June 2011

Last updated March 21, 2012

ii PhreePlot Guide
 iii

Table of contents

1 INTRODUCTION ............................................................................................. 1
1.1 What does PhreePlot do?............................................................................ 1
1.2 What you need to know before using PhreePlot ......................................... 2
1.3 Navigating this document .......................................................................... 2

2 INSTALLATION ................................................................................................ 5
2.1 Installing PhreePlot .................................................................................... 5
2.1.1 Windows .............................................................................................. 5
2.1.2 Windows Vista and Windows 7 ........................................................... 5
2.1.3 Running under Linux ........................................................................... 6
2.1.4 Running on Mac OS X machines ......................................................... 6
2.2 Installing GPL Ghostscript and GSview ..................................................... 6
2.3 Setting the file paths, environment variables and permissions..................... 7
2.3.1 Ghostscript ........................................................................................... 7
2.3.2 Specifying the input file name on the command line ............................ 7
2.3.3 Specifying input and output filenames in PhreePlot input files ............. 8
2.3.4 Setting the PhreePlot environment variable .......................................... 8
2.3.5 Setting file paths using the ‘path’ environment variable ........................ 9
2.3.6 Search path for files .............................................................................. 9
2.3.7 Ensuring that the correct databases are found ....................................... 9
2.4 Other useful software ................................................................................. 9
2.5 Trouble-shooting ..................................................................................... 10
File conversions ................................................................................. 10
Problem and bug reporting................................................................ 11

3 GETTING STARTED ....................................................................................... 13

3.1 The command line interface and batch processing ................................... 13
3.2 Running the demo examples .................................................................... 13
3.3 The ‘pp.log’ file........................................................................................ 14
3.4 Examining the results of the run............................................................... 15
3.5 Making a working directory ..................................................................... 15
3.6 Getting familiar with the options ............................................................. 15
3.7 Using batch files to run a set of examples ................................................. 16

4 PHREEQC BASICS ....................................................................................... 17

4.1 Online PHREEQC documentation ......................................................... 17
4.2 How PHREEQC interacts with PhreePlot ............................................... 17
4.3 Thermodynamic databases ....................................................................... 18
4.4 Types of output produced by PHREEQC................................................ 18
4.5 The SELECTED_OUTPUT file and the USER_PUNCH data block ........................... 19
4.5.1 The SELECTED_OUTPUT filename and forcing the file to be written ......... 19
4.5.2 Scope of PHREEQC keywords .......................................................... 20
iv PhreePlot Guide

4.5.3 What is sent to the SELECTED_OUTPUT file? ............................................ 21

4.6 Setting up the SELECTED_OUTPUT file for input to PhreePlot ....................... 22
4.6.1 Possibilities for looping of PHREEQC input files .............................. 22
Predominance plots .......................................................................... 22
Data-led calculations......................................................................... 24
Custom plots .................................................................................... 24
Knowing which minerals might form using the given database ......... 26
4.6.2 Setting up a loop file .......................................................................... 27
4.7 Running PHREEQC without any plotting.............................................. 28
4.8 Include files ............................................................................................. 28
4.8.1 Use of ‘include’ files ........................................................................... 28
4.8.2 Supplied include files ......................................................................... 28

5 PHREEPLOT INPUT AND OUTPUT FILES ........................................................ 31

5.1 Input/output files .................................................................................... 31
5.2 Input files ................................................................................................ 31
5.2.1 Different types of input file ................................................................ 31
5.2.2 Structure of the main input files ......................................................... 32
5.2.3 Format of all input files ...................................................................... 33
Physical and logical lines ................................................................... 33
Specifying keyword-value pairs and keyword-lists ............................. 34
Format of keywords and their associated values................................. 34
5.2.4 Data separators and parsing input files ............................................... 34
5.2.5 Case sensitivity of input ..................................................................... 35
5.2.6 Reporting of errors in input files ........................................................ 35
5.3 Tags......................................................................................................... 36
5.3.1 What are tags used for? ...................................................................... 36
5.3.2 Rules for choosing tag names ............................................................. 36
5.3.3 Tag expressions .................................................................................. 36
5.3.4 Numeric tag expressions and available functions ................................ 36
5.3.5 Tags for character variables ................................................................ 37
5.3.6 System tags ........................................................................................ 37
5.3.7 User-defined tags ............................................................................... 38
5.3.8 The scope of tags, their initial values and their order of evaluation ..... 39
5.3.9 Examples of the use of tags ................................................................. 40
5.4 Output files ............................................................................................. 41
5.4.1 Output files produced ........................................................................ 42
5.4.2 The logical switches ........................................................................... 43
5.4.3 ‘log’ file (log) ..................................................................................... 44
5.4.4 ‘out’ file (out) ..................................................................................... 44
5.4.5 ‘track’ file (trk) .................................................................................. 45
5.4.6 ‘points’ file (pts) ................................................................................ 45
Predominance plot calculations (ht1 only) ........................................ 45
Other calculations............................................................................. 45
5.4.7 ‘vectors’ file (vec) ............................................................................... 45
5.4.8 ‘polygon’ file (pol) .............................................................................. 46
5.4.9 ‘labels’ file (labelFile) .......................................................................... 46
5.4.10 ‘ppa’ export file (ppa) ......................................................................... 47
5.4.11 Other output files .............................................................................. 47
5.5 Inserting plot files into Microsoft Word, Powerpoint and other software. 48
5.6 Speed of computations and plotting ........................................................ 49
 v

6 RUNNING PHREEPLOT ................................................................................. 51

6.1 Conventions for data input ...................................................................... 51
6.1.1 Types of variables ............................................................................... 51
6.1.2 PHREEQC notation for chemical formulae ....................................... 51
6.2 PhreePlot Looping ................................................................................... 52
6.2.1 Loop variables and their use ................................................................ 52
6.2.2 An example of the use of various looping mechanisms ........................ 53
Using the <x_axis> tag....................................................................... 53
Using the <loop> tag ......................................................................... 54
Using a loop file ................................................................................ 55
Using the ‘simulate’ calculationMethod............................................. 55
Looping over two variables ................................................................ 56
6.2.3 Looping in multi-simulation input files .............................................. 57
Introduction...................................................................................... 57
Basic structure of a multi-simulation PHREEQC input file .............. 57
6.2.4 Defining the expected output in the selected output file ..................... 59
6.3 Possible types of calculations and plots..................................................... 59
6.4 Preparing the SELECTED OUTPUT file................................................ 60
6.4.1 Normal behaviour .............................................................................. 60
6.4.2 The use of the ‘headings’ identifier ..................................................... 60
Controlling the plotting of individual columns.................................. 62
Use of labels in a custom plot and the minimum text size.................. 62
6.5 Debugging ............................................................................................... 63
6.5.1 Types of problem ............................................................................... 63
6.5.2 General approach to debugging .......................................................... 63
6.5.3 Using the debug keyword .................................................................... 64
6.5.4 The most common reason for a failure to converge ............................. 65
6.5.5 Changing PHREEQC’s convergence parameters ................................ 67
6.6 Interrupting execution and changing keyword values ............................... 67
6.7 Running the standard PHREEQC examples ............................................ 68
6.7.1 Going round for just one iteration ...................................................... 68

7 PLOTTING BASICS ......................................................................................... 69

7.1 Introduction............................................................................................. 69
7.2 Types of plot............................................................................................ 69
7.3 Summary of basic plotting........................................................................ 69
7.3.1 Introduction ....................................................................................... 69
7.3.2 Setting up the plotting area ................................................................ 69
7.3.3 Setting up the axes scales and tick marks ............................................ 70
7.3.4 Axis numbering and annotation ......................................................... 70
7.3.5 Adding fills, lines and points .............................................................. 71
7.4 Controlling the colour of lines and symbols in Custom plots ................... 71
7.4.1 The default colour sequence for lines and symbols .............................. 71
7.4.2 Lines ................................................................................................... 72
Automatic colouring.......................................................................... 72
7.4.3 Symbols .............................................................................................. 72
7.5 Labelling plots.......................................................................................... 73
7.5.1 Label names and label position ........................................................... 73
7.5.2 Legend ............................................................................................... 74
7.6 Inputting text strings................................................................................ 75
7.6.1 Available fonts and character sizes ....................................................... 75
vi PhreePlot Guide

7.6.2 Available characters ............................................................................ 75

7.6.3 Text enhancements including Greek characters .................................. 76
7.6.4 Justification ........................................................................................ 77
7.6.5 Angle ................................................................................................. 77
7.7 Special PhreePlot variables or tags............................................................ 77
7.7.1 Available tags ..................................................................................... 77
7.8 Axis scaling .............................................................................................. 78
7.8.1 Auto or user-defined axis scaling ........................................................ 78
7.8.2 Secondary y axis (the 2y axis) ............................................................. 78
7.9 Controlling the properties of text, symbols, polygon fills and lines .......... 79
7.9.1 Principles ........................................................................................... 79
7.9.2 The colour palette .............................................................................. 80
7.9.3 Automatic or explicit ......................................................................... 81
7.9.4 The colour dictionaries ...................................................................... 81
Fill colours ........................................................................................ 81
Line colours and auto line colouring ................................................. 81
Point colours..................................................................................... 83
Filled symbols with a different rim colour ......................................... 84
7.9.5 Directories for the colour dictionaries ................................................ 84
7.10 Labelling.................................................................................................. 84
7.10.1 Predominance plots ........................................................................... 84
7.10.2 Contour plots .................................................................................... 84
7.10.3 Custom plots ..................................................................................... 84
7.11 Replotting without recalculating.............................................................. 85
7.11.1 The ‘replot’ option ............................................................................. 85
7.11.2 The ‘reprocess and replot’ option for predominance plots .................. 86
7.12 Adding extra lines, symbols and text ........................................................ 87
7.12.1 Lines and symbols .............................................................................. 87
7.12.2 Text ................................................................................................... 88
<input>............................................................................................. 90
<loop> or <loop...> ........................................................................... 90
<legend> ........................................................................................... 91
<mainspecies> ................................................................................... 91

8 PREDOMINANCE DIAGRAMS .......................................................................... 93

8.1 setting up a file to calculate a predominance diagram............................... 93
8.1.1 The ‘grid’ and ‘ht1’ approaches .......................................................... 93
Grid approach................................................................................... 93
‘Hunt and track’ approach ................................................................ 94
8.1.2 Using the ht1.inc code to return the dominant species ..................... 95
8.1.3 Optimising the calculation efficiency ................................................. 96
8.1.4 Predominance vs mineral stability diagrams ....................................... 96
8.1.5 Using ht1minerals.inc to determine the minerals present ................ 97
8.2 The ‘grid’ approach ................................................................................. 97
8.3 The ‘Hunt and track’ approach................................................................ 98
8.3.1 Strategy .............................................................................................. 98
8.3.2 Details of the ‘hunt and track’ algorithm ............................................ 98
Applying the concepts of hunting and tracking at the practical level . 98
Definitions of 'predominance' and mineral stability........................ 100
8.3.3 Failure of the ‘hunt and track’ approach ........................................... 101
8.4 Feasible domains and the preparation of Eh (pe) -pH diagrams ............. 101
 vii

8.4.1 General principles ............................................................................. 101

8.4.2 Domain tags - avoiding speciation calculations in part of the predomi-
nance diagram 102
8.4.3 Speciation failure when there is not enough reactant present ............ 103
8.5 Choice of the resolution of the plot........................................................ 103
8.6 Monitoring the progress of a ‘hunt and track’ run .................................. 104
8.7 Plotting and Replotting.......................................................................... 105
8.8 Modifying the appearance of predominance plots .................................. 105
8.9 Adding lines and points to a predominance plot..................................... 106
8.10 Controlling the labelling of plots and the plotting of fields..................... 107
8.11 Failure to complete a predominance diagram ......................................... 107

9 CONTOUR PLOTS........................................................................................ 109

9.1 What are contour plots? ......................................................................... 109
9.2 Implementation ..................................................................................... 109
9.2.1 Generating the contour data ............................................................. 109
9.2.2 Choosing the contour levels .............................................................. 109
9.3 A simple example ................................................................................... 110
9.4 Some details of the data processing......................................................... 112
9.4.1 Algorithm ......................................................................................... 112
9.4.2 Problematic cases .............................................................................. 113
9.5 Modifying the appearance of the plot..................................................... 114
9.6 Refining a plot – replotting without recalculating .................................. 115
9.7 Overlapping or misplaced labels ............................................................. 116
9.8 What happens if PHREEQC fails during contouring calculations?.......... 116

10 CUSTOM PLOTS .......................................................................................... 117

10.1 Overview................................................................................................ 117
10.2 Preparation of the input file ................................................................... 117
10.2.1 Introduction ..................................................................................... 117
10.2.2 Controlling the scope of custom plots .............................................. 118
10.3 Simple looping ....................................................................................... 118
10.4 Modifying the appearance of custom plots ............................................. 119
10.4.1 Overview .......................................................................................... 119
10.4.2 Customising the plot ........................................................................ 120

11 SPECIES PLOTS ............................................................................................ 123

11.1 What is special about a ‘species’ plot? ..................................................... 123
11.2 Modifying the appearance of species plots .............................................. 125
11.3 Adding other variables to a species plot .................................................. 126

12 FITTING AND SIMULATIONS ....................................................................... 127

12.1 Introduction........................................................................................... 127
12.2 Approach to fitting................................................................................. 128
12.3 Practical Setup ....................................................................................... 128
12.3.1 Approach .......................................................................................... 128
12.3.2 Flow of data and information during fitting ..................................... 130
12.3.3 The parameters ................................................................................. 130
12.3.4 Variables ........................................................................................... 132
12.3.5 Passing the fitted values from PHREEQC to PhreePlot .................... 132
One pass to generate a single data value........................................... 132
viii PhreePlot Guide

One pass to generate all data values................................................. 133

12.3.6 Data file ........................................................................................... 133
12.4 The optimization routines ..................................................................... 134
12.4.1 Choice of fit algorithm ..................................................................... 134
12.4.2 Scaling of parameters ....................................................................... 134
12.4.3 Control parameters .......................................................................... 134
Finite difference step size (‘nlls’ only).............................................. 136
Convergence criterion ..................................................................... 136
Maximum step size ......................................................................... 136
Maximum iterations ....................................................................... 136
Weighting method.......................................................................... 136
12.5 Preparing an input file ........................................................................... 137
12.6 Forcing relations between parameter values ........................................... 138
12.7 Response in the event of a failure of PHREEQC to converge ................ 138
12.8 Plotting the results of the fitting ............................................................ 138
12.9 Simulations............................................................................................ 139
12.10 Root finding .......................................................................................... 139

13 THE INPUT FILE PRE-PROCESSOR ................................................................ 141

13.1 Use of the pre-processor......................................................................... 141

14 KEYWORDS ................................................................................................. 143

14.1 Summary of available keywords ............................................................. 143
14.2 Conventions .......................................................................................... 143
14.3 Keyword description.............................................................................. 143
ai ................................................................................................................. 147
axisLineColor .............................................................................................. 147
axisLineWidth ............................................................................................. 148
axisNumberColor........................................................................................ 148
axisNumberSize........................................................................................... 148
axisTitleColor.............................................................................................. 148
axisTitleSize ................................................................................................ 149
backgroundColor ........................................................................................ 149
beep ............................................................................................................ 149
blockRangeColumn..................................................................................... 150
calculationMethod ...................................................................................... 150
calculationType ........................................................................................... 151
changeColor ................................................................................................ 151
characterTags .............................................................................................. 152
colorModel.................................................................................................. 153
contourFillColor ......................................................................................... 153
contourLabelColor ...................................................................................... 154
contourLabelFigs......................................................................................... 154
contourLabelFont........................................................................................ 154
contourLabelSize ......................................................................................... 155
contourLineColor........................................................................................ 155
contourLineWidth ...................................................................................... 155
contours ...................................................................................................... 156
contourShiftLabel........................................................................................ 156
contourZvariable ......................................................................................... 158
convertLabels .............................................................................................. 158
 ix

customLoopManyPlots ................................................................................159
customXcolumn...........................................................................................159
dashesPerInch ..............................................................................................159
database .......................................................................................................160
databaseVersion ...........................................................................................160
dataFile ........................................................................................................160
dataSeparators..............................................................................................161
dateDatabase................................................................................................163
debug...........................................................................................................163
dependentVariableColumnObs....................................................................164
dependentVariableColumnCalc ...................................................................165
domain ........................................................................................................165
dominant .....................................................................................................166
eps ...............................................................................................................166
epsi ..............................................................................................................167
extradat........................................................................................................168
extraSymbolsLines .......................................................................................169
extraText......................................................................................................170
fillColorDictionary ......................................................................................171
FIT ..............................................................................................................172
fitAdjustableParameters................................................................................172
fitConvergenceCriterion ..............................................................................172
fitFiniteDiffStepSize ....................................................................................173
fitLogParameters ..........................................................................................173
fitLowerParameterValues .............................................................................174
fitMaxIterations ...........................................................................................174
fitMaxStepSize .............................................................................................175
fitMethod ....................................................................................................175
fitnpt ...........................................................................................................175
fitParameterNames ......................................................................................176
fitParameterValues .......................................................................................176
fitUpperParameterValues .............................................................................176
fitWeightingMethod....................................................................................177
font..............................................................................................................177
info ..............................................................................................................179
initialValue ..................................................................................................180
jobTitle........................................................................................................180
jpg ...............................................................................................................180
labelColor ....................................................................................................181
labelEffort ....................................................................................................181
labelFile .......................................................................................................182
labels............................................................................................................182
labelSize .......................................................................................................183
legendTitle...................................................................................................183
legendTextSize.............................................................................................184
lineColor, lineColor2y .................................................................................184
lineColorDictionary.....................................................................................185
lines, lines2y ................................................................................................185
lineWidth, lineWidth2y...............................................................................186
log................................................................................................................186
logDepVariable ............................................................................................186
x PhreePlot Guide

logVariableIn............................................................................................... 187
loopFile ....................................................................................................... 188
loopIndexStartNumber ............................................................................... 189
loopInt ........................................................................................................ 189
loopLogVar ................................................................................................. 190
loopMax...................................................................................................... 190
loopMin ...................................................................................................... 191
mainLoop.................................................................................................... 191
mainLoopColumn....................................................................................... 192
mainspecies ................................................................................................. 192
mainLoopColumn....................................................................................... 193
minimumAreaForLabeling .......................................................................... 193
minimumYValueForPlotting....................................................................... 194
missingValue ............................................................................................... 194
multipageFile .............................................................................................. 194
nameSpeciationProgram.............................................................................. 195
numberOfFitParameters.............................................................................. 195
numericTags................................................................................................ 196
onePass........................................................................................................ 196
out .............................................................................................................. 197
pageOrientation .......................................................................................... 198
paperSize ..................................................................................................... 198
pdf .............................................................................................................. 199
pdfMaker .................................................................................................... 199
PhreePlotVersion......................................................................................... 200
PLOT ......................................................................................................... 200
plotFactor.................................................................................................... 200
plotFrequency ............................................................................................. 200
plotTitle ...................................................................................................... 201
plotTitleColor ............................................................................................. 201
plotTitleSize ................................................................................................ 201
png.............................................................................................................. 202
pointColor, pointColor2y ........................................................................... 202
points, points2y........................................................................................... 203
pointsSameColor......................................................................................... 203
pointSize, pointSize2y ................................................................................. 204
pointType, pointType2y ............................................................................. 204
pol............................................................................................................... 204
post ............................................................................................................. 205
postSize ....................................................................................................... 206
ppa .............................................................................................................. 206
pplog ........................................................................................................... 207
printScreenFrequency.................................................................................. 207
ps ................................................................................................................ 207
pts ............................................................................................................... 208
pxdec........................................................................................................... 208
pxmajor....................................................................................................... 208
pxmax ......................................................................................................... 209
pxmin.......................................................................................................... 209
pxminor ...................................................................................................... 209
pydec, p2ydec.............................................................................................. 209
 xi

pymajor, p2ymajor.......................................................................................210
pymax, p2ymax............................................................................................210
pymin, p2ymin ............................................................................................210
pyminor, p2yminor......................................................................................211
resolution.....................................................................................................211
restartColorSequence ...................................................................................212
rewriteInputFile ...........................................................................................213
rimColor......................................................................................................213
rimFactor.....................................................................................................213
screen...........................................................................................................214
selectedOutputFile.......................................................................................214
selectedOutputLines ....................................................................................215
simplify........................................................................................................216
skip ..............................................................................................................216
SPECIATION.............................................................................................217
speciationProgram .......................................................................................217
speciationProgramVersion ...........................................................................217
startTemperature .........................................................................................217
tickColor .....................................................................................................218
tickSize ........................................................................................................218
trackSymbolColor........................................................................................218
trackSymbolSize...........................................................................................219
trk................................................................................................................220
units.............................................................................................................220
updateFitParameters ....................................................................................220
useLineColorDictionary...............................................................................221
vec ...............................................................................................................221
weightColumn.............................................................................................222
xaxisLength..................................................................................................222
xmax ............................................................................................................222
xmin ............................................................................................................222
xoffset ..........................................................................................................223
xtitle ............................................................................................................223
yaxisLength..................................................................................................224
ymax ............................................................................................................224
ymin ............................................................................................................224
yoffset ..........................................................................................................224
yscale ...........................................................................................................225
ytitle, 2ytitle.................................................................................................225

15 EXAMPLES ................................................................................................... 227

Predominance plots (grid approach).................................................................................. 228
1 Fe-H2O (grid approach) ....................................................................................... 230
2 Cu-S-C (‘island’ found with ‘grid’) ....................................................................... 234
Predominance plots (ht1 approach) .................................................................................. 237
3 Fe-H2O (‘Hunt and track’ approach) ................................................................... 238
4 Fe-H2O: close-up (predominance criterion) ......................................................... 240
5 Fe-H2O: close-up (stability criterion) ................................................................... 242
6 Fe-H2O (pe scale)................................................................................................. 244
7 Fe-H2O (Eh scale) ................................................................................................ 246
8 As-O2(g)-H2O...................................................................................................... 248
xii PhreePlot Guide

9 As-O2(g)-H2O (sub-dominant)............................................................................. 250

10 Fe-As-C-S ............................................................................................................. 252
11 Fe-As .................................................................................................................... 256
12 Fe-As-Hfo (ht1.inc) .............................................................................................. 258
13 Fe-As-Hfo (ht1c.inc)............................................................................................. 260
14 Fe-S-As (without sorption).................................................................................... 262
15 Fe-S-As (low Fe, without surface speciation) ......................................................... 266
16 Fe-S-As (goethite, CD-MUSIC) ........................................................................... 270
17 Fe-As-S (high Fe) .................................................................................................. 274
18 Fe-CO2-SO4-H2O with sample points.................................................................. 278
19 Fe-Ni-S................................................................................................................. 282
20 Fe-Zn-C-H2O (HFO) .......................................................................................... 286
21 Fe-Zn-C-H2O (HFO) .......................................................................................... 290
22 Ca-Fe-Na-X-HFO (adsorption and ion exchange) ................................................ 294
23 Acid mine drainage ............................................................................................... 298
24 AMD (carbon)...................................................................................................... 302
25 Ca-Mg-Zn-CO3 ................................................................................................................................................. 306
26 U-CO3 ..................................................................................................................................................................... 310
27 Ca-Mg-CO3 at high T .......................................................................................... 312
28 P-Ca-Mg-CO3(aq)................................................................................................ 314
29 P-Ca-Mg-CO3 (with solids) .................................................................................. 316
30 Mn-CO2-H2O (no minerals) ................................................................................ 320
31 Mn-H2O (with minerals)...................................................................................... 322
32 Mn-CO2-H2O...................................................................................................... 324
33 Pu-F-H2O ............................................................................................................ 326
34 U-C-H2O (wateq4f.dat) ....................................................................................... 328
35 U-C-H2O (NAPSI) .............................................................................................. 330
36 U-C-H2O (llnl.dat)............................................................................................... 332
37 U-Fe-C-H2O ........................................................................................................ 336
38 U-Fe-C (risk colours)............................................................................................ 340
39 U-F-P (U)............................................................................................................. 344
40 U-F-P (F).............................................................................................................. 348
41 U-F-P (P).............................................................................................................. 350
42 Cu-S-C (‘island’ not found with ‘ht1’) .................................................................. 352
43 Cu-S-C (simplification factor = 1) ........................................................................ 354
44 Cu-S-C (simplification factor = 3) ........................................................................ 358
45 Cu-EDTA-H2O ................................................................................................... 362
46 Ca-F-P-C-H2O..................................................................................................... 364
47 Ni-S-C-H2O......................................................................................................... 366
48 Zn-S-C-H2O ........................................................................................................ 370
49 Cd-S-C-H2O ........................................................................................................ 374
50 Pb-S-C-P-H2O ..................................................................................................... 376
51 Sb-S ...................................................................................................................... 380
52 Se-S ...................................................................................................................... 384
53 Clay mineral stability diagram............................................................................... 386
Custom plots..................................................................................................................... 389
54 Gibbsite solubility vs pH....................................................................................... 390
55 Acid titration of groundwater (using ‘REACTION’) ............................................ 394
56 Acid titration of groundwater (using PhreePlot looping)....................................... 396
57 Redox sequence..................................................................................................... 398
58 Kd’s for trace metals as a function of pH............................................................... 402
59 Cd speciation vs pH.............................................................................................. 406
60 Zn-HFO: %sorption vs pH curves........................................................................ 410
61 Zn-HFO: Surface speciation ................................................................................. 414
62 As-HFO: reduction in surface area........................................................................ 418
 xiii

63 CD-MUSIC: As(III) adsorption on goethite......................................................... 422

64 CD-MUSIC: As(V) adsorption on goethite .......................................................... 426
65 Kinetics of pyrite oxidation................................................................................... 430
66 Kinetics of quartz dissolution................................................................................ 434
67 Symbols and lines ................................................................................................. 436
68 Varying symbols and lines in plots........................................................................ 438
69 Text...................................................................................................................... 442
70 Simple PHREEQC looping.................................................................................. 444
71 PHREEQC mineral species .................................................................................. 448
Species distribution plots .................................................................................................. 450
72 Cd speciation vs pH (species plot) ........................................................................ 452
73 Cd speciation vs pH (log species plot) .................................................................. 456
74 U species plot (oxidizing)...................................................................................... 458
75 U species plot (reducing) ...................................................................................... 460
76 Carbon speciation vs pH ...................................................................................... 462
77 CD-MUSIC: As(V) surface speciation on goethite ............................................... 464
78 Test plot output formats....................................................................................... 468
Fitting models to data ....................................................................................................... 470
79 Langmuir isotherm (1) ......................................................................................... 472
80 Langmuir isotherm (n) ......................................................................................... 476
81 Langmuir isotherm (pre-processor) ....................................................................... 482
82 Ni sorption by goethite......................................................................................... 486
83 As(V) sorption on hydrous ferric oxide ................................................................. 490
Contour plots ................................................................................................................... 493
84 Contour two metals at three resolutions ............................................................... 494

16 THE WATEQ4F.DAT DATABASE ................................................................... 497

1 Ag......................................................................................................................... 500
2 Al ......................................................................................................................... 502
3 As ......................................................................................................................... 504
4 B .......................................................................................................................... 506
5 Ba......................................................................................................................... 508
6 Br ......................................................................................................................... 510
7 C .......................................................................................................................... 512
8 Ca ........................................................................................................................ 514
9 Cd ........................................................................................................................ 516
10 Cl ......................................................................................................................... 518
11 Cs......................................................................................................................... 520
12 Cu ........................................................................................................................ 522
13 F........................................................................................................................... 524
14 Fe ......................................................................................................................... 526
15 Fulvate.................................................................................................................. 528
16 I............................................................................................................................ 530
17 K .......................................................................................................................... 532
18 Li.......................................................................................................................... 534
19 Mg ....................................................................................................................... 536
20 Mn ....................................................................................................................... 538
21 N.......................................................................................................................... 540
22 Na ........................................................................................................................ 542
23 Ni......................................................................................................................... 544
24 P........................................................................................................................... 546
25 Pb......................................................................................................................... 548
26 Rb ........................................................................................................................ 550
27 S ........................................................................................................................... 552
xiv PhreePlot Guide

28 Se.......................................................................................................................... 554
29 Si .......................................................................................................................... 556
30 Sr .......................................................................................................................... 558
31 U .......................................................................................................................... 560
32 Zn......................................................................................................................... 562
References ......................................................................................................................... 563
Acknowledgements............................................................................................................ 564
Appendix 1. Glossary of terms........................................................................................... 566
Appendix 2. Thermodynamic databases ............................................................................ 568
Appendix 3. Symbol numbers and names.......................................................................... 580
 Introduction 1

1 Introduction

1.1 WHAT DOES PHREEPLOT DO?

PhreePlot makes it possible to produce certain types of high quality geochemical plots using
PHREEQC (Parkhurst and Appelo, 1999). PHREEQC is a popular and freely-available pro-
gram for calculating geochemical speciation and mass transport. It has a very flexible input
structure that makes it easy to customise the type of calculations performed. This includes the
ability to modify the thermodynamic database used. It also has a very flexible mechanism for
outputting the results of these calculations which makes it straightforward for programs such
as PhreePlot to interface with it.
Originally PHREEQC did not including any charting options but these were added in an
early offshoot from PHREEQC, PHREEQC for Windows (Post, 2011), and have now been
incorporated in the latest Windows version of PHREEQC (Version 3). These versions make
use of the internal looping provided by PHREEQC through keywords such as REACTION and
TRANSPORT. The ‘custom’ plots of PhreePlot provide a similar capability. These ‘official’ ver-
sions of PHREEQC do not contain the specialised processing used to make predominance
diagrams and contour plots, or to do fitting.
PhreePlot contains an embedded version of PHREEQC (Charlton and Parkhurst, 2011).
This includes most of the functionality of the batch version of PHREEQC. PhreePlot sits on
top of PHREEQC and makes it relatively straightforward to do repetitive PHREEQC calcu-
lations, the type of calculations that are often needed to make a plot. PhreePlot uses tags
placed within the PHREEQC input file to identify places where substitutions are to be made
and has several looping mechanisms to control the values substituted. It also contains software
for generating Postscript plot files. If Ghostscript and GSview are installed then automatic
conversion to pdf, png, jpg, ai, eps and epsi formats is possible, as well as viewing of the
natively-generated ps files. In addition to normal PHREEQC-type calculations, PhreePlot
can be used to generate predominance diagrams and contour plots, and to fit observations to
PHREEQC models by nonlinear least squares.
One feature of PhreePlot is the ability to calculate predominance and mineral stability dia-
grams, often known as Eh-pH or pe-pH diagrams, using both a ‘brute force’ or ‘grid’ approach
and a novel ‘hunt and track’ approach which focuses on tracking the internal boundaries (Kin-
niburgh and Cooper, 2004). These approaches use PHREEQC to calculate a full speciation
throughout the diagrams. This numerical approach avoids many of the limitations and
approximations of the more traditional analytical approach adopted by other software, such as
the Geochemist’s Workbench (Bethke, 2005). One of the advantages of the numerical
approach is that reactions that do not obey the classical speciation model can also be included
in the diagrams. This includes adsorption, ion exchange and co-precipitation reactions. Since
a full speciation is undertaken, the impact of all interactions are automatically taken into
account and the results are fully consistent with those of other speciation and reaction path
calculations undertaken with the same databases.
The intellectual ‘penalty’ is that realistic and solvable reaction paths have to be devised to map
the whole of the activity space of interest. The practical penalty is that the large number of
computations required means that the numerical approach is significantly slower than the ana-
lytical approach.
While the ‘hunt and track’ approach usually requires considerably fewer speciation calcula-
tions than the ‘grid’ approach to produce a diagram of equivalent quality, it makes the
2 PhreePlot Guide

assumption that all fields can be reached in some way by tracking along the boundaries start-
ing from a domain boundary. This is not necessarily the case and so fields can be missed1. This
appears to be relatively uncommon in practice but is nevertheless an important limitation of
the ‘hunt and track’ approach. The ‘grid’ approach makes no such assumption and so should
always be the final arbiter.
A somewhat different way of looking at predominance diagrams is to ‘contour’ the data for
some diagnostic variable such as the total dissolved amount or concentration of some element.
PHREEQC is very flexible in the way that it can define its output and this is translated into a
great flexibility in the variables that can be contoured.
PhreePlot uses PHREEQC to generate text and graphical output for plotting using a slightly
modified PHREEQC-format input file. PhreePlot includes added features such as simple
looping which make it easier to generate a wide range of graphical output from PHREEQC,
the motivation being that graphical output can often convey information more effectively
than raw tables and text. PhreePlot can also fit PHREEQC models to user-supplied data
(observations), again in an environment that is fully consistent with other calculations made
with the software. Several optimization routines are available for this.
PhreePlot makes use of the PSPLOT Postscript library (Kohler, 2005) to produce high qual-
ity Postscript plot files. These can be edited, printed or converted to other graphical formats
using various software packages, e.g. GPL Ghostscript/GSview, Adobe Illustrator, Inkscape,
CorelDRAW, The GIMP, etc.

1.2 WHAT YOU NEED TO KNOW BEFORE USING PHREEPLOT

PhreePlot currently only runs on the Windows operating system. It contains iPHREEQC, an
embedded form of PHREEQC, and so does not need another copy of PHREEQC. However,
it will be necessary to have an up-to-date version of PHREEQC available for the documentation,
release notes, licence conditions and other information.
The plotting part of PhreePlot uses as input the output from PHREEQC, as communicated
through its ‘selected output’ file. PHREEQC provides very versatile facilities for writing these
files. Therefore it is necessary to be fairly competent at running PHREEQC in the normal
way and of manipulating the selected output file. If you are not, follow the documentation
provided with PHREEQC and study the examples included in that manual carefully, initially
choosing the one closest to your needs as a template. The demos included with PhreePlot also
provide examples and templates for many types of plot.
Since PHREEQC includes a BASIC interpreter for customising output to the selected output
file, some knowledge of BASIC programming is useful. A careful study of the demo examples
provided here should give an introduction to this and will provide example of the link to
PhreePlot.

1.3 NAVIGATING THIS DOCUMENT

This Guide is primarily intended for online browsing not for printing. There are several aids
to help navigate around the document using Adobe Reader. Some tips for navigating the doc-
ument are given below though these may vary slightly depending on the version of Adobe
Reader used.
A roadmap to the documentation can be seen by enabling the bookmarks for this document
in Adobe Reader. If these bookmarks cannot be seen, toggle them on by clicking the book-
mark icon or on the left-hand side of the Reader window or go through the menu
system and tick the View|Navigation Panels|bookmarks item.
Various hyperlinks are available within the Guide including links to all of the keywords used

1.Thanks to Hans Meeussen for pointing this out.

 Introduction 3

in the text. These link to the corresponding description in the Keywords section (Section 14).
All links appear in blue text and are underlined. Hyperlinks are indicated by the cursor chang-
ing to a pointed finger when hovering over the link.
You can navigate over your navigation history in one of three ways: (i) use the or
toolbar icons; (ii) use the Alt+Left arrow. to go backwards; Alt+Right arrow navigates
forward again, or to go backwards (iii) use the Previous View item from the right click (con-
text) menu. If the toolbar icons are not already visible in Adobe Reader, activate them with the
Tools|Customize Toolbars|Page Navigation Toolbar dialog or similar.
4 PhreePlot Guide
 Installation 5

2 Installation

2.1 INSTALLING PHREEPLOT

The latest version of PhreePlot for Windows XP and later can be downloaded from http://
www.phreeplot.org. The filename for the installer should have the format, setup-pp-sss-
yymmdd-zzzz.exe where sss is the operating system, yymmdd is the date of the PhreePlot build
and zzzz is the PHREEQC Subversion number.

2.1.1 Windows

PhreePlot is available in both 32-bit (win32) and 64-bit Windows (x64) versions. The Win32
version will run in both 32- and 64-bit versions of Windows whereas the 64-bit version will
only run in native 64-bit versions of Windows Vista and Windows 7. The 32-bit and 64-bit
executables both have the same file name, pp.exe, so that the batch files will work for both
versions in a straightforward manner. The banner sent to the screen and log file will indicate
the verison of PhreePlot actually being used.
The installer should be executed and PhreePlot installed to your preferred directory (often
called a ‘folder’). The default directory is a PhreePlot sub-directory in your application data
directory. This can be changed during installation. The installation will create a sereies of sub-
directories in which the PhreePlot files will be installed. However, the program executable
(pp.exe) will always be installed in the Program Files directory, e.g. C:\Program
Files\PhreePlot\ (or in C:\Program Files (x86)\PhreePlot\ when installing the 32-bit
version of PhreePlot on a 64-bit system). You have no control over this.
The following files and directories will be created:
\system
\demo
\doc
where
\system The PhreePlot system directory.
pp.set User-defined initial settings and preferences
override.setany override settings.
ht1.inc PHREEQC USER_PUNCH code to calculate
predominance diagrams.
ht1c.inc As above but combines all adsorbed species for a
given sorbent-element combination.
More inc and other ‘system’ and database files
\demo A directory containing examples (ppi and
associated files), one or more ppi files per
subdirectory (see the Examples Section)
\doc
PhreePlot.pdfThis user guide
changes.pdf List of changes made.

Each of the demo sub-directories contains a specific example, or collection of related examples.
These include a PhreePlot input file and any other input files required. Input filenames gen-
erally have the extension .ppi though this is not necessary. However, if ppi is associated with
the PhreePlot executable during installation, as recommended, then double clicking a ppi file
in Windows Explorer or similar will automatically execute it with PhreePlot. This is the easi-
est way to run PhreePlot.
Spaces in input file names should work but are best avoided. If possible, enclose the filename
in quotes. The search path for the input file follows the normal operating system conventions
although as with most PhreePlot searches, PhreePlot will also search the system directory. In
6 PhreePlot Guide

batch files, the current working directory is the directory from which the batch file originated.
Use the ‘change directory’ (cd ...) command in a batch file to change to a new working
directory if required.
If PhreePlot is having trouble finding the input file, use the full path name including the
drive.
Output files are automatically put in the same directory as the input file using the input file
name minus the extension as the root.
PhreePlot also needs to know where to find certain files such as Ghostscript files when
Ghostscript is installed. It does not use the Windows registry for this and so some file paths
need to be set explicitly. The steps outlined below should be taken to ensure that PhreePlot
knows where to find the necessary files.

2.1.2 Windows Vista and Windows 7

Installing PhreePlot under Windows Vista and Windows 7 requires Administrator rights.
The installer should be executed and PhreePlot installed to your preferred directory.
The PhreePlot executable, pp.exe, does not require Administrator privileges to run. If set,
these should be turned off by opening the Properties dialog for the pp.exe file (right-click the
file), opening the Compatibility tab and unticking the ‘Run this program as an administrator’
tick box. The same should be done for all users by clicking the ‘Show settings for all users’ but-
ton. This should prevent UAC prompts when running PhreePlot.
Batch files such as demo.bat also do not need Adminstrator privileges to run but will need per-
mission to ‘Read & execute’ (set under the Security tab of the file’s properties).

2.1.3 Linux

PhreePlot should be able to be run on x86 Linux machines by using the Wine Windows
‘emulator’ or similar. You will have to specify file names with their full paths, e.g. including
drive and directory, if the input file is not in the current working directory.

2.1.4 Mac OS X machines

PhreePlot has been reported to work on Apple Mac’s with Windows emulators such as Wine
and Parallels.

2.2 INSTALLING GPL GHOSTSCRIPT AND GSVIEW

Ghostscript and GSview are not essential for the proper functioning of PhreePlot but they
provide a convenient way of viewing the Postscript files produced and for converting these to
other graphic formats such as eps, pdf, png, jpg and ai. It is therefore strongly recommended
that they are installed.
Both programs have licence restrictions but Ghostscript is essentially free to use. GSview can
be registered at a nominal price . This avoids having a nag screen displayed on startup and
supports its development.
The latest versions of GPL Ghostscript and GSview can be downloaded from http://
pages.cs.wisc.edu/~ghost/doc/GPL/ and http://pages.cs.wisc.edu/~ghost/gsview/, respec-
tively. Both programs are available in 32- and 64-bit Windows versions. Follow the installa-
tion directions.
After downloading and installing, ensure that the paths containing the executable files and
libraries are added to your path variable so that they can be found from any directory. This is
important since some of the Ghostscript batch files used assume this.
The paths should be updated as newer versions of Ghostscript are installed. The default
installation directories are:
 Installation 7

Ghostscript:

C:\Program Files\gs\gsx.xx\bin
C:\Program Files\gs\gsx.xx\lib
GSview:
C:\Program Files\Ghostgum\gsview

where x.xx is the version number. The name of the Program Files directory may vary with
the operating system and version of software installed, e.g. installing a 32-bit version on a 64-
bit PC will install to the Program Files (x86) directory.
The pdfMaker keyword in PhreePlot should also be set to the location of the ps2pdf14.bat
file, usually something like C:\PROGRA~1\gs\gs8.64\lib\ps2pdf14.bat. This is set in the
pp.set file and so will not need to be set in the individual input files. This is used not only for
pdf production but also the Ghostscript path is used by all of the other file format conver-
sions.
Several of the batch files used internally by Ghostscript check for an environment variable,
GSC, which if present is used to point to the Ghostscript executable. This environment varia-
ble should therefore be set if there is any ambiguity in the location of the Ghostscript execut-
able. Include the full path, e.g. C:\Progra~1\gs\gs8.64\bin\gswin32c.exe.
The file structure used by Ghostscript during installation should be retained since PhreePlot
uses the default structure to search for other Ghostscript files in order to make the conver-
sions. If the pdfMaker keyword is not empty but points to an invalid file, then PhreePlot will
attempt to locate the latest version first using the GSC environment variable if defined, and
then by searching the current drive.
Once the system has been configured and your PC rebooted, running the demo\demo1.bat file
will indicate whether the setup has been successful or not. This should produce example ps,
pdf, png, eps, epsi, jpg and ai plot files.

Ghostscript and GSview are updated quite regularly. If you update, make sure that GSview is
using the latest installed version of Ghostscript (use Options|Easy Configuration in
GSview configure to choose which version to use). It does not point to the latest version auto-
matically.

2.3 SETTING THE FILE PATHS, ENVIRONMENT VARIABLES AND PERMISSIONS

2.3.1 Ghostscript

Installing Ghostscript 8.64

If installed, the Ghostscript path must be added to the Path variable in the System variables
dialog box. In Windows XP, this setting is set manually as follows:
Control Panel | System | Advanced | Environment variables, and in the System vari-
ables dialog highlight and edit the Path variable and add the paths

C:\PROGRA~1\gs\gsx.xx\bin\;C:\PROGRA~1\gs\gsx.xx\lib;C:\PROGRA~1\Ghostgum\gsview

where x.xx is the version number of Ghostscript. Note the use of short filenames to avoid any
possible problems with filenames containing spaces (only usually a problem with older Win-
dows systems). There must not be any spaces following the semi-colons. Reboot after setting.
PhreePlot calls the \gs\gsx.xx\lib\ps2pdf14.bat and \gs\gsx.xx\bin\gswin32c.exe exe-
cutables and so both of these need to be able to be run as executables. A simple test to make
sure that Ghostscript is set up properly is to open a console window and type:

ps2pdf14.bat

If the reply is:

8 PhreePlot Guide

Usage: ps2pdf input.ps [output.pdf]

or: ps2pdf [options...] input.[e]ps output.pdf

then the path to Ghostscript has been recognised and it should work from within PhreePlot.
If the reply is something like:

'ps2pdf14.bat' is not recognized as an internal or external command, operable

program or batch file.

then Ghostscript has not been recognised. Check all the settings and reboot.

2.3.2 Differences between different versions of Ghostscript

Ghostscript is periodically updated. These updates can change both the Ghostscript executa-
bles, gswin32c.exe etc, as well as some of the other ps and batch files files used by Ghost-
script for the file conversions. We have noticed no difference to the quality of the output
based on the changes made to the post-8.64 executables but there have been significant
changes to the batch files. This has made a difference to the way that Ghostscript finds the
various files that it uses, and the way that you must set it up.
The latest versions of Ghostscript are available in 32- and 64-bit versions.
The following are notes on some of the important changes between the 8.64 and 9.04 ver-
sions. These are not intended as a comprehensive description of all the changes.

Version 8.64

This is the version on which most of the testing of PhreePlot has been made (using the Win32
variant) and whose installation is described above. The ps2pdf14.bat file calls the
ps2pdfxx.bat file without a full pathname and so the ...\gs\gs8.64\lib directory must be
specified in your Path. This batch file as well as several others also use gssetsg.bat to locally
set and use the environment variable GSC. It is set simply to ‘gswin32c’. This variable is used to
run the Ghostscript executable (gswin32c.exe) again without any qualification which means
that the ...\gs\gs8.64\bin file also has to be in your Path. The Win32 and x64 versions use
the same name for their executables (gswin32c.exe) which means that both versions can use
the same scripts.

Version 9.04

Many of the batch files now use a more sophisticated method for identifying the location of
files. For example, the LIBDIR environment variable is locally set to the ...\gs9.04\lib direc-
tory and this is used to qualify the location of ps2pdfxx.bat. This means that the lib Path
does not need to be set.
However, the internally-generated GSC environment variable still uses the unqualified
gswin32c to point to the executable. Therefore you must either add the bin directory to your
Path or set the GSC environment variable to the full path using a notation that does not include
spaces, e.g. GSC C:\Progra~2\gs\bin\gswin32c.exe. This can be done either through the
Control Panel or using the setx utility.
The epsi conversion routine ps2epsi.bat has not worked reliably since version 8.71 when the
cat.ps routine replaced the system copy routine. This is because cat.ps does not work with
filenames and paths containing spaces or quoted filenames. 9.04 works fine if there are no
spaces and no quotes. Reverting to the old system copy should work even for filenames con-
taining spaces. This is done by replacing the line
%GSC% -q -dNOPAUSE -dBATCH -P- -dSAFER -dDELAYSAFER -sDEVICE=bit -sOutput-
File=NUL cat.ps

with
copy %outfile% + %infile%
 Installation 9

There has also been a problem since 9.01 in that the Win32 and x64 executables are now
named differently (gswin32.exe and gswin64.exe, respectively). However, the gssetgs.bat
file still sets the name of the executable to gswin32c even for the x64 version. Manually setting
the GSC environment variable explicitly to the fully qualified shortform path should get round
this, e.g. C:\Progra~1\gs\gs9.04\bin\gswin64c.exe.

Version 9.05

This is the latest version of Ghostscript. This has fixed the problem with the gswinxxc/
gssetgs.bat files. The 32- and 64-bit versions now both work fine without setting the GSC
environment variable. The only remaining known problem is the epsi conversion for filena-
mes containing spaces.

The overall conclusion is that the 32-bit 8.64 version is still the preferred version though the
latest version should work without any problems in most cases.

2.3.3 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). If the input file
is not found in the current working directory, PhreePlot searches the sub-directories of the
current working directory, using the ‘dir’ and ‘find’ system commands. Access to these utili-
ties is therefore required (find.exe may not be present with the WINE emulator). Normally
the path to the appropriate Windows directory where these are found is set as standard so that
should not be a problem.
This 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.

2.3.4 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. With the following proviso, filenames can
be any valid filenames under the Windows operating system but special care must be taken
with filenames containing spaces.
IMPORTANT: Long file paths are allowed but if there are embedded spaces in the filepath,
enclose the filepath in quotes. This situation is likely to be encountered when specifying the
pdfMaker filepath for Ghostscript since the Ghostscript home directory by default (since
version 8.51) is the \Program Files directory. If problems occur with such file paths either try
to avoid the use of spaces or use the short (8.3) DOS-style filename that is associated with
each file, e.g. C:\PROGRA~1\PhreePlot\... The appropriate short name can be obtained by
typing dir /x in a console window aimed at the appropriate directory or file, e.g.

C:\>dir \p* /x

will normally bring up the short-name for the C:\Program Files directory.
File paths should also 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 / ? < > \ : * | " ). However, as well as the + sign, the
following characters may also cause problems and are best avoided: , ; % & and a space (as
mentioned above, the filepath has to be within quotes if a space is present in the filepath).
Although Windows XP and later allow long filename extensions, the maximum length of the
10 PhreePlot Guide

extension in PhreePlot is 3 characters. Longer extensions will be truncated and may result in
failure.
File paths are not case sensitive in Windows so any mixture of cases will do. However, what-
ever is entered is preserved in PhreePlot. PhreePlot tends to use lowercase filenames with the
exception that elements follow their normal notation.
Windows uses \ as a separator for its file hierarchy but / will also usually work (there may be
some idiosyncrasies such as cd / and cd \ from a high level directory).

2.3.5 Setting the PhreePlot environment variable

The environment variable, PHREEPLOT, should be set to your PhreePlot directory, i.e. the root
directory containing the system, demo and doc directories such as C:\PhreePlot\. Note the
trailing backslash.
This is the application directory selected during installation and the environment variable will
will normally be set during installation.. You can check that this has been done correctly by
typing ‘set PhreePlot’ in a console window. This will return the directory currently set. If it
is not set correctly, you will have to change it. PhreePlot will not run until this variable is set
properly.
The environment variable can be set manually in a similar way to setting the Ghostscript path
described above but using New under ‘User variables for xxx’ to add the PhreePlot varia-
ble, e.g.:

Variable name PHREEPLOT

Variable value C:\PhreePlot\ your PhreePlot directory.

Similar methods also apply to older Windows systems. The program setx.exe is available to
do this under Vista and Windows 7. It can also be installed for older systems and can be used
to make the necessary changes rather easily. Once set, the ‘demo directory’ for example could
be referred to as %PHREEPLOT%demo in batch files.

2.3.6 Setting file paths using the ‘path’ environment variable

As mentioned above, the Ghostscript lib and bin directories, and the GSview directory
should be added to the Path environment variable if they are not already there. It is also con-
venient if the PhreePlot executable path is included in the Path so that pp.exe can be run
from any directory, e.g. add

C:\PROGRA~1\PhreePlot\;

to the Path variable. This will be automatically done if this option is selected during installa-
tion.
Your PC must be rebooted after these changes have been made.
It is always possible to check that a path has been set correctly by opening a console window
and trying to execute the program or batch file by simply entering the name of the program
without a path, e.g. pp. If it runs from any directory, the path has been set properly.

2.3.7 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 (iv) the path, if any,
defined by the <file> tag.
Finally, if PhreePlot cannot find the specified input (ppi) file, it will use a system search to
search the current directory and all sub-directories. When launching from Windows Explorer,
or similar, the current directory is the directory of the file launched. This can be a batch file in
 Installation 11

which the current directory is changed. This can lead to problems in locating the full path of
the input file if it is not a sub-directory of the launch directory.
If in doubt, include the full path to be absolutely sure. Put in quotes if there is a space in the
name. The naming convention, e.g. whether case is significant follows that of the operating
system. In Windows, case is not significant for file paths.

2.3.8 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
convenience. 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.
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 of dissolution and precipita-
tion reactions.

2.4 OTHER USEFUL SOFTWARE

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

Notepad++ a free and highly capable text editor that includes syntax
highlighting for a large number of file types. If the exten-
sions in the installation file phr_in_NP++.exe are added,
this includes pqi and ppi file types (http://notepad-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 all the other things you have to do)
(http://zabkat.com/index.htm).
Able Batch Converter batch conversion of Postscript files to other image formats
including autocropping and resizing (http://www.graphicre-
gion.com).
CoPlot Flexible and powerful scientific plotting package (http://
www.cohort.com/coplot.html).
R Powerful and well-supported open-source working environ-
ment for data processing including flexible, high quality
graphics (http://www.r-project.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
12 PhreePlot Guide

added and label positions etc changed. Inkscape 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.5 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.
You can check whether your file paths have been set correctly by opening a console, going to
the root directory and typing the name of one of the executable files such as ps2pdf14.bat.
The console is opened by Start|Run|cmd or from a shortcut to something like C:\WIN-
DOWS\SYSTEM32\CMD.EXE. If the executable files run from the root directory, then the file paths
have been set correctly, e.g.

C:\>ps2pdf14.bat

should return

Usage: ps2pdf input.ps [output.pdf]

or: ps2pdf [options...] input.[e]ps output.pdf

Similarly the paths and PhreePlot environment variable can be checked by trying to run the
pp.exe file from the root directory
C:\>pp
Error: no input file specified
Usage: pp <input_file_name>

The values of the environment variables can be viewed by typing set in the console, e.g.
C:\>set

which will return a full set of the environment variables known to your system and their values
including those for the Path and PhreePlot variables. All PhreePlot log files also record
whether a correct Ghostscript path has been found.
Once installed, the demo examples should be run (see Section 3.2).

Problem and bug reporting

Contact David Kinniburgh ([email protected]).

 Getting started 13

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

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.3.3).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
mechansim for plotting multiple curves from different runs in a single custom plot – the out-
put 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.
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 debug 2 just before this will cause the phreeqcall.out file to be created which will
contain a copy of the PhreePlot input and 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, ai, eps, epsi and jpg files if Ghost-
script is installed and so can be used to test that installation.
The output looks something like:
*** PhreePlot 1 *** (10:39:45 17 May 2011)
Incorporating the PHREEQC library by DL Parkhurst, SR Charlton (USGS),
& CAJ Appelo (Amsterdam)
Hunt & Track by DG Kinniburgh, and DM Cooper, CEH (NERC)
Fitting by MJD Powell (University of Cambridge)
Postscript plotting by KE Kohler
14 PhreePlot Guide

Input filename: C:\Program Files\PhreePlot\0.01\demo\test\test.ppi

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
several 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
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
 Getting started 15

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 then PhreePlot will normally 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.3), e.g.

C:\projects\PhreePlot>md FeS2
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
16 PhreePlot Guide

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 EXAMPLES

The demo.bat file illustrates how a set of examples can be run in batch mode. This has obvi-
ous 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 advan-
tage of the separate processors.
It is possible to intersperse other batch commands in a batch file of PhreePlot runs in order to
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 the batch files sequentially.
 PHREEQC basics 17

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 for-
mat. 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 gen-
erate 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 60).
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
sections.
18 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 vari-
ous 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. 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 main-
tains 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 sim-
ulations 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 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 typ-
ically 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 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 fitting that is built into PhreePlot.

4.3 THERMODYNAMIC DATABASES

The standard databases distributed with PHREEQC and PhreePlot include a varied range of
elements 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
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.out and phreeqcall.out files.
 PHREEQC basics 19

(ii) selected output file: the SELECTED_OUTPUT and USER_PUNCH data blocks control tabular out-
put to the selected output file. This is the file normally used by PhreePlot for generating plots
and it is 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 output 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 trans-
port 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, a header line but no output
is produced.
The PHREEQC library used by PhreePlot has switches to control whether the selected out-
put 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 FILE AND THE USER_PUNCH DATA BLOCK

All output communications between PHREEQC and PhreePlot are sent via the selected out-
put file. Therefore it is necessary to ensure that the correct output is sent to this file and to tell
PhreePlot what the format of the selected output 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 the values of the calculationType and selectedOutputLines keywords in
PhreePlot.
Normally PhreePlot uses the last line of the selected output file but this can be changed with
the selectedOutputLines setting.
Selected output will only be provided if the SELECTED_OUTPUT data block is present somewhere
in the PHREEQC part of the input file. It may also be useful to include the -reset FALSE
and -high_precision TRUE identifiers to suppress unnecessary headers and to retain maxi-
mum precision in the output numbers.
The SELECTED_OUTPUT ‘file’ provides the necessary communication between PHREEQC and
PhreePlot. It consists of one or more lines of output and contains an entry for each of the
items ‘punched’ in the USER_PUNCH data block. The -selected_output identifier in the
SELECTED_OUTPUT and PRINT data blocks can be used to selectively suspend and resume writ-
ing results to the selected output file. This is useful to prevent output being sent to the ‘out’
file during pre-loop calculations.
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 varia-
bles 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 data block by checking the
STEP_NO and jumping over any PUNCH statement(s) for which the output is not wanted.

The structure of the selected output file can therefore be as complex as you like but each of the
various calculationTypes in PhreePlot expects a specific format for the selected output file.
These requirements are described in detail in Section 4.6 and in the description of the various
calculation types at the end of this Guide.

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.out’ but this can be
changed using the SELECTED_OUTPUT -file identifier, as normal in PHREEQC. As men-
20 PhreePlot Guide

tioned above, the selected output in PhreePlot is written to a ‘virtual’ file (a block of memory)
and is not necessarily also written to this ‘physical’ file. The writing of the physical file is con-
trolled by debug and the optional second parameter (‘force’) of selectedOutputFile. This will
apply to all selected output files created during the run.
With debug < 2, no physical file is normally produced and so the name of the
file is not required.
SELECTED_OUTPUT

debug > 1 produces a physical file with the given file name. If the ‘force’ parameter of the
selectedOutputFile keyword is set to TRUE, any implicit setting from debug is overridden and
the selected output file will always be written even when debug < 2. There will be small per-
formance 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.
If the specified selected output file exists as a physical file before running a simulation with
PhreePlot, it will be deleted with debug > 1 or ‘force’ set to TRUE. This makes it clear when
no new output has been produced. The file name for the selected output file must be sent to
PhreePlot with the selectedOutputFile keyword – it does not parse the CHEMISTRY section to
find it. If this is set, this ensures that, if present, the file is deleted before it is due to be created.
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.
Unlike in normal PHREEQC, it is not possible to redefine the selected output filename
within a given run of PHREEQC. If a change in the structure of the selected output is
wanted, make sure the simulations involved are run in separate PHREEQC runs (see main-
Loop). The data will still be accumulated in a single outfile.

4.5.2 Scope of PHREEQC keywords

Each PHREEQC simulation consists of a series of keyword data blocks which define the cal-
culations for that simulation. The order of these keywords within a simulation is normally not
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
 PHREEQC basics 21

SOLUTION 4 #Simulation 4
Cd 0.6
END

This produces the following output in the selected.out file when the wateq4f.dat database
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
SELECTED_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. Addi-
tional 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 out-
put 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 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
simulation 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-
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 defi-
nitely preferable when fitting data to models and when calculating predominance diagrams.
The maximum width of any single column is 1000 characters. The maximum total width of a
selected output line is 10,000 characters.
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
SELECTED_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.
22 PhreePlot Guide

(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
executed 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-
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 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

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
 PHREEQC basics 23

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.

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
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
24 PhreePlot Guide

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 optional second parameter to the loopFile to FALSE.

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)

selected output
simulation 4 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 blockRangeCol-
umn. The default value for the simulation is 1 which is the value assumed if no block-
RangeColumn 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
calculations 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
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
 PHREEQC basics 25

mainspecies loop
z-loop

simulation 1 selected output

USER_PUNCH tags
END (last line only)

selected output
pre-loop simulation 2 USER_PUNCH tags
(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.

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
26 PhreePlot Guide

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 fix-
ing 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 ‘auto’. This transfers 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
-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
 PHREEQC basics 27

Knowing which minerals might form using the given database

PHREEQC has no simple way of automatically inserting a valid set of minerals into an
EQUILIBRIUM_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 pos-
sible minerals 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.
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.
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-
28 PhreePlot Guide

(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.

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 cal-
culations which do not require a plot. Setting calculationMethod <0 will suppress any plot-
ting, as will setting plotFactor = 0. If data are to be read from a data file, as in fitting, then the
calculationType = “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
containing analyses of groundwater chemistry. It runs a small PHREEQC include file which
contains 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 CHEMISTRY section of an input file 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. All of the statements in this file will be inserted line by
line at the insertion point. This substitution 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 normal rules for the search path when looking for include files are followed
 PHREEQC basics 29

(Section 2.3.7).
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.
This option is not supported in other parts, i.e. non-CHEMISTRY sections, of the input file.

4.8.2 Supplied include files

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

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
ht1c.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

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.
ht1c.inc is similar except that all adsorbed species of one element and one surface are com-
bined into a single species (a ‘superspecies’) for the purposes of the predominance calculations
(ranking) and for plotting. Other include files are variations on these. See the examples in the
\demo directory for their use.
30 PhreePlot Guide
 PhreePlot input and output files 31

5 PhreePlot input and output files

5.1 INPUT/OUTPUT FILES

PhreePlot uses a number of files for input and output. All but one are in ASCII format (the
points file for predominance plots is binary). 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 logical 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.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.4.

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:

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-
32 PhreePlot Guide

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
somewhere in it the line ‘CHEMISTRY ’. This divides
PhreePlot keywords from PHREEQC-format chemistry, if
any. It is best if it 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
attributes 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 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 produced>
...
CHEMISTRY
...
<PHREEQC-format chemical input which is normal PHREEQC code but with 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.
 PhreePlot input and output files 33

The CHEMISTRY section includes the PHREEQC code. This can only be included in the main
input file. This determines what is calculated and has almost the same format as a normal
PHREEQC input file. There are two principal differences: (i) it can contain ‘include’ state-
ments which pull in code from the specified files, and (ii) 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 pro-
vide placeholders for substituting variable values generated by PhreePlot and give PhreePlot
its ability to loop, fit data to models etc. The earlier section defines how the tag values are gen-
erated and other aspects of the calculations including the plotting of results. The keyword val-
ues can be floating point, integer, character or logical.

5.2.3 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
characters.
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.
Any input following a comment character (#) is ignored. This includes ; and \ (see below).
Blank lines and lines which are entirely made up of a comment are not counted as logical
lines.
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 qutotes 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-blank charac-
ter on a physical line. The use of a comment character takes precedence over the continuation
character, i.e.

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

<pH> = -<logH> # -pH

is valid but

#pdf \
T

is not.
34 PhreePlot Guide

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
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.4 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.3).
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-
 PhreePlot input and output files 35

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.
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 includes 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.5 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 but they may be
under other operating systems, e.g. Linux.
In general terms, things that have been defined by PhreePlot are not sensitive to case whereas
things that you have defined are case sensitive.

5.2.6 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:5:2 (logical 6:2)

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 both the physical line (here line 6) and the logical line (here line 5). An
attempt is also made to signal the position in the file where the error was detected, in the
example above in the second word of the respective line in both cases. The keyword involved
(if known), the line of text where the error was detected and an error message are also given.
These may not identify 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
36 PhreePlot Guide

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.

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
complex 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 char-
acters 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.
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)
<pxmin> the value of pxmin (numeric)
38 PhreePlot Guide

<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).

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.9) 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.
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 per-
formed.
 PhreePlot input and output files 39

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 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.
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
simulations within the block have been completed. PHREEQC has complete control during
this execution 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 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
values 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;

40 PhreePlot Guide

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 ini-
tial 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 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 simula-
tions 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-
 PhreePlot input and output files 41

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
they have already been assigned a value.
Therefore

<site_density_w_per_m2> = <initial_site_density_w_per_g>/
(<initial_specific_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 62.
42 PhreePlot Guide

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 calculations that would otherwise be rather tedious to set up (see Section 6.2 and
Example 70). 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:\phree-
plot\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)
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
ai Adobe Illustrator 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 or contour plot
out tabular output file with accumulated results from the SELECTED_OUTPUT
file used as input by some of the plotting routines.

All files are output as space-delimited ASCII files except the pts file which is a binary file for
predominance plots and an ASCII file for custom, species and fit plots. 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
 PhreePlot input and output files 43

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
(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, a binary file. The
vector, polygon 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 (calcula-
tionMethod 3) is requested, then the calculations start with a pre-existing points file and recre-
ate 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 (calcu-
lationMethod 2) starts with all the existing data files including the labels file and then regener-
44 PhreePlot Guide

ates 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).

5.4.4 ‘out’ file (out)

The ‘out’ file accumulates the selected lines of output from the selected output 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 file. This does not include all the lines in the selected out-
put but only those chosen by selectedOutputLines explicitly or implicitly. By default, this is
just the last line of the last simulation. It is assumed that earlier lines reflect intermediate cal-
culations such as initial solution calculations.
No output file is created during a replot (or resimplify).
The maximum width of any single selected output column is 1000 characters and the maxi-
mum total width of a selected output line is 10,000 characters. These limits also apply to the
out file. Column widths on screen and in the log file are truncated to 20 or 30 characters for
readability. The maximum width of column headers is 30 characters.
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 depend-
ent variable (fitted value) and probably the independent variables (see the -headings line in
the USER_PUNCH block).
In ‘grid’ and ‘ht1’ calculations, the ‘out’ file contains a rearranged version of the data sent in
the selected output. It has the following format:
sequence number, nout1, nout2, nout3, nout4, nout5 then species name + value pairs
for the five species types as given below. The five counters tell PhreePlot how to read the
incoming data in order to construct a predominance diagram. They can be seen being set in
the ht1.inc and ht1c.inc include files.
In summary, the five counters are:

nout1 the number of predominant solution/adsorbed/exchanged/mineral species

returned (maximum 3)
nout2 the number of predominant mineral species returned – these will take
precedence over solution species (maximum 3)
nout3 the number of non-mineral constraints which may override the nout1
species (these can be used to impose the ‘water limits’)
nout4 the number of ‘carry’ variables – these are values that ares not used in pre-
dominance calculations but which you might want to examine for some
 PhreePlot input and output files 45

other reason. These ‘species’-value pairs are sent to the ‘out’ and ‘trk’ out-
put files for viewing and are summarised in the log file. The values are
also added to the tag dictionary
nout5 the number of ‘system’ variables returned (must be 5!)

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. It is also used
by the fit plot to record the progress of the fitting.
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
normally echoed to the screen during execution.

5.4.6 ‘points’ file (pts)

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

Predominance plot calculations (ht1 only)

This is a binary file (and therefore not viewable in a text editor). It records the results of calcu-
lating 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 explictly 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. Most of these boundaries are shared between two fields. The file looks like this:

100 494 1408 16 25.00

-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
46 PhreePlot Guide

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 and the temperature of the last speciation.
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
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 predominace 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. This can be useful for
removing the domain boundaries in pe/Eh-pH plots using the ‘grid’ approach where domain
does not work. 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 ‘ht1’ and ‘contour’ plots.

 PhreePlot input and output files 47

For ‘ht1’ plots, this file is used to tell the plot where to place the labels as well as providing a
list of the species 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 reposition or rotate the labels. A labels file looks like this:
Species sp x y pe angle %area
"Fe(OH)3(a)" 5 -8.300 -32.338 4.406 0.000 61.62
"Fe(OH)3-" 1 -11.541 -81.218 -11.054 0.000 0.41
"Fe+2" 6 -4.789 -61.095 0.735 0.000 32.10
"Fe+3" 10 -2.371 -12.279 15.333 0.000 2.10
"Fe2(OH)2+4" 11 -2.854 -11.174 15.150 0.000 0.49
"FeOH+" 3 -10.189 -81.442 -9.750 0.000 0.25
"FeOH+2" 9 -2.783 -22.242 12.454 0.000 0.00
"H2(g) > 1 atm" 4 -6.990 -83.939 -7.177 0.000 2.49
"O2(g) > 0.21 atm" 13 -7.000 -0.212 13.745 0.000 0.50

Label size and colour are determined by the labelSize and labelColor keywords. Individual
labels and the colouring of their associated polygons 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 species 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 mini-
mumAreaForLabelling 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 minimumAreaForLabelling to 0.1, say.
If labelColor is set to ‘nd’ or labelSize is set to 0.0, no labels will be plotted.
One species can have more than one label if it occupies more than one field. The order of the
labels is important and corresponds with the order that the polygons are read from the poly-
gon file. This should not be changed.
A labels file is also produced by a ‘contour’ plot when calculationMethod 1 or 3. This con-
tains information about the position and orientation of the contour labels. It is used to move
labels when calculationMethod 2 and contourShiftLabel f and also provides a check that the
contour values have not been changed when replotting with calculationMethod 2.

5.4.10 ‘ppa’ export file (ppa)

A <root>.ppa file can be produced at the end of a successful run if the ppa setting is set to
TRUE. This is an expanded input file in a standard input format with comments removed. It
has all the settings set at their values just before the calculations begin. It also expands any
include files. This file is therefore useful for sending to others to run as it does not depend on
any other input files (other than extraText etc files).

5.4.11 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 calculations)
selected.out this is the default name of the file containing the last
SELECTED_OUTPUT returned by PHREEQC when 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 itera-
tion when debug>0
phreeqcall.out this is an accumulation of the normal PRINT output from
PHREEQC for all iterations and is only produced when debug>1.
48 PhreePlot Guide

It contains 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 is important that each problem run from the same directory is given a different dic-
tionary name.
Some other temporary files may be produced during a run. These are normally deleted at the
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.
Graphic files in various formats can be imported into office software such as Microsoft Word.
The filters available depend on the version used. With Word 2002 and later, Postscript (ps)
and Encapsulated Postscript (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). These
files all have a preview when viewed in Word.
png and jpg files can also be imported directly in Word 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.
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 resolution of the png file pro-
duced by PhreePlot (300 dpi) is not what is wanted, use GSview to convert the ps file manu-
ally.
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.
 PhreePlot input and output files 49

Cropping is also possible. Open Office/LibreOffice does not provide a preview for eps files.
If the graphic files need to be edited, Adobe Illustrator, Inkscape, Mayura Draw or other
suitable vector-based software can be used. Inkscape is vector-based (based on the SVG for-
mat) and is versatile, modern and free. Mayura Draw requires conversion to ai format before
editing. It is no longer being actively developed. Many software suites (e.g. Microsoft Office
and Open Office/LibreOffice) can now edit image files including pdf files. The 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 pres-
entation.
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 number 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.5) 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.4 and Section 8.11).

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
essentially the same starting point each time. Sometimes ‘setup’-type calculations can be taken
‘outside the loop’ by making use of the END keyword to separate setup code from the looping
code.
50 PhreePlot Guide
 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 Non-integer numbers. Range allowed depends
number (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–
Ca2+ Ca+2 Ca2+
CaSO4.2H2O CaSO4:2H2O CaSO4.2H2O
FeS1.7 FeS1.7 FeS1.7
(CH3)2COOH (CH3)2COOH (CH3)2COOH
Hg0 Hg0 Hg0
Phenanthroline Phenanthroline Phenanthroline
HFO_s Hfo_s Hfo_s
Fe(3) Fe(3) Fe(3)
18O [18O] 18O
As(V) [As5] As5

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
52 PhreePlot Guide

accordingly. 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.

6.2 PHREEPLOT LOOPING

6.2.1 Loop variables and their use

Looping, or iteration, is at the centre of PhreePlot. 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 z-loop is controlled in several ways, most simply by the keywords loopMin, loopMax,
loopInt and loopLogVar. These generate a regular sequence of values for the <loop> variable.
Alternatively the <loop> variable can be set to any discrete set of values using loopFile. The
loop file approach also provides a mechanism for carrying varying values of other variables for
each z-loop iteration.
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 file will always be produced for species
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
<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,
 Running PhreePlot 53

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 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 set-
tings.
The ‘simulate’ approach is more suitable when there are a lot of independent variables to be
fed in since tags are automatically generated with descriptive names taken from the header row
of the data file. An example of this approach is given below and in the calculation of saturation
indices for a batch of water samples (see the SIs example in the \demo\SIs directory).

6.2.2 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

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.
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 0.1. Amorphous iron oxide solubility as a function of pH calculated using the
<x_axis> loop variable.

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 0.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.

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 sepa-
 Running PhreePlot 55

rator 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 0.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:

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 selected output file - this is done with the dependentVariableColumnCalc keyword.
The customXcolumn also has to be set. This is the only plot type that uses the ‘pts’ file
56 PhreePlot Guide

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
variables 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
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.1). 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.
 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.1. Amorphous iron oxide solubility as a function of pH and NaF con-
centration calculated using the <x_axis> and <loop> variables.

6.2.3 Looping in multi-simulation input files

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 calculations that do not have to be repeated. 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 the necessary substitutions to the input file 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 sim-
ulations or ‘blocks’ of simulations. A block of simulations is therefore defined by a range of
simulations.
In most cases, PhreePlot considers the input file to be a single block but it can also be treated
58 PhreePlot Guide

as a series of unrelated blocks. This is possible with the ‘fit’ and ‘simulate’ types of calcula-
tions where each line of data in the associated data file can point to a different 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.
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
simulations to set up the database, do initial solution etc. calculations. This is then followed
by one or more simulations which will be subject to the y- and x axis PhreePlot looping
mechanisms. This division into ‘pre-loop’ and ‘main loop’ is specified with the mainLoop key-
word which specifies the PHREEQC simulation number where 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 simulations is run separately and the tag dictionary updated between runs
(Figure 6.2). This means that tag variables can be passed from one simulation to the next.
The ‘main loop’ iterates most rapidly 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 updating 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 ‘last’ 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 -user_punch identifier in the SELECTED_OUTPUT
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 refers to each PHREEQC simulation
in turn. The settings are recycled if the list is short.
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
simulation. Some calculations only need to be carried out once and so can safely be ‘parked’ in
the pre-loop section.
The outfile file is often used directly for plotting and the challenge is to end up with a well-
formed outfile suitable for plotting.
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 or sets of data points. Each
data point can 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
 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.2. 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.

specified in a special column in the fit data file, the mainLoopColumn. Weighting of the
residuals becomes a particularly important consideration when mixing ‘apples and oranges’ in
this way.

6.2.4 Defining the expected output in the selected output file

Use selectedOutputLines to define the number of row(s) to be read from the selected output
file, starting from the bottom. Set to 1 to pick just the last row or ‘auto’ to pick all rows. Dur-
ing fitting, the number of rows 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 onePass is TRUE.
If the selectedOutputLines value is 0 for all simulations, no selected output file is expected and
no plotting 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. This ensures that all the simulations will be run
as a single run and so forces the accumulation into a single output file. Don’t use any other
looping mechanism, i.e. just loop through the whole lot once. However, note that tags will
only get updated and substituted 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.

6.3 POSSIBLE TYPES OF CALCULATIONS AND PLOTS

The types of calculations undertaken and the type of plot produced is controlled by the calcu-
lationType keyword (Table 6.3).
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

60 PhreePlot Guide

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

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. Output
to this file is itself controlled using one or more USER_PUNCH data blocks within the
PHREEQC code part of the CHEMISTRY section.
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 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 selecte-
dOutputLines) that are produced each time the selected output is ‘punched’ (once per itera-
tion 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).

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
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 charac-
ters +-/*()<>^\ 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
 Running PhreePlot 61

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 label-
Size<=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 and so they can be used to
force interpretation as a non-PHREEQC formula on a one-off basis without affecting the
appearance in the plot, e.g. ¬Zn8 will plot as Zn8 rather than as Zn8. However, these non-
plotting characters should be used with caution as their behaviour is non-standard and may be
unpredictable. Also starting a heading with a lowercase character will force it to not be inter-
preted 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.
62 PhreePlot Guide

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
¬CH4 CH4
PHREEQC formula
PHREEQC removes backslash and first character after it and the remain-
\C(-4) (-4)
ing is 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) Χ(−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 including 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.
A simple legend is normally drawn to the top right of plot. This can be suppressed by setting
legendTextSize to less than or equal to zero.

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 value than this. 0.0 suppresses plotting of text altogether.
The headings can contain super- or subscript tags, e.g. H₂O or Fe²⁺,
and Greek characters as per normal rule (only to the first level – no superscripted Greek char-
acters are allowed).
Label headings must not be duplicated.
 Running PhreePlot 63

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
problem 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 phreeqcall.out (see below). Examine this carefully making sure that
all the expected substitutions have been made properly. The values of all the tags just before
executing 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 expla-
nation. However, failure of PHREEQC to converge can be quite a common problem and is
usually due to the calculations 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.
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 conver-
gence tolerance. Relaxing the criterion from 1e-12 to 1e-10 solves the problem.

6.5.2 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:
64 PhreePlot Guide

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 proc-
ess.

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
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, adsorp-
tion etc. and only the best speciation programs are robust enough to complete such a challeng-
ing set of calculations reliably.

6.5.3 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 nor-
mally 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, debug works in the following way:

debug=0 minimal diagnostic output

debug=1 selected.out and phreeqc.out produced
 Running PhreePlot 65

debug=2 selected.out, phreeqc.out and phreeqcall.out 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.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.
The file phreeqcall.out file is generated with debug=2 or greater. 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 writ-
ten 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. The exception to this is that with
debug=0 and when calculating a predominance plot, computations continue unless stopped
manually with the Esc key.
The selected.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.4 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
converge given ‘reasonable’ chemistry. We have run it through millions of iterations without
problems. 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
66 PhreePlot Guide

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.
The best way around this problem is to try and arrange for it not to happen by starting at an
extreme pH such that the specified acid/base will always succeed. Alternatively, add a relatively
benign equilibrium phase such as NaCl such that it always maintains a finite (but probably
small) concentration of the co-solute (here Cl) 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+
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.
Using the -force_equality option in the EQUILIBRIUM_PHASES keyword block may be neces-
sary 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
 Running PhreePlot 67

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 trig-
gered by PHREEQC when the target phase activity is not achieved because of insufficient res-
ervoir size. Therefore care is necessary with the setup to ensure that what is being calculated is
what is required.

6.5.5 Changing PHREEQC’s convergence parameters

It is occasionally necessary to alter the default KNOBS settings in PHREEQC to get convergence.
We have found the three most critical options to adjust are -iterations,
-convergence_tolerance, and -pe_step_size.

Reducing the -convergence_tolerance from its default value of 1e-12 to 1e-10 or lower is
often a good start. 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. Reducing the pe_step_size from
10 to 2 may help, and increasing the maximum number of iterations (-iterations) to 1000
from 200 or so may also sometimes be necessary.
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.

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 proc-
68 PhreePlot Guide

essed, 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
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

debug 2 # accumulate output in phreeqcall.out

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 phreeqc.out and phreeqcall.out files if debug has been
set appropriately.
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, debug to 2
and ensuring that PRINT is TRUE in the Chemistry section automatically includes a commented
block of USER_PRINT statements in the cumulative PHREEQC output (phreeqcall.out) that
give a commented 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.
 Plotting basics 69

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
custom direct plotting of output from the SELECTED_OUTPUT file (th1
e 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 varia-
bles 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 (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 calculations 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.
The pageOrientation can be set to 0 (portrait) or 1 (landscape).
70 PhreePlot Guide

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 extraText 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 and tick marks

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 always placed at the plot origin (bottom left-hand corner).
Major tick marks are then added at intervals of pxmajor and pymajor and minor ticks at pxmi-
nor 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.
A second y axis (‘2y axis’) can 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. Positive tick sizes are for inside ticks, negative values for outside
ticks.

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.
 Plotting basics 71

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 pointsSa-
meColor.
A simple legend with an optional legendTitle is automatically drawn to the right of the plot. It
can be turned off by setting legendTextSize to 0. The position of the legend can be moved
with a line of extraText.
Additional lines, points, symbols and text can be added to a plot with extraLinesSymbols and
extraText as described in more detail below. Points or lines from additional files can be added
with extradat.

7.4 CONTROLLING THE COLOUR OF LINES AND SYMBOLS IN CUSTOM PLOTS

7.4.1 The default colour sequence for lines and symbols

Each dataset (lines, points, lines2y, points2y) has its own list of 15 colours. These are picked
off one by one as needed.
72 PhreePlot Guide

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
brown
sky
gray
yellow
maroon
lawn
spring
black

Once the list is exhausted, it is recycled but the colour density is also cycled 4, 6, 8, 2, 4...

7.4.2 Lines

Automatic colouring

Each dataset can show a line drawn between the data points. The colour of lines is automati-
cally selected based on the line colour sequence in effect (see above). When changeColor is
FALSE, the colour picked is determined by the position of the variable in the corresponding
lines list, e.g.
lines pH Ca Mg Na K
lineColour purple green
will give the following colours: pH = purple, Ca = green, Mg = red, Na = blue, K = orange.

The first n colours selected are always given by lineColor where n = length of the list of colours
specified with lineColor.
If changeColor is TRUE, the colour of each dataset plotted is picked sequentially from either
the line or points colour lists. The y and 2y lists increment the same counters.
The same colour can be used for several lines by replicating the colour in the lineColor list.
Line colours can also be controlled with the line colour dictionary (Section 7.9.4).

7.4.3 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 of a name. The available sym-
 Plotting basics 73

bols and their symbol codes are shown in Appendix 3 and Figure 7.4.
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.
Each curve has the same colour symbols. The colour of the symbols can be controlled by the
pointColor, pointsSameColor and changeColor parameters. 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.
Symbol types rotate through filled circle, empty circle, and open diamond. If different sym-
bols are wanted for different curves, then a separate extraSymbolsLines file should be pre-
pared. However, there is no guarantee that the symbols will be centered exactly.
The size 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 (note that the rim colour is not auto-selected).
The minimum size of positively-sized symbols is set to 0.01 inch. A size of 0.0 suppresses plot-
ting of symbols.

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 centred in the field. The species name is in
turn derived from the database and any changes subsequently made by the ht1.inc or similar
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 (calculation-
Method = 3) as this will recalculate the label positions and return them to their original posi-
tions.
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
74 PhreePlot Guide

force (simulated annealing) approach is taken. The time taken is broadly controlled by the
labelEffort setting (0-3).
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.
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 formu-
lae 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
setting convertLabels to FALSE or by including a non-printing character in the label name
(Section 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.
With ‘contour’ plots, the labels file is generated with calculationMethod 1 and 3 and is read
with calculationMethod 2 in which case it can be used to change the position of labels.

7.5.2 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 labelColor.
The order of items in the legend is the order specified in the lines and points settings in the
input file(s).
The legend will not be drawn if labelColor is ‘nd’, 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.
The placement of the legend can be changed by specifying its position in the ‘extraText’ file
using the special <legend> option. <legend> is not like a typical tag but rather acts as a place-
holder 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).
 Plotting basics 75

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 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 main fonts 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 extraText mechanism.
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

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.

“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 most of the available 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.
76 PhreePlot Guide

7.6.3 Text enhancements including Greek characters

A certain degree of text enhancement is possible although the possible combinations are rather
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 bold-italic 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 uwxyz

ΑΒΧΔΕ ΦΓΗΙϑ ΚΛΜΝΟ ΠΘΡΣΤ ϒΩΞΨΖ

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

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>
 Plotting basics 77

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 Justification

This can usually be specified as either left, centre or right justified horizontally. The text is also
approximately 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 coor-
dinates refer to the bottom of the first (top) line.
For accurately centered symbols, use the extraSymbolsLines keyword rather than the extraText
one.

7.6.5 Angle

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

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:

<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
78 PhreePlot Guide

<input...> Part of the input file (only in 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.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 axis labelling always starts at the bottom left hand corner usually at xmin, ymin. 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
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.1.
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
 Plotting basics 79

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.1. Use of the secondary (2y) axis to provide an expanded y-scale for displaying the saturation

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.
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.
80 PhreePlot Guide

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 (ensures that different subsets of data from the same column of data are
plotted with the same colour).
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.

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.2)
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
(black for text and lines; white for fills).

Figure 7.2. 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.
 Plotting basics 81

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 of labels in a ht1
predominance plot is achieved by 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.

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 whther
this is the case. For example, if 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
82 PhreePlot Guide

"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

The sequence specified by this list is modified by the lineColor settings which promotes the
given colour(s) to the top of the list. For example, the default lineColor setting in pp.set is
red which means the colour sequence will be red, blue, ... . If lineColor setting is set to blue,
then the sequence would be: blue, red, green, ... .
Autocolors only consider the basic colors (colors without a number). If the lineColor setting
is red2, red6, black, the autocolor 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 same base lineColor
will be used for all subsets of the same variable though the actual colour will rotate the colour
density, 4, 6, 8, 2, 4..., e.g. red4, red6, red8, red2, red4, ... .
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
 Plotting basics 83

(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.

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.3. These
examples can be found in the autocolorn.ppi files found in the demo\phreeqcloooping
directory.
ecolor = orange, pointcolor = blue, changecolor = T, pointsSamecolor F ecolor = orange, pointcolor = blue, changecolor = T, pointsSamecolor T

1.0 sin_1 1.0 sin_1

sin_2 sin_2
sin_3 sin_3
sin_4 sin_4
sin_5 sin_5
0.5 0.5

• •
sin_3 sin_3
sin

sin_4
sin

sin_2 sin_4
0.0 • • 0.0 • •
sin_2
sin_5 sin_5
• •
sin_1 sin_1
• •

-0.5 -0.5

-1.0 -1.0
0 2 4 6 8 10 0 2 4 6 8 10
x x
linecolor = orange, pointcolor = blue, changecolor = F, pointsSamecolor f ecolor = orange, pointcolor = blue, changecolor = F, pointsSamecolor T

1.0 sin_1 1.0 sin_1

sin_2 sin_2
sin_3 sin_3
sin_4 sin_4
sin_5 sin_5
0.5 0.5

• •
sin_3
sin

sin_3 sin_4
sin

sin_4 sin_2
0.0 • •
sin_2 0.0 • •

sin_5 sin_5
• •
sin_1 sin_1
• •

-0.5 -0.5

-1.0 -1.0
0 2 4 6 8 10 0 2 4 6 8 10
x x

Figure 7.3. Effect of the changeColor and pointsSameColor settings on the auto colouring of lines and points for
a data file (the ‘out’ file) containing several data sets created using PhreePlot’s in-built looping mechanism. The
lineColor was set as orange4 and the pointColor was set to blue4. These provide the starting values of the auto-
selected colour sequence. Top left: changeColor = TRUE and pointsSameColor = FALSE; top right,
changeColor = TRUE and pointsSameColor = TRUE; bottom left, changeColor = FALSE and
pointsSameColor = FALSE; bottom right, changeColor = FALSE and pointsSameColor = TRUE.

Filled symbols with a different rim colour

Normally points are plotted as simple symbols. However, there are six filled symbols which
84 PhreePlot Guide

can have a separate rim colour. The filled colour is controlled by the points, pointSize, point-
Color and changeColor settings.
Points will be plotted providing their size is greater than zero and their colour is not ‘nd’. Rims
will be added if the rim colour defined by rimColor is not ‘nd’ and the line width of the rim
defined by rimFactor is greater than zero. If changeColor is FALSE so that all the lines are the
same colour (as set by lineColor(1)), then pointColor is used for all the lines.

7.9.5 Directories for the colour dictionaries

If only the filename is given, then the specified file is sought following the usual search path
(Section 2.3.7). If in doubt, give a full path name.

7.10 LABELLING

All plots can be automatically labelled. An attempt is made to do this ‘nicely’ but this can be
time-consuming especially when there are a large number of labels and when there is the
potential for overlap. It is difficult to find a universal set of criteria that define good placement
and it may be necessary to manually move labels using the appropriate label file or colour dic-
tionary. In the case of contour plots, the labels are moved along the contour using the con-
tourShiftLabel setting.
The algorithms employed at present are ‘experimental’ and rather inefficient. The time taken
for labelling goes up roughly as the square of the number of labels and so can quickly become
excessive. The effort taken can be controlled using the labelEffort keyword (see below). Labels
can always be moved manually by editing one of the ‘dictionaries’ and making sure that these
values take precedence over any automatic labelling.

7.10.1 Predominance plots

Labels are automatically centered at the centre of each field. There is some effort to try and
resolve overlapping labels should any be identified and to ensure that labels are centred within
their respective polygons. The present approach cannot deal with polygons with holes or
islands in them. calculationMethod 2 uses the label coordinates from the labels file if present
whereas calculationMethod 3 re-calculates the label coordinates. The latter is necessary to re-
centre labels if the plotting domain has been changed.

7.10.2 Contour plots

Labels are automatically placed at the centre of the ‘longest, straightest’ part of a contour seg-
ment. The contours are drawn from the ‘vec’ file and the position of the sequence in this file
indicates the contour number. The labels can be moved forward and backward along the con-
tour using the contourShiftLabel setting. ‘Forward’ is ‘moving along the contour with the high
side on the right’. First choose the number or ‘n’ option to identify the contour and then
experiment with different shift settings. If the shift moves the placement outside of the con-
tour, no label is drawn. Reducing the size of the label may help in crowded situations. Once
the placement has been decided, change back to the contour or ‘c’ option.
The contour plot produces a labels file with calculationMethod 1 and 3, and reads it with cal-
culationMethod 2. This can be used with contourShiftLabel f to move labels.

7.10.3 Custom plots

The method of simulated annealing is used to determine the position of label placement in
custom plots. This is why ‘temperature’ appears in the output as the notional ‘temperature’ is
gradually reduced allowing less freedom to roam randomly in search of a better set of label
positions. This approach is experimental and can be very slow. The labelEffort keyword con-
trols the amount of effort put into searching for good label placement. It only applies with cal-
culationMethod 1 or 3.
 Plotting basics 85

The main objectives are to make the labels legible and their attribution unambiguous. The size
of the labels is an important parameter (labelSize) since small labels obviously tend to overlap
less than large labels. Set against this is the overall readability of the labels.
The labelEffort parameter is used as follows:

labelEffort = 0 Labels are plotted roughly half-way along x axis; avoids the issue of
label overlap etc altogether but rarely satisfactory
labelEffort = 1 Minimal effort; this should take no more than a few seconds
labelEffort = 2 Medium effort; slower
labelEffort = 3 Much effort; much slower, can take many minutes – designed for
batch processing where time is not such an important factor.

The following objectives are sought when deciding where to place labels:

avoid labels overlapping with other labels

avoid labels overlapping lines
avoid labels being placed outside the plotting area
place labels as close to the centre of the plot as possible

These objectives will conflict to some extent and PhreePlot tries to find a reasonable compro-
mise. This is computationally demanding and the optimum solution may not be found in the
time available.
Interrupting this process using the Esc key will exit gracefully while retaining the best label
positions found up to that point.
In custom plots, each label is anchored to one of the calculated points. This anchor is shown
by a small filled circle (by default red) which is controlled by the track symbol (trackSymbol-
Color and trackSymbolSize).

7.11 REPLOTTING WITHOUT RECALCULATING

7.11.1 The ‘replot’ option

It is often necessary to ‘fine tune’ the appearance of existing plots. The calculationMethod
parameter controls the extent of recalculating: 1 = calculate from scratch and plot; 2 = just
replot; 3 = reprocess data, relabel and replot but do not re-speciate. This enables the appear-
ance of a plot to be changed without repeating the underlying calculations.
1 does speciation calculations; 2 and 3 do not. The replot options make use of the output files
produced during an earlier calculation. These files must be present.
It is possible to make the following changes during a replot:

change the font

change the size and colour of all text, symbols and lines
add, remove or change any extra text, symbols and lines that are specified by the ‘extra-
Text’ and ‘extraSymbolsLines’ files
implement any changes made to the label file or colour dictionaries including deletion
or repositioning of labels
change from a native y-axis scale to some other scale in predominance plots
change the sign on the x- or y axis
change which graphic output files are produced (pdf, png etc).
change from a series of single page graphic files to a multipage file and vice versa.
86 PhreePlot Guide

Unpredictable results will occur if you:

change anything to do with the scope of the calculations involved, e.g. xmin, xmax,
ymin, ymax, looping, number and type of main species, fitting parameters, extent of
simplification
change the resolution
change the thermodynamic database used.

All the required files must be present and in the correct format for replotting to work. If they
are not, regenerate them from scratch (calculationMethod = 1). The following output files are
required for replotting:

ht1 vec, pol, lab (calculationMethod = 2)

pts, vec, lab (calculationMethod = 3)
grid pol, lab (calculationMethod = 2)
trk (calculationMethod = 3)
contour vec, pol (calculationMethod = 2)
out, vec, pol (calculationMethod = 3)
fit or simulate out

custom out

species out

Adobe Reader locks open files so a new pdf file cannot be recreated while a file with the same
name is already open. Close it first. This limitation does not apply to files opened by GSview.
It is possible to use the replot option to enable PhreePlot to make a plot of any data in a user-
derived text file providing the file format and name are correct, i.e. data in regular columns
with the first line containing the labels. The filename should be the base filename with the
extension ‘out’. The calculationType should be ‘custom’ and mainSpecies=‘’. Alternatively, a
data file for making a custom plot can be added with the extradat keyword. This can be used
for adding data to predominance plots too.
The calculationType should be ‘custom’ and mainspecies=‘’.

7.11.2 The ‘reprocess and replot’ option for predominance plots

The reprocess and replot option (calculationMethod = 3) goes back one stage further than
simple replotting and starts with the stored output from the speciation calculations. For the
ht1 calculation type this is the pts file rather than the vec file . With ‘grid’ plots, this is the
‘trk’ file and with ‘grids’ plot this is the ‘out’ file. In all cases, the polygons are re-assembled
and the label positions recalculated before replotting. In the case of the ht1 calculation type,
this enables the degree of simplification to be changed without recalculating the chemistry.
In the case of the ‘grid’ and ‘grids’ plots, if the speciation calculations have been terminated
early for some reason, the track and out files, respectively, will not be fully populated and it
may not be possible to complete the plot. This can happen when Esc has been used to termi-
nate calculations early or if PhreePlot has crashed part way through the speciation calcula-
tions, for example if the operating system has run out of virtual memory.
Restarting ‘grids’ plots with calculationMethod = 3 will attempt to fill incomplete ‘out’ files
thus preserving the effort of earlier calculations.

7.12 ADDING EXTRA LINES, SYMBOLS AND TEXT

If extra text, symbols or lines need to be added to the plot, they can be specified in separate
 Plotting basics 87

files. Tags can be used anywhere in the extraSymbolsLines or extraText files.

7.12.1 Lines and symbols

Points on plots are plotted with symbols. Extra symbols can be added to a custom plot or pre-
dominance plot with an extraSymbolsLines file. This has the format:

plotnumber,x,y,[lw,linecol,[isymb,[sizesymb,[symbcol,[rimcol,[rimfactor,sig-
figs}]]]]]]

isymb is the symbol number or name either natively generated (1–10, decimal numbers) or
from the Symbol (11–40, decimal numbers) or the ZapfDingbats font (41–176, 241–376,
hexadecimal numbers). These sequences may be incomplete – some of the numbers do not
have symbols associated with them.
The file has no header. Use a comment line if necessary.
See Example 68 for a display of the symbols available and their corresponding symbol num-
bers. A full list of the symbol numbers and their names is given in Appendix A3.
The size of the symbol is given by abs(pointSize) in the current units. If pointSize>0 then a
line is drawn connecting the points otherwise not. The attributes of the line are taken from
the current line attributes.
plotnumber is the plot number (starts at 1) for which the text applies. The plot number is
printed on the top line of the info text which, if selected, is printed at the bottom left-hand
corner of each plot. See the extraText summary for the numbering of plots in multi-loop runs.

plotnumber plot number: special case, auto means ‘all’ plots

x x position: special case, auto means just to the right of pxmax, i.e.
pxmax+0.03*(pxmax-pxmin)
y y position in plot coordinates: special cases, auto means level with the top
of the plot (pymax), 998 means centre (pymin+0.5*(pymax-pymin)) and
997 means bottom (pymin)
lw line width (in the length units in force); a negative value will give a dashed
line (default is lineWidth)
linecol line colour (‘nd’ for no colour; default is lineColor(1))
isymb integer code or name for the symbol (see Section 7.6) (optional, default =
1)
1–10 are natively generated, 11–40 use the Symbol font and 41–376 use
the ZapfDingbats font
sizesymb symbol size in the units in force (optional, default = 0)
symbcol symbol colour (optional, set to pointColor)
rimcol rim colour (optional, default = ‘nd’)
rimfactor thickness of rim as fraction of sizesymb (optional, default = 0.1)
sigfigs number of significant figures to use for any substituted numeric tag val-
ues, -ve also removes trailing zeros (optional, default = -3)

The available symbols and their isymb codes are shown in Appendix 3 and Figure 7.4.

The first ten symbols are centered symbols:

1 = filled circle
2 = filled square
3 = filled triangle
4 = filled upside down triangle
5 = filled diamond
6 = filled octagon
7 = open circle
8 = plus
9 = multiply
10 = star
88 PhreePlot Guide

Symbols, dingbats and lines

0 1 2 3 4 5 6 7 8 9
# % ∗ + − . ? ⊥ _
10 11 12 13 14 15 16 17 18 19
⎯ | ′ ≤ ♣ ♦ ♥ ♠ ↔ ←
20 21 22 23 24 25 26 27 28 29
↑ → ↓ ∼ ©
30 31 32 33 34 35 36 37 38 39

 Ê    w v u     
40 41 42 43 44 45 46 47 50 51 52 53 54 55 56 57
i         
60 61 62 63 64 65 66 67 70 71 72 73 74 75 76 77


 
 
  !  "  # $ % & ' ( ) *
100 101 102 103 104 105 106 107 110 111 112 113 114 115 116 117
+ , - . / 0 1 2 3 4 5 6 7 8 9 :
120 121 122 123 124 125 126 127 130 131 132 133 134 135 136 137
; < = > ? @ A B C D E F G H I J
140 141 142 143 144 145 146 147 150 151 152 153 154 155 156 157
Ë K Ì L M N O Q R S T a b c d
160 161 162 163 164 165 166 167 170 171 172 173 174 175 176 177

200 201 202 203 204 205 206 207 210 211 212 213 214 215 216 217

220 221 222 223 224 225 226 227 230 231 232 233 234 235 236 237
e f g h j k l p o n m x y z {
240 241 242 243 244 245 246 247 250 251 252 253 254 255 256 257
| } ~  €  ‚ ƒ „ … † ‡ ˆ ‰ Š ‹
260 261 262 263 264 265 266 267 270 271 272 273 274 275 276 277
Œ  Ž   ‘ ’ “ ” • – — ˜ ™ š ›
300 301 302 303 304 305 306 307 310 311 312 313 314 315 316 317
œ  ž Ÿ   ¡ £ ¤ Ä ¥ À ¦ § ¨ © ª
320 321 322 323 324 325 326 327 330 331 332 333 334 335 336 337
« ¬ ­ ¢ ® ¯ ° ± ² ³ Á ´ Ç µ È ¶
340 341 342 343 344 345 346 347 350 351 352 353 354 355 356 357
É · ¸ Å ¹ Â Æ º Ã » ¼ ½ ¾ ¿
360 361 362 363 364 365 366 367 370 371 372 373 374 375 376 377

All symbols have a nominal height of 2 mm (without rims).

C:\PhreePlot\demo\symbols\symbols.ps

Figure 7.4. The symbols available in the native, Symbols and ZapfDingbats fonts and their corre-
sponding isymb codes. This diagram can be generated from the ...demo\symbols\sym-
bols.ppi file.

The six ‘filled’ symbols above can each have a separate rim colour and associated rim thickness.
It is therefore possible to plot an open circle using the filled circle code but specifying that the
point or symbol colour is ‘nd’. Specifying the symbol colour as ‘white’ will have a similar effect
except that it will remove any underlying features.

Include a blank line to force a break in a plotted line. A new plot line can also be signified by a
line of data having either a line colour of ‘nd’ or a line width of zero.
If there are any formatting errors in the line, it is omitted (with a comment). PhreePlot plots
each line segment in turn using the parameters for the second point. For example,
auto -2 1 0 black 2 8 red
auto -5 3 -0.4
auto 2 3 -0.4 black

will plot a solid red circle at the point (-2, 1) and a black dashed line from (-5, 3) to (2, 3)
(clipped if necessary). Because the first line has a line width of zero, the next line is deemed the
start of a new line and so no line is drawn from the first line of data to the second line. Note
that redundant trailing parameters have been omitted in lines 2 and 3.
The lines are clipped to the axes but the text is not.

7.12.2 Text

Additional text can be placed inside or outside the plot area (as defined by the axes) using an
extra file, the These are specified in the ‘extra text’ file and defined in detail under the extra-
Text keyword. This file has the format:

plotnumber,x,y,text,[height,[colour,[angle,[justify,[digits,[font]]]]]]

plotnumber is the plot number (auto for ‘all’), x and y are the x- and y-coordinates of the
anchor position, and text is the single text string (usually embedded in quotes). This text
 Plotting basics 89

string can contain tags from the tag dictionary or special plotting tags such as subscript/super-
script. There are also other special tags which can be used.
The remaining parameters are optional. Although these are optional it is necessary to keep the
parameters in order, i.e. you can omit font and include the rest but cannot omit colour and
keep angle, justify, digits and font. If necessary specify all the parameters explicitly.
Defaults for the optional parameters if left blank are:

height = legendTextSize
colour = ‘black’
angle = 0 (degrees)
justify =0
digits = -3 (if numbers are being printed, this provides some control over the
format: default is three figures/decimal places depending on
the type of number involved; the negative sign indicates that
trailing zeros will be removed)
font = the font (name or number, 1-44), or the current font if undefined.
plotnumber is the plot number (starts at 1) for which the text applies. ‘auto’ means all plots.
The plot number is the sequential number of the plot and is always printed on the first line of
the info block if that whole block is printed. For more detail on the numbering see the extra-
Text summary. Text is truncated to 200 characters. This includes any text used to specify tags
(see below). Enclose the text within paired single or double quotes if the text contains a delim-
iter (space, comma or tab). This will keep the text as a single string entity.

x and y can be made dynamic by making use of the <pxmin> etc tags which are set after the
plotting limits have been determined., e.g. first set

numericTags <px> = “<pxmin>+0.3*(<pxmax>-<pxmin>)”

then use <px> in place of say x in the extraText file.

The y-position always refers to the main y axis. If a point needs to refer to the 2y axis, then the
corresponding y value must by calculated separately. This can be done using a numeric tag
expression like:
<p2y> = "(<2y>-<p2ymin>)/(<p2ymax>-<p2ymin>)*(<pymax>-<pymin>) + <pymin>"

where <2y> is the wanted position on the 2y axis and should be defined using numericTags.
The <p2y> tag can then be used in an extraText or extraSymbolsLines file.
When printing, leading tabs are replaced with three spaces and subsequent tags replaced by
single spaces. Multiple spaces are also reduced to a single space. Spaces might appear with
unpredictable length with proportional fonts.

justify: refers to the justification of the string (0= left, 1= centre, 2= right) irrespective of the
angle, i.e. as if rotated about the appropriate character, so justify=2 with angle=180 will
rotate around the last character whereas justify=0 will rotate about the first character. The x
and y coordinates therefore by default specify the left-hand baseline (bottom left-hand corner)
of the text. x defines the left-hand edge; y defines the baseline of the text string (‘g’ falls below
the baseline). Where there is more than one line because of the use of embedded line breaks,
<br>, y refers to the first line. If the text goes off the bottom of the screen, increase yoffset to
reposition the plot higher, or increase the page size. Remember the page size of the printing or
viewing device controls what part of the plot will actually be seen.
digits: specifies the number of digits to print when a numeric tag is substituted by a value. It
is specified by an integer, n. n gives the number of digits printed after the decimal point (valid
range 0>=n>=16). 0 prints the nearest integer. If a negative integer is given, multiple trailing
90 PhreePlot Guide

zeros are removed. If the absolute value of the number is less than 1e-3, it is printed in scien-
tific (x.xEee) format. This format applies to all numeric tags in the text string (default n = -3).
font: The font is either specified by a defined font name (see fonts.dat, if present) or by a
font number, numbered consecutively across and down the fonts.dat table, if present, e.g.
Times-Roman or 17. If the font or font number is unrecognised, the current font is used if
defined else it reverts to the Helvetica font.

<input>

A special piece of text is:

<input> prints all lines from the main input file.

“<input:str1>”prints all lines from the input file starting at the first line containing
str1 to the last line of the CHEMISTRY section.

“<input:str1,str2>”prints all lines from the input file starting at the first line con-
taining str1 to the first line containing str2 inclusive.

str1 and str2 are ASCII character strings. Case is significant for both str1 and str2. Use the
quotes for the second form otherwise the comma will be parsed and str2 will be set to col
and then the text ignored completely. Justification, if present, is ignored. The text will be left
justified, vertically aligned with the top of the text at ypos and starting at x. x,y may be out-
side the plot axes. mjus is ignored – the text is always left justified. Multiple spaces and tabs are
replaced by single spaces except any leading spaces (indentation) are preserved. A leading tab is
replaced by three spaces. Blank lines are omitted.
The first example will print the entire input file. This is based on the input file as input - not
the expanded input file that is created after expanding any include files.
The second example will print the input file starting from the first line containing str1 and
finishing at the first line containing str2. If str1=””, then printing starts at the first line; if
str1 is non-blank and str2=””, printing continues to the last line. If str1 is found but not
str2, then the text is printed from str1 to the end of file but if str2 is found and str1 is not,
then nothing will be printed.
<br> is not recognised within this tag. If str1=str2, only that line is printed.
Angle is the angle in degrees measured clockwise from the horizontal.
The size and colour of the text is either given on the <input> line or by default takes on the
values of legendTextSize and ‘black’, respectively. The legend can be turned off by setting
labelColor to ‘nd’.
If info(1) is set to ‘nd’ then this input text will not be printed. This allows clean plots to be
produced without editing the individual extraText files, possibly by using the override.set
file.

<loop> or <loop...>

Substitutes the current numeric value of the appropriate loop variable. The primary loop var-
iable is <loop> which if a regular sequence, can either be defined in an input file using the
loopMin, loopMax, loopInt and loopLogVar settings.
If the sequence of loop values is irregular or if more than one variable value needs to be set on
each iteration, use the loop file approach instead (Section 4.6.2). <loop> is equivalent to
<loop1>, the first column of numbers in the loop file. Successive columns are set to the
<loop2>, <loop3> etc tags or if a header row is present, this is used to generate tag names.

The loop variable is printed as an integer if it is an integer otherwise it is printed in floating

point format. No extra spaces are added to the number. The value of the loop variable used is
the value at the time of plotting.
 Plotting basics 91

<legend>

Inserts the legend for custom plots at x,y rather than in its normal position to the right of the
plot. If found, all other text in the string is ignored. Height and colour can be included but if
absent, the defaults are:

text height = the legendTextSize setting

colour = black.

e.g.

auto 4 -12 “<b>Key</b><legend>” 2 blue

will insert the top left-hand corner of the legend box at approximately (4,-12) based on the
plot scale. Legend lines will be left-justified at 4 and the top line vertically centered on -12.
Symbols, if plotted, are justified slightly to the right of this.
Any text before <legend> is treated as the legend title and will override the legendTitle setting.
The legend title will therefore be ‘Key’ in the above example. If no legend is defined in the
<legend> line, legendTitle will be used.
Text after <legend> is ignored. Text tags such as <b> will be ignored if split by a <br>.
This option allows the legend to be moved inside the plot area, or by using out-of-range x
and/or y coordinates, removed completely from the plot.

<mainspecies>

Inserts the name of the current main species into the text string, e.g. “<mainspecies>” would
substitute “Fe” if that was the main species.
92 PhreePlot Guide
 Predominance diagrams 93

8 Predominance diagrams

8.1 SETTING UP A FILE TO CALCULATE A PREDOMINANCE DIAGRAM

The various calculation types available in PhreePlot require the user to PUNCH certain data to
the SELECTED_OUTPUT ready to be read in a specific and pre-defined format by PhreePlot. The
requirements for the two methods that generate predominance diagrams are exactly the same
and are described below. Details of the algorithms used are also given.

8.1.1 The ‘grid’ and ‘ht1’ approaches

Grid approach

PhreePlot is able to calculate predominance diagrams based on a full speciation of the system
using the grid and ht1 algorithms. The grid approach is a direct search approach that calcu-
lates speciation on a grid while the ht1 approach finds and tracks the field boundaries. The
results should be quite close to those obtained using traditional analytical approaches such as
used by the Geochemist’s Workbench (Bethke, 2005). However, they will not be exactly the
same since the simplifying conditions required in the analytical approach are often unrealistic
and can be difficult to achieve in practice. The full speciation approach requires that all parts
of the domain under study be accessible via a plausible and specifiable reaction path. Activities
are seen to reflect all the interactions in the system rather than being simply imposed on the
system. Achieving constant activities along a boundary usually requires variable quantities of
an element to be present whereas more realistic systems have constant total concentrations of
elements and variable activities.
If the total quantity is kept constant, then the concentrations of dominant species at bounda-
ries will be close to half the total concentration while at triple points will be close to one third
of the total concentration.
The grid method is a ‘brute force’ method in that PhreePlot simply calculates the speciation
at each point on a rectangular grid and reports the dominant species. The range and spacing of
the grid points is determined by the xmin, xmax, ymin, ymax and resolution parameters. This
method requires nres2 speciation calculations plus any pre-loop calculations, e.g. initial solu-
tion calculations.
The matrix of predominant species can be rendered directly by colouring each species differ-
ently but this does not identify field boundaries and results in rather large image files.
PhreePlot uses a ‘pixel aggregation’ technique to identify the boundaries. This enables the
fields to be polygon-filled with colour and so avoids pixelation of the generated image This
results in better rendering of the plots and much smaller file sizes.
One or more main species can be specified. With the ‘grid’ approach, a new set of speciation
calculations is repeated for each main species even though the grid is the same. With the
‘grids’ approach, the speciation calculations are made for all main species in one pass and the
results written to individual ‘out’ files in the normal way. Progress during the speciation calcu-
lations is shown by a series of dots on the screen. Each dot represents 10 speciation calcula-
tions and a full line of dots 500 calculations. The individual ‘out’ files are then processed in a
second pass to give the plots.
This approach needs different USER_PUNCH statements to export the data since the ‘grids’
option requires that the full speciation for all elements be returned and written to the appro-
priate ‘out’ files in one call to USER_PUNCH. ‘grid’ uses the ‘ht1.inc’ file or similar, while
94 PhreePlot Guide

‘grids’ uses the ‘grids.inc’ file or similar.

It is possible to add a z-loop to ‘grid’ and ‘grids’ plots. Normally the z-loop is inside the main
species loop but in ‘grids’ plots, the results of all main species calculations are returned in one
speciation calculation and so in this case the z-loop must be outside the main species loop.
This special case is intercepted when the first z-loop is executed. This is reflected in the output
in the log file, and affects the calculation of the printed timings of individual plots. These tim-
ings are estimated by dividing the total speciation time by the number of main species to give
an approximate time taken per main species.
The ‘grids’ approach carries considerably more overheads but can be faster for two or more
main species especially when the speciation calculations are themselves relatively slow. See the
demo\grids directory for an example.

‘Hunt and track’ approach

The ht1 method uses a ‘hunt and track’ approach to find and track the field boundaries. It is
based on the assumption that all such boundaries can be reached from the domain (‘axis’)
boundaries, i.e. that there are no ‘islands’. In fact, islands can occur (see Example 42) and so
while this method is usually quicker than the grid approach, it is not so reliable and in critical
situations the results of the ht1 approach should always be compared against the grid
approach.
The ht1 approach first works along the domain boundaries looking for a change in the domi-
nant species. This is the ‘hunting’ mode. Once it has found a change-over on the boundary, it
tracks internally along it. During this tracking, it only makes evaluations (speciation calcula-
tions) on a fixed grid defined by the same parameters that the grid method uses. It bounces
along the boundary keeping track of where changes in the dominant species occur and noting
where triple points - the intersection of three equally dominant species - occur. Where possi-
ble, more precise boundary positions are estimated by interpolation along a cell edge using the
logarithm of the dominant and subdominant concentrations.
It is possible to define constraints that override the normal predominance criteria. The tradi-
tional ‘water limits’ are commonly applied in presenting predominance diagrams. The
ht1.inc code provides a check to see if these have been exceeded and PhreePlot elevates them
to the top of the list if they have. A check is also made on the methane partial pressure since
this can be high in strongly reducing, carbon-containing systems.
The overall strategy is best appreciated by examining the ht1.inc and ht1c.inc files which
provide generic pieces of PHREEQC code for returning the predominant species. These are
used by both the hunt and track and grid methods. ht1.inc is the simpler of the two scripts in
that it treats all adsorbed species as distinct species whereas ht1c.inc combines all adsorbed
species into a single ‘super’ species for the purposes of counting and display.
PhreePlot expects the SELECTED_OUTPUT to have a specific format in order to be able to draw a
predominance diagram. The list of data required consists of five different blocks of data, each
of which can contain a variable number of species name-number (often a concentration) pairs.
The counts for each of these blocks is given by five numbers at the end of the list. These can
be zero if no pairs are returned. This ensures that PhreePlot knows how to read the data list
returned. The structure is summarised in Figure 8.1.

nout1 nout2 nout3 nout4 nout5

Dominant species Dominant minerals Constraints Carry variables 5 system variables 5 counts

Figure 8.1. Data structure expected to be returned to PhreePlot in the SELECTED_OUTPUT in order to calcu-
late a predominance diagram using the ht1 and grid plot types.

ht1c.inc also gives the option of calculating either a predominance or stability diagram (Sec-
 Predominance diagrams 95

tion 8.1.4). In a stability diagram, mineral species assume predominance over solution species
no matter what their relative concentrations. This is done by commenting out either line 20
or 30 (using a # or REM statement).
The script defines the five blocks of species which must be returned by PUNCHing them. These
blocks are:

1. the three dominant species (solution, mineral, gas or adsorbed), (nout1<=3)

2. the three dominant mineral species, i.e. those which account for the largest con-
centrations of the main species (nout2<=3)
3. any constraints: these will override all other considerations and if the constraint
is true will force the species to be treated as the dominant one. Limits on the partial pressures
of H2(g), O2(g) and CH4(g) are usually included (nout3=3 usually) and can be used to plot
the usual ‘water limits’. Other constraints are possible. See the carbonate example with con-
straints on the total carbonate in the system (Example 25)
4. any ‘carry’ variables (nout4)
5. the ‘system’ variables - pH, pe, the log partial pressures of O2(g) and H2(g) and
temperature (oC) (always these five pairs of values in that order).

The final items PUNCHed are the five counts, nout1-nout5. PhreePlot receives the five groups
of species, their values and their counts as one long list. The counts tell PhreePlot how to read
the list.
The minimum output required to prepare a predominance diagram is one dominant species
(nout1 = 1) and five system variables (nout5 = 5).
‘Carry’ variables are species that are wanted to be output but which play no part in the calcu-
lation of the predominance diagram. They are also sent as species name-value pairs. For exam-
ple, the script ht1minerals.inc script can be used to list all the minerals that precipitate
somewhere in a predominance diagram. This can be used to reduce the mineral phases consid-
ered during the speciation calculations and thereby reduce the time to calculate a predomi-
nance plot. In this example, a list of the summary statistics (count, minimum, mean and
maximum value) for each species output as a variable is listed in the log file provided the out
file has been turned on (out T). The ‘carry’ variables are written to the out and track files and
automatically added to the tag dictionary. The track file uses the first species name as the col-
umn heading.
The ht1.inc and ht1c.inc scripts use the SYS() function to return a list of the concentration
of all the species of the element of interest, the so-called ‘main species’. This list is returned
from PHREEQC pre-sorted in decreasing amount of the main species element. This is not
necessarily in terms of decreasing species concentrations where polynuclear species are
involved.
The top three of these are sent back to PhreePlot as block 1 via the SELECTED_OUTPUT ‘file’ by
PUNCHing them in the sequence:

name1 concn1 name2 concn2 name3 concn3

where name1 has the highest concentration and name3 the lowest. If less than three species
exist, then either one or two is returned depending on the number available (the predomi-
nance diagram is trivial if there is only one species).
The remaining output is written to the selected output ‘file’ in a similar manner, i.e. always as
a species name followed by a numeric value, usually a concentration.

8.1.2 Using the ht1.inc code to return the dominant species

A predominance diagram is most easily calculated using the ht1.inc code described above. A
simple example is given below for preparing a pe-pH diagram for Fe (see Example 3).
96 PhreePlot Guide

The CHEMISTRY section starts with the include file (its position is unimportant) and then has a
SOLUTION keyword block to define the initial conditions - the total amount of each element
present in the system. This is constant and so can be setup in a separate simulation.
This is followed by a second simulation which includes an EQUILIBRIUM_PHASES keyword
block. This provides the mechanism for traversing the x- and y-axes, and for defining mineral
phases that may precipitate (or dissolve). This means that the two tags, <x_axis> and
<y_axis> have to be present, either explicitly or implicitly. Note that the x axis is controlled by
Fix_H+ (defined in ht1.inc) and is therefore the pH. The initial conditions include the total
concentration of Fe3+.
The pH is adjusted by adding (or subtracting) NaOH. Note that the initial pH is low (and is
preferably set to less than the minimum pH required on the x axis) The y axis is linked to a
fixed partial pressure of O2(g) supplied by an external reservoir of O2 (10 mol). The plot cre-
ated is therefore one of log f O2(g) vs pH. This runs faster than using a ‘Fix_pe’ approach.
Since the pe is always carried in the calculations and in the output files, a switch of y scales can
be done either when the plot is being generated or afterwards by replotting using the yscale
setting (pe, Eh or mV).

CHEMISTRY
include 'ht1.inc'
SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2
Na 1e-1
Cl 1e-1
END

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 the negative sign directly in front of the <x_axis> tag. This enables the x axis to be spec-
ified in directly terms of pH. This works because the substitution of the tag is done without
introducing extra spaces around the tag. This approach works providing the value of <x_axis>
does not become negative. The alternative is to use a numericTags relation to define a new tag
as -<x_axis>.
In summary, you have to supply the initial solution conditions (total concentrations), the
means of traversing the x- and y-axes by including the <x_axis> and <y_axis> tags, and you
must include any phases that might precipitate in an EQUILIBRIUM_PHASES keyword block.
It is possible to modify the ht1.inc file to alter the logic by which a species is promoted to the
top. For example, the minstab1.inc and minstab2.inc files are designed to highlight the
most abundant or most likely minerals present. It is also possible to alter the way that species
names are presented, for example, for minerals, by adding the mineral formula underneath the
mineral name (e.g. see for an example of this) or instead of the mineral name.

8.1.3 Optimising the calculation efficiency

Minimizing the size of the tag dictionary can significantly increase the speed of computations
and therefore unused tags should be removed wherever possible. Minimizing the number of
mineral phases considered will also improve the calculation speed.

8.1.4 Predominance vs mineral stability diagrams

A predominance diagram always shows the predominant species (unless overridden by a con-
straint). The predominant species is the species accounting for the largest number of moles of
 Predominance diagrams 97

the main species. A stability diagram is similar except that if a mineral species is present, it
overrides all solution species in precedence no matter what their concentration. The diagrams
are not too different since minerals are often quite insoluble and often dominate the overall
speciation not far from solution-mineral boundaries. If more than one mineral species is
present, the most abundant mineral (in terms of moles of the main species) takes precedence.
The choice of calculating predominance and mineral stability diagrams can be readily imple-
mented by including the ht1c.inc code in the PHREEQC code.
If a mineral stability diagram containing only mineral species is wanted then the main species
should be set to the special value ‘minerals’ and most importantly, the minstab1.inc include
file used instead of ht1.inc ( Example 53). Precedence is then calculated in terms of the most
abundant mineral species (in terms of moles of mineral), if present. Precedence in this case can
therefore depend on the mineral formula used.

8.1.5 Using ht1minerals.inc to determine the minerals present

Many of the minerals in a database will never actually become stable anywhere in a predomi-
nance plot even where all the necessary components are present in the system. They may never
be anywhere near saturation or may be protected from precipitating by a closely-related but
more stable mineral.
These non-precipitating minerals can be excluded from the speciation calculations without
any loss of accuracy. This is significant since excluding these unnecessary minerals from the
EQUILIBRIUM_PHASES data block can speed up calculations considerably.

The include file, ht1minerals.inc, is similar to ht1.inc except that it also writes as ‘carry’
variables all minerals that have a saturation index of zero or above for each speciation calcula-
tion, i.e. these are the species that are either saturated or supersaturated.
PhreePlot automatically analyses all the ‘carry’ variables in the out file, if present, and sends
summary statistics to the log file. In this case, there will be a table of all the minerals species for
which SI>=0 at some point. Looking at the ‘max’ column in this table gives the required infor-
mation. All species which have a max value of 0 (or very close to it) have precipitated and must
have already been included in EQUILIBRIUM_PHASES. Those with a max value significantly
greater than 0 might precipitate if included and are therefore potentially relevant.
The supersaturated minerals will be those that exist in the database and which might have pre-
cipitated but have not done so since they have not been included in the EQUILIBRIUM_PHASES
data block. Re-running with all of these minerals included will enable a minimum set of min-
erals to be identified, i.e. those that then have a max value close to zero.
Using ht1minerals.inc therefore identifies all minerals in a database that may be relevant to
the present system – as well as those that are definitely not. This includes all minerals, not just
those containing the main species.
This option requires that the out file is actually produced – it is not by default. This is
achieved by setting ‘out T ’ in the input file. Other than that just replace ‘ht1.inc’ by
‘ht1minerals.inc’ in the input file.
Since this approach only analyses the speciation calculations actually carried out, it is necessary
to cover the whole domain of interest fairly systematically. This is best done with the ‘grid’
method.
An alternative approach is to automatically include all possible minerals in the
EQUILIBRIUM_PHASES data block. This is the approach taken by the ht1allminerals.inc
include file and the demo\minstab\allminerals.ppi example.

8.2 THE ‘GRID’ APPROACH

The grid approach ( Example 1) is simple and reliable but relatively slow especially at high res-
olutions. It does not rely on being able to access all internal boundaries from the domain
98 PhreePlot Guide

boundaries nor does it require relatively noise-free boundaries. The ht1 approach requires
both of these conditions.
The resolution specified for a grid plot divides the x- and y-axis ranges into a square grid
with the specified number of nodes in each direction. There are therefore resolution-1 grid
cells in each direction, each with a node at its centre. Since the cells are centered on the nodes
and the plot is clipped on the domain boundaries, the peripheral set of cells around the plot
are actually plotted as half cells.
Speciation calculations are carried out at each node and the dominant species identified for
each node-centered cell. The results of these calculations are stored in the track file. This is the
file that is used for replotting.
Each cell or pixel is ‘coloured’ according to the dominant species and the boundaries between
species located to give polygons. This approach does not go down to the vector (individual
line segment) level which means that it is not possible to simplify the boundaries using the
same algorithm as used in the ht1 approach. The characteristic steps in the original pixel
boundaries are therefore retained.
By default all of the polygons are coloured and labelled. This includes polygons such as H2(g)
and the ‘not available’ or an NA field that is produced when the PHREEQC speciation fails.
Any field can be omitted from a replot by setting the species (sp) number in the labels file
(*.lab) to a negative value.
The polygons are rendered in order of decreasing size, largest first.
The results of the speciation are stored in the track (‘trk’) file. Since these are calculated in a
well-defined manner, the calculations can be restarted from a partially complete set of calcula-
tions produced by a crash or by using an interrupt and stop. To do this, set calculationMethod
to 3 and restart. This should resume calculations from where they left off and applies to both
the track file and the out file if selected. This works with both the ‘grid’ and ‘grids’ calcula-
tion methods.

8.3 THE ‘HUNT AND TRACK’ APPROACH

8.3.1 Strategy

The ‘hunt and track’ approach finds and follows internal boundaries on predominance and
mineral stability diagrams. It starts by hunting along the left-hand y axis until it finds a cross-
over of predominant species then uses this to track internally. Once this has been exhausted, it
hunts along the remaining axes. Critically, this approach relies on the assumption that all such
boundaries can be reached from a domain (axis) boundary, i.e. that there are no ‘islands’. This
is often the case (Example 1 and Example 3), but not always (Example 2 and Example 42).
The ‘ht1’ algorithm tracks the internal boundaries using single steps of fixed length along an
imaginary grid. At each point, the algorithm requests a speciation calculation to be made and
expects the speciation program to return the concentration and name of the top three species,
i.e. the three most abundant species. These are transmitted via the SELECTED_OUTPUT file. The
precise way that these are calculated is controlled by the user using statements within the
USER_PUNCH block of a PHREEQC input file. It is also possible to provide user-defined con-
straints that override the normal predominance sequence. This enables infeasible areas of the
diagram to be clearly defined.
The input file also controls all other aspects of the chemistry including the initial chemical
setup, e.g. total element concentrations and a list of all the gas, mineral and adsorbed phases
potentially present, and the way in which the x- and y-axes of the diagram are to be traversed
in response to requests from the ht1 algorithm.
The step size and resolution of the grid is controlled by the resolution parameter. The step size
is simply the span of each axis (maximum value – minimum value) divided by the resolution-
1. The resolution is always the same for both x- and y-axes.
 Predominance diagrams 99

8.3.2 Details of the ‘hunt and track’ algorithm

Applying the concepts of hunting and tracking at the practical level

We assume that presented with values for the two 'master' variables (representing the x and y
axes on the predominance diagram), the speciation program can return either a complete spe-
ciation or at least, the predominant species. This is what the ht1.inc script does.
As mentioned above, the ht1 strategy for locating the field boundaries makes the assumption
that all domain and axis boundaries are interconnected, i.e. there are no 'islands' (Kinniburgh
and Cooper, 2004).
The grid approach on the other hand is rather inefficient since many of the points evaluated
will be far from a boundary and will therefore contribute little useful information. It is also
difficult to guarantee locating all of the fields without a fairly large computational effort. The
ht1 approach concentrates on locating and tracking the various boundaries and puts no effort
into computations far from the boundaries. It requires no initial grid of points. The algorithm
is similar to that sometimes used to locate 'zero phase fraction lines' in phase diagrams and
starts by systematically hunting along each axis boundary in turn until a change in predomi-
nance field is found. Once a change has been located, the algorithm tracks along the boundary
until it reaches another axis, remembering any junctions with other predominant species as it
goes. It then returns to these junctions to follow these paths until all of the internal boundaries
have been followed. It then hunts along any remaining axes, again tracking internal bounda-
ries until all four axes have been searched.
Our hunt and track algorithm is based on a fixed regular grid over the domain of interest
defined by the x and y axes. The domain is usually rectangular, with its boundaries (axes) also
being grid lines. The algorithm assumes that at least one predominance boundary actually
crosses an axis (if none does, there must be just a single predominant species).
The first task is to identify such a crossing point by searching along boundaries. Starting at a
selected corner of the domain, the predominant species is identified. The next point for com-
putation is the nearest grid point on the axis defining the domain boundary, moving in a
selected direction. If this has the same predominant species, the algorithm moves on to succes-
sive grid points on the axis until a change is found. This is the ‘hunting’ part of the algorithm.
Once a point of change has been identified, the algorithm moves into "tracking" mode, fol-
lowing the predominance boundary within the domain.
Figure 8.2 shows an example with a predominance boundary (shown as a dashed line), whose
precise location is unknown, crossing the y axis of a rectangular domain. Grid points where
speciation calculations are undertaken are identified in Figure 8.2 by numbered open and
filled circles. The numbering indicates the order in which the grid points of interest are vis-
ited.

(a) (b)

9 10 11

ary
c und
e bo d
Tru 2
cies
4 5 7 12
spe
a
log concn

g b
ckin
3 Tra 6 8
spec
ies 1
Domain boundary

2
Species 1 dominant
Species 2 dominant
Hunting

1 x1 xb x2
(5) (7)

Figure 8.2. Strategy for tracking the boundary between two fields. (a) after locating a change in dominance on a
100 PhreePlot Guide

domain boundary, cells are explored in the order a, b, c…. The numbers indicate the order and location where spe-
ciation calculations are undertaken and the filled and open symbols at the grid intersections indicate the dominant
species returned by these calculations; (b) method of linear interpolation used to establish boundary location in cell
d).
In this example, the first grid point in the sequence is on the y axis where the algorithm is in
hunting mode. It continues through points 2 and 3, where there is no change in predominant
species, reaching point 4 where a change is identified. There must therefore be an intersection
of the y axis with the predominance boundary between points 3 and 4. The tracking mode
now begins with predominance values calculated at points 5 and 6, which complete rectangle
a on the grid. The predominance boundary must exit through one of the remaining three sides
of this rectangle. This is immediately identified as the side linking points 5 and 6. This exit
side for rectangle a becomes the entry side for rectangle b, the second to be constructed. Cal-
culation of predominant species at points 7 and 8 shows that the exit side for rectangle b is the
side linking points 5 and 7. Rectangle c is built on this side, with exit side linked by points 7
and 10, on which rectangle d is constructed.
This technique tracks a sequence of grid squares through which the predominance boundary
runs. It does not provide coordinates through which the line passes. These can be approxi-
mated by linear interpolation along each exit or entry side. Four values are required to carry
out this interpolation (Section 8.2). These are the concentrations of the dominant and sub-
dominant species at the end points of the side. Denote the end points (x1,y1) and (x2,y2), and
the dominant and subdominant log10 concentrations are d1, s1, d2 and s2. Then the linearly
interpolated approximate location (xb,yb) of the predominance boundary as it crosses the line
joining (x1,y1) and (x2,y2) is:
On a rectangular grid, either x1=x2 or y1=y2, so one or other of the equations will always be
degenerate, with either xb=x1 or yb=y1. It is straightforward to extend this concept to three
components. This improves the all-important location of triple points.
The successive construction of exit/entry lines, and rectangles on the fixed grid continues until
it either exits from the domain, or a junction on the predominance boundary is identified. A
junction is indicated when more than two species are identified as dominant amongst the four
corners of a rectangle. If, for example, there are three dominant species then these define two
exit sides from a single rectangle. The two boundary lines from this rectangle are then tracked
in turn, with appropriate flagging of the necessary sequence of operations. For more complex
examples, a predominance boundary may return to a previously identified junction. The algo-
rithm keeps track of when this occurs. Finally, the line segments are assembled into polygons.
The domain boundary should be exhaustively searched in hunting mode to ensure no pre-
dominance boundaries are missed. Once a crossover point has been established, its location is
progressively refined with sub-grid accuracy. It is sometimes necessary to increase the grid res-
olution to ensure that the hunting and tracking sequences join up properly. This is done auto-
matically but requires a complete restart.
The present approach of stepping sequentially through every domain boundary grid point is
recognised as inefficient, though guaranteed to detect all crossings within the resolution (grid
spacing) chosen. If the grid is too coarse, the location of junctions may be poorly estimated.
For a fixed grid algorithm of this sort there will be a trade-off between computational effi-
ciency and accuracy. A grid spacing equivalent to a resolution of 1/500 of the domain bound-
ary normally gives smooth and reliable curves. The advantage of using a fixed grid is that quite
complex curves may be tracked. However, the scheme does not take full account of the known
characteristics of some predominance boundaries inherent in the underlying chemical model.
This can lead to some inefficiency. We make no assumptions about the curvature of the field
boundaries which are often straight but which can be curved and can even show very sharp
changes of direction.
A similar tracking procedure can be followed when the stability criterion is used or when an
artificial boundary is added as a result of a user-defined constraint, e.g. H2(g) = 1 atm. In these
cases, linear interpolation can no longer be used to refine the point of intersection and so the
 Predominance diagrams 101

mid-point is always chosen.

Definitions of 'predominance' and mineral stability

In classical mineral stability diagrams, the position of the mineral-solution boundary depends
on the assumed activity of the solution components at the boundary. Garrels and Christ, fol-
lowing Pourbaix, defined the boundary as the point where the 'sum of the activities of the ions
in equilibrium with the solid exceeds some chosen value'. They chose 10-6 as a default value
on the basis that if it is less than this value, the solid will tend to behave as an immobile con-
stituent in the environment. In the full speciation approach, the activity at the boundary is
determined by the system specification and the speciation calculation and will normally be
specified by either a fixed total amount of the various components or by a fixed activity/fugac-
ity, e.g. for gases. There is no need for excessive simplification of the system and so such dia-
grams can be customised for systems of particular interest. The only decision is whether to
draw the boundary for the predominance domain or the stability domain.
When adsorption reactions are included, it is possible to compare the total number of moles
of the main species in each of the phases (gas, solid, solution, adsorbed) to determine the pre-
dominant phase (out of the four possibilities). Alternatively, more detail can be revealed if each
species is considered independently as is normally done in solution-only predominance dia-
grams. The predominant species is then defined as the species accounting for the greatest
number of moles in the whole system. The ht1.inc code treats each adsorbed species as a sep-
arate entity, just like a solution species. The definition of 'species' becomes more ambiguous
when an 'adsorbed' phase is considered since the normal definition of an adsorbed species is in
terms of the type of binding site and so would make the diagrams very sensitive to adsorption
model adopted. Probably a more useful approach is to lump all adsorbed species together into
one ' super species' for the purposes of ranking. This is the approach adopted in the ht1c.inc
code. If the detailed adsorbed speciation is of particular interest, then ht1.inc should be used.

8.3.3 Failure of the ‘hunt and track’ approach

One advantage of the ‘hunt and track’ approach is that it can creates a vectorised diagram
directly. This leads to a small plot file size and after smoothing of the field boundaries can pro-
duce smooth-looking boundaries as opposed to the jagged boundaries of the grid approach.
In principle the ‘hunt and track’ approach can produce better quality diagrams with less com-
putational effort - the effort depends on the length of the boundaries that must be tracked
rather than on the square of the resolution as with the grid approach. But the important caveat
is that it can miss potentially important fields if they do not cross any of the domain bounda-
ries. This can occur when ‘wedges’ intersect the domain boundary
Such islands appear to be quite rare and the phase rule indicates that they are likely to be con-
fined to solution species. One example is given in Example 42. We have checked all the other
diagrams in this report and have found no other ‘islands’.
Nevertheless, it is always important to check that there are no islands by switching the calcula-
tionType from ‘ht1’ to ‘grid’ and reducing the resolution setting to a more reasonable value.
A second problem is that in order to generate the required field boundaries and associated pol-
ygons, it is necessary that all the various line segments produced during tracking fit together
exactly. Because of numerical errors implicit in the numerical approach used by PHREEQC,
this is not always the case and it is possible to get lack of closure of some polygons.

8.4 FEASIBLE DOMAINS AND THE PREPARATION OF EH (PE) -PH DIAGRAMS

8.4.1 General principles

The classical Pourbaix diagrams extend from pH 0 or less to pH 14 and over a wide range of
redox conditions effectively ranging in oxygen partial pressures, say from more than 1e0 to less
102 PhreePlot Guide

20
O2(g) > 0.21 atm

0
Fe2(OH)24+
Fe3+
-20
log f O2(g)

Fe(OH)3(a)
-40

-60 Fe2+

-80 Fe(OH)3-
FeOH+
H2(g) > 1 atm
NA
-100
0 2 4 6 8 10 12 14
pH

Figure 8.3. log f O2(g) vs pH diagram for the Fe-H2O system at 25oC calculated using the
hunt and track approach for a domain range of -100 >log f O2(g)>+20 and 0<pH<14. It
shows the regions with log f O2(g) < -95 and pH< 1 where PHREEQC fails to converge
(label = NA).

than 1e-100 atm. Extreme conditions such as these may not be physically realistic and are only
considered in classic Pourbaix diagrams because the constraints of a full speciation are not
imposed. This is also not entirely within the domain within which PHREEQC is able to
operate (at least using its ion association activity model) especially under the extremes of redox
conditions where water is itself not stable – making the concept of ‘dissolved’ species a non-
sense. This domain of failure can be mapped and is shown in using the ht1 approach (Figure
8.3). The grid approach gives a similar result.
At 25oC, the failure occurs at below log f O2(g) of -96 atm and arises because of the strong
decomposition of water under these conditions – it decomposes releasing H2(g). This failure
occurs at a higher log f O2(g) at higher temperatures, e.g. at log f O2(g) of -86 at 60C. There is
also a limit to the maximum O2(g) partial pressure that can be sustained in aqueous systems
since it combines with H+ to produce water. PHREEQC will eventually fail under these
extreme conditions, though not without trying hard (and taking a lot of time attempting to
find a solution).
As a consequence of these reactions and of limits to the practical limits of O2(g) that are rea-
sonable, a typical Eh(pe)-pH has upper and lower diagonal lines that demarcate regions where
the diagram is not evaluated.
On an orthogonal log f O2(g)-pH diagram, these ‘no evaluation’ regions can be simply
excluded from being calculated by specifying appropriate upper and lower limits to the O2(g)
fugacity.
Therefore a pe-pH diagram can be most easily prepared by specifying the y-axis variable to be
log f O2(g) and then converting the redox scale with the yscale setting. It is possible to drive
the y axis with the pe by defining the pe in an analogous way to that used for pH:
 Predominance diagrams 103

Fixed_e-
e- = e-
log_k 0.0
and then
...
EQUILIBRIUM_PHASES
...
Fixed_e- <loge-> O2(g)
where the sign of the y-axis variable is reversed using
numericTags <loge-> = -<y_axis>

8.4.2 Domain tags - avoiding speciation calculations in part of the predominance diagram

The calculation domain for predominance diagrams is always a rectangular area defined by
(xmin, xmax, ymin, ymax). It can be useful to omit certain parts of this domain from the spe-
ciation calculations, e.g. because the speciation is known to be unsuccessful or unnecessary in
some region(s).
A special set of tags called domain tags can be used to clip the speciation domain, e.g.
<domain1_value> = “<x_axis>+<y_axis>” \
<domain1_min> = -2 \
<domain1_max> = 22
These tags are defined in the usual numericTags block. <domain1_value> is evaluated before
each speciation calculation and compared with the minimum and maximum values set with
the <domain1_min> and <domain1_min> tags. If the value is outside this range, then the specia-
tion calculation is skipped.
Note that domain value needs to be determined before the speciation calculations and so the
definition of the <domain1_value> tag should only use those tags that are known before speci-
ation. The most obvious ones are the <x_axis> and <y_axis> tags.
The above test is only applied to main loop simulations. Pre-loop simulations will always be
calculated in full.
These tags can be used when generating a pe-pH diagram in order to eliminate speciation cal-
culations from areas outside of the lower and upper bounds for the stability of water.
The skipped domain is by default assigned the ‘species’ name “Skip” and speciation values are
set to UNDEFINED. The results are included in the track file as usual. A ‘-’ sign precedes the iter-
ation number of the rolling summary shown on the screen during the calculations.
The species name and therefore the label used can be renamed by editing the labels file and
replotting, or by adding a special character tag with the name, <domain1_name>. The name
can be the empty string, “”.
Up to nine sets of domain tags, <domainn>_... (n = 1...9), can be used in this way. The name
of the field used is taken from the first out-of-domain criterion searching from 1 to 9.

8.4.3 Speciation failure when there is not enough reactant present

This most frequently happens when trying to fix the pH using the ‘Fix_pH’ ploy. PHREEQC
will fail to converge at low pH if the reaction being used to achieve the desired pH is not feasi-
ble. For example, if NaOH is being used to change a solution from pH 2 to pH 1, it will likely
eventually fail. In the presence of a background electrolyte such as NaCl, this failure does not
occur at exactly pH 2 but at a somewhat lower pH depending on the amount of Na present.
PHREEQC will attempt to achieve the low pH by withdrawing NaOH (negative NaOH
additions) until all the Na has disappeared at which point it will necessarily fail. This problem
can be solved by linking the Na to a large reservoir of a Na-containing mineral (Section 6.5.4)
such as NaCl but this itself can have undesirable side effects. The problem can be more com-
plicated when other side reactions such as redox reactions are themselves producing/consum-
ing protons.
104 PhreePlot Guide

8.5 CHOICE OF THE RESOLUTION OF THE PLOT

The speed of calculation depends on many factors including the complexity of the chemistry,
especially the number of mineral phases, the length of the USER_PUNCH code and the resolution
of the plot. A reasonable approach is to start at a low resolution, say 50-100 for a ht1 plot or
20-50 for a grid plot, and increase it when a production quality plot is required. The resolu-
tion must be 10 or greater and should normally be less than 2000. The ht1 algorithm can fail
to resolve junctions at low resolutions which can lead to a failure to close all the polygons
properly.
If more detail is required for a particular area, zoom in by reducing the domain size with the
xmin, xmax, ymin, or ymax parameters and recalculate rather than just replotting at the new
scale.
PhreePlot sometimes overrides the resolution originally set in the input files and either
increases or decreases it. It does this when it either needs more resolution to resolve apparent
4-way junctions or when a junction is too close to a domain boundary: Changing the relevant
domain boundaries (xmin, xmax, ymin, or ymax) would avoid the latter problem. A reduction
in resolution is sometimes necessary if the output from PHREEQC is for any reason unstable.

8.6 MONITORING THE PROGRESS OF A ‘HUNT AND TRACK’ RUN

Providing that the screen output has not been disabled, progress of the tracking will be dis-
played on the screen. An example is given below:
*** PhreePlot *** Pre-release 0.01 (3 Jan 2008)
Incorporating the PHREEQC library by DL Parkhurst, SR Charlton (USGS),
& CAJ Appelo (Amsterdam)
Hunt & Track by DG Kinniburgh, BGS and DM Cooper, CEH (NERC)
Fitting by MJD Powell (University of Cambridge)
Postscript plotting by KE Kohler (Nova SE University)

<mainspecies> = Se
1 2.0000 -80.0000 11 Se H2Se -3.0010 -5.6388
2 2.0000 -76.8000 11 Se H2Se -3.0000 -7.2388
3 2.0000 -73.6000 11 Se H2Se -3.0000 -8.8388
4 2.0000 -70.4000 11 Se H2Se -3.0000 -10.439
5 2.0000 -67.2000 11 Se H2Se -3.0000 -11.847
6 2.0000 -64.0000 11 Se H2Se -3.0000 -13.447
7 2.0000 -60.8000 11 Se H2Se -3.0000 -15.047
8 2.0000 -57.6000 11 Se H2Se -3.0000 -16.647
9 2.0000 -54.4000 11 Se H2Se -3.0000 -18.247
10 2.0000 -51.2000 11 Se H2SeO3 -3.0000 -18.105
11 2.0000 -48.0000 11 Se H2SeO3 -3.0000 -14.905
12 2.0000 -44.8000 11 Se H2SeO3 -3.0000 -11.705
13 2.0000 -41.6000 11 Se H2SeO3 -3.0000 -8.5055
14 2.0000 -38.4000 11 Se H2SeO3 -3.0029 -5.3055
15 2.0000 -35.2000 11 H2SeO3 HSeO3- -3.1277 -3.5938
16 2.0000 -36.8000 11 Se H2SeO3 -3.1333 -3.7055
17 2.0000 -35.2000 11 H2SeO3 HSeO3- -3.1277 -3.5938
18 2.0000 -36.0000 11 H2SeO3 HSeO3- -3.1277 -3.5938
19 2.0000 -36.4000 11 H2SeO3 Se -3.3055 -3.4738
20 2.0000 -36.6000 11 Se H2SeO3 -3.2358 -3.5055
21 2.0000 -36.4000 11 H2SeO3 Se -3.3055 -3.4738
22 2.0000 -36.5000 11 Se H2SeO3 -3.3256 -3.4055
23 2.0000 -36.4000 11 H2SeO3 Se -3.3055 -3.4738
24 2.0000 -36.4500 11 H2SeO3 Se -3.3555 -3.3892
25 2.0000 -36.4750 11 Se H2SeO3 -3.3553 -3.3805
26 2.0000 -36.4500 11 H2SeO3 Se -3.3555 -3.3892
27 2.0000 -36.4625 11 H2SeO3 Se -3.3680 -3.3717
28 2.0000 -36.4687 11 Se H2SeO3 -3.3634 -3.3743
29 2.0000 -36.4625 11 H2SeO3 Se -3.3680 -3.3717
30 2.0000 -36.8000 21 Se H2SeO3 -3.1333 -3.7055
31 2.0000 -36.0000 22 H2SeO3 HSeO3- -3.1277 -3.5938
32 2.0800 -36.0000 23 H2SeO3 HSeO3- -3.1496 -3.5356
33 2.0800 -36.8000 24 Se H2SeO3 -3.1415 -3.7055
34 2.0000 -36.8000 11 Se H2SeO3 -3.1333 -3.7055
35 2.0000 -36.4687 11 Se H2SeO3 -3.3634 -3.3743
36 2.0000 -36.8000 21 Se H2SeO3 -3.1333 -3.7055
37 2.0000 -36.0000 22 H2SeO3 HSeO3- -3.1277 -3.5938
38 2.0800 -36.0000 23 H2SeO3 HSeO3- -3.1496 -3.5356
39 2.0800 -36.8000 24 Se H2SeO3 -3.1415 -3.7055
40 2.0800 -36.0000 22 H2SeO3 HSeO3- -3.1496 -3.5356
41 2.1600 -36.0000 23 H2SeO3 HSeO3- -3.1744 -3.4804
 Predominance diagrams 105

42 2.1600 -36.8000 24 Se H2SeO3 -3.1514 -3.7055

43 2.2400 -36.0000 23 H2SeO3 HSeO3- -3.2026 -3.4285
44 2.2400 -36.8000 24 Se H2SeO3 -3.1638 -3.7055

The columns are from left to right:

iteration number (number of speciation calculations)

x-axis value
y-axis value
type of move
sign: a -ve sign means a ‘constraint’ (a forced value) is in operation
first digit: 1 = hunting along an edge 2 = tracking an internal boundary
second digit: 1-4, side being traversed (starting with the left-hand y axis as 1 and
counting clockwise).
‘00’ is used for ‘grid’ plotting. ‘20’ for a ‘multi-point’ point
dominant species name
subdominant species name
log concentration (mol/kgw) of dominant species
log concentration (mol/kgw) of subdominant species.

Where a constraint is operating, the indicated ‘dominant species’ is the constraint species, such
as a gas or in the case of a mineral stability diagram, a mineral. The indicated ‘subdominant’
species is the species that would be dominant in the absence of the constraint. The numeric
values of constraints are the log’s of the constraint value. In the case of pure phases (gases and
minerals), this is the saturation index.
In the above example, the algorithm starts hunting along the y axis, finds a boundary crossing
the axis between -36.4625 and -36.8 and then starts tracking inwards along that boundary.
The boundary being tracked is between H2SeO3 and Se.
A full record of the tracking is recorded in the track file.
A graphical display of the grid or ht1 tracking can be obtained by using the ‘Esc p’ combina-
tion. A plot file ‘plot.ps’ will then be written to the input file directory showing progress. In
a ht1 plot, the blue filled circle shows the current calculating position. This plot only records
the tracking phase, not the hunting phase.

8.7 PLOTTING AND REPLOTTING

calculationMethod 1 does a full set of speciation calculations and will generate all the files nec-
essary for plotting.
calculationMethod 2 does not recalculate the speciation or redo the calculation of the polygon
boundaries but reads in these results from the polygon file and the label names and positions
from the labels file.
calculationMethod 3 does not recalculate the speciation but does recalculate the polgons and
label placement.

8.8 MODIFYING THE APPEARANCE OF PREDOMINANCE PLOTS

The appearance of the plot can be modified through many of the keywords. These can be
changed in the input file and the file rerun with one of the two replot options - there is no
need to redo the calculations unless a different resolution is required.
The colours of the fields can be modified by editing the appropriate fill colour dictionary -
that is a file with the default name of fillcolor.dat.
106 PhreePlot Guide

Fields are known primarily by the number assigned to them. The labels file translates this
number into a field name. The colouring of individual polygons can be turned off by setting
the species number in the labels file to zero.
Individual polygons, and their boundaries, can be removed from the plot by setting the species
number for all points (‘lines’) for the polygons of interest in the polygon file to zero or a nega-
tive number (reversing the sign in a text editor is the most convenient way of doing this).
The label can be changed by editing the species name in the labels file. This can include the
blank field name, “”.
It is possible to change the y scale (native, pe, mV or V) without recalculation using yscale.
Plot limits can be changed using pxmin etc but beware that if a larger range is specified there
will be a blank area around the plot and if a smaller domain is chosen the field boundaries will
appear correspondingly coarse – would be better to recalculate at the new resolution which
will also calculate the label positions better.
The ‘steppiness’ of the boundaries in ‘ht1’ plots can be controlled with the simplify keyword.
The default value is 1 so choose a larger value (up to 10 say) to smooth the line more. Recalcu-
late the boundaries and replot using calculationMethod 3 rather than 2 since the smoothing
has to be redone. A simplify value of 0 will show all the boundary points. ‘grid’ plots are by
definition ‘steppy’ and simplify has no effect on this.
Additional text, including labels, can be added with extraText. There is full control over the
plot on which to apply the text plus the font, size, colour, justification and orientation of the
added text.
Additional data from other files can be added to the plot using the points and lines keywords
combined with the extradat keyword to add the additional data files to the search path. These
data must be in regular tabular output format. There is no automatic labelling or generation
of a legend for lines or points added in this way. extraText can be used to add labelling manu-
ally. extraSymbolsLines can be used where more control is wanted over the symbols used or
the line widths.
The entire plot can be rescaled with plotFactor.
Some of the main settings for ill are shown in Figure 8.4. For more complete control over the
appearance of the plot transfer the data to a more powerful plotting package. This can be done
at either the image (ps file) or data (pol and vec files) level.

8.9 ADDING LINES AND POINTS TO A PREDOMINANCE PLOT

It is possible to add lines and points to a predominance plot using the lines and points key-
words. However, these data are not included in the auto scaling – this will be determined by
the predominance plot alone. customXcolumn will need to be defined though this does not
need to match the x-axis variable in the predominance plot. No legend will be produced. The
2y axis option does not operate in this mode.

8.10 CONTROLLING THE LABELLING OF PLOTS AND THE PLOTTING OF FIELDS

The label positions are taken from the labels file and so may not be centered if the plot has
been rescaled. They will not be plotted if their centres are out of the plot area. In such cases,
do a full recalculation (calculationMethod 1) to position the labels properly or edit the labels
file manually.
Turning the printing of individual labels on and off can be automatically controlled with the
minimumAreaForLabelling based on the size of the fields (useful for excluding the labelling of
small fields) or by editing the labels files and setting the species number to a negative value. All
labelling can be turned off by setting labelSize to zero. The plotting of entire polygons can be
turned off with the exclude list of the pol keyword. In a ‘ht1’ plot, the domain boundaries can
be turned off with domain.
 Predominance diagrams 107

plotTitle
plotFactor
plotTitleSize
plotTitleColor

font Fe-O2-H2O
(only HFO precipitates: pe scale)
domain
pymax 25

pymajor minimumAreaForLabeling tickSize

tickColor
Fe3+
pydec 15 Fe2(OH)24+
O2(g) > 0.21 atm
axisLineWidth
yscale axisLineColor
yaxisLength

pe 5 Fe(OH)3(a) labelSize
labelColor
ytitle Fe2+

lineWidth
-5 lineColor
changeSignOnYaxis H2(g) > 1 atm simplify
FeOH+
Fe(OH)3-
pyminor
pymin -15 axisNumberSize
2 4 6 8 10 12 axisNumberColor

xoffset pxminor pxdec pH pxmajor

yoffset pxmin pxmax
xtitle
axisTitleSize
changeSignOnXaxis axisTitleColor

xaxisLength

Figure 8.4. Typical ‘ht1’ predominance plot showing some of the keywords that control the
appearance of the plot.

The plotting of labels also depends on the calculationMethod setting – choose method 2 or 3
after editing the labels file (Table 8.1).

Table 8.1. Influence of the calculationMethod setting on when and where labels are plotted,

Setting Action
Does a full speciation calculation. Generates new labels and polygon files which are
used for positioning labels and identifying fields. If a labels file of the correct for-
calculationMethod = 1 mat* exists before calculations, then a negative sign in front of a species number
will suppress the plotting of that label. The labels file will be rewritten.
Does not carry out any new speciation calculations and does not regenerate the
labels and polygon files. If a labels file of the correct format* exists before calcula-
calculationMethod = 2 tions, then a negative sign in front of a species number will suppress the plotting of
that label.
Does not carry out any new speciation calculations but does regenerate the labels
and polygon files. If a labels file of the correct format* exists before the calculations,
calculationMethod = 3 then a negative sign in front of a species number will suppress the plotting of that
label. Reassembles and resimplifies the field polygons starting with the results of
the initial speciation which are read in from the points (‘ht1’) or track (‘grid’) files.
* Each row of a correctly formatted labels (*.lab) file corresponds one to one in order and species number with the spe-
cies (sp) specified in the polygon (*.pol) file.

The domain keyword controls whether the domain boundaries will be plotted or not. The
default is T(RUE) which will plot the boundaries. If the native scale and automatic axis scaling
are chosen, the domain boundaries will coincide with the axes boundaries. It can be useful to
switch the domain boundaries off when a plot is rescaled and a constraint such as a gas partial
pressure exists, e.g. to remove the outer lines specifying the water limits in pe-pH plots.
The default x- and y-limits to a predominance plot are set to the calculation domain as speci-
fied by xmin, xmax etc and any fields with out-of-plot boundaries are clipped. The plot limits
can be reset with pxmin, pxmax etc.
108 PhreePlot Guide

Since predominance plots calculated with the ‘grid’ approach have cell-centered speciation
values, the first and last rows and columns of the grid are half clipped when the default (auto)
x- and y-limits are specified.
The labels are allowed to extend beyond the plot domain by 15% of the axis length. Anything
beyond that is clipped.

8.11 FAILURE TO COMPLETE A PREDOMINANCE DIAGRAM

The grid approach should always produce a valid diagram although its quality will be deter-
mined by the resolution chosen. There is no requirement for any spatial continuity between
adjacent cells.
There is no guarantee that the ‘hunt and track’ approach will always work. Either PHREEQC
may fail or the tracking may fail. Possible reasons for the failure of PHREEQC have been dis-
cussed elsewhere (Section 6.5.4).
The simple ‘hunt and track’ algorithm used in PhreePlot assumes that the speciation is
returned without error and tracks accordingly. Clearly since all speciation programs, including
PHREEQC, use numerical methods to derive their solution, the boundaries between fields
must contain some ‘noise’. This may mean that the fields reported near field boundaries may
themselves be in error , eg. varying 1212 rather than 1122. This may in turn mean that the
fields (polygons) cannot be closed properly and so cannot be plotted as coloured polygons.
This is par for the course and is not an error in PHREEQC per se but in the way it is being
used.
In PHREEQC, the convergence_tolerance parameter in the KNOBS keyword block speci-
fies a relative error for an element’s mass balance and this controls when a valid solution is
deemed to have been achieved. Typically this parameter is set at 1e-12 when
SELECTED_OUTPUT; -high_precision is set to true. Either use KNOBS to increase it (e.g. to
1e-8) or set -high_precision to false. It may be helpful to change this setting where there is a
problem in convergence typically seen when the residuals are very small but exceed 1e-12.
If the tracking grid falls on or very close to a true predominance boundary, PhreePlot could
end up tracking noise, or more likely, some of the results of the speciation calculation could be
erroneous resulting in confusion for the tracking algorithm as indicated above. This can also
occur when a field boundary–domain boundary intersection is very close to one of the four
domain corners. If detected, PhreePlot attempts to get round this automatically by reducing
the resolution of the plot by about 10% and recalculating but this does not always work. A ‘*’
in the n column of the pp.log file indicates that an automatic restart has been made. The
Mn.ppi, fluoritepredominance.ppi and fluoritestability.ppi demos are examples of this.
It also sometimes occurs that the ‘ht1’ method requires a greater resolution than given to
resolve a junction or to close all polygons. In these cases, PhreePlot will automatically restart
with a doubling of the resolution. This increase will be repeated if necessary up to a maximum
resolution of 2000.
Other actions that can be used to resolve failures of the method involve moving the grid in
other ways: changing the domain of the calculations (xmin, xmax, ymin, ymax) or by reducing
the resolution more radically.
In rare cases, PHREEQC does not converge at all. This is usually, but not necessarily, clearly
signalled by PhreePlot and can often be seen by the failure to write the SELECTED_OUTPUT file.
Convergence can sometimes be helped by (i) changing the -high_precision setting in the
SELECTED_OUTPUT section of the ht1.inc file (if used) to FALSE; (ii) reducing the convergence
tolerance, (iii) reducing the pe_step_size (under KNOBS), or (iv) increasing the allowed max-
imum number of iterations (also under KNOBS). However, by far the most common reason
for failure to converge is because of a poorly-constructed PHREEQC input file, i.e. inconsist-
ent chemistry somewhere.
With debug >= 1, failure, if detected, will result in an immediate halt to execution and a dump
 Predominance diagrams 109

of the offending phreeqc.out file, and in the case of debug = 2 and 3, of all the PHREEQC
output to that point. With debug = 0, the failed region will be mapped as its own species (‘NA’)
and a question mark will be added to the pp.log file to indicate a failure.
110 PhreePlot Guide
 Contour plots 111

9 Contour plots

9.1 WHAT ARE CONTOUR PLOTS?

Contour plots are the sort of plots you see when looking at a topographic map, i.e. a diagram
showing lines of equal height. Each height is called a ‘contour’. Contours do not normally
cross each other and always change in a regular sequence, one contour followed by one of its
nearest neighbours. There should be no missing, intervening contours.
This concept of ‘height’ can of course be generalised to any continuous variable and that is
what is done here. Note however that not all geochemical variables are continous variables.
Phase changes for example can introduce step changes and this can cause problems in con-
touring.
Contour plots provide another way of viewing x, y, z data where z is the variable being con-
toured. In some senses, they complement predominance diagrams.
Contours can in principle be viewed from various angles. Here we deal only with a view
directly from above rather like in a topographic map.

9.2 IMPLEMENTATION

9.2.1 Generating the contour data

The contouring algorithm requires regularly-gridded data. This is generated by PhreePlot in

the same way that is done for ‘grid’ plots using xmin, xmax, ymin, ymax and resolution.
A contour plot is made by specifing the calculationType to be ‘contour’ and by specifying a
contourZvariable.
You must provide the PHREEQC code to calculate a z-value at each x, y, point. This is nor-
mally done using the SELECTED_OUTPUT and USER_PUNCH data blocks. The name of the z-varia-
ble is given by the contourZvariable keyword defined in an input file and should correspond
with one of the USER_PUNCH headings. This variable takes the place of the ‘main species’ that is
found in a predominance plot. The position of the z-variable in the ‘punched’ output list is
not important.
It is not necessary to output the corresponding x- and y-variable values since these are defined
implicitly by their respective ranges, the grid resolution and the iteration number. However, if
the output data are to be used by some other software package, it may be helpful to output
their values. Simply add the <x_axis> and <y_axis> tags to the list of variables to be
‘punched’.
Note that because the x- and y-values are implicit, you have to be careful to make sure that
you regenerate the whole set of data when changing any of the parameters that define the
domain of the grid or the speciation calculations. The contouring package has no knowledge
of these values explicitly – it calculates their values from the position that the z-variable is read.

9.2.2 Choosing the contour levels

The contour levels are specified with the contours keyword. This can either be a list of user-
defined values in ascending order, or can be one of several automatic selected sets of values.
See contours for details. The default is for a list of 17 values to be automatically generated
from the percentiles of the z-data values.
 112 PhreePlot Guide

The main requirement for the selection of a set of contour values is that the values are well
separated – they should not be so close to each other that they enter the area of ‘noise’ created
by the numerical procedures used in generating the data being contoured.
The number of contours used will be automatically reduced if neighbouring contour values
are deemed to be too close to each other. Successive contours should always differ by at least
1e-8 x average value of successive pairs of values. This is to try and avoid contouring ‘noise’.
The ‘simplified percentiles’ auto option requires an even greater separation between contour
values and prunes the set of contour values even more aggressively (see contours).

9.3 A SIMPLE EXAMPLE

A simple example is to gain another view of the solubility of Fe (total Fe = 1e-2 mol/kgw) in a
system where the mineral Fe(OH)3(a) may precipitate. This complements the predominance
diagram produced by the input file demo/Fe/hfo.ppi. The input file would look something
like:

SPECIATION
calculationType "contour"
calculationMethod 1
contourZvariable FeT
xmin 2.0
xmax 12.0
ymin -90.0
ymax 0.0
resolution 50

PLOT
plotTitle "Fe solubility<br>(a) percentile contours"
xtitle pH
ytitle "log <i>f</i> O₂(g) (atm)"
extraText extratextcontour_hfo.dat

CHEMISTRY

# first simulation - fixed bits

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

SELECTED_OUTPUT
-reset FALSE
-high_precision TRUE

USER_PUNCH
-headings FeT
10 PUNCH log10(TOT("Fe"))

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2
Na 1e-1
Cl 1e-1
END

# second simulation - loop on this

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -<x_axis> NaOH 10
-force_equality true
O2(g) <y_axis> 0.1
Fe(OH)3(a) 0 0
END

The keywords controlling the contour plot appearance are all implicitly set at their default val-
ues as read from the pp.set file. The following are these default settings:
contours auto 17 p
contourFillcolor auto
 Contour plots 113

contourLineWidth auto
contourLineColor auto
contourShiftLabel c
contourLabelSize 2
contourLabelFont "Helvetica"
contourLabelColor auto
contourlabelFigs auto

The plotting domain is from pH 2 to pH 12 (x axis) and from -90 to 0 atm log f O2(g) (y axis)
and the z-variable is defined by FeT. The principal task for the user is to set up the calculation
of the z-data. This requires defining (a) a z-variable, here the total dissolved Fe, FeT, in the
USER_PUNCH data block, and (b) a resolution, here a 50 x 50 grid.

FeT is calculated with:

USER_PUNCH
-headings FeT
10 PUNCH log10(TOT("Fe"))

The name of this column (FeT) matches that in the contourZvariable settings and this pro-
vides the necessary link. The value of the x- and y-variables are implicit and not required but
these and others variables could also be exported, for example, with
USER_PUNCH
-headings x y FeT Fe(OH)3(a) water
10 PUNCH <x_axis>, <y_axis>, log10(TOT("Fe")), MOL(“Fe(OH)3(a)”), TOT(“water”)

If this is done, then the USER_PUNCH data block must be moved from the first to the the second
simulation otherwise <x_axis> and <y_axis> will not get updated on each iteration.
The plot produced from this input file is shown in Figure 9.1(a). This plot has been made
with auto-generated contour values and the default colouring which ranges from dark blue
(low) to dark red (high). It is possible to specify any set of contour values and any set of col-
ours.
The main task in generating a contour plot is to decide on a set of suitable contour values.
With the defaults operating, this is done by dividing the z-data into 17 approximately equally-
occupied intervals. This is called the ‘percentile’ or ‘p’ option as in Figure 9.1(a).
The major variation in the concentration of dissolved Fe shown by the plot occurs where
Fe(OH)3(a) has precipitated. Under more acidic and more reducing conditions where
Fe(OH)3(a) does not precipitate, the concentration of dissolved Fe is close to that added,
namely 1e-2 mol/kgw. This results in several contours with the same truncated label (-2) since
the actual contour values used (from the log file) are -2.000191900824, -2.000191868200, and
so on. The small but systematic variation in Fe concentration in the absence of Fe(OH)3(a)
precipitation is due to small changes in the mass of water reflecting various hydrolysis reac-
tions.
A second option when auto-generating a set of contour values is to start with the precentile
values and then to eliminate any values which are fairly close in value to each other (within a
relative difference of less than 1e-4 of the z-data range). This is called the ‘simplified percen-
tile’ (or ‘s’) option ( Figure 9.1(b)).
A third auto option is to define the contours by dividing the range of z-values (maximum z -
minimum z) by the number of contours, by default, 17, to give arithmetically-spaced inter-
vals. This is called the ‘empirical’ (or ‘e’) choice ( Figure 9.1(c)).
Of course, a list of any number of contour values can also be entered explicitly ( Figure
9.1(d)).
However derived, the set of contour values defines a set of lower class values, namely, <con-
tour(1), contour(1)-contour(2), contour(2)-<contour(3), ... >contour(n). There will always be
one more class than the number of contours specified. Internally, an additional very large con-
tour value is automatically added to the set of contours so that all data values will fit into one
of the contour intervals defined. If a value sits exactly on a contour boundary, it is allocated to
114 PhreePlot Guide

Fe solubility Fe solubility
(a) percentile contours (b) simplified percentile contours

-10

-2
-10

-2

-7.49
-7.49

-7.25
-7.25

-6.86
-6.86

-6.41

-5.12
-6.41

-6.02

-4.68
-5.12
-6.02

-4.68

log f O2(g) (atm)

-5.6
-30
log f O2(g) (atm)

-5.6
-30

-2 -50 -2
-50 .8
2 -3.8
.8
2 -3.8
8 8

-2
-70 -70

-2
-2 -2-2 -2
-2
-90 -90
2 4 6 8 10 12 2 4 6 8 10 12
pH pH
0.01 mol/kgw total Fe 0.01 mol/kgw total Fe
Concentrations of dissolved Fe in log (mol/kgw) Concentrations of dissolved Fe in log (mol/kgw)

C:\PhreePlot\demo\contour\contour_hfop.ps C:\PhreePlot\demo\contour\contour_hfos.ps

Fe solubility Fe solubility
(c) empirical contours (d) user contours
-2.3

-2.1
-10 -10

-7.5
-7.28
-6.97

-7
-6.66

-5.41
-6.35

-6.5
-5.1
-6.04

-4.79

-5.5
-5.72

-5
log f O2(g) (atm)

log f O2(g) (atm)

-30 -30

-6
-4 -4
-2 .4 .5
.6 8 -2
1 .5
--2-33..5 -4 -3-3.5
-50 .9234 -.31
2 .78
-50 -4
6

-70 -70

-2
-90 -90
2 4 6 8 10 12 2 4 6 8 10 12
pH pH
0.01 mol/kgw total Fe 0.01 mol/kgw total Fe
Concentrations of dissolved Fe in log (mol/kgw) Concentrations of dissolved Fe in log (mol/kgw)
C:\PhreePlot\demo\contour\contour_hfoe.ps C:\PhreePlot\demo\contour\contour_hfou.ps

Figure 9.1. Four options for defining contour intervals for the same z-data: (a) contours ‘auto’ option with
percentile contours (‘p’); (b) same with simplified percentile options (‘s’); (c) same with empirical (‘e’) option;
(d) a user-supplied set of contour values.

the higher class.

9.4 SOME DETAILS OF THE DATA PROCESSING

9.4.1 Algorithm

The speciation data generated by PHREEQC are stored in the ‘out’ file as normal.
These data are scanned line by line to produce the contours. The quality of the plot obviously
depends on the resolution of the grid. Normally this should be 10 or greater for draft, and 50
or greater for production.
The interpolation procedure, CONREC (Bourke, 1987), used to identify the contour location is
a ‘local’ one and only makes use of the enclosing four grid points. This may not be as efficient
 Contour plots 115

as some more sophisticated interpolation procedures but has proven to be more robust given
some of the extreme changes in slope and discontinuities encountered in geochemical-based
contour plots.
After the z-data have been generated on the requisite grid, the domain is scanned horizontally,
cell by cell, top down, and the various contour crossings established. In each cell where there is
a crossing, the contour level forms a horizontal plane that intersects an inclined plane formed
by the z-surface. This intersection is output as a short segment and eventually all such seg-
ments for a given contour level are joined together to form the contour. The raw contour data
are treated in much the same way as in a ‘ht1’ plot in that the data first undergo a line simpli-
fication to reduce the number of points. The intention is to reduce the file size without sub-
stantially changing the accuracy of the plot. This can usually be achieved with a simplify value
of 1. Smaller values will include more points, larger values, fewer points. A value of 0 will
include all of the original points, i.e. no simplification.
The simplified vectors are written to the vector (‘vec’) file along with the boundary vectors.
The individual vectors or line segments are assembled into polygons (‘pol’ file) for colouring.
The vector and polygon files include ‘direction’ information – walking forward along the con-
tour in the sequence given in the file, the high side is always on the right. This is sometimes
necessary to differentiate between ‘peaks’ and ‘holes’. The polygon files are also listed (and
plotted) in order of decreasing polygon area.
A given contour may give rise to more than one polygon if it leaves and enters the plotting
domain more than once.
Finally, the domain boundary segments are added for each contour level to enable closed pol-
ygons to be formed and therefore for the polygons to be filled with colour.
Once these ‘vec’ and ‘pol’ files have been written, they are used to produce a plot.

9.4.2 Problematic cases

The contouring is normally successful but the very steep boundaries and step changes that can
be produced by geochemical data, e.g. at mineral-solution boundaries, can give rise to practi-
cally convergent contours. The reverse situation can also occur: the surface can be extremely
flat (and inevitably somewhat ‘noisy’) leading to a relatively large error in locating the con-
tours. This can lead to ‘wiggly’ contours. This often happens when contour values are auto-
generated with the ‘percentiles’ option. Judicious choice of contour values can ameliorate both
of these problems to some extent.
These problems can lead to attempts to contour along a boundary that is particularly ‘noisy’.
This in turn can lead to an excessive amount of jumping across a contour boundary and will
eventually lead to a termination of the plotting with the message:
“Error: too many separate contour segments. 'Noisy' contour? Try changing con-
tour values, e.g. auto 10 e.”

This problem can usually be avoided by changing the contour values so that the positions of
the boundaries do not correspond with the noisy region, for example, as suggested by choos-
ing a set of equally-spaced ‘empirical’ contour values.
A good example of this is when contouring the variation of a saturation index of a potentially
precipitating mineral in a given pH-log f O2(g) domain. The saturation index will be negative
over the areas where the mineral is unstable but will be zero or ‘very close to it’ where the min-
eral is stable. Depending on the convergence settings in PHREEQC, the value of ‘very close
to it’ will vary but can be -3e-14 to 3e14 or smaller. It is entirely reasonable that the SI value
can be anywhere in this range. Therefore if a contour value of 0.0 (exactly) is chosen either
manually or automatically, there are likely to be an excessive number of contour crossings as
the contour attempts to track the boundary.
This is made worse in this case because of the discontinuity in the slope at the mineral precip-
itation boundary and the fact that the change is from a fairly steep slope while undersaturated
116 PhreePlot Guide

to a slope of exactly zero when the mineral is present.

In this and similar cases, setting a contour value of exactly 0.0 should be avoided. A small neg-
ative value, e.g. -1e-6, would probably avoid these problems and still identify the precipita-
tion boundary accurately enough.
A zero (or very small) contour value is likely to be selected in this case when the auto percen-
tile option is chosen since many of the SI values are likely to be 0.0 or very close to it. Either
set the contour values manually as described above to avoid the ‘noisy’ region around 0.0 or
choose the ‘emprical’ option for the auto selection of contour values which will probably avoid
this region anyway.
In order to fill the contour levels with colour, it is necessary to calculate closed polygon for fill-
ing. If PhreePlot fails to close a polygon, including the domain boundaries, a message to that
effect is issued and where possible the plot will be completed without any colour fill (calcula-
tionMethod 1 or 3) or just with the offending polygon(s) not coloured (calculationMethod 2).
The problem may disappear if a different set of contours is chosen or if the resolution is
increased.

9.5 MODIFYING THE APPEARANCE OF THE PLOT

The number of contours, their values and the overall appearance of the plot can be changed
explcitly with a number of contour-related keywords. These are listed in Table 9.1 and dis-
cussed in more detail under their individual headings in Section 14.

Table 9.1. Contour-related keywords

Keyword Action Default values

list of increasing values at which to draw ‘auto 15 p’ = choose 15 contours with spac-
contours contours or ‘auto [n [p|e]]’ for auto- ing based on percentiles. Round values to
selection three figures and remove any replicates
contourFillColor ‘auto’ = range of colours from dark blue to
list of colours to fill contour intervals
light blue to light red to dark red
contourLineWidth list of line widths of contours. Negative
‘auto’ = same as main line width
widths define dashed lines.
contourLineColor list of the colours of contour lines ‘auto’ = same as main line colour
c = plot as contour values and do not move
contourShiftLabel list of labels to move and by how much
any labels from their default positions
contourLabelSize list of label sizes ‘auto’ = same as main label size
contourLabelFigs list of number of figures in labels ‘auto’ = depends on value but usually 3 or less
contourLabelFont list of fonts for labels ‘auto’ = same as main font
contourLabelColor list of colours for labels ‘auto’ = main label colour

In principle, apart from contourShiftLabel, the lists above have a length that is the same as the
number of contours that are actually defined, i.e. length of contours + 1. A list of these con-
tours is given in the log file. If the specified list is shorter than required, it is recycled. If it is
longer, the excess is ignored.
The property associated with each contour is then simply picked off the appropriate list based
on the corresponding position of the contour of interest within the list of contours.
In this way it is easy to repeat sequences of properties, e.g. if contourLineWidth 0.3 -0.3,
then this would alternate a full line and a dashed line.
It is also possible to add extra text, lines and symbols with extraText and extraSymbolsLines in
the normal way.
Figure 9.2(a) shows the above example plotted with user-defined contour values and default
values for most of the other settings. contourFillColor has been set to ‘nd’ in order to give a
 Contour plots 117

black and white plot.

Figure 9.2(b) shows the same example but with some tweaking – the grid resolution has been
increased from 50 to 200 to remove the ‘wiggle’ in the -2.10 contour, the label size has been
reduced, the number of digits in the label reduced to 2 and the labels moved to increase legi-
bility, the contour line width has been reduced and now alternates full line–dashed line with
corresponding colours black-gray4. The settings were:

(a) Fe solubility (b) Fe solubility

-10 -10

-7.5

-7.0

-6.5
-7

-6.0
-5.5
-5.0
log f O2(g) (atm)
-5
log f O2(g) (atm)

-30 -30

-6
-4
.0

-2 -
.5 3.5
-50 -3
-4 -50 -4
.5

-2
.1
-3
.0

-70 -70

-2 -2.0
-90 -90
2 4 6 8 10 12 2 4 6 8 10 12
pH pH
0.01 mol/kgw total Fe 0.01 mol/kgw total Fe
Concentrations of dissolved Fe in log (mol/kgw) Concentrations of dissolved Fe in log (mol/kgw)
C:\PhreePlot\demo\contour\contour_hfond.ps

Figure 9.2. Black and white versions of the contour plot. (a) version made with a grid resolution of 50 and
mainly default settings; (b) the same but with a grid resolution of 200 and minor tweaking to the plot settings.

resolution 200
contours -8 -7.5 -7 -6.5 -6 -5.5 -5 -4.5 -4 -3.5 -3 -2.5 -2.1 -2.0
contourfillcolor nd
contourLineWidth 0.2 -0.15
contourLineColor black gray4
contourShiftLabel c 1 10 1 1 7 1 1 8 -1 1 12 60
contourLabelSize 1.5
contourLabelFont "Helvetica"
contourLabelColor black gray4
contourlabelFigs 2

9.6 REFINING A PLOT – REPLOTTING WITHOUT RECALCULATING

As with the predominance plots, it is possible to change various plotting parameters and to
replot without going through the potentially slow process of regenerating the geochemical
data.
calculationMethod = 1 uses PHREEQC to produce the ‘out’ file containing the z-grid of val-
ues based on the specified speciation calculations. It then produces the intermediate ‘vec’ and
‘pol’ data files and the plot. Since the calculations start at the beginning, any of the contour-
ing parameters can be changed (maximum computing effort)
calculationMethod = 2 starts with the existing ‘vec’ and ‘pol’ files and uses these to generate a
new plot. There is no recalculation of contours or line simplification. You can change plotting
parameters including shifting the labels but not ‘calculation’ parameters such as the grid reso-
lution or the number or values of the contour levels. If contourShiftLabel is set to ‘f ’ for file,
then the labels file is used to determine the text, position and orientation of the labels (mini-
mum computing effort).
calculationMethod = 3 starts with the existing ‘out’ data file, recontours the data and regener-
ates the ‘vec’ and ‘pol’ files with renewed line simplification before replotting (intermediate
computing effort).
Therefore, if the number or values of the contour intervals is changed or the line simplifica-
118 PhreePlot Guide

tion factor altered, it is necessary to use calculationMethod = 3 otherwise the somewhat

quicker calculationMethod = 2 can be used.
If the geochemical model has changed in any way or the resolution changed, it will be neces-
sary to regenerate the geochemical data with calculationMethod = 1.

9.7 OVERLAPPING OR MISPLACED LABELS

One label is normally plotted for each distinct contour segment. The position of the label is
normally chosen to be at the centre of the longest, ‘straightest’ part of the contour. This is
derived from the output of the line simplification procedure if it has been used. Such a strat-
egy often produces a satisfactory placement, but certainly does not always. For ecample, no
account is taken of the spatial relationship between the various labels – they may overlap.
For a given plot, the size of the contour label and its likelihood of overlapping other labels, is
governed in part by the label text height (contourLabelSize) and in part by the number of dig-
its actually printed in the label (contourLabelFigs). If PhreePlot thinks that there is not
enough space to print a contour in the desired position, it will not be printed at all.
It is common, especially where there are rapidly changing conditions near mineral-solution
boundaries, that two or more labels overlap rendering them more or less illegible. One strategy
for dealing with this (other than changing the contour intervals or reducing the label size) is to
move one or more of the offending labels with contourShiftLabel, even moving them so far
that they are not plotted at all. With a little effort, it should be able to derive satisfactory label
positions.
The contourLabelSize can also be set to 0. or the contourLabelColor set to ‘nd’. This will sup-
press all labelling of this contour. However, the ‘shift’ approach is more versatile where there is
more than one label per contour since it addresses individual contour labels rather than all the
labels for a given contour level.

9.8 WHAT HAPPENS IF PHREEQC FAILS DURING CONTOURING CALCULATIONS?

The contouring package expects a full set of regularly-spaced data and cannot deal properly
with ‘missing data’.
As discussed earlier, PHREEQC may fail to converge for perfectly valid reasons, e.g. insuffi-
cient material available to equilibrate with a pure phase. In these cases, there is no valid output
and this results in ‘missing data’. PhreePlot records this by entering a blank line in the ‘out’
file. This acts as a placeholder and when subsequently read by the contouring package, the z-
value for this record is given the ‘undefined’ value (-99999.).
Rather than abandoning the plot completely when this happens, the contouring package will
treat this as a valid value and will include it in its calculations. Since the undefined value has a
very low value by normal standards, this will usually cause the undefined region to plot in the
lowest contour class.
When the fill colours are auto selected and some undefined values have been detected, the first
class limit is set to just below the minimum z-data value and and its associated colour set to
‘nd’. The undefined region will therefore usually appear white. This should highlight the failed
region.
If there are just a few missing data, then it is in principle possible to calculate replacement val-
ues by hand and edit these into the ‘out’ file. The plot is then regenerated with calculation-
Method = 3 thereby using the substituted values.
It is of course normally better to arrange for the calculation to avoid failures of this kind.
Details of the location of the first 30 failures are summarised on the screen with details sent to
the log file.
 Custom plots 119

10 Custom plots

10.1 OVERVIEW

‘Custom’ plots do not have any of the intricacies of predominance diagrams or of fitting. They
simply take the selected output that has accumulated from one or more PHREEQC simula-
tions and make a plot using the columns of data found. The challenge is to get the results to
produce a well-formed ‘out’ file ready for plotting.
One column has to be defined as an ‘x axis’ and all the other chosen columns are plotted using
a common ‘y axis’. A secondary y axis can be chosen if wanted. The headings given in the
SELECTED_OUPTUT file become column labels in the normal PHREEQC fashion and these are
used to select the column (‘variable’) to plot and to label it. Additional text, lines and symbols
can be added to the plot through ‘extra’ text and data files.
The simplest approach is to use the USER_PUNCH keyword data block to only send the results
that need plotting, or at least, to ensure that these results are the last thing written following
any output from any initial solution etc calculations. If the problem is similar to one of the
examples given here, use the example as a template to get started.
Keep it simple to begin with, and use the log file with debug = 2 to take a close look at what is
being done. Decide which calculations can be put into pre-loop simulations and which belong
best to the main loop.
A loop file provides a flexible way of defining variables if more than one is wanted since the
variables do not have to increment in any particular way, and any number of variables can be
made to change ‘in parallel’. Each row in the loop file results in a separate iteration. The
results are accumulated in the ‘out’ file which can be used to produce a custom plot. Data
from pre-existing ‘out’ files (or other files with a similar tabular format) can be imported and
added to the plot.
If no SELECTED_OUTPUT file is created or the plotFactor is set to zero or calculationMethod is
negative, then no plot will be created. Therefore custom-type plots can be used to do
PHREEQC type calculations in the normal way without any plotting. PhreePlot has the
advantage that it is possible to do some simple looping and so generate a stream of output
suitable for viewing or for input to other software. For example, it is possible to accumulate all
of the normal PHREEQC output from a series of runs in the phreeqcall.out file (see Exam-
ple 70).

10.2 PREPARATION OF THE INPUT FILE

10.2.1 Introduction

Custom plots are used for all x-y plots other than predominance plots. This includes species
plots and fit plots.
A custom plot calculation normally expects PHREEQC to produce selected output data with
an x-variable in the column defined by customXcolumn, and y1...yn-1 in the other columns
where n=no. of columns. Data for plotting are selected from these columns using the lines and
points keywords.
The ‘out’ file is the primary file used for plotting but additional files can be included by using
the extradat keyword. The specified customXcolumn must be present in each file.
120 PhreePlot Guide

Selected data are copied from the selected output to the out file. Normally this will be just the
last line that is copied but more lines can be transferred using the selectedOutputLines key-
word. PhreePlot gets the label names from the selected output header line. The length of
these label names should be 1000 characters or less although only the first 198 will be used to
define tag names.
The PHREEQC headings identifier which should be included as part of the
SELECTED_OUTPUT data block has the format
-headings xxxx xxxx ...
where xxxx should not contain whitespace (spaces or tabs) or \ or /. Commas are not required
as separators and so should not be included.
Values transferred with the value imissingValue are treated as missing data.
If no data are found within the plot area, the label is printed in the legend but no entry is sent
to the lineColor.dat file and no label is plotted on the graph.
The size of the legend labels is controlled by labelSize – the same setting as used for the labels.
If a species appears in the legend but is not shown on the plot, this is because it is not found
within the plot area.
Labels are taken from the names of column headers as sent from PHREEQC to the selected
output using the header identifier: The labels are by default interpreted as PHREEQC species
and formatted accordingly (see Section 6.4.2). This behaviour can be overridden with the con-
vertLabels keyword. In order to avoid generating situations such as <sub>._....</
sub>, no attempt will be made to translate column headers if they contain <sub> or <sup>
before translation.
The <x_axis> increment is controlled by xmin, xmax and resolution.

10.2.2 Controlling the scope of custom plots

Execution of custom plots is controlled by:

xmin, xmax etc controls the x-axis scope.

ymin, ymax does not matter as y is calculated
loopMin, loopMax and loopInt are used as an additional loop variable (the z-dimen-
sion) by the <loop> t1.inc.

If loopInt=0., then only one circuit round the loop is made. This uses <loop>=loopMin. This
is useful for checking the input file for a specific setting. Alternatively the <loop> variable can
be omitted from the CHEMISTRY section which will then only run through the loop once
assuming the normal default settings.

10.3 SIMPLE LOOPING

One use of a custom plot procedure is to simply loop on a calculation many times changing
one or more variables on each iteration. It is not necessary to actually produce a plot. This is
something that can be awkward to do in PHREEQC at present. The PHREEQC_looping\Fes-
pecies demo example (Example 70) shows how this can be done. The input file looks like
this:

SPECIATION
calculationType "custom"
calculationMethod -1
xmin -10.0
xmax -4.0
resolution 3
debug 2

CHEMISTRY
PRINT
 Custom plots 121

-reset false # don't output initial solution calculation

PHASES
Fix_H+
H+ = H+
log_k 0
SOLUTION 1
pH 2
units mol/kgw
Fe 1e-2
Na 1e-1
Cl 1e-1
# no reaction so no need to SAVE solution 1
END

USE solution 1
PRINT
-equilibrium_phases true
-species TRUE
EQUILIBRIUM_PHASES
Fe(OH)3(a) 0 0
Fix_H+ <x_axis> NaOH
-force_equality true
END

where the pH is controlled by the <x_axis> tag which is generated from xmin, xmax and reso-
lution. PHREEQC will be run resolution times with the values -10, -6 and -4 being substi-
tuted in turn for the <x_axis> tag.
The PHREEQC code is split into two simulations, an initialization (pre-loop) simulation and
a second iteration which is the one that is iterated.
debug is set to 2 so as to create the phreeqcall.out file which contains the accumulated
phreeqc.out output from all iterations. All of the normal PHREEQC output is first turned
off with -reset false and then the species output is turned on to minimize the file size.
The calculationMethod is set to -1 so as not to produce a plot. No selected output is pro-
duced.
It is also possible to use a loop file to provide the successive values of the loop variable(s) (see
loopFile). Another approach is to use the ‘simulate’ plot type which takes loop values from a fit
data file.
One of the challenges of running custom calculations for more complex examples is to ensure
that a ‘well-formed’ outfile is produced so that any plotting that is needed produces the
desired results. This can usually be achieved by splitting the PHREEQC input part into the
‘correct’ number of simulations (using END’s), using mainLoop to define the divide between
pre-loop and main loop simulations thereby controlling the looping and selected output from
these simulations, and finally using selectedOutputLines to control the sending of the results
to the outfile (Section 4.6).

10.4 MODIFYING THE APPEARANCE OF CUSTOM PLOTS

10.4.1 Overview

Many of the keywords can be used to control the appearance of the final plot (Figure 10.1).
Axis scaling can either be ‘auto’ or can be forced using keywords such as pxmin, pxmax etc.
Note the use of the x-axis scale factor, a dividing factor, which is automatically used by
PhreePlot for very small or large numbers. Since this approach always produces some confu-
sion, it is usually better to avoid the problem altogether by rescaling (changing units) in the
selected output to bring the scale somewhere in the range 1e-3 to 1e3.
A second, independent y-axis scale can be used for the right-hand y axis. Point and lines that
use this scale are specified with points2y and lines2y in the same way as for points and lines.
Tags can be used to give super and subscripted text, italics, bold or line breaks. Single Greek
characters can be entered with the \letter notation or more generally Greek text can be added
122 PhreePlot Guide

with <g> ... </g> (Section 7.6.3).

Additional data from other files can be added to the plot using the points and lines keywords
combined with the extradat keyword to add the additional files to the search path. These data
must be in regular tabular output format. extraSymbolsLines can be used where more control
is wanted over the symbols used or the line widths.

plotTitle
plotTitleSize
plotFactor plotTitleColor

font
Pyrite oxidation kinetics

2y axis (points2y & lines2y)

pymax

8I 0.1 M KCl 6 extraText with <br>'s

1500 μS/cm
pymajor
<sub> tags 25 C
Greek character (\m)
6 5
yaxisLength

PCO2(g) (%)

P O2(g) (%)
ytitle 2ytitle
4 4
I O (g)*
• 2

lines I J J data from extraSymbolsLines

2 J J 3
pydec
•
J
CO2(g) I points
J points2y
pxminor J
I I
I
pymin 0J 2
0 2 4 6 8 10 12 14
pxmin pxmax
2
pxdec Time (hours) ( /10 ) pxmajor
axisNumberSize
axisNumberColor xtitle scale factor automatically inserted by PhreePlot
axisTitleSize (means 0 - 1400)
axisTitleColor

xaxisLength

customXcolumn

Figure 10.1. Some of the keywords used to control the appearance of custom plots.

10.4.2 Customising the plot

Providing legendTextSize is greater than zero, the default is to print a simple legend just out-
side of the plot area close to the top right corner of the plot. This legend provides a key for the
plotted lines and symbols. The position of the legend can be moved inside or outside the plot
area using the <legend> tag in the extraText file. auto for x or y coordinate position chooses
the default value.
The labels associated with each item in the legend are derived in various ways. Most simply
they are generated from the column names in the plot data file from which the plotted data
were derived. Often these are derived from the ‘out’ file which is automatically generated from
the PHREEQC selected output. The labels appear in column output order which itself is
determined by the PUNCH order. The data and labels used can also be derived from another file
provided it is in the tabular out file format and that it is defined in the search path given by
extradat.
Where there are blank lines in the plot data file, these generate line breaks and each line is
labelled separately in the legend. By default, the column name is appended with “_n” where n
starts at 1 and increments by 1 for successive datasets.
These names can be replaced with your own names by using the labels keyword. This provides
a list, one name for each successive value of the loop variable. This list is recycled as needed, or
names can be read from a loop file or from the plot data file used in simulations and fitting. If
 Custom plots 123

only one loop name is given, then the plot data file providing the data plotted is searched to
see if this name appears as a column label. If it does, then this column is used to provide the
legend label for that dataset. Since only one name is needed per dataset, this is taken from the
first row of each dataset. Variable values can also be ‘posted’ next to plotted points using the
post keyword.
A legend is automatically placed to the right of a plot if the legendTextSize is greater than zero.
It is also often useful to include a heading for the legend. This can be done using the legendTi-
tle keyword or the <legend> approach in the extraText file which can also be used to move the
legend to somewhere else. Any text in the text string that precedes <legend> is used as the leg-
end title. This can include text enhancement tags and line breaks. If a dataset has the ‘nd’ col-
our then that dataset will not be drawn and no entry in the legend will be made.
Line and point colouring can either be left to PhreePlot or defined in the line colour diction-
ary. Line curves are automatically labelled if labelSize is greater than zero and the labelColor is
not ‘nd’. When there are many overlapping lines finding the ‘optimal’ label placement can be
slow. The optimization can be turned off by reducing labelEffort to zero. A red ‘tracking’ sym-
bol is used to show the label anchors. These can be turned off by setting trackSymbolSize to
zero.
124 PhreePlot Guide
 Species plots 125

11 Species plots

11.1 WHAT IS SPECIAL ABOUT A ‘SPECIES’ PLOT?

A ‘species’ plot is a special type of custom plot which shows the distribution of species for a
particular element in terms of their concentration or percentage distribution versus some mas-
ter variable, such as pH. The element is specified with the mainspecies keyword. The percent-
age is calculated in terms of the moles of an element in a given species as a percentage of the
total number of moles of that element present in all species.
Two common types of species plots are shown in Figure 11.1 and discussed in more detail in
the Examples section (Example 72 and Example 73)

Cd speciation log species concn vs pH

(using speciesvsph.inc) (using logspeciesvsph.inc)

Cd2+
Cd2+
CdCl+ -5 +
Cd2+ Cd(OH)2 CdCl+ CdNO3
80 CdNO3+ CdOH+
CdOH+
log concentration (mol/kgw)

Cd(OH)2 CdOHCl
Cd(OH)3- -10
Cd(OH)42- Cd(OH)2 CdCl2
60 CdOHCl
CdCl3-
% in species

-15 Cd2OH3+
Cd2+
Cd(OH)3- Cd2OH3+
CdCl+
40 Cd(OH)3-
CdCl2
CdCl3-
-20 CdNO3+
CdOH+
CdOH+ Cd(OH)2
Cd(OH)3-
Cd(OH)42-
20 CdOHCl
-25
CdNO3+ CdOHCl
Cd(OH)42-

CdCl+
0
Cd(OH)42- -30
6 8 10 12 6 8 10 12
pH pH

Figure 11.1. Two common types of species plots produced using the ‘species’ method showing the distribution
of Cd species with pH. The two plots use different ‘include’ files to generate the selected output.

A species vs pH plot is obtained by setting calculationType to ‘species’ and by including one

of the special ‘include’ files in the CHEMISTRY section. An example of using the ‘species-
vspH.inc’ include file is given in Figure 11.1 (left). The ‘logspeciesvspH.inc’ file is used to
generate a plot of log species concentrations vs pH (Figure 11.1, right). These files filter out all
H and O species which normally dominate aqueous systems.
It was necessary to make the species plot a special type of custom plot since PHREEQC can-
not automatically generate a set of heading names (column titles) at run time to correspond
with the species found. Therefore it is necessary to write the species name to the selected out-
put file along with each value. Furthermore, the SYS() function that is used to extract the set
of species present and their concentrations is written to the selected output file in order sorted
by concentration rather than sorted alphabetically. This means that the sort order is likely to
vary and must be reordered to enable species distribution curves to be plotted.
The ‘species’ method expects a specific type of input to be returned in the selected output.
This consists of a series of species name-value pairs. The species names are used for the labels
while the values are plotted. The customXcolumn should be set to the column where the x-
126 PhreePlot Guide

axis variable is located. The other pairs of columns are assumed to contain y-values (species
percentages or concentrations) to be plotted. For example, if the x-axis variable is PUNCH’ed
first, then the customXcolumn would be set to 2 and the default name of the x axis is taken
from the name given in column 1. The remaining columns are the names-species pairs to plot.
Four include files for making species plots are included in the system directory. These are for
analysing solution species or adsorbed species and report in either relative concentrations (%)
or in absolute concentrations (mol/kgw) (Table 11.1). The files can easily be edited to custom-
ise their behaviour. For example, instead of pH as the independent variable, other variables
can be chosen.

Table 11.1. Standard include files used for generating species plots

Name of file Purpose

<mainspecies> specifies the ‘element’ to analyse, e.g.
“Cd”. Output is in terms of the relative concentration (in %) of
speciesvsph.inc all species, including minerals and adsorbed phases, containing
that element vs pH. If the <mainspecies> is “elements”
then the analysis is done at the element level for all elements.
As above but includes as a ‘species’ the overall percentage of the
speciesvspht.inc
‘element’ that is in the form of dissolved species.
As for speciesvsph.inc but the output is in terms of the
logspeciesvsph.inc
log10(mol/kgw) concentration of each species.
As above but includes as a ‘species’ the overall log10(mol/kgw)
logspeciesvspht.inc concentration of the ‘element’ that is in the form of dissolved
species.
As for speciesvsph.inc but only considers adsorbed spe-
cies for a particular element. If <mainspecies> is set to
adsspeciesvsph.inc
“elements” then all adsorbed species of all adsorbed elements
are counted.
As for logspeciesvsph.inc but output in terms of
logadsspeciesvsph.inc
log10(mol/kgw).

These files pick up the main species from the mainspecies setting and use the SYS() function
to obtain a list of the species present for this ‘element’ and their amounts (in moles). These are
then either converted to percentages of the total amount present or converted to log concen-
trations and punched in name-value pairs to the SELECTED_OUTPUT file which, in turn, is cop-
ied to the out file, one row per pH.
The column headings in the ‘out’ file are those given by PHREEQC for unnamed columns,
namely, no_heading_1 for column 1 and so on. The species are written to the ‘out’ file starting
with the most abundant species followed by all the other species in order of decreasing abun-
dance. The order of the species written will tend to vary with chemistry of the system.
For adding species-type plots to other plots, a table with fixed column positions is required.
These data are automatcially written to the ‘pts’ file. This file is also automatically added to
the search path for variables and so the indicated species can be selected for plotting with the
lines or points keywords.
PhreePlot automatically displays the distribution of all species as lines. No lines line is
required in the input file. The colour of the lines drawn is determined by the normal line col-
ouring algorithm, i.e. using auto colour selection or the line colour dictionary depending on
the useLineColorDictionary setting. The line width is controlled by the lineWidth setting.
The minimumYValueForPlotting setting is useful to remove minor species from the plot.
A sorted table of the speciation results is written to the pts’ file irrespective of whether ‘pts’ has
been set to true or not in the input files. This can be used for plotting the results with other
software.
If mainspecies is set to “elements”, the distribution is over the total concentrations of all dis-
solved elements and valence states (solution master species) in the system rather than for the
 Species plots 127

plotTitle
plotTitleSize
plotFactor plotTitleColor

font Cd speciation
(using speciesvsph.inc)
legendTitle is blank
pymax 100 Cd2+ legendTextSize
CdCl+
pymajor CdNO3+
Cd(OH)2 CdOH+
80 •
Cd(OH)2
Cd(OH)3-
trackSymbolSize Cd(OH)42-
trackSymbolColor CdOHCl
% in species
yaxisLength

60 (calculationMethod = 1) • lines
Cd2+
lineWidth
Cd(OH)3- lineColor
•
40 useLineColorDictionary

ytitle •CdOH
+ labelSize
labelColor
20 labelEffort
pydec CdOHCl
•
•
• CdNO3+ Cd(OH)42-
minimumYValueForPlotting
CdCl+ •
pymin 0
6 8 10 12
pxminor
pxmin pxdec pH pxmajor pxmax
xtitle
axisTitleSize
customXcolumn axisTitleColor

xaxisLength

Figure 11.2. Some of the keywords used to control the appearance of custom plots.

concentrations of all species of a particular element.

The ‘adsorbed’ option considers the distribution of adsorbed species vs pH either for just one
element or of all elements, as determined by the mainspecies setting.
A list of main species can also be specified to give multiple plots. The multipageFile setting
controls whether all the ps and pdf plots produced will be combined into one file or not.
Much the same effect can be achieved using an ordinary custom plot but here the sorting has
to be done with BASIC code in the USER_PUNCH block (Example 59).
The ‘species’ calculation method discussed above can be modified to plot a variety of things
providing the selected output is set up to produce a fixed set of name-value pairs.
Note that in Figure 11.1 (left) the curves for several minor species have been omitted for clar-
ity. This was achieved by setting minimumYValueForPlotting to a value of 5. Only curves
with a maximum value exceeding 5% are plotted.
If the x-axis variable wanted is not pH but some other variable then it is straightforward to
edit the include files to ensure that the required variable is the first one to be punched to the
selected output, and to associate customXcolumn with it.
It is possible to make multiple plots by using the loop variable.

11.2 MODIFYING THE APPEARANCE OF SPECIES PLOTS

The default x-axis title is for a species plot is hard coded as “pH” and that for the y-axis title is
either “% in species” for a linear scale plot or “log concentration (mol/kgw)” when a log
scale has been inferred, i.e. when minimumYValueForPlotting is less than or equal to zero and
there are no 2y axis variables to plot. The plot title is automatically set to “Distribution of
<mainspecies> with pH”. All of these defaults can be overridden from the input files.

Species plots are produced with the custom plot procedure and so all the same keyword set-
tings discussed for custom plots apply. Many of these are illustrated in Figure 11.2.
128 PhreePlot Guide

11.3 ADDING OTHER VARIABLES TO A SPECIES PLOT

It is possible to plot other variables on a species plot.

Add any additional variables to the list of PUNCH’ed items in the speciesvsph.inc file. They
can be added anywhere providing the x-column remains the first to be PUNCH’ed. Normally,
they would be added before or after the actual species have been PUNCH’ed. This makes sure
that they will be included in the outfile. Thereafter they are treated as if they are ordinary spe-
cies, i.e. they will be plotted on the main y axis.
The column names in the outfile from a species plot will be in pairs beginning no_heading_1,
no_heading_2 .... for the most abundant species followed by the other species in order of
decreasing abundance.
For species type plots, a table with fixed column positions is required. This is given in the ‘pts’
file. This file is automatically added to the search path and so the indicated species can be
plotted with the lines or points settings.
 Fitting and simulations 129

12 Fitting and simulations

12.1 INTRODUCTION

Calibrating models is a key part of modelling but can be rather daunting in the beginning. Fit-
ting with PhreePlot definitely belongs to the ‘advanced’ category of tasks. You have to get
quite a few things working correctly together to be successful and while it would be nice to
have a ‘fire-and-forget’ approach for this, it is rarely that straightforward.
The setup for fitting is very flexible. Each observation can be simulated using either the same
block of PHREEQC simulations (containing variable tags) or a different block of simulations
as specified in the fit data file.
Nevertheless, PhreePlot includes three fairly easy-to-use optimization procedures that can be
used to fit models to data, i.e. they automatically adjust a set of parameter values in a
PHREEQC input file to their optimal values based on a set of observations (data) and an
objective function to provide a measure of the goodness of fit. The objective function used
here for this is the weighted sum of squares of the residuals.
The three optimizers available, all by M.J.D. Powell, are:
(i) ‘nlls’: a modified Marquardt-Levenberg procedure is described in Powell (1965).
The version used here is based on the VA05 routine from the Harwell Subroutine Library
(HSL) Archive;
(ii) ‘newuoa’ (NEW Unconstrained Optimization Algorithm): this is not specifically a
least squares optimizer although it is used here as such. NEWUOA is a general-purpose opti-
mizer that uses a quadratic model to approximate the objective function in a ‘trust region’
(Powell, 2007). The ‘trust region’ is a restricted part of the objective function in which the
quadratic approximation is ‘trusted’ to be correct. This region is progressively enlarged as the
approximation improves. NEWUOA is robust and has proven to be capable of dealing with a
large number, i.e. hundreds, of adjustable parameters.
(iii) ‘bobyqa’ (Bound Optimization BY Quadratic Approximation’): BOBYQA is simi-
lar to NEWUOA except that it allows lower and upper bounds to be specified for each adjust-
able parameter (Powell, 2009).
All of these methods are derivative-free meaning that you do not need to provide functions to
calculate the derivatives. This makes the fitting of new models much easier – and even possible
– but there is a penalty in terms of speed of execution and more importantly, stability. When
numerical derivatives are themselves calculated from a numerical model which itself carries
estimation errors, as all PHREEQC calculations do, care has to be taken to ensure that the
derivatives are obtained with sufficient accuracy to be useful.
The parameters to be optimised, and the independent variables used, are identified using tags
defined by the user and placed in the PHREEQC input code of the Chemistry section of the
main input file. The adjustable parameters are each systematically varied in such as way as to
find the minimum value of the objective function. This should correspond with an optimal fit
between calculated and observed values of the dependent variable(s) taking into account the
weight assigned to each observation.
Weighting options are: unit weighting (all weights are automatically assigned a value of 1), rel-
ative weighting (weights are 1/observed value), or the weights for each observation can be read
from the data file.
130 PhreePlot Guide

The calculations can be run either in simulation (‘simulate’) or fitting (‘fit’) mode. The sim-
ulation mode is useful where a particular PHREEQC input file is wanted to be run with vari-
ous sets of parameter values or variables. These values can be entered in the ‘data file’ and
picked up from there with each row in the data file corresponding to a separate simulation.
The headings of the data file are used to generate tag names. The corresponding tags are used
to mark the position of a substitution in the input file.
If the number of degrees of freedom in a fit file is 0, i.e. there are the same number of adjusta-
ble parameters as data points, then least squares optimization is not appropriate as there is an
exact solution. PhreePlot assumes that the problem is then one of ‘root finding’ and will
attempt to find the solution by iteration.

12.2 APPROACH TO FITTING

There are two distinct components to fitting:

(i) defining the objective function, i.e. defining what is to be minimized subject to any constraints
on the values that the function variables (‘adjustable parameters’) may take. Here we use a sum
of squares of the weighted residuals. Other functions are possible;
(ii) adjusting the given set of variables in such a way as to locate an acceptable minimum value of
the objective function ;
Given (i), the challenge of (ii) is simply defined but finding fast and reliable approaches has
exercised numerical analysts for a long time. All optimizers should in principle converge to the
same minimum given the same (i).
In our case, the objective function itself consists of three components:
(i) the chemical model used to calculate the value of the dependent variable(s);
(ii) the corresponding observations of the dependent variable(s);
(iii) the weighting applied to each observation or more particularly to the residuals (the difference
between (i) and (ii)) for each observation.
Again, given a well-defined chemical model (including the thermodynamic database) and the
same weighting scheme, all fitting programs should in principle converge to the same final
solution – the ‘best’ fit. This can be tested by comparing the values of the fitted parameters
and the individual residuals. The relative degree of success of fitting by various procedures can
be judged by a measure of the overall ‘goodness of fit’ such as the root mean square error
(RMSE) or coefficient of determination (R2). The aim is that the fit should at least be better
than assuming the mean value of the dependent variable throughout – it can of course be
worse giving negative R2.
Ultimately, the details of exactly how the model calculated the individual contributions to the
objective function should make no difference. It is assumed that this has been done reliably,
though of course this is a critical assumption, and is itself a measure of model quality.
Pitalls in the fitting involve converging to a local not a global minimum, and not finding a
unique minimum perhaps because of two or more highly correlated variables. The latter situa-
tion leads to the optimiser ‘wandering along a long flat valley bottom’ and is a sign of an over-
parameterised model. This does not mean that the model is wrong, just that there are insuffi-
cient data to uniquely define all variables. The usual solution to this is to reduce the number
variables by fixing one or more of the variables at an acceptable value, or by adding one or
more constraints on the values that the variables can take (‘constrained optimization’).

12.3 PRACTICAL SETUP

12.3.1 Approach

It is helpful to break down the overall task into several more manageable sub-tasks:
 Fitting and simulations 131

1. Organise your data

A file needs to be made containing the data (‘observations’) that are to be fitted. This
should be an ASCII-coded flat file. It can be easily prepared in a spreadsheet and
exported in tab or csv format. It should have one line per observation with columns
which include all the independent variables. The first line should be a header contain-
ing the column labels – keep these simple by avoiding spaces and other special charac-
ters, e.g. use only upper and lowercase characters, numbers and the underscore (‘_’).
The data should start on the second valid line. It is important that there are no blank
columns in this second line (the first line of data) as this line determines the format
(numeric or character) with which the whole column will be read. If necessary, rear-
range the order of rows or insert a dummy ‘format’ line to make sure that this is so. Also
decide which data separator is to be used and tell PhreePlot either with the dataSepara-
tors keyword or with the optional second parameter of the dataFile keyword. If addi-
tional lines need to be included but not used in the calculations, turn them into
comments by making the first non-blank character a hash (#).
When reading entries, quotes are stripped from the entry and the entry is then read as
numeric or character according to the format established from the first data line. Non-
numeric values are assumed to be character. Quotes alone do not define a character
value, e.g. “1.23”,“4.56”,... will be interpreted as valid numeric values.
Empty fields are given the missingValue setting if the column is designated numeric or
as the empty string (“”) if designated character. An ‘NA’ in a numeric field is also given
the missing value. The missing value is treated as a valid value in calculations unless it is
assigned the value of UNDEFINED (-99999) in an input file. The default missing value is
set as UNDEFINED.
If fitting, you will need to decide how you want to weight the observations and if neces-
sary include a ‘weights’ column.
2. Get the chemical model working
Write the block of PHREEQC code that will take your independent variables and out-
put the value of the dependent variable. This will usually contain at least the SOLUTION
and USER_PUNCH keyword blocks. Check that the code is working properly by checking
the calculation for a single point. The column headings defined in the USER_PUNCH data
block are used to name the columns in the output files (and so can be used for identify-
ing which columns to use for plotting) as well as for telling PhreePlot where to expect
the calculated value of the dependent variable. Columns can be referred to by column
name or column number.
3. Make up the PhreePlot input file
If possible, choose an existing input file of a similar fitting problem as a template and
edit accordingly. This will remind you of the parameters that need to be considered.
You will need to define the name of the data file (dataFile), the column in that file con-
taining the observations (dependentVariableColumnObs) and the column in the
selected output file containing the value of the dependent variable (dependentVaria-
bleColumnCalc). Each column in the data file is converted into a tag which can be
used in the PHREEQC model code to indicate where a substitution needs to be made.
Decide which fitting algorithm to use (fitMethod) and which variables need to be
defined as model parameters – usually this is all the parameters that may need to be
adjusted at some stage – and define the model names and other parameter switches
accordingly (numberOfFitParameters, fitParameterNames, fitAdjustableParameters).
The numberOfFitParameters should be set to the number of distinct parameters speci-
fied by tags in the input file – it should include both fixed and adjustable parameters.
Set the initial parameter values for all parameters (fitParameterValues) and the bounds
on these parameters if appropriate. It is important that this combination of parameter
values works so if necessary check with PHREEQC or by other means. You may have
to fine tune some of the fitting algorithm’s operational settings controlling such things
132 PhreePlot Guide

as the step size, the maximum number of iterations etc. Finally decide what the most
diagnostic plot will be and define customXcolumn and points accordingly. Any col-
umns defined in the ‘pts’ file can be used for plotting including the automatically-gen-
erated ‘observed’, ‘calculated’ and ‘residuals’ columns. Refinements include adding
extra text (extraText) and labelling individual points using post.
Each data point will have to be associated with a block of one or simulations which will
be used to calculate the fitted value for that observation. It is best to (a) identify all
‘constant’ PHREEQC blocks, i.e. those blocks that are always the same and do not
change – these can be put in a pre-loop simulation; (b) identify all PHREEQC blocks
that are constant for all observations (data points) but which may vary during fitting –
these can be included in the simulation for observation 1; (c) identify the simulation or
range of simulations that will be used for each observation – these should mainly con-
tain non-constant data blocks, i.e. those containing a tag that will vary. This can
include extra simulations too.
For maximum speed, in step (c) above, associate all of the observations with the same
range of simulations, e.g. 2-11 and use the onePass TRUE option. This means that all
the simulations will be calculated in a single call to PHREEQC.
4. Run the file
Run the file using debug = 2 or 3 if necessary. You may need to adjust some of the fit-
ting parameters particularly fitFiniteDiffStepSize. The R2 value is a guide to how well
the model is actually fitting the data. If the model seems to be running properly but
PhreePlot refuses to adjust the adjustable values, check the model and data carefully,
e.g. by looking at the table of observed and calculated values near the end of the log file.
This type of failure is usually because the model cannot work out how to improve the
fit and is often a sign that there is something wrong with the model. When you think
you have a good fit, confirm its uniqueness by starting from a different set of initial
parameter values, or even by using one of the other algorithms.

12.3.2 Flow of data and information during fitting

A summary of the overall flow of data and information during fitting is shown in Figure 12.1.
Data are read in from the data file (dataFile). If necessary, the data are transformed before
being stored in memory (logVariableIn). These data contain values for the dependent variable
(for a fit), the weight to be applied to each observation if applicable and any independent var-
iables needed in the calculations. It can contain additional columns of data but these are
ignored. The column headings are used to define special ‘fit data’ tags. These are used in the
CHEMISTRY part of the input file to identify the variables to be substituted when calculating the
value of the dependent variable. It is also necessary to identify which column contains the
dependent variable. This is done by the column position or name (dependentVariableColum-
nObs). The PHREEQC simulation(s) used for each data point are indicated by the integer
value or integer range found in the column of the data file given by the blockRangeColumn.
These simulations can be shared by different observations or can be different for each observa-
tion.
There can also be a column in the fit data file to indicate which simulations within each block
range are pre-loop simulations and which are the main loop simulations. Like the block-
RangeColumn, this can be specified separately for each observation. The name of the column
is given by the mainLoopColumn keyword. If this is not specified and the mainLoop keyword
has a valid setting, then this setting is used for all observations. This setting is relative to the
start of the block of simulations used for each observation.
The default setting of mainLoop is auto which for fitting and simulations is set to ‘1’, i.e. all
simulations will be run on each iteration. Remember that ‘1’ refers to the first simulation in
the specified range not the first simulation in the whole set of simulations.
All pre-loop simulations are executed only once per run – at the very beginning of the run.
 Fitting and simulations 133

Pre-loop simulations should include static data such as database blocks. If there are data blocks
that vary but apply to all data points in a given set of function evaluations and so only need to
be run once per iteration, include them in the set of simulations specified for the first data
point. The simulations specified for the second and subsequent data points should only refer
to the simulations specifically required for those data points.
The input files define the number and names of parameters used by the chemistry model to
calculate the value of the dependent variable (numberOfFitParameters and fitParameter-
Names) for a given set of conditions. Parameters can be fixed or adjustable (fitAdjustablePa-
rameters) and may be fitted as log parameter values (fitLogParameters). The parameter values
set (fitParameterValues) are either used as initial estimates if adjustable or as fixed values.
The CHEMISTRY section contains the code that is used to calculate the dependent variable and
this is normally output via the selected output ‘file’. The column for this is given by depend-
entVariableColumnCalc and whether it should be transformed or not by logDepVariable. The
observations from the data file are compared with calculated value of the dependent variable
and the difference (the ‘residual’) multiplied by the given or calculated weight (fitWeighting-
Method and weightColumn). This weighted residual is passed to the optimizer.
The optimizer adjusts the adjustable parameters, identified by fitAdjustableParameters until
the convergence criterion of some other factor signals an exit. After convergence, summary
statistics are calculated, some tabular output produced and a plot made. The plot is made
from the ‘pts’ file with the columns used specified by the lines and points keywords. Data
from other files, including the ‘out’ file, can be used by adding the relevant files to the search
path with extradat. The value of customXcolumn controls the x-axis variable. If no satisfactory
convergence is achieved, a message is issued accordingly.

12.3.3 The parameters

Parameters are variables that remain constant during a simulation, i.e. they have the same
value for all observations with a given data set. Parameters can either be fixed or adjustable
depending on whether they are to be adjusted by PhreePlot to provide the best fit or not.
The number of parameters should be defined first using the numberOfFitParameters key-
word. Each parameter has various attributes associated with it such as its name, its value and
whether it is fixed or adjustable, whether the log of the parameter should be optimized, and
any constraints (lower and upper bounds). These are specified by a series of lists, one entry per
parameter.
Unlike most other settings, the order of the numberOfFitParameters keyword in the input file
is important. Specifically this setting should always come before any of the other parameter list
settings in the input file since it automatically re-initialises all these other parameter settings to
arrays of the specified length and with the system default values. This is to ensure that all the
parameter lists have the correct length. The parameter list settings (all have length of num-
berOfFitParameters) are: fitParameterNames, fitLogParameters, fitAdjustableParameters, fit-
ParameterValues, fitLowerParameterValues, and fitUpperParameterValues.
The parameter tag names are defined by the fitParameterNames keyword in an input file, one
name for each parameter. Once defined, these names can be used as tags in the PHREEQC
input file (the tag is generated by enclosing the name in angle brackets). The values assigned to
these parameters is determined by the fitting procedure in PhreePlot.
The initial values of each of the parameters are defined by the fitParameterValues keyword. fit-
MaxStepSize controls the largest permissible change in a parameter value during an iteration
for the ‘nlls’ algorithm. It defines RHOBEG, the initial radius of the ‘trust region’ in the
‘newuoa’ and ‘bobyqa’ algorithms. The parameter values are either fixed or automatically
adjusted by PhreePlot to provide the best possible fit. This option is controlled by the fitAd-
justableParameters keyword.
134 PhreePlot Guide

'input' files
calculationType
fit data file fitMethod
dataFile numberOfFitParameters
dataSeparators fitParameterNames
dependentVariableColumnObs fitParameterValues
fitWeightingMethod fitAdjustableParameters
weightColumn fitLogParameters
blockRangeColumn onePass
mainLoopColumn updateFitParameters
rewriteInputFile

logVariableIn update tags parameters

transform
data in update
parameters

'nlls', 'newuoa' or 'bobyqa'

main iteration fitConvergeCriterion
indep. loop fitMaxStepSize
variables PHREEQC exit
fitMaxIterations
memory USER_PUNCH [fitFiniteDiffStepSize]
[fitnpt]
wt fobs [fitLowerParameterValues]
[fitUpperarameterValues]
gobs -- gcalc
selected output
residuals
dependentVariableColumnCalc logDepVariable wt (fobs - f calc)
fcalc transform
data out

'pts' file
+ extraOut

'log' file
plot file(s) best fit
'out' file
customXcolumn R2
'pts' file lines(2y) RMSE
points(2y)

Figure 12.1. Flow of data and information during fitting.

12.3.4 Variables

Variables can vary for each observation within a given dataset. The dependent variable is the
variable that is calculated from the model and a combination of the given parameters and the
independent variables. It is the variable which is fitted when optimisation is being undertaken.
Fitting minimises the weighted sum of squares of the differences between the observed and
calculated values of the dependent variable. It is assumed that the independent variable con-
tains all the errors, both errors of observation and model errors.
There can only be one dependent variable per line of input in the data file but different
dependent variables can be defined on different lines of the data file. These will then necessar-
ily point to different simulations to calculate the various fitted values.
The independent variables are the variables that are fixed by the user and control the value of
the dependent variable. It is assumed that the independent variables are known without error.
There can be up to 100 independent variables in PhreePlot. It is possible to have no inde-
pendent variables as in a ‘root finding’ problem.
 Fitting and simulations 135

12.3.5 Passing the fitted values from PHREEQC to PhreePlot: preparing the input file

There are limitations to the structure of the PHREEQC input file that can be used during fit-
ting. This particularly relates to the use of multi-simulation input code and the way in which
the value of the dependent variable is calculated.
There are two principal calculation options: either one pass through the PHREEQC code is
made to calculate a single value of the dependent variable, or all dependent variable values are
calculated in a single, multi-simulation pass. There is no half-way house. The latter is compu-
tationally faster but the input file is more complex and less flexible since it must include a sep-
arate simulation to generate each data value.
Typically many iterations (or function evaluations) are made through the whole data set dur-
ing fitting and so the former approach will make ndata x niterations calls to PHREEQC while
the latter approach will make just niterations calls.
The difference between these two approaches can be seen in the iso (Example 79) and ison
(Example 80) examples.

One pass to generate a single data value

When onePass is FALSE during ‘simulate’ or ‘fit’ calculations, only one data value should be
written to the selected output at a time. This may be because the whole input file must be
repeated each time in order to calculate one value or because a different block of simulations is
used to calculate each value. If there is more than one line of selected output data, the last line
in the selected output is always used.
The SELECTED_OUTPUT keyword block (optionally plus a USER_PUNCH block) should generate at
least one line of data in the selected output file for each calculation (i.e. after “any initial solu-
tion, initial exchange-composition, initial surface-composition, or initial gas-phase-composi-
tion calculation and after each step in batch-reaction or each shift in transport calculations”).
The PhreePlot keyword selectedOutputLines is not used since only one line will ever be
picked up. The PRINT -selected_output statement (or similar in SELECTED_OUTPUT) can be
used to control which PHREEQC simulations send data to the selected output file and so
which simulation actually sends the last line of data.
The dependentVariableColumnCalc keyword controls the column where the dependent varia-
ble will be found.
The PHREEQC code can include several simulations, for example, different types of simula-
tions can be combined into a single global optimization, but only one can be used to generate
the value for each data point. The block of simulations to be used are set by the value or range
set in the column defined by the blockRangeColumn keyword providing onePass is set to
FALSE. This means that completely different models can be used to generate the various values
of the dependent variable.

One pass to generate all data values

When onePass is TRUE, all of the data values is expected to be written to the selected output file
in a single pass through the designated block of PHREEQC code. If there are more lines of
data than required to pair off with the number of observations in the fit data file (n), then the
last n lines of selected output will be selected.
It is up to you to ensure that the USER_PUNCH code does actually produce the required output.
The ‘one pass’ option is most often used for REACTION, KINETICS, ADVECTION and TRANSPORT
calculations where PHREEQC has its own built-in iterators. Here a single call to USER_PUNCH
transfers all of the required output values. Alternatively, a whole set of different simulations
can be run in one call to PHREEQC which will also result in a multi-line block of selected
output containing all of the required dependent variable values. This approach uses the main-
Loop setting to select more than the last simulation to iterate on.
136 PhreePlot Guide

Since the onePass TRUE option along with the default oneSimulationAtATime switch of the
mainLoop keyword set to FALSE means that all the main loop simulations are expected to be
produced in a single call to PHREEQC, there is normally no updating of tag values between
simulations. If variables need to be passed from one simulation to another, use PHREEQC’s
own PUT/GET mechanism or set both the onePass and oneSimulationAtATime switches to
TRUE. The PRINT -selected_output statement can be used to control which PHREEQC sim-
ulations send data to the selected output file and so which simulation actually sends the last
line(s) of data.
In the case of a fit, the ‘auto’ option controlling the number of selected output lines is set to
one when onePass is FALSE and to the number of data points when onePass is TRUE.
The selected output produced by a given input file can be easily viewed by setting debug to 2
– the output is written to the screen and also written to the file selected.out (default name)
which will be found in the working directory.

12.3.6 Data file

The data file consists of the observations, one line per observation. It needs to be sorted in x-
column in order to make the plot that is automatically produced sensible (the fitted values are
plotted as a continuous line).
The data separator needs to be specified to match that found in the data file (see ‘Organise
your data’).
Each line in the data file contains: values for each of the independent variables (if present) and
the single value of the dependent variable (if present). The first line contains a list of headers,
one per column variable. The header names are automatically converted to tags so must
adhere to the tag naming convention, i.e. they must not contain operators (+-*/^) and will be
case sensitive. If the dependent variable is not present, then only simulated values can be cal-
culated.
Anything following a number sign (i.e. pound sign or hash symbol, #) is treated as a comment
and is ignored. One or more blank lines indicates a break in the data set. The break is pre-
served in the ‘out’ file and produces a break in line plots.
The data file can also contain columns containing alphanumeric data (descriptive columns).
These also produce tags which can be used for substituting character strings in the input files.
The type of column (numeric or character) is determined by analysing the first valid row of
data. If necessary rearrange the row order to ensure that the correct column type is indicated in
row 1 of the data.
If the descriptive text contains spaces, embed in quotes. Only the first 20 characters are trans-
ferred, 18 if the text contains embedded spaces and quotes need to be used.
If the blockRangeColumn has been set to a positive integer or valid column name, then this
column (counting from the left) is assumed to contain the PHREEQC simulation number (or
range of simulations) to be used for calculating the dependent variable for this line of data.
The default value of blockRangeColumn is 0 (undefined).
The data file can be used in simulation mode (calculationMethod = simulate) which has a
similar setup to that of ‘fit’ but does not compare observed and calculated values and does no
‘fitting’. No dependent variable need be defined though it can be. A summary of the selected
output is sent to the ‘out’ file.
The log file contains the mean and standard deviation of all numeric columns. It also contains
the sum of the relative standard deviations of each of the columns. This figure can be used as a
‘checksum’ to indicate whether two data files are the same or not.
The number of observations (lines of data) in the data file (n) fixes the number of lines to be
read from the ‘out’ file: if onePass is TRUE, then the last n lines will be read (irrespective of the
selectedOutputLines setting). If onePass is FALSE, then only the last line will be read from the
‘out’ file. These two options are demonstrated in the demo\kineticsSi\kineticsSifit.ppi
 Fitting and simulations 137

and demo\kineticsSi\kineticsSifit1.ppi examples, respectively. The latter option is used

for fitting kinetic models when the observations are at irregular time intervals.

12.4 THE OPTIMIZATION ROUTINES

12.4.1 Choice of fit algorithm

Providing that reasonably good initial estimates of the adjustable parameters can be given,
then the ‘nlls’ algorithm is likely to be fastest of the three available algorithms. This algo-
rithm was especially developed for minimizing nonlinear functions involving sums of squares
and is noted for its ability to rapidly home in on a solution when close to it. However, it suf-
fers the disadvantage that it can be confused by local minima and so should be started from
different starting positions to ensure the solution given is the global solution. Its behaviour is
controlled by a rather small, and not-too-obscure, number of settings.
If the ‘nlls’ algorithm fails to converge either because of poor initial parameter estimates or
because of its tendency to stray into undesirable territory (e.g. negative concentrations), then
it is worth trying the ‘newuoa’ or ‘bobyqa’ algorithms. These algorithms were designed for
large-scale optimization problems with hundreds of adjustable parameters (‘variables’). They
also have more general application than the specialised least squares optimizers such as ‘nlls’
and should be more efficient than the ‘nlls’ algorithm when the Gauss-Newton approach per-
forms less well. This tends to be on large residual problems with nonlinear terms in the sum of
squares.
At present, ‘bobyqa’ is the only one of the three algorithms that can apply constraints to the
adjustable parameter values, in this case, simple box constraints.

12.4.2 Scaling of parameters

These optimization algorithms have to estimate successive steps in multi-dimensional space in

order to reduce the value of the objective function to a minimum. This requires the calcula-
tion of distances between points. The estimation of derivatives may also involve a fixed shift in
parameter values (‘nlls’). Therefore it may be necessary to scale the adjustable parameters to
ensure that the magnitudes of their expected changes are all similar. This could be done by a
change in units, for example, or where appropriate, by taking logs (see fitLogParameters).
Other than the option of taking logs, this scaling has to be done outside of PhreePlot.

12.4.3 Control parameters

Details of the algorithms and their underlying control parameters can be found in the library
and online documentation of the routines (‘nlls’, ‘newuoa’ and ‘bobyqa’). Most of the critical
control parameters have been translated into PhreePlot settings so that a large degree of con-
trol over each algorithm’s behaviour can be achieved from within PhreePlot (Table 12.1).
Parameters that are to be fitted or made to be easily adjusted should be entered as parameters
with names (up to 30 characters) (fitParameterNames) and values (fitParameterValues). These
values are assumed to be either fixed values or initial estimates to be adjusted during fitting.
This distinction is set by the fitAdjustableParameters keyword (0= fixed; 1 = adjustable).
The log10 of the parameter value can also be easily fitted. Set the appropriate fitLogParame-
ters keyword value to 1 otherwise set it to 0. This can provide a useful form of scaling to bring
very large or very small numbers into the same order of magnitude as other parameters. It also
is a simple way of constraining a parameter to a positive value.
It is important that each of the above parameter lists should have the same length. This can be
set with the numberOfFitParameters keyword but can also be allowed to be automatically set
from the length of any of the above lists as they are entered. If present, the numberOfFitPa-
rameters keyword should precede all the parameter lists in the input file.
138 PhreePlot Guide

Table 12.1. Translation of PhreePlot settings into the control parameters for the various optimization algorithm’s

PhreePlot keyword and action Algorithm (fitMethod)

‘nlls’ ‘newuoa’ ‘bobyqa’
fitFiniteDiffStepSize DSTEP=fitFiniteDiffStepSize

Controls the difference used in

Small values will mean less chance of
estimating partial derivatives.
straying too far on the first step and better
Used for the initial, exploratory
estimates of derivatives but if too small not used
shift in all variables. there may not be a significant change in
WRSS given the background noise.
Choose judiciously.
fitConvergenceCriterion ACC=fitConvergenceCriterion^2 RHOEND=fitConvergenceCriterion

Controls when to stop. Smaller Converges when the predicted value of Final radius of ‘trust region’ determines the
values mean more iterations and WRSS is <ACC above the true minimum or final accuracy in the parameter estimates.
more accurate convergence. when there is little predicted change in Also RHOEND<=RHOBEG
parameters. WRSS is a sum that depends
on the number of data points.
fitMaxStepSize DMAX=fitMaxStepSize RHOBEG = fitMaxStepSize

Controls the maximum size of a Maximum ‘distance’ of initial estimate Initial radius of the ‘trust region’. This con-
step. Smaller values mean more from the solution (not scaled). Also the trols the ‘granularity’ of the objective func-
iterations but less chance of minimum size of the Marquadt parameter tion that the algorithm will see.
straying into unwanted terri- = fitConvergenceCriterion/fit- Diameter of the ‘trust region’ (2*RHOBEG)
tory. MaxStepSize. must also be smaller than each of the range of
bounds (see below)
fitMaxIterations MAXFUN=fitMaxIterations MAXFUN=fitMaxIterations

Controls the maximum number

of iterations allowed. Normally
want a large value to avoid early
termination.
fitLowerParameterValues XL(:) = fitLowerParame-
terValues
fitUpperParameterValues XU(:) = fitUpperParame-
terValues
Also
Constraints on acceptable not used not used XU(:)-XL(:) =< 2*fit-
parameter values. MaxStepSize

Lower and upper bounds on

parameter estimates
fitAdjustableParameters Counting 1’s gives the number of adjusta- As for ‘nlls’ but N is also used to determine
ble parameters, N. the parameter, NPT, when it has not been
Provides a simple way of includ- defined explicitly, see below.
ing/excluding model parameters
from the optimization.
fitnpt if fitnpt is UNDEFINED then
if (N<6) then
Controls the number of inter- not used NPT=(N+2)*(N+1)/2
else
polation conditions. Larger is NPT=2*N+1.
better but will be slower.

Finite difference step size (‘nlls’ only)

This controls the step size of each parameter value used in the estimation of partial derivatives
by finite differences numerically. The value of the step size should be large enough to achieve a
significant change in the objective function while being small enough to give derivatives with
sufficient accuracy. The correctness of the choice can best be seen from the first few iterations
where each of the adjustable parameters is adjusted one by one by the specified step size. This
should produce a significant change in the objective function for at least some of the parame-
ters (preferably all). If it does not, increase the step size by an order of magnitude. Default 1e-
6. Where approximate (numerical) methods are being used to generate the dependent variable
values, as in PHREEQC, there will inevitably be some noise in the generated values and so a
larger value may be appropriate to ensure sufficiently accurate derivatives.
 Fitting and simulations 139

Convergence criterion

Determines when to stop the iterations can accept a fit. The residual sum of squares will be
less than the convergence criterion at convergence. A small value will tend to increase the
accuracy of the fit, albeit with more iterations, but there will be a limit when the other numer-
ical procedures (both in the calculation of partial derivatives and in PHREEQC) will limit the
accuracy that can be obtained. The default value is 1e-6.

Maximum step size

The maximum step size taken during a change in adjustable parameters. A large value (say
100) will enable a large area to be searched but may lead to the focus wandering away from the
best solution and even lead PHREEQC to fail for some reason.
With the NEWUOA and BOBYQA methods, the maximum step size sets the initial size (radius) of
the trust region and is an important parameter. A small value will constrain the search area to
be close to the original parameter estimates which is fine provided the initial estimates were
good but may lead to misleading results otherwise. A large value may lead to physically unreal-
istic parameter estimates during fitting and therefore to problems in PHREEQC convergence.
The default value is 1.0.

Maximum iterations

The maximum number of iterations. If convergence has not been achieved by the time this
limit has been reached, PhreePlot will exit the optimization gracefully and move on.
If set to 1, this will force an immediate exit from the optimization routine but it will give an
indication of the correctness of the initial estimates. The default value is 5000.

Weighting method

fitWeightingMethod determines how the objective function is calculated from the residuals.
The residuals are multiplied by weights, one for each observation. See the definition of the fit-
WeightingMethod for more details.
It has the following options:

0 absolute error: all weights = 1.

1 relative error: weights = abs(1/fitted value) if fitted value is not equal to 0 else it
is abs(1/observed value).
2 from the input data file: weights in the column given by weightColumn.

The weights should be related to the quality of each observation in terms of the size of the
observation error. Weights are normally given by the inverse of the standard deviation of each
observation or something proportional to that
wi = 1 ⁄ σi

where the objective function to minimize is given by

minimize ∑ [ w i ( f obs, i – f calc, i ) ]

2

12.5 PREPARING AN INPUT FILE

The following is a simple example based on the iso.ppi file found in the \demo\fit directory.
This example fits a Langmuir isotherm to data for Zn sorption by Hfo at constant pH (pH
5.5). The iso.dat data file looks like this:

Znsorbed Znconcn pHobs wt sim#

140 PhreePlot Guide

0.75 0.030 5.5 1 1

1.40 0.069 5.5 2 1
1.95 0.118 5.5 2 1
2.51 0.166 5.5 2 1
3.03 0.217 5.5 5 1
3.53 0.270 5.5 5 1
4.02 0.325 5.5 5 1
4.41 0.388 5.5 5 1
4.79 0.453 5.5 2 1
5.22 0.512 5.5 1 1

where the units are mmol Zn/mol Fe for Znsorbed, mmol Zn/L for Znconcn and pHobs is
dimensionless. wt is the relative weight assigned to each observation and sim# is the
PHREEQC simulation number. Simulation 1 is used for all the calculations and so all simula-
tion numbers have been set to 1.
The PHREEQC input file part is

PHASES
Fix_H+
H+ = H+
log_k 0.0
SURFACE_MASTER_SPECIES
Surf Surf
SURFACE_SPECIES
Surf = Surf
log_k 0.0
SELECTED_OUTPUT
-high_precision true
-reset false
USER_PUNCH
# fit Langmuir isotherm
-headings sorbZn pH mmolZn& step_no
10 sorbedZn=SURF("Zn","Surf")
20 punch sorbedZn, -la("H+"), tot("Zn")*1e3, step_no
SOLUTION 1
-units mmol/L
-pH <pH>
Na 1000
N(5) 1000
Zn <Znconcn> #tag name from iso.dat data file
EQUILIBRIUM_PHASES
Fix_H+ -<pHobs> NaOH 10
SURFACE_SPECIES
Surf + Zn+2 = SurfZn+2
log_K <log_k>
SURFACE
Surf <M1>
-equil 1
-no_edl
END

12.6 FORCING RELATIONS BETWEEN PARAMETER VALUES

It is possible to force relations between parameter values by using the numericTags keyword to
define the desired relations and then substituting the corresponding tags in the input file in
the normal way.
For example, say there are four parameters and that these are referred to in the input file by
their corresponding tag names: <p1>, <p2>, <p3> and <p4>. If you want to force p4 = p1 then
reduce the number of parameters from 4 to 3 (p1, p2, p3) and add <p4> = <p1> in the
numericTags block. <p4> should be left unchanged in the input file. Its value will be updated
based on the numericTags expression on each iteration.
Other more complex relations may be specified in a similar way.
Note that it is important not to include the redefined parameter (<p4> above) in the set of fit
parameters since the optimizer expects to have full control over all parameter values and does
not expect them to be changed by an external procedure. <p4> is now a tag variable rather than
a fit parameter. There is no connection between the tag variables and fit parameters during
 Fitting and simulations 141

optimization.

12.7 OUTPUT FILES

Other than the log and plot files, the useful files produced during fitting and simulations are
the ‘out’ file and the ‘pts’ file.
The ‘out’ file contains a copy of the selected output, one record per observation. During fit-
ting, this normally contains just one block of results containing one record per observation –
the results from the last iteration (which is not necessarily the best-fitting iteration). Simula-
tions always just contain one block of results since there is no iteration. Fits can be made to
store the results of all iterations by changing the rewind data separator for the ‘out’ file to null
(‘’) instead of the default ‘\r’. This prevents the rewind before writing results and also intro-
duces a blank line after each block of results. This behavour is controlled by the fifth parame-
ter of the dataSeparators keyword.
The ‘pts’ file contains a comprehensive list of results for each observation including both the
input data, fitted, observed and weighted residuals and the results of the selected output, all-
from the best-fitting iteration. This is the file that is normally used for plotting.

12.8 RESPONSE IN THE EVENT OF A FAILURE OF PHREEQC TO CONVERGE

The response if PHREEQC should fail to converge during fitting depends on the debug set-
ting. If debug is 0 or less, then the offending point is deleted from the input and the fitting
restarted without it. When this happens, a ‘?’ is appended to the number of iterations in the
pp.log file to indicate that this has happened.

If debug is greater than zero, then PhreePlot will stop if PHREEQC fails. A list of any
offending points is sent to the log file. This gives the physical line numbers of the offending
points as found in the fit data file (counting the header line).

12.9 PLOTTING THE RESULTS OF THE FITTING

The ‘pts’ file is the primary plot data file for fitting and simulations though other files can be
added using the extradat keyword.
The ‘pts’ file contains data from three sources: (i) the fitting (5 columns: row number,
observed, calculated, residual, weighted residual); (ii) all the variables read in from the data
file; and (iii) all the columns from the selected output with values from the ‘best’ fit.
A plot of the observed points (as points) and the fitted values (as a continuous line) is often
useful. The lines and points which are plotted is controlled by the lines and points keywords,
respectively. ‘Lines’ plots only make sense when the points are contiguous.
The customXcolumn setting is also important as this fixes the x-variable.
The accumulated output from the selected output is stored in the ‘out’ file if present - this is
produced for debug > 0. If the fifth data separator is “\r”, the file is rewound at the beginning
of each set of function evaluations so only the last set will be found on the file (not necessarily
for the ‘best’ fit since this may have occurred in an earlier iteration). Any other character
means that there is no rewind and so all selected output results will be accumulated on the file.
The ‘trk’ file, if requested, contains a copy of the nlls monitoring results.
The use of the labels and post/postSize keywords can be useful for making a key and for ‘post-
ing’ values beside each individual point. Such posting can be useful for identifying outliers.
Additional text can be added with extraText and additional data from other files with extradat.
After a successful fit, three special system tags are populated. These are <R2>, <RMSE> and
<nFit> which contain the R2, RMSE and number of data points. These tags can be used to
annotate the plot using the extraText approach.
142 PhreePlot Guide

plotTitle
plotTitleSize
plotFactor
plotTitleColor

font
Refitting As(V) sorption data for Hfo
(1eAsv.dat)
from the fit data file
pymax 100 EAs1
EAs2 legendTextSize
pymajor EAs3
EAs4
observations
80 EAs5
EAs6
EAs1
EAs2
yaxisLength

60 EAs3 fitted values

% bound

EAs4
EAs5
EAs6
40 colours defined by
useLineColorDictionary
ytitle

20 lines
lineWidth from pts file
pxminor points
pointSize
pymin 0
2 4 6 8 10 12
pxmin pH pxmajor pxmax
pxdec
xtitle
axisTitleSize
customXcolumn axisTitleColor

xaxisLength

Figure 12.2. Some of the keywords used to control the appearance of fit plots.

An example of a fit plot with some of the more commonly used keywords is shown in Figure
12.2. Since the ‘pts’ file contains both observed and fitted data, it provides a useful source of
data to plot. Observations are often plotted with points and calculated values with lines.
Where the dependent variable depends on more than one independent variable, it can be dif-
ficult to choose a suitable plot. In these cases, a plot of calculated or residual values vs observed
values can be useful.

12.10SIMULATIONS

Simulations use essentially the same setup as fitting except that there are no observations to
compare with calculated values and so no fitting takes place. Typically simulations are used
after fitting to plot a calculated curve. based on the fitted parameters. This is done by chang-
ing the calculationType from ‘fit’ to ‘simulate’. Values of the independent variables are still
read in from a data file and tags assigned, exactly as for fitting.
This mechanism provides a way of running a gvien piece of PHREEQC code for a disparate
range of samples read from a file. It is somewhat similar to the use of SOLUTION_SPREAD in
PHREEQC but has more flexibility in the way that the data are read in.

12.11ROOT FINDING

You may want to estimate the value of one or more unknown parameters in a fully-defined
chemical model. Most chemical models are too complex to calculate the unknown values
explicitly and so the values have to be estimated numerically. When there are more data points
than adjustable parameters, the system is over-determined and ‘fit’ attempts to find the opti-
mal solution based on minimizing some kind of least squares objective function.
When the number of data points is the same as the number of unknown parameters, there are
zero degrees of freedom and the problem is then one of finding the unique set of parameter
values, or roots to the equation(s).
 Fitting and simulations 143

For example, assume that we want to find the volume of acid required to reach a certain pH.
We set up the chemical model such that the volume of acid added is a variable and represented
by some tag, say <titre>. The selected output is arranged to contain the pH after adding this
amount of acid. The pH is the dependent variable. In this example, there is one dependent
variable and no independent variables.
Then we make a fit data file with a single data point which specifies the end point pH of inter-
est. ‘fit’ then adjusts the single adjustable parameter, <titre>, so that the match between the
input and output pH is very close. The closeness is controlled by the normal convergence cri-
teria.

SPECIATION
calculationType fit
FIT
dataFile "fittitration.dat"
dependentVariableColumnObs pHwanted
dependentVariableColumnCalc pH
numberOfFitParameters 1
fitParameterNames "titre"
fitParameterValues 0 #initial estimate
fitAdjustableParameters 1
PLOT
# turn off the plotting
plotFactor 0.

CHEMISTRY

SELECTED_OUTPUT
-reset false
-pH true

SOLUTION 1
pH 7.05
units mg/L
water 0.050 kg # start with 50 ml water
Na 6
K 0.6
Ca 124
Mg 1.6
Cl 11
Alkalinity 348 as HCO3
S(6) 3 as SO4
Si 5.8

REACTION 1 Add 0.16M HCl to the soln

# 1 mL of 0.16M HCl
HCl 0.16e-3
H2O 55.5e-3
<titre>
END

The fit data file, fittitration.dat, simply looks like this:

pHwanted
4.5

It takes 1.76149 mL of acid. In this case, there is only one PHREEQC simulation involved
and the default is to use only the first simulation in fitting. If two or more simulations were
involved, then it would be necessary to add a column to the fit data file with the range of sim-
ulations to use (e.g. “1-2”) and to set blockRangeColumn to point to this column.
This example can be found in demo\titration\fittitration.ppi. While this particular
example could be solved pretty closely using a more direct PHREEQC approach, the princi-
ple is general and applies to more complex examples where such direct approaches are not pos-
sible.
144 PhreePlot Guide
 The input file pre-processor 145

13 The input file pre-processor

13.1 USE OF THE PRE-PROCESSOR

Although the use of tags can eliminate the need for repetitive blocks of text in an input file,
this may avoid the more efficient internal looping mechanisms provided by PHREEQC and
so might be undesirable especially when speed is an issue. This most obviously occurs during
fitting where the onePass TRUE option is much more efficient than the onePass FALSE option.
For example, consider the test fitting example shown below. This is similar to the demo\fit-
preprocessor\isopp.ppi example:

PRINT
-reset false
SURFACE_MASTER_SPECIES
Surf Surf
SURFACE_SPECIES
Surf = Surf
log_k 0

Surf + Zn+2 = SurfZn+2

log_k <log_k> # from fitParameterNames

SELECTED_OUTPUT
-high_precision true
-reset false

USER_PUNCH
-headings sorbZn pH molZn step
10 sorbedZn=SURF("Zn","Surf")
20 if (step_no=0) THEN punch sorbedZn, -la("H+"), tot("Zn")*1e3, step_no

SOLUTION_SPREAD
-units mmol/L
-pH <pH>

include 'isopp.dat'

SURFACE
Surf <M1> # from fitParameterNames
-no_edl
-equil 1
END

SURFACE
Surf <M1>
-no_edl
-equil 2
END

SURFACE
Surf <M1>
-no_edl
-equil 3
END

...
SURFACE
Surf <M1>
-no_edl
-equil 10
END

where the ten observations are defined as a series of SOLUTIONS 1-10 using the
146 PhreePlot Guide

SOLUTION_SPREAD keyword data block. The surface is equilibrated in turn with each of the
solutions using a repetitive block of code that looks something like:

SURFACE
Surf <M1>
-no_edl
-equil n
END

where n is the solution number.

The pre-processor provides a very simple mechanism for generating these repetitive blocks of
code with a simple form of numeric substitution. In the above example, the repeating blocks
would be replaced by:

<repeatStart1> 1 10 1 # startvalue, endvalue, increment

SURFACE
Surf <M1> # from fitParameterNames
-no_edl
-equil <repeatValue1>
END
<repeatEnd1>

The critical parts are the <repeatStart1> tag which defines the start of the repeat block and
the <repeatEnd1> tag which defines its end.
The three parameters on the <repeatStart1> line define a simple looping mechanism: start
value, end value, increment value. The generated values are substituted at the <repeatValue1>
point and the repeat block added to the input with the substituted value.
All three parameters must be numeric. The increment value must be positive. If the second
value is smaller than the first, the value counts down by the given increment.
The ‘1’ block identifier appended to the end of <repeatStart in the above example can be
any unique character string.
More than one repeat block can be given but they must not overlap or be nested. The blocks
are expanded top down.
This expanded input is fed into the input parser in the normal way. The parser knows nothing
about the pre-processing. The results of the pre-processor’s expansion are written to the log
file.
 Keywords 147

14 Keywords

14.1 SUMMARY OF AVAILABLE KEYWORDS

Table 14.1 gives a summary of the available keywords. The keywords are arranged in their
three major sections: SPECIATION, FIT and PLOT based on their function.

14.2 CONVENTIONS

The PhreePlot keywords are listed below in alphabetic order. Keywords are not case sensitive.
Each keyword has one or more attributes associated with it. The type of these attributes is
fixed. Each one belongs to one of the following types:

logical T(RUE) or F(ALSE)

integer a whole number (no decimal point)
number an integer or floating point number
string a character string (with or without enclosing quote marks)
filename a valid filename which may include the path (system dependent)
filepath a valid filepath without a filename (system dependent)
color a valid colour name

14.3 KEYWORD DESCRIPTION

The function and use of each keyword is given below. Keywords have been ordered alphabeti-
cally. Aliases are alternative names for the keywords. The default is the value set internally by
PhreePlot and read from the pp.set file. These default values can be overridden from the
input files (*.ppi or override.set) or during an interrupt (‘Esc’) while running. Values given
in square brackets are optional.
148 PhreePlot Guide

Table 14.1. Available keywords

Keyword Function
SPECIATION section heading
PhreePlotVersion version of PhreePlot
jobTitle title of this job for log file
speciationProgram speciation program used
speciationProgramVersion version of speciation program used
database thermodynamic database to use
dateDatabase date or version of thermodynamic database to use
pdfMaker file path of ps to pdf conversion program
fillColorDictionary file path for fill colour dictionary used in predominance diagrams
lineColorDictionary file path for line colour dictionary used in custom and fit plots
blockRangeColumn name of column in a data file defining the range of a block of simulations
mainLoopColumn name of column in a data file defining the start of the main loop simulations
selectedOutputFile name of the selected output file (set with SELECTED_OUTPUT -file)
log logical switch for the log file
trk logical switch for the track file
pts logical switch for the points file
pplog logical switch for the pp.log file
pol logical switch for the polygon file
labelFile logical switch for the labels file
arc logical switch for the arc format points file
vec logical switch for the vectors file
out logical switch for the output (or out) file
rewriteInputFile determines if the original input file is overwritten by a reformatted version
dataSeparators controls the separator(s) used for data input files and the format of output files
calculationType type of calculations and plotting to do
calculationMethod whether to calculate and plot or just replot
mainspecies main species in a predominance or mineral stability plot
xmin minimum x-value for calculations
xmax maximum x-value for calculations
ymin minimum y-value for calculations
ymax maximum y-value for calculations
loopFile file path for file containing values for the z-loop variable
loopMin minimum value for the z-loop variable
loopMax maximum value for the z-loop variable
loopInt interval or increment for the z-loop variable
loopLogVar determines whether the z-loop variable value is to be anti-logged (10^z)
loopIndexStartNumber initial number of loop index used eg for naming files
resolution number of intervals on which x- and y-axis interval is divided
debug controls response to errors and extent of reporting made to log file
omitAccumulate filter out all lines containing the given string(s) from being sent to PHREEQC
printScreenFrequency frequency with which progress in ht calculations is sent to screen
plotFrequency frequency with which plot.ps file showing plotting progress is written
selectedOutputLines controls which of the selected output lines are used by PhreePlot
mainLoop controls the division between pre-loop and main loop PHREEQC simulations
dominant dominant or subdominant predominance diagram
numericTags number of numeric tag definitions to follow
characterTags number of character tag definitions to follow
initialValue sets the value of all undefined numeric tags

FIT section heading

dataFile file path for the data file containing dependent and independent variables
 Keywords 149

Table 14.1. Available keywords (contd)

onePass determines if all dependent variable values are calculated in one pass or not
logDepVariable indicates whether dependent variable is entered on a linear or log scale
logVariableIn indicates whether independent variables are entered on a linear or log scale
dependentVariableColumnObs column from which to read the dependent variable from the fit data file
dependentVariableColumnCalc column from which to read the dependent variable from the selected output
skip controls the number of records read in from the fit data file
fitMethod choose optimization procedure
fitFiniteDiffStepSize finite difference step size for estimating first derivatives in fitting routine
fitConvergenceCriterion convergence criterion in fitting routine
fitMaxStepSize maximum step size in fitting routine
fitMaxIterations maximum iterations in fitting routine
fitWeightingMethod weighting method to use in fitting routine
weightColumn column giving the weights in the fit data file
numberOfFitParameters number of parameters that are defined and tagged for fitting
fitParameterNames names of fit parameters
fitLogParameters determines whether to log transform fit parameters or not
fitAdjustableParameters determines whether fit parameters are fixed or adjustable
fitParameterValues initial values of fit parameters
fitnpt number of interpolation points used by the NEWUOA and BOBYQA optimizers
fitLowerParameterValues lower constraint on fit parameters (not currently used)
fitUpperParameterValues upper constraint on fit parameters (not currently used)
updateFitParameters determines if fitted parameter values are written to file(s) or original ones retained

PLOT section heading

units units to use for all dimensions
paperSize paper size to write to Postscript file
backgroundColor colour of background within the plot boundaries and for the rest of the page
colorModel colour model to use for all colours
ps logical switch for the ps format plot file
pdf logical switch for the pdf format plot file
png logical switch for the png format plot file
screen logical switch for screen output and setting for close down time on failure
epsi logical switch for the epsi format plot file
eps logical switch for the eps format plot file
ai logical switch for the ai format plot file
jpg logical switch for the jpg format plot file
ppa logical switch determines whether an archive (ppa file) is written
plotTitle title to be placed at top of plot
plotTitleColor color of plot title
plotTitleSize height of plot title
xtitle x-axis title
ytitle, 2ytitle y(2y)-axis title
xoffset distance from left hand edge of page to left-hand y axis
yoffset distance from bottom of page to lower x axis
pageOrientation portrait or landscape
multipageFile for multiplot runs, determines whether the plots are all in one file or not
customLoopManyPlots make many separate plots (if T) or just one (if F) when multiple z-loops specified
xaxisLength length of x axis
yaxisLength length of y axis
pxmin minimum value of x axis on plot
pxmax maximum value of x axis on plot
pxmajor interval between major tick marks on x axis
pxdec controls number of figures after decimal point on x-axis labelling
150 PhreePlot Guide

Table 14.1. Available keywords (contd)

pxminor x-axis interval between minor (unlabelled) tick marks

yscale determines the yscale of predominance plots: native, pe or Eh (V or mV)
pymin, p2ymin minimum value of y(2y)-axis on plot
pymax, p2ymax maximum value of y(2y)-axis on plot
pymajor, p2ymajor interval between major tick marks on y(2y)-axis
pydec, p2ydec controls number of figures after decimal point on y(2y)-axis labelling
pyminor, p2yminor y(2y)-axis interval between minor (unlabelled) tick marks
customXcolumn column name or number of x-axis variable for plotting
lines list of column names or column numbers to plot as lines
lineWidth line width
dashesPerInch number of dashes per inch for dashed lines
lineColor set initial colours in the line colour sequence
changeColor determines if the colour changes automatically for subsets of data in custom plots
useLineColorDictionary is the line colour dictionary is used for colours and label positions
restartColorSequence controls color sequence between plots & within subsets of the same data column
points list of column names or column numbers to plot as points
pointType, pointType2y list of number or names of symbols used in custom plots
pointSize, pointSize2y size of symbols used in custom and fit plots
pointColor starting colour of symbols used in custom and fit plots
rimFactor widths of the rims of symbols (filled circles) as a fraction of symbol sizes
rimColor colours of the rims of filled circle symbols
pointsSameColor controls whether all symbols have the same colour
tickSize length of the tick marks and possibly the grid lines
tickColor colour of the tick marks
axisNumberSize height of the axis numbers
axisNumberColor colour of the axis numbers
axisTitleSize height of the axis title
axisTitleColor colour of the axis title
axisLineWidth width of the axis lines
axisLineColor colour of the axis lines
labels list of names to be used for the lines labels in custom plots
labelSize height of the labels used for labelling lines
labelColor colour of the labels used for labelling lines
info colour for the text of the ‘info’ data accompanying each plot
legendTitle text for legend (key) title in custom plots
legendTextSize height of text in the legend for custom, fit and grid plots
labelEffort controls the effort (and time) taken to improve automatic label placement
trackSymbolSize size of symbol used for a tracking plot and for labelling anchor positions
trackSymbolColor colour of symbol used for a tracking plot and for labelling anchor positions
domain determines if the domain boundaries are plotted in a ht1 predominance plot
customXcolumn number or column name pointing to the x-column in a custom or fit plot
font font to be used for all text
plotFactor scaling factor to be used for all plot elements
missingValue dummy value to signal a missing value
minimumAreaForLabeling minimum size of field (as a %age of total area) to plot a label in a ht plot
minimumYValueForPlotting minimum maximum y-value for which to plot a curve in a custom plot
beep turn sound on or off
simplify controls the degree of polyline simplification in ht plots
convertLabels interpret label names as PHREEQC formulae or not
extraSymbolsLines path name for file containing additional symbols and line data to add to plot
extraText path name for file containing additional text to add to plot
extradat list of path names for files to add to the search path for variables used in plotting
post list of names to be used for the posted text or a data file column tag name
 Keywords 151

Table 14.1. Available keywords (contd)

postSize size of the posted text

contourZvariable name of the variable/column in the outfile that contains the z-data for contouring
contours list of values at which to draw the contour lines
contourFillColor list of colors to fill the contour levels
contourLineWidth list of the widths of the contour lines
contourLineColor list of the colours of the contour lines
contourShiftLabel list of contour labels to move and the distance to move them
contourLabelSize list of the size (height) of the contour labels
contourLabelFigs list of numbers specifying the number of digits to use in the contour labels
contourLabelFont list of fonts used for printing the contour labels
contourLabelColor list of colours used for the text of the contour labels

ai
Value logical
Description Determines whether the plot output (if any) is converted to a file in the
Adobe Illustrator (ai) format.
Aliases aifile
System default F

Use An ai file can only be produced if Ghostscript/GSview is installed.

PhreePlot makes use of the Ghostscript ps2ai utility to produce this file.
Illustrator files are a type of vector-based graphic file that can be edited
using suitable software. The file created is given the extension ai.
Curiously, the ai file produced by Ghostscript cannot be read by Adobe
Illustrator but can be read by FrameMaker. It can also be edited rather
simply with Mayura Draw (www.mayura.com) and exported as an eps
file. The best formats for importing into Adobe Illustrator is either
PhreePlot’s native ps/eps format or the pdf format.
Example 78

axisLineColor
Value Cohort colour
Description Determines the colour of the axes.
Aliases
System default black
Use Enables the line colour of the axes to be changed.
Example 38
152 PhreePlot Guide

axisLineWidth
Value non-negative number
Description Determines the width of the axes.
Aliases axislw
System default 0.3
Use Enables the line width of the axes to be changed.
Example 38

axisNumberColor
Value Cohort colour
Description Determines the colour of the numbers on the axis scales.
Aliases numberColor
System default black
Use Enables the line colour of the axis numbering to be changed.
Example 38

axisNumberSize
Value non-negative number
Description Determines the size of the axis numbers.
Aliases numberSize
System default 3
Use Enables the size of the axes to be changed.
Example 38

axisTitleColor
Value Cohort colour
Description Determines the colour of the titles of the axis scales.
Aliases
System default black
Use Enables the colour of the axis titles to be changed.
Example 38
 Keywords 153

axisTitleSize
Value non-negative number
Description Determines the size of the axis titles.
Aliases axisTitleHt
System default 3
Use Enables the size of the axis titles to be changed.
Example 38

backgroundColor
Value Cohort colour [cohort colour]
Description Determines the background colour of the plot and optionally of the page.
Aliases background
System default nd nd

Use Enables the background colours to be changed. This plot background is

the area bounded by the x and y axes. The plot background is overwritten
by any text, lines or fills produced by the plot.
The page background is the whole page. The page background colour, if
drawn, will be overplotted by the plot background colour, if drawn.
nd, or equivalently “”, will suppress the drawing of the colour.
Example 69

beep
Value logical
Description Determines whether the sound is on or off.
Aliases
System default T

Use Switches the sound on (T) or off (F). A high-pitched beep is produced on
successful completion of a plot. A low-pitched beep is produced when
PHREEQC fails to converge or when the plot fails to complete. This
option can be useful to signal progress when multiple plots are being pro-
duced in the background or to highlight when PHREEQC fails. It can
also be irritating. Placing beep FALSE in the override file will ensure that
no sound is heard from any run no matter what the setting in the pp.set
and input files!
Because of the duration of the beep, repeated low frequency beeps can sig-
nificantly slow down execution. The beeping can be turned off during
154 PhreePlot Guide

execution using the ‘Esc i beep F’ sequence.

blockRangeColumn
Value zero or a positive integer or a column name
Description Specifies the column number (counted from the left) or column name in
the fit data file in which the range of PHREEQC simulations number to
use to calculate each observation will be found.
Aliases fitSimulationColumn, fitSimulationNumberPosition, fitSimulationPosi-
tion
System default 0
Use Only used in ‘simulate’ and ‘fit’ calculations. When onePass is FALSE,
the dependent variable for each line of data is calculated from its own
PHREEQC simulation, or range of simulations. This variable specifies
the column name in the fit data file which contains the PHREEQC sim-
ulation number(s) to use for each observation. A range is entered in the
form ‘m-n’ or ‘m_n’ without any spaces.
In principle, every line of the data file could use a different set of
PHREEQC simulations.
When onePass is TRUE, blockRangeColumn is not checked or used since
the selected output from all simulations is automatically used for each
observation.
When this setting is set to 0 (the default) or a negative integer, it is
assumed that the block range used for all observations is from 1–n, where
n = number of simulations in the input file, i.e. the entire block of simula-
tions is computed in a single PHREEQC run for each observation.
Use mainLoopColumn to specify a column in the data file in which the
division between the pre-loop calculations and main loop calculations
within each block can be set for each observation.
Examples 79, 82

calculationMethod
Value 1, 2 or 3 and their negatives
Description Determines whether to undertake the calculations and plot or just replot
existing results
Aliases method, plotMethod
System default 1
Use 1 = calculate and plot
2 = replot only (necessary results files must be present). For ht1 plots, the
existing polygon file is used. Do not re-optimize label positions in custom
plots.
3 = do not re-speciate but reprocess the output data and replot. With pre-
dominance plots, this generates new polygon and label files from the
 Keywords 155

points file (‘ht1’) or the track file (‘grid’ and ‘grids’).

Typically the plot files are generated first time through with a setting of 1
then set to 2 (or 3) during fine-tuning of the appearance of plots. This
saves speciation time but not labelling time. Negative values of calcula-
tionMethod will do the same as their positive counterparts except that no
plot will be produced.
Use of calculationMethod 2 or 3 (replot) will not generate ‘run time’ val-
ues for those tags assigned values at run time, namely the user punch tags
and the tags automatically created during a fit run. In these cases, user
punch tags that are not defined values will not be recognised as valid tags
in subsequent simulations and so will either plot as their literal text string,
i.e. no substitution will be undertaken, or will produce an error message
where a numeric value is required. In these cases, recalculating with calcu-
lationMethod 1 is the only option.
For custom plots, calculationMethod 2 does not reoptimize label posi-
tions; calculationMethod 3 does.
For grid plots, calculationMethod 3 can be used to resume calculations
when there has been a crash or an interrupt and stop. The track file is read
in and calculations resumed where they left off.
Dummy user punch tags will be defined from the second (first non-
header) line of the appropriate ‘out’ file, if present, and fit tags generated
from the second line of the data file, if present. This is necessary since all
tags are updated just before plotting and some of these tags may be
involved in tag definitions. Clearly the values will have little significance
in a replot.
If the tags cannot be defined, an error will result.
In order to get dynamic tags – i.e. those generated during a run and whose
effects are not stored in the various data files used for plotting – properly
substituted, it is necessary to do the calculations from scratch
(calculationMethod 1) each time a plot is wanted.
Example 3

calculationType
Value one of ‘grid’, ‘ht1’, ‘custom’, ‘species’, ‘simulate’ or ‘fit’
Description Determines the calculations carried out and the type of plot drawn
Aliases plotType, type, calculation
System default “custom”

Use Specifies one of the six calculation types available: ‘grid’, ‘ht1’, ‘custom’,
‘species’, ‘simulate’ or ‘fit’. This keyword should be specified in each input
file.
Examples 1, 3, 54, 72, 79
156 PhreePlot Guide

changeColor
Value logical
Description Determines the extent to which auto-generated colours vary for multiple
sets of data especially for subsets of the same variable (column)
Aliases chgCol
System default F

Use If set to FALSE and if the line colour dictionary is not being used, all line
and point colours will be those specified by the lineColor(m) and point-
Color(n) settings, where m, n are the positions of the variable in the lines
and points sequences, respectively. All subsets of data for a given variable
will have the same base colour although the colour density may vary.
If restartColorSequence is TRUE, the the same colors will be used for all
subsets of a particular variable. If restartColorSequence is FALSE, then the
density of the chosen colours will be cycled through 4, 6, 8, 2, 4 ... for the
different subsets, e.g. red4, red6, red8, red2, ....
If set to TRUE and if the line colour dictionary is not being used, the
colours used for successive subsets of data and for different variables will
be automatically chosen from an appropriate points or lines colour list.
These two lists start with the colours so far unused for points and lines
(both y and 2y), respectively, in their normal order and then with the used
colours are appended. The list is recycled as necessary changing the colour
density on each cycle.
Example 61

characterTags
Value A list of character tag definitions, all on one logical line.
Description Character tags can be used to substitute strings.
Aliases numberOfCharacterTags
System default ““
Use Used to enter user-defined character tags with a similar syntax to
numericTags, as list of triplets:
tagname = expression, e.g.
characterTags <myTextColor> = “blue4” \
<mySymbolColor> = “red4”
If none is to be defined, use a blank string:
characterTags ““

See Section 5.3.2 for a definition of valid tag names. Spaces around the
‘=’ sign are optional. The tag expression should be a simple character
string, embedded in quotes if necessary. It can also be another character
tag. The initial integer, if present, and the definitions should all be on a
single logical line, hence the use of \ above. A \ continuation character
 Keywords 157

enables each tag definition to be placed on a separate physical line. This

can aid legibility.
The tag expression must be a single ‘word’. Enclose in quotes if it contains
one or more spaces. A null string can be entered as “” or ‘’. Character tag
names are case sensitive.
When a character tag is substituted into an input file, no enclosing quotes
are included. Therefore in situations where enclosing quotes are needed to
force the string to be interpreted as a character string, enclose the tag
expression itself in quotes, e.g. if <data>=”Clear Lake”

USER_PUNCH
- headings pH dataset
10 PUNCH -log10(“H+”), “<data>”

Character tags can also be used to replace lists of character or numeric

items in an input file, e.g.

characterTags <col> = “green6 purple” \

<contours> = “0 2 4 6 8 10”
...
lineColor <col>
contours <contours>

colorModel
Value rgb, b&w or gray
Description Sets the colour model used
Aliases color
System default rgb

Use Three colour models are available:

rgb => the red-green-blue colour model
b&w => black and white only
gray => a grayscale
rgb colour names are based on the Cohort colour scale. b&w converts all
colours to black. gray attempts to convert colours to a grayscale based on
their hue. The Postscript file produced reflects the colour model used, i.e.
a black-and-white file can never be made to produce a colour plot. On the
other hand, a colour plot file can often be made to produce a grayscale
print on a black and white-only printer.
The ‘b&w’ and ‘gray’ colour models translate any ‘coloured’ colours to
their black and white or gray equivalents at plot time. The original
colours are written to the appropriate colour dictionary so that the plot
can be replotted in full colour if desired.
If full control over the gray colours used is wanted, these should be
entered explicitly in the colour dictionary.
158 PhreePlot Guide

contourFillColor
Value list of colours
Description Sets the colours used for filling in between the contour lines
Aliases
System default auto

Use The list of colours should be the same length as the number of contours
plus one. If shorter, the list is recycled. If longer, it is truncated.
The colors are paired off in sequence, one per contour class.
Use ‘nd’ for ‘not drawn’ or no colour.
‘auto’ generates a list of blue-red colours centered on sky1-red1 with the
lowest class being the darkest blue and the highest class being the darkest
red. The blue list is expanded sky1, sky2, ..., sky9 and the red list is
expanded red1, red2, ..., red9. There are therefore a maximum of 18 dis-
tinct colors. These colors are recycled if there are more than 18 classes.
This corresponds with 17 specified contour levels.

contourLabelColor
Value list of colours
Description Sets the colours used for the labels to the contour lines
Aliases
System default auto

Use The list of colours should be the same length as the number of contours.
If shorter, the list is recycled. If longer, it is truncated.
The colors are paired off in sequence, one per contour value.
Use ‘nd’ for ‘not drawn’ or no colour. This will suppress the drawing of the
label(s) for this contour level.
‘auto’ will copy the colour specified by labelColor.

contourLabelFigs
Value list of non-negative integers
Description Determines the number of figures used in the numeric contour labels
Aliases
System default auto

Use The list of integers should be the same length as the number of contours.
If shorter, the list is recycled. If longer, it is truncated.
 Keywords 159

The integers are paired off in sequence, one per contour value.
The format used depends on the size of the value of the label. Exponential
format is used for very large or small numbers.
Use 0 to force the value to be printed to the nearest integer.
‘auto’ will use 3 or less figures depending on the value.

contourLabelFont
Value list of fonts
Description Determines the font used by the contour labels
Aliases
System default auto

Use The list of fonts should be the same length as the number of contours. If
shorter, the list is recycled. If longer, it is truncated.
The fonts are paired off, one per contour value.
The fonts are specified by font names or font family names (see font).

contourLabelSize
Value list of numbers
Description Determines the size (height) of the contour labels
Aliases
System default auto

Use The list of label sizes should be the same length as the number of con-
tours. If shorter, the list is recycled. If longer, it is truncated.
The sizes are paired off, one per contour value.
The units of contourLabelSize depend on the units in effect when con-
tourLabelSize is set.
‘auto’ copies the size given by labelSize.

contourLineColor
Value list of colours
Description Sets the colours used for the contour lines
Aliases
System default auto

Use The list of colours should be the same length as the number of contours.
If shorter, the list is recycled. If longer, it is truncated.
160 PhreePlot Guide

The colors are paired off, one per contour value.

Use ‘nd’ for ‘not drawn’ or no colour. This will suppress the drawing of the
contour(s) for this contour level.
‘auto’ will match the colour specified by lineColor

contourLineWidth
Value list of numbers
Description Sets the width of the contour lines
Aliases
System default auto

Use The list of widths should be the same length as the number of contours. If
shorter, the list is recycled. If longer, it is truncated.
The widths are paired off, one per contour value.
Use ‘nd’ for ‘not drawn’ or no colour. This will suppress the drawing of the
contour(s) for this contour level.
‘auto’ will copy the width specified by lineWidth.

contours
Value list of numbers in strictly ascending order or auto [n [p|s|e]]
Description Sets the values of the contours to plot
Aliases
System default auto 17 p

Use This keyword defines the contour levels used. The main task is to get a set
of contours that displays what you want without getting confused by
numerical noise, especially around phase boundaries.
There are several ways of defining the number and value of the contour
levels.
The first way is simply a list of user-defined contour values in a strictly
ascending order (cannot be equal). The list can be of any length.
The second way, auto [n [p|s|e]], lets PhreePlot choose the number and
value of the contours. n contours are chosen (default n = 17).
These values are selected based on the z-data being contoured. This is
done in one of three ways: (i) by percentiles (‘p’) in which the various con-
tour classes are approximately equally occupied, (ii) by simplified percen-
tiles (‘s’) which is the same as the ‘p’ option except that any pair of
adjacent contour values that are ‘rather close’ to each other (within less
than 1e-2 of the z-data range) are replaced by a single average value, or
(iii) by dividing the z-range (zmax - zmin) into n equally-spaced contours
(‘e’).
Aside from the simplified percentiles approach which explicitly ‘simplifies’
 Keywords 161

or reduces the number of contours, successive pairs of contour values

must always differ from each other by at least 1e-8 of their average value.
If specified or generated contour values are closer than this, the pair of val-
ues will be replaced by their average value.
The actual number of contours plotted may therefore be fewer than the
number specified. This occurs when the contours are deemed to be ‘too
close’ to each other as described above.
The percentiles (‘p’) approach is the default.
The contour values actually used are always reported in the log file.
Example 84

contourShiftLabel
Value ‘c’, ‘n’ or ‘f’ then zero or more triplets of integers which specify the plot
number, contour number and shift amount
Description Display label position and specify which labels to move and by how much
Aliases
System default c

Use The first character is interpreted as follows:

‘c’ ‘c’ for contour. The contours are labelled with their values
(default).
‘n’ ‘n’ for number. The contours are labelled with their sequential
number. The position of the vertices are also shown with the track
symbol (filled circle) of size trackSymbolSize(1).
‘f ’ ‘f ’ for file. The label text, postion and orientation are taken from
the labels file – but only with calculationMethod 2. With this
option, no triplets of integers should be appended.
If triplets of integers follow, these define a contour label and how much to
move it from its default position. The triplets are specified as follows:
first integer (non-negative): the absolute value defines the plot number of
interest. Each plot is numbered sequentially as plotted. The plot number
is given in the log file and is printed at the top left of the info block. The
sequence number increments on cycling through the main species (outer
loop) and then the loop variables (inner loop).
second integer (non-negative): gives the contour number. The contours
are plotted from the ‘vec’ file with the list of vertices of each contour
being separated by a blank line. The contours are numbered sequentially
as read from this file. The contour number refers to this sequential posi-
tion. Each contour can in principle be represented by more than one vec-
tor when it intersects a domain boundary, hence the reason to specify by
this number rather than simply the contour class.
third integer (non-negative): gives the ‘distance’ to shift or move the label
from its default position in terms of vertices. The default position places
the label at the centre of the longest straight segment in the simplified vec-
tor. A shift of +1 moves the label to between the next pair of points, +2 to
two points forward etc. -1 moves the position backwards one point etc.
162 PhreePlot Guide

‘Forward’ is always ‘moving with the high side on the right’.

In order to estimate the shift settings, it is simplest to first plot with the ‘n’
option. This will show the contours numbered in the way required above.
It also shows the vertices that make up the contour line - the number of
vertices to shift by – forwards or backwards – can then be easily deter-
mined.
Simplified straight line segments will have few vertices. The number can
be increased by reducing simplify.
It is also possible to identify labels from the labels file. This file is written
with calculationMethod 1 and 3 and read with calculationMethod 2.
If the shift places the label outside the list of points, the label is not drawn.
This is how the plotting of individual overlapping labels can be entirely
suppressed. Another way is to edit the labels file and use the ‘f ’ option.
With the ‘f ’ option, the text can be moved away from the contour line.
However, no line break is drawn with this option which may make the
label difficult to read. Changing the label colour may help here.
The printing of all labels for a given contour level can be suppressed by
setting the contourLabelSize to 0. or the contourLabelColor to ‘nd’.

contourZvariable
Value name of an outfile column (case sensitive)
Description Specifies the variable (column) in the outfile to be used as a source of z-
data for contouring
Aliases
System default “”

Use The contourZvariable must be present in the outfile. Normally this is set
by the -headings setting in a USER_PUNCH data block.
There must be nres x nres rows of z-data in the outfile where nres is the
resolution. Missing data, e.g. when the speciation has failed, is represented
by a blank line.
Example 84

convertLabels
Value logical
Description Determines whether an attempt is made to interpret plot labels as
PHREEQC chemical formulae with subscripts and superscripts etc
Aliases convertLabelNames
System default T

Use If T(RUE), label names are checked to see if they are plausible PHREEQC
chemical formulae and is so, they are converted. This does not check the
thermodynamic database for formulae names but does check for basic
 Keywords 163

things such as the first character must be a (, [ or upper case letter, and it
must not contain any of the characters: ¬#~@;?!"£$%^&*'”.
If a label does not look like a formula or if convertLabels is FALSE, then no
attempt to interpret it as formula. For examples of the conversion see Sec-
tion 6.4.2.
If some labels are to be interpreted as formulae and some not, then con-
vertLabels should be set to TRUE and the individual label names should be
written in such a way as to prevent them being interpreted as a formula,
e.g. begin names with a lower case character or include one of the ‘illegal’
characters.
The ¬ character can be read but will not be printed and so if added to the
end of a name will prevent its conversion without being seen in the final
plot.
This setting applies to all label names including loop names.
Example 83

customLoopManyPlots
Value logical switch
Description Determines if each new value of the z-loop variable produces a new plot
or not.
Aliases
System default FALSE

Use Only used for custom plots. The default (FALSE) means that each value of
the loop variable will normally produce a separate curve on a single plot.
This can be messy and so when this option is set tot TRUE, a new plot is
produced for each value of the loop variable. These can be combined into
a single file using the multipageFile option.

customXcolumn
Value positive integer or column name (case sensitive)
Description Determines which column of data in the outfile is used for the x axis dur-
ing custom plotting.
Aliases xColumn, customXPosition
System default 1

Use Ensures that the correct column is used as the x-axis variable for plotting.
The order of output is determined by the order of USER_PUNCH statements
and the choice of other SELECTED_OUTPUT parameters in the PHREEQC
code. The columns are counted from the left. Used for custom and species
plots. In species plots, customXcolumn should point to the column of
either the species name or the numeric value of the pair wanted.
Examples 54, 72, 79
164 PhreePlot Guide

dashesPerInch
Value positive integer
Description Determines the number of dashes per inch for dashed lines.
Aliases
System default 10

Use All dashed lines produced by a single file will have this number of dashes
per inch. Dashed lines are indicated by a negative lineWidth.

database
Value filename
Description Controls which thermodynamic database file is used by PHREEQC.
Aliases
System default wateq4f.dat

Use Set the filename of the database that is to be used by PHREEQC.

Example 39

databaseVersion
Value string
Description Gives information about the version of the database selected.
Aliases
System default none
Use If the log file is activated, this string is printed to it. It is also printed in the
info block of a plot if that is selected to be printed. These provide a record
of which database was used in the calculations used to make the plot. The
string can be a date but does not have to be.
This setting does not affect the computations.

dataFile
Value filename [data separator]
Description Specifies the file containing data for the simulate and fit calculations and
optionally the data separator(s) used to parse it.
Aliases fitDataFile
System default
 Keywords 165

Use This text file contains the observations (dependent variable), if present,
and the independent variables if present. The first line should consist of
the column headers. These are converted to tags and so should conform
to the tag naming conventions (e.g. arithmetic operators like + or - and
other illegal characters will be automatically replaced by an underscore).
The total number of columns to be read is determined from the number
of entries in the column header. This should also match the number of
entries specified by the logVariableIn setting.
Contiguous blanks are treated as a single separator but multiple other sep-
arators (e.g. ,,) will introduce null fields. Comments can be included
using a # as usual. Blank lines are ignored.
Where only some non-essential data are absent, some form of missing
data identifier can be used to identify such cells, essentially acting as
placeholders. For example, a blank field can be entered as a null string, “”,
or by a missing value. A null string will be set to zero if it represents a
numeric field.
The header line and the remaining part of the file will be parsed, by
default, according to the separator(s) specified by the first entry in the
dataSeparators keyword. If the optional data separator string is specified
with the data file name, then this is used. The options for this separator
are given in Section 5.2.4.
The location of the column containing the dependent variable if present
is specified by the dependentVariableColumnObs keyword.
The other columns that have been read in are given tags defined by their
column headers with numeric or character type depending on the type of
the corresponding entry in the first valid data line. These tags can then be
used in the PHREEQC input file. Each iteration of PHREEQC will read
in one line of the data file, generate a full set of tags and their correspond-
ing tag values, make any tag substitutions in the PHREEQC input and
run. A maximum of 20 characters is output by PHREEQC - longer
strings will be truncated.
If calculationType = ‘simulate’, then the data file can be used to supply a
list of tag values to the input file without undertaking any fitting. There
need not even be a dependent variable.
Examples 79, Using the ‘simulate’ calculationMethod

dataSeparators
Value six separate 1- or 2-character strings
Description Defines the separators used in data input and formatted output files.
Aliases sep
System default “\” “\t” “\p” “\p” “\r” “”

Use The standard input files use a space, tab or comma for separators but this
can be too flexible for formatted data files. Also it is useful to be able to
specify whether blank lines (indicating a break in a plotted curve) are
written to the ‘out’ file after a change in a loop variable. This keyword
can be used to inform PhreePlot of the various options available.
166 PhreePlot Guide

Contiguous separators can be treated as a single separator or in the case of

tabs and commas, they can be treated as true separators indicating a blank
or missing field.
Quoted fields are treated as single field even if they contain spaces.
The six entries are:
1. default separator(s) for reading data input files, e.g by ‘fit’ and
‘speciate’ as well as loop and extradat files (they can also be specified sep-
arately for each file, see Section 5.2.4);
2. separator to be used in formatted output files notably the ‘out’, ‘trk’
and custom ‘pts’ files;
3. controls whether a blank line is inserted into the ‘out’ file for each new
value of <x_axis> or <y_axis>;
4. controls whether a blank line is inserted into the ‘out’ file for each new
value of the loop variable (z-value);
5. controls whether the ‘out’ file should be rewound at the beginning of
each iteration or not.
6. a ‘break variable’ used to introduce one or more breaks in a column of
data based on the change in slope of this variable.
The first separator defines the separator for reading ‘user-prepared’ data
files (as opposed to input files with keywords, extra text files or dictionary
files). The three data files that use this setting at present are the fit data file
used during fitting and simulations, the loop data file and any extradat
data files.
Use any single character or “\t” for a tab , “\b” for a blank space or “\w”
for both (whitespace). A null string, entered as a pair of quotes with noth-
ing in between (“”) , indicates that either a tab, space(s) or comma is
interpreted as a valid separator. This is equivalent to “\”. Consecutive
blanks are treated as a single separator but multiple other separators are
not, i.e. they will be interpreted as blanks. This allows blank fields to be
read. Tabs alone are useful when an input file has been pasted into a text
file from a spreadsheet and when spaces and commas are present in text
strings and the strings are not embedded in quotes. Although quoted
strings will preserve whatever is inside them, the quotes can get lost on
pasting to and from a spreadsheet.
“,” should be used for the first setting in comma-separated (csv) files.
The second separator specifies the separator to use for formatted output
files, notably the ‘out’, ‘trk’ and ‘pts’ files (but not the binary ‘pts’ file
used for predominance diagrams). Tabs (“\t”), commas(“,”) or spaces
(“\b”) are the most commonly used separators. Enclose the specified sep-
arator in quotes if necessary. Tabs are useful when the file is to be pasted
into a spreadsheet. Spaces and commas are preserved in strings without
the need to quote them.
When a space (“\b“) is used for the output separator, then additional
spaces are inserted to justify the columns. This format is better for reading
and printing. However, character strings are truncated to 18 characters to
allow the strings to be quoted. Use tabs if this is a problem.
Note that “” is not the same as “ ”. The former is the null string; the lat-
ter is a space.
 Keywords 167

The third and fourth separators refer to the between-the-line separator

used in the ‘out’ file. If these two strings are “\p”, then a blank line is
inserted into the out file after (i) a change in the x- and y-axis loop vari-
able (third separator); or (ii) a change in the z-loop (or <loop>) variable
(fourth separator). Any other characters, including the null string, ‘’,
means that no blank line is inserted at these points. These settings can be
used to control the breaks made when plotting curves. If a loop file is
used, it is also possible to insert a blank line into the ‘out’ file by inserting
a blank line into the corresponding position in the loop file.
The fifth separator determines if the ‘out’ file should be rewound at the
beginning of a fit iteration or not. A rewind is indicated by the “\r” com-
bination otherwise there is no rewind. The net result is that if the file is
rewound at the beginning of each fit iteration, the ‘out’ file will only be
left with the results from the last set of calculated values returned from
PHREEQC. Otherwise the results from each iteration, i.e. all
PHREEQC calculations, will accumulate in this file.
The sixth parameter is a break variable that can be useful for separating
the plotting of a column of data from the out file into two or more sepa-
rate curves (as can be done with a blank line). Sometimes it is not possible
to introduce a blank line in the out file where it is needed. For example, if
more than one PHREEQC simulation is executed during a single
PhreePlot iteration (using the mainLoop) the selected output from the
two simulations is run together without a break. However, it is usually
possible to arrange for some variable to indicate when a break is needed.
This could be one of the loop variables or the simulation step number.
This sixth parameter is the name of the numeric column in the outfile
that is used to identify a break. This only applies to the file containing the
break variable, and only one such break variable can be specified. A break
is signalled when the direction of the ‘slope’ in this break variable changes.
The reference direction is determined from the first two rows of data and
is positive, negative or zero (signalled by an absolute difference of less than
1E-8). A break is made at every change of direction in slope with each
block of data being considered independently. Care should be taken to
avoid choosing a variable in which the difference between adjacent data
values is subject to significant numerical errors.
The data separator used for custom plots is always the separator set by the
second separator, the data output separator, since the file used for plotting
is automatically generated with this format. Care has to be taken to not
edit the plot data files in such a way as to bring this relationship out of
synchronization. If in doubt, regenerate the files, calculationMethod 1.
Examples 81, Using the ‘simulate’ calculationMethod, \demo\sis.ppi

dateDatabase
Value string
Description Gives the date of the specified database
Aliases databaseVersion
System default ‘’
Use Not set internally but usually set in the pp.set file. Only used for printing
168 PhreePlot Guide

to the log file and the info data block.

debug
Value -3, -2, -1, 0, 1, 2, 3, 99
Description Controls the amount of information sent to the log file and in some cases,
the action taken when an error is encountered.
Aliases
System default ‘0’
Use The higher the absolute value, increasingly more information is sent to
the log file. Negative values are the same as the positive values but also
mean that while the normal calculations will be undertaken no plot will
be produced.
There are many switches controlled by debug but the main actions are:
0 = provides the least logging and therefore gives the fastest execution
times. In this case, all PHREEQC input/output is via memory rather
than via disk files. This debug setting is the normal value for production
runs. With predominance plot calculations, the species returned in the
case of errors in speciation are all given the label ‘NA’.
1 = as above and also writes the values of all the tags substituted to the log
file and saves a copy of the speciation output from the last simulation in
the file phreeqc.out. With predominance plot calculations, any error in
speciation triggers an immediate halt to the calculations.
2 = as above and also accumulates the phreeqc.out data for each simula-
tion in the file phreeqcall.out which can get very large.
3 = as above and also echoes the PHREEQC input to the screen just
before it is executed. The PHREEQC output is also inserted into the log
file. This can produce a very large log file with slow execution times.
Debug also controls the file switches which determine the output from
PHREEQC. These are indicated in the table below.

Table 14.2. The effect that the debug setting has on the generation of PHREEQC output files.

PHREEQC output file debug keyword setting

<=0 1 2 3
Output (phreeqc.out) * FALSE TRUE TRUE TRUE
Error (phreeqc.err) FALSE TRUE TRUE TRUE
Log (phreeqc.log) FALSE TRUE TRUE TRUE
Selected output (e.g. selected.out) FALSE ** TRUE ** TRUE ** TRUE **

* with predominance plots, there is a special case when resolution = 1 in that this forces phreeqc.out to be writ-
ten whatever. This file will contain a list of all the possible mineral phases ready for pasting into the input file.
** can be overridden by the second parameter of the selectedOutputFile keyword.

The special value of ‘99’ does not run the input files but rather checks the
 Keywords 169

files for the use of any keyword aliases. If found these are listed along with
the respective main keywords. This function operates from the point of
the definition of debug onwards. Therefore to check all the files move
debug to the top of the pp.set file and give it a value of 99.

dependentVariableColumnObs
Value zero or a positive integer or column name (case sensitive)
Description Used in fitting to specify which column in the data file holds the depend-
ent variable.
Aliases dependentVariablePositionIn, dependentVariableColumnIn
System default “”

Use When fitting data to a PHREEQC model, there is always one dependent
variable containing the observations and this identifies where in the data
file it will be found. The columns are counted from left to right.
A value of zero should be used when a simulation is being carried out and
there is no dependent variable present. If a simulation is being carried out
and the data file contains a column with dependent variable data then
dependentVariableColumnObs should point to this column so that it can
be skipped when reading the file. This makes it possible to switch between
fit and simulate without changing the data file.
If dependent variable is to be read in, then dependentVariableColum-
nObs should be given the value zero.
Examples 79, Using the ‘simulate’ calculationMethod

dependentVariableColumnCalc
Value zero or a positive integer or column name (case sensitive)
Description Used in fitting to specify which column in the selected output file holds
the dependent variable.
Aliases dependentVariablePositionOut, dependentVariableColumnOut
System default “”

Use When fitting data to a PHREEQC model or when calculating the results
of a simulation, there is usually one dependent variable that must be cal-
culated and sent to the selected output file. dependentVariableColumn-
Calc identifies where in the selected output file this will be found. The
columns are counted from the left.
The column specified depends on the sequence of the PUNCH statements in
the USER_PUNCH keyword block and whether other selected output param-
eters have been selected. If in doubt, set debug 2 or 3, run and interrupt
after a few iterations. Then look at the selected output file to determine its
position or use the column name set in the USER_PUNCH block. This will
also be printed in the log file.
If no selected output is wanted, then dependentVariableColumnCalc
170 PhreePlot Guide

should be given the value zero.

Example 79, Using the ‘simulate’ calculationMethod

domain
Value logical
Description Determines if domain boundaries are plotted in a ‘ht1’ plot
Aliases plotDomain
System default F

Use The domain boundaries are the vectors from xmin to xmax, ymin to ymax
etc. This keyword is useful for deciding whether the domain boundaries
should be shown in ht1 plots (this is where one of the two species codes in
the vectors file is set to 99). With the native y-scale, the boundaries will
normally be overdrawn by the axis lines and so this setting has little visible
effect. However, this keyword setting is useful for suppressing the drawing
of these boundaries in pe-pH plots, for example. If you want to see the
boundary vectors, set domain to TRUE.
The same effect can be achieved in ‘grid’ plots by commenting out the
appropriate polygons in the polygon (‘pol’) file or by setting the species
number (sp column) for the field to less than or equal to zero and replot-
ting Alternatively, the polgons can be completely excluded from plotting
using an exclude list attached to pol.
Example 45

dominant
Value logical
Description Determines if the dominant or sub-dominant domain boundaries are
plotted in a predominance plot
Aliases
System default T

Use dominant set to TRUE plots the normal predominance or stability diagram
with the fields showing the dominant species.
dominant set to FALSE plots fields for the second most abundant (sub-
dominant) species instead.
Example 9

eps
Value logical [epstype]
Description Determines whether the plot output (if any) is converted to a file in the
Encapsulated PostScript (eps) format.
 Keywords 171

Aliases
System default F

Use Encapsulated Postscript (eps) files are Postscript files that are one page
long and have a bounding box included. They will only be produced for
the first page in multipage files (multipageFile).
eps files are useful for embedding in other documents as they are always
closely cropped.
An eps file can only be produced if Ghostscript/GSview is installed. If
the optional epstype parameter is set to ‘gs’ (or ‘GS’) then the Ghost-
script version of the eps file is produced using the epswrite device. Oth-
erwise PhreePlot only makes use of the Ghostscript epswrite device to
generate the required values of the bounding box and then adds these to
the native ps file. This version is normally smaller in file size and better in
quality.
An example of output in eps in native format is given below.

Fe-O2-H2O
(only HFO precipitates. Native y scale)

O2(g) > 0.21 atm

-10 Fe2(OH)2
Fe3+
4+
Fe

-30 Fe(OH)3(a)
log f O2(g)

-50

Fe2+

-70
0.1 mol/kgw NaCl
25oC
-
FeOH+ Fe(OH)3
H2(g) > 1 atm
-90
2 4 6 8 10 12
pH

Example 78

epsi
Value logical
Description Determines whether the plot output (if any) is converted to a file in the
Adobe Encapsulated PostScript Interchange (epsi) format.
Aliases
System default F

Use An epsi file can only be produced if Ghostscript/GSview is installed.

PhreePlot makes use of the Ghostscript ps2epsi utility to produce this
file.
The Adobe epsi format is a type of eps file which includes a coloured bit-
map preview image as well as the bounding box. It is therefore clipped at
the boundaries of the plot which makes it convenient for inserting into
documents. The plot is visible when inserted into software such as Micro-
172 PhreePlot Guide

soft Word. The preview is stored in a platform-independent format.

Unlike ps files, eps and epsi files can only be one page long. As a result,
multipage ps files produced by PhreePlot cannot be converted to epsi
files. If eps and multipageFile are set to TRUE and more than one page is
produced, no epsi file is produced.
The file size tends to be quite large but the quality tends to be better than
the eps format files produced by PhreePlot.
The file created is given the extension epsi.
An example of output in epsi format is given below.

Fe-O2-H2O
(only HFO precipitates. Native y scale)

O2(g) > 0.21 atm

-10 Fe2(OH)24+
Fe3+
Fe

-30 Fe(OH)3(a)
log f O2(g)

-50

Fe2+

-70
0.1 mol/kgw NaCl
25oC
-
FeOH+ Fe(OH)3
H2(g) > 1 atm
-90
2 4 6 8 10 12
pH

Example 78

extradat
Value filename [data separator]
Description Name of a data file which is added to the search path when looking for
variables used in a custom plot, or for tag definitions. Unlike for other
keywords, there can be multiple occurrences of the extradat keyword, each
adding a new file to the search path. An optional data separator can be
specified which will be used to parse the file.
Aliases extraOut
System default ““
Use By default, the data to be plotted are sought by checking the column
names in the header of the ‘out’ file. extradat allows the search path to be
extended to other files. The first occurrence of the variable in the search
path is used.
Columns can still be referred to by numbers in these extra files. The num-
bering continues consecutively based on the order of the files in the extra-
dat list.
These additional files should have the same format as an ‘out’ file, namely
a matrix layout with row 1 as column headers. These define the variable
 Keywords 173

names.
The header line and the remaining part of the file will be parsed, by
default, according to the separator(s) specified by the first entry in the
dataSeparators keyword. If the optional data separator string is specified
with the file name, then this is used. The options for this separator are
given in Section 5.2.4.
Each file used must contain a column of data with the same specified cus-
tomxColumn heading. Each y-column uses the x-column from the same
file so that the lengths of x and y arrays will always be the same.
The extradat files can also be used as a source of the post and loop col-
umns.
They can also be used to define tag expressions. The first header line is
used to generate the tag name and the second line defines the correspond-
ing tag values, either numeric or character. The extradat file can be gener-
ated from an earlier simulation.
Example

extraSymbolsLines
Value filename
Description An optional file containing details of additional symbols lines and to be
added to the plot.
Aliases symbols, extraSymbols
System default ““
Use The file is useful for adding extra symbols and lines to the plot. Normal
PhreePlot input file conventions apply. The file has the following struc-
ture:
plotnumber,x,y,[xlw,xcol,[isymb sizesymb,col,[sigfigs]]

The file must have at least 3 columns to plot a line and at least 6 columns
to plot a symbol. There is no header line. Use a comment line if necessary.
plotnumber is the plot number (starts at 1) for which the text applies.
This number is printed in the info at the bottom left-hand corner of each
plot. auto or ‘999’ means all plots. 0 means no plots.
x and y are the x- and y-coordinates for the points in plot coordinates (i.e.
as seen on the screen or page).
xlw is the line width in whatever length units are in force.
xcol is the colour of the line (including nd).
isymb, sizesymb and col refer to the symbol code number or name, the
symbol size and the symbol colour.
sigfigs is the number of significant figures used for floating point num-
bers (0 <= sigfigs <= 16) that are specified by a tag value. If sigfigs is a
negative number, then trailing zeros will also be removed.
If xlw is not specified, a default value is used: either the xlw setting of the
last xlw setting in the file or the lineWidth setting if no xlw has been
174 PhreePlot Guide

defined. A similar convention applies to the other parameters with line-

Color being the default xcol, symbol 1 (a filled circle) being the default
symbol and pointSize and pointColor being the default symbol size and
colour, respectively.
By selecting the appropriate size and colour of the symbols and lines it is
possible to have any combination of lines and symbols of any colour. The
line width and colour of a segment are taken from the endpoint of the
segment if specified rather than the beginning.
The joins between successive line segments are butt ends and not mitred
or square. If necessary, square joints for rectangles can be drawn by adjust-
ing the coordinates to allow for an extra half line width at each end.
The default is for the symbols and lines to be clipped to the plot area. If
the symbols and lines are to be plotted outside the plot area, put the string
‘noclip’ (case insensitive) on a separate line in the extraSymbolsLines file.
Clipping will be turned off from this point in the file forward.
A blank line in the file signifies a break in the line if a line is being drawn.
See Section 7.12 for more details and a display of the available symbols
and their symbol codes (isymb) and names.
Comments can be included in the file by using a # symbol.
See Section 2.3.4 for how to ensure that the file will be found.
Examples 65, 68

extraText
Value filename
Description An optional file containing details of additional text to be added to the
plot.
Aliases text
System default ““
Use The file is useful for adding extra text to the plot. Each logical line will
plot a piece of text. There is no limit to the number of lines. Normal
PhreePlot input file conventions apply. Comments can be included in
the file by using a # symbol.
See ‘Section 2.3.4’ for how to ensure that the file will be found.
Each line in the file has the following structure:
plotnumber,x,y,text[,size[,colour[,angle[,justify[,dig-
its[,font]]]]]

plotnumber is the plot number (starts at 1) for which the text applies. If
the info block is printed, the plot number will be printed at the begin-
ning. ‘auto’ means all plots. A value of 0, or any other out of range num-
ber, would suppress plotting.
The plotnumber increments by one for each plot produced. The outer
loop is the z loop and the inner (most rapidly changing) loop is the main
species loop. so in a run with m-elements and n-loop (z) values, the order
of plots will be:
 Keywords 175

z1-el1, z1-el2,...z1-elm, z2-el1, z2-el2, ...z2-elm, ...zn-

el1,zn-el2,...zn-elm.

x and y are the x- and y-coordinates for the text position in plotting coor-
dinates (i.e. as seen on the screen or page). x and y can take on special val-
ues: x = ‘auto’ (case insensitive) sets x just to the right of the x axis; y =
‘auto’ sets y to just below the key, 998 to the centre of the y axis and 997
to the minimum of the y axis. The text is horizontally justified according
to the justify parameter (0=left, default; 1=centre; 2=right justification)
and is always vertically aligned such that y refers to the position of the text
baseline. The default is therefore for x and y to refer to the bottom left of
the top line (if the text string contains any <br>’s). If x is set to ‘last’ (case
insensitive) then the last x value is used. If y is set to ‘last’ then y is set to
one line below the last line. Setting both x and y to ‘last’ means that the
text is continued below where it previously finished. This is useful to over-
come the 200 character limit to the length of a plotted text string.
text is the text string, enclosed in quotation marks if necessary. It can be
of any length but is trucated to a maximum length of 200 characters
including tags when actually plotted. It can include the normal text
enhancement tags for sub- and superscripts, line breaks and so on (Section
7.6.3). In addition, there are a number of special tags to load variable text
relating to the current simulation and plot. These tags are: <input:s1,s2>
to copy PHREEQC text from the input file; <legend> to move the legend
to a different place; <mainspecies> to plot the name of the main species
and <loop> to plot the value of loop variable. When these tags are used,
they may impose their own layout rules which override the given ones.
size is the size of the text in the current units.
color is the colour of the text.
angle is the angle of the text measured in degrees anti-clockwise. 0 is hor-
izontal and upright.
justify is the justification with respect to the x, y coordinates. 0 = left-
justified, 1 = centre, 2 = right-justified.
digits refers to the number of decimal places when substituting values
for numeric tags (1<=digits<=16). If digits is a negative number, then
trailing zeros will also be removed. Exponential format is used when
abs(value) is less than 0.001. This value is ignored for non-numeric text
strings.
font refers to the font (name or number) given by the font keyword, or
‘Helvetica’ if undefined.
The special plot tags which are evaluated after computations are <pxmin>,
<pxmax>, <pymin> and <pymax>. These contain the current values of
pxmin, pxmax etc and can be used to generalise plotting positions.
The size of the text, its colour, angle, justification and digits are optional
though the order must be maintained. For example, if the justify
parameter needs to be included, then all of the other preceding ones also
do.
Default values for the parameters are:
size = legendTextSize if >0 else labelSize if >0 else plotTitleSize/
2.
color = black
176 PhreePlot Guide

angle = 0 (horizontal and upright)

justify = 0 (=left)
digits = -3
Examples 3, 50, 54

fillColorDictionary
Value filename
Description A text file that is used to store a list of chemical species and their associ-
ated fill colours. This is used during the plotting of predominance and
mineral stability diagrams.
Aliases fillFile, FillDict
System default fillColor.dat
Use This is a file containing a list of species names and associated colours used
for the colouring of polygons.
If the specified file exists, it will be used and any additional species auto-
matically added. Colours can be changed by editing this file and replot-
ting.
If the specified file does not exist, it will be created in the input file direc-
tory with the filename given by the fillColorDictionary setting.
Example 38

FIT
Value none (section heading)
Description Optional section header
Aliases
System default
Use Can be used in the input file to highlight the beginning of FIT keywords.
There is no attribute associated with it.

fitAdjustableParameters
Value list of 0 or 1’s
Description Flags whether fit parameters are fixed (0) or adjustable (1)
Aliases
System default all 0
Use The list should be of length given by the number of fit parameters. Each
parameter has the vale of 0 or 1 signifying whether it is fixed or adjustable.
Examples 79, 82
 Keywords 177

fitConvergenceCriterion
Value positive number
Description Specifies the convergence criterion used during fitting.
Aliases fitConvergeCriterion
System default 1e-6
Use Controls when fitting is deemed to have converged.
Interpretation depends on the algorithm chosen (see Section 12.4.3 and
Table 12.1). For ‘nlls’, a ‘normal’ termination is triggered when the
WRSS is predicted to be less than fitConvergenceCriterion^2. Since the
WRSS is itself a summation this will depend on the number of observa-
tions.
For the ‘trust region’ methods, fitConvergenceCriterion defines the radius
of the final trust region, RHOEND. This should indicate the accuracy that is
required in the final values of the variables.
Small values will always provide more accurate fits but at a cost in terms of
the number of iterations required.
Normally if this setting is set at a very small value, the lack of a significant
change in parameter values will also trigger termination.
Examples 79, 82

fitFiniteDiffStepSize
Value positive number
Description Specifies the size of the interval that is used by the fitting routine to calcu-
late numerical derivatives by finite differences.
Aliases
System default 1e-3
Use The size should be sufficiently large to give rise to a significant change in
the response of the dependent variable since each of the n adjustable
parameters is adjusted by this amount during the first n+1 iterations.
However, if the setting is too large then the fitting may wander too far
from the optimal solution, and possibly into territory where PHREEQC
fails or where convergence of the fitting is not achieved.
Examples 79, 82

fitLogParameters
Value a list of 0 and 1’s
Description Specifies whether the fit parameters are to be log10 transformed (1) or not
178 PhreePlot Guide

(0) during fitting.

Aliases
System default all 0’s
Use The list should be the same length as indicated by the number of fit
parameters. Each parameter should have a 0 or 1 associated with it.
A value of 0 fits the parameter as given.
A value of 1 indicates that the parameter will be anti-logged (10^x) before
being substituted in the model so the parameter values specified by fitPa-
rameterValues should be log10 values.
This option can be useful to: (i) restrict a parameter to positive values; (ii)
fit parameters that can vary by orders of magnitude.
Although this option will not necessarily affect the final fit, it can affect it
because the rescaling will affect how the parameters are adjusted between
steps. For example, the fitFiniteDiffStepSize applies to the parameters in
the original log space as does the fitMaxStepSize.
Examples 79, 82

fitLowerParameterValues
Value list of numbers
Description Specifies the minimum allowable value of each adjustable parameter dur-
ing fitting.
Aliases
System default UNDEFINED UNDEFINED
Use Used for constrained optimization (fitMethod = ‘bobyqa’ only).
There should be one value for each parameter, corresponding one-to-one
with the other parameter lists such as that of fitParameterValues and
length defined by numberOfFitParameters. Values should be included for
‘fixed’ parameters to maintain the correspondence of the lists. These val-
ues will not be used.
A value of UNDEFINED (or -99999) means that no constraint will be applied
(it is automatically set to a huge negative value).

fitMaxIterations
Value positive integer
Description Controls the maximum number of iterations allowed during fitting
Aliases maxIterations
System default 500
Use An ‘iteration’ is one set of calculations of the residuals for all observations.
fitMaxIterations can be varied to either allow more time for convergence
or to deliberately force an early exit, e.g. after one iteration.
 Keywords 179

PhreePlot will attempt to exit gracefully after the maximum iterations

have been reached. This includes reporting the optimal parameter values
(so far) and their errors, and plotting the results. A low-pitched beep will
be given if the sound is on and an error message written to the log file and
screen, if active.
Examples 79, 82

fitMaxStepSize
Value positive number
Description During fitting, controls the maximum size of a step that can be taken.
Aliases
System default 100
Use The interpretation of this parameter depends on the fitMethod used (see
Table 12.1). With ‘nlls’, it controls the minimum size of the Marquardt
parameter (along with the fitConvergenceCriterion) and so influences the
size of the steps taken – the large its value, the larger the step sizes. With
the ‘trust region’ methods, it defines RHOBEG, the initial radius of the ‘trust
region’. This radius is subsequently reduced as the algorithm converges to
a solution. RHOBEG and so fitMaxStepSize should be about one tenth of the
expected greatest change to an adjustable parameter (hence the impor-
tance of some approximate scaling of the adjustable parameters).
This parameter should not be so small as to lead to an insignificant shift
in the objective function during fitting or so small as to make progress
painfully slow. Neither should it be so large that it allows the parameter
values to wander into ‘undesirable’ territory causing PHREEQC to fail to
converge.
Examples 79, 82

fitMethod
Value String: ‘nlls’, ‘newuoa’ or ‘bobyqa’ (case is significant)
Description Specifies the optimization (fitting) procedure used
Aliases
System default ‘nlls’
Use Three procedures are currently available: nlls, NEWUOA and BOBYQA, all by
M.J.D. Powell. These are all derivative-free methods. The first two are
unconstrained and the last is box-constrained. See “Fitting and simula-
tions”, p. 129.

fitnpt
Value integer
180 PhreePlot Guide

Description Specifies the number of conditions or interpolation points (NPT) used by

the NEWUOA and BOBYQA optimization algorithms.
Aliases
System default UNDEFINED

Use This value must be in the interval [n+2,(n+2)*(n+1)/2] where n = the

number of adjustable parameters. A larger value will provide more accu-
racy but at a cost.
If the value is set to UNDEFINED, then the chosen value will depend on the
value of n:
if n<6, then NPT = (n+2)*(n+1)/2 (the maximum)
else NPT = 2*n+1 (the recommended value for large problems).

fitParameterNames
Value list of character strings (up to 30 characters)
Description Specifies the names of each of the fit parameters
Aliases
System default “”
Use Specifies the names of the parameters (fixed or adjustable) used in the
model. These names are used to make tags which can be used within the
CHEMISTRY section (the PHREEQC code).

Examples 79, 82

fitParameterValues
Value list of numbers
Description Specifies the initial values of each of the fit parameters.
Aliases
System default missing value
Use A value must be assigned to each parameter. It will either be treated as
fixed or adjustable depending on the values of fitAdjustableParameters.
Examples 79, 82

fitUpperParameterValues
Value list of numbers
Description Specifies the maximum allowable value of each parameter during fitting.
Aliases
System default UNDEFINED UNDEFINED
Use Used for constrained optimization (fitMethod = ‘bobyqa’ only).
 Keywords 181

There should be one value for each parameter, corresponding one-to-one

with the other parameter lists such as that of fitParameterValues and
length defined by numberOfFitParameters. Values should be included for
‘fixed’ parameters to maintain the correspondence of the lists. These val-
ues wil not be used.
A value of UNDEFINED (or -99999) means that no constraint will be applied
(it is automatically set to a huge positive value).

fitWeightingMethod
Value 0, 1 or 2
Description Controls how the residuals are weighted in the objective function used by
the fitting algorithms.
Aliases weighting
System default 0
Use The objective function to be minimized, s, is given by:

ˆf ) ] 2
s = ∑ [ w i × ( f i – i
i

where fi = observed value for observation i, ˆf i = fitted value for observa-

tion i, wi = weight for observation i. Note wi is inside the square.
The fitWeightingMethod setting can take the following values:
0 = unit weighting (all wi =1)

1 = relative error weighting (wi =1/ ˆf i )

2 = weights (wi) read from the data file

Ideally, the weights should be equal to the standard deviation of each
observation. This can be estimated from repeat measurements. It may
vary with the magnitude of fi.
If fitWeightingMethod = 2 is used, then the column containing the
weights is given by the weightColumn setting.
Examples 79, 82

font
Value string
Description The name or number of the font family or font to use (up to 40 charac-
ters), case insensitive
Aliases
System default Helvetica
182 PhreePlot Guide

Use Name or number of the font family (or font) to use. Only one font family
is normally used for all text in a plot.
Fonts are numbered consecutively based on their order of appearance in
PhreePlot’s default font table, or in the fonts.dat file, if present, scan-
ning across and down the table, i.e. 1 = Helvetica, 2 = Helvetica-Oblique,
3 = Helvetica-Bold, ..., 44 = Dingbats. Font numbers outside this range
lead to a fatal error.
The specified font is checked against the current fonts table first checking
for the name of a font family, and if this is not found, checking for a spe-
cific font. If a font family is found, the ‘regular’ face of this font is used as
the base font (i.e. plain text). If the name of a specific font face is found,
this will be used as the base font. If this font is not a plain text font, then
unexpected results may occur, e.g. using <i> ... </i> around an italic
base font will make the text normal.
The following eight font families are the default in PhreePlot: Helvetica,
Helvetica-Narrow, Bookman, Avantgarde, Times, Palatino, NewCentury-
Schoolbook and Courier. The Chancery (only the italic font), Symbol and
Dingbats fonts are also defined. The Symbol font contains Greek charac-
ters and some common plotting symbols. The Ghostscript distribution
normally contains all these fonts.
The principal text fonts look like this:

Helvetica: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Helvetica-Narrow: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Bookman: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Avantgarde: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Times: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Palatino: The quick brown fox jumps over a lazy dog 0123456789 italic bold
NewCenturySchoolbook: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Courier: The quick brown fox jumps over a lazy dog 0123456789 italic bold
Chancery: The quick brown fox jumps over a lazy dog 0123456789 italic bold

Dingbats are mostly iconic symbols and are only approximately centered.
The above font families and their various faces make up the 35 standard
Postscript fonts.
How software reacts to these fonts depends on whether the output device
recognises the specified fonts either in terms of having the font of the
exact same name available or being able to provide an appropriate substi-
tution font (there is no standardization of font names and so similar fonts
can have more, or less, different names).
The fonts.dat file contains the names of the 11 font families and the 35
fonts defined in PhreePlot. These are the names of the fonts actually
written to the Postscript file. This file can be edited to give the required
font names for the device of interest based on the available fonts
The fonts.dat file has a standard format and consists of eleven rows of
data, each line containing the family name of the font (as used by font)
and then the font names for the regular font, the italic (or oblique) font,
the bold font and the bold, italic font. A blank string (“”) is a placeholder
that indicates that no such font is defined. This file is read in free format.
 Keywords 183

The fonts.dat file that comes with the PhreePlot distribution also shows
the default font family and font names that will be used by PhreePlot
when a valid fonts.dat file is not be found.
It is in principle possible to use different font families for plain text, italic,
bold and italic-bold by editing the fonts.dat file.
The search path for the font file is the current directory followed by the
system directory.
If font is not one of the specified font families, then a close match is
sought – if the given font includes a font family name within it, this this
font family is chosen. Also if font contains any of the words below, the
corresponding font family is selected:
arial Helvetica font family

roman Times font family

Text tags provide a way of specifying changes to the appearance of indi-
vidual characters (bold, italic) and groups of characters. They can also
specify Greek characters (these are converted to the Symbol font).
Example 65

info
Value Cohort colour for the info data block
Description Sets the colour of the ‘info’ block printed at the bottom left-hand corner
of the plot.
Aliases infoColor
System default nd [nd]

Use One or two colours must be specified: the first is for the whole ‘info’
block. The second is for the file path of the input file and is only used
when the first colour is ‘nd’ or blank. If the second colour is omitted or
the first colour is not ‘nd’ or blank, then the first colour is used for both.
The info block contains summary information about the figure. The
information given varies slightly depending on the type of calculation. An
example is shown below for a ‘ht1’ calculation:

1 Main species = Fe Temperature = 25.0 oC

Resolution = 250 Speciation calculations = 2544; Time = 0.251 min
C:\Program Files\PhreePlot\0.01\demo\Fe\hfo_Fe1.ps
PhreePlot version = Pre-release 0.01 (27 Jun 2008)
Speciation program = PHREEQC (4 April 2007)
Database = wateq4f.dat (8 Sept 2006)
12:25:47 27 June 2008

The printing of the ‘info’ block can be turned off by setting the first
colour to ‘nd’ or blank and giving no second colour.
‘nd’ as the first parameter also turns off the printing of any “<input:” text
specified in an extraText file (“<input:” enables a copy of all or some of
the input file to be printed to the right of the plot). ‘nd’ overrides any
input settings in this file and so can be used to produce ‘clean’ plots with-
out editing the individual extraText files. This can be set in the over-
ride.set file to ensure that this text is missing from all plot files whatever
the input file states.
184 PhreePlot Guide

The size of the info text is automatically determined from the labelSize
setting. If labelSize>=0.1 inch (or the equivalent on other scales) then
the text size will be 0.6 x labelSize. If it is less than 0.1, then it is fixed
at 0.05 inch.
Example 38

initialValue
Value number
Description Value given to all undefined numeric tags
Aliases
System default UNDEFINED (-99999)

Use A numeric tag should normally be defined in terms of constants and other
tag values that have already been defined, i.e. that precede the given tag in
terms of evaluation order.
However sometimes this is not appropriate and it is necessary to set an
initial value, e.g.
<n> = “<n> + 1”

jobTitle
Value string
Description Description of job
Aliases job
System default ““
Use Free text used to describe the job (up to 200 characters long). This string
is printed in the log file so can be used for comments about the job.

jpg
Value logical
Description Determines whether the plot output (if any) is converted to a file in the
jpg format.
Aliases
System default F

Use A jpg file can only be produced if Ghostscript/GSview is installed.

PhreePlot makes use of the Ghostscript jpeg device to produce this file.
The resolution is fixed at 300 dpi.
An example of output in jpg format is given below (the resolution seen
here has been reduced during conversion to pdf – the quality of the origi-
nal jpg was better than this).
 Keywords 185

Example 78

labelColor
Value Cohort colour
Description Sets the colour of labels in plots
Aliases labCol
System default black
Use Specify the colour to be used for labels. Use ‘nd’ (not drawn) if no labels
are wanted. This also controls the default color of the text used by the
<input...> tag.

Example 50

labelEffort
Value 0, 1, 2 or 3
Description Controls the amount of effort used to place the labels for lines plotted
with custom and fit plots so as to minimize the amount of overlapping
and other aspects of poor label placement.
Aliases effort
System default 1
Use Controls the amount of effort (and time) used to optimize the placement
of labels for lines in custom and fit plots.
0 No optimization; labels are placed half-way along the x axis
1 Basic
2 Moderate
3 High
The time taken varies greatly with the number of labels, their size and the
186 PhreePlot Guide

degree of overlap found in the default placement (near the centre point of
the curve). In order to reduce overlap, reduce the label size, change the
axis scale, or reduce the number of curves plotted.
The Esc key can be used to interrupt the labelling. If the plotting is
stopped at this point, the best placement found so far is used.
The labels can be repositioned manually by editing the line colour dic-
tionary and using calculationMethod 2. The line colour dictionary con-
tains the position of the centre of each label and the line colour.
useLineColorDictionary should be set to 2 to give the dictionary priority
over automatic labelling.
A value of 0 rarely produces worthwhile output.
The labels can be turned off altogether by setting labelColor to ‘nd’ or
labelSize to be 0.
Example 44

labelFile
Value logical
Description Now redundant.
Aliases
System default <inputfile_ending>.lab T

Use Originally a switch that controlled the creation and deletion of the labels
(*.lab) file that is used by ht1. The labels file contains the name, position
and angle of all of the labels used to label the fields in predominance and
contour plots.
Since this file is essential for the operation of ‘ht1’ and ‘contour’, the
labels file is automatically created and retained with these plots.

labels
Value list of strings (up to 30 characters each).
Description Can be used to override the default names used for labelling the curves on
custom and fit plots
Aliases loopNames, loopName, loopNumberNames
System default ‘’ (use default names)
Use A list of names to be associated with each set of data plotted in a multi-
loop or multi-curve custom plot. The order in which the curves are plot-
ted is in the order shown in the legend. This order is the order that the
data have been written to the appropriate plot data file(s) (the ‘out’ file or
‘pts’ file depending on the type of plot, and any extradat files) and will
run sequentially through each z-loop value for each of the variables to be
plotted.
A single curve is designated by a contiguous set of records in a single col-
 Keywords 187

umn in the data file being read. Multiple curves are designated by having
one or more blank lines in a column of data or by the data being derived
from several columns, or both of these.
Blank lines are normally inserted in ‘out’ files at each change in the value
of the z-loop variable. The third and fourth dataSeparators settings con-
trol the insertion of line breaks in generated data files during looping.
If the data are derived from fit data files, then blank rows are copied across
from the input files to the output files preserving the column breaks.
Names are picked off the labels list as needed, one by one, for each data-
set. All curves for a given variable and a given z-loop variable will be plot-
ted first, then curves with different values of the z-loop variable will be
plotted. The labels list is recycled if short.
If the labels keyword is set blank, then the column headers of the data
being read will be used to generate default label names. If more than one
subset of data is being plotted, then a subset identified will be appended
to the label name. This takes the form columnHeader_subsetIdentifier. The
subset identifier is the subset number. This is often the z-loop number.
Labels set with the labels keyword take precedence over those set by speci-
fying an alphanumeric variable as the first column of a loopFile. These
label names will always be used as is – they are never appended with the
subset number, e.g. “_1” and so on.
The loop names can be used to label each iteration of the loop variable, or
in the case of a data file, each separate subset of data as indicated by a
break (blank line) in the plot data file (the ‘out’ and ‘extradat’ files for
custom plots and the ‘pts’ file for fit plots).
The convertLabels setting controls whether there is an attempt to convert
the loop names to PHREEQC formulae for the label plotting, or not.
Examples 60, 83

labelSize
Value non-negative number
Description Controls the size of the labels used in the plots and the size of the info
text.
Aliases labelHt, label
System default 2
Use Controls the size of the labels used in the ht1, fit and custom plots. The
size of the text is also controlled by the units being used (default is mm).
The size of the info text is also automatically set to 0.5 x labelSize.
Example 39, 66, 73
188 PhreePlot Guide

legendTitle
Value non-negative number
Description One way of specifying the legend title in custom and grid plots.
Aliases keyTitle, key
System default “”
Use Adds a title to the legend in custom plots. Maximum length is 200 char-
acters. This can contain text enhancements such as <b>...</b> and line
breaks (<br>).
The legend text can also be added with the <legend> tag in the extraText
file. If present, this will override any legendTitle setting.
By default, the legend is placed to the right of the plot. If you want to
place it somewhere else, including inside the plot, use the <legend>
approach.
Example 72

legendTextSize
Value non-negative number
Description Determines the size of the legend text in custom and grid plots.
Aliases keyTextSize, keyText
System default 2
Use Enables the size of the legend text to be changed. The units are defined by
the units keyword. The default units are mm. If set to zero, no legend is
drawn.
Example 73

lineColor, lineColor2y
Value list of one or more Cohort colours
Description Controls the colours used for lines in ht1, custom and fit plots for the
main y and 2y axes.
Aliases col
System default black

Use In ht1 plots, lineColor(1) controls the colour of the line separating the
fields. In custom and fit plots, the effect of lineColor depends on the use-
LineColorDictionary setting. If useLineColorDictionary is 0, then line-
Color sets the colours for the first n lines plotted where n = length of the
list colours set by lineColor. Additional line colours are selected sequen-
tially from the PhreePlot colour sequence (Line colours and auto line col-
 Keywords 189

ouring). In effect, lineColor promotes the given colours up the colour

sequence list.
If useLineColorDictionary is 1 or 2 and the species being plotted is speci-
fied in the line colour dictionary, then the dictionary colour is used in
preference. If the species is not in the dictionary then the colour is chosen
from the PhreePlot line colour sequence.
Colours should be chosen from the colour palette.
Example 72

lineColorDictionary
Value filename
Description Specifies the filename for the line colour dictionary.
Aliases linefile, lineDict
System default lineColor.dat

Use If the filename is blank or the specified file cannot be found, then the sys-
tem default filename is used.
The line colour dictionary is used to record and, if specified, control the
colour of points and lines in plots. It also stores the coordinates of any line
labels.
The specified file is read and updated if found; otherwise it is created.
Whether the colours and coordinates in the dictionary are used is deter-
mined by the useLineColorDictionary setting (see Section 7.9).
Example 72

lines, lines2y
Value character list
Description Specifies which columns should be plotted as lines for datasets plotted on
the main y (left) and 2y (right) axes.
Aliases plotLines; plotLines2y, lines2y
System default “”

Use The list should contain the column names or column numbers of col-
umns for which the lines are to be plotted. The names are case dependent.
The names or numbers refer to the column of the file being used for plot-
ting, e.g. the ‘out’ file for custom plots or the ‘pts’ file for fit plots.
The names can contain tags, most usefully character tags.
The order of plotting the lines is determined by the column order in the
‘out’ file.
Additional files can be added to the search path using the extradat key-
word. These files must be in tabular format with a single header row
defining the column names. One of these columns must be the same as
the customXcolumn defined elsewhere.
190 PhreePlot Guide

Additional lines can be added to predominance diagram plots as well as

custom plots (including fit and species plots). No legend is produced for
lines added to predominance plots.
The 2y axis is the right-hand y axis which can have a different scale from
the left-hand or main y axis.
Examples 54, 64

lineWidth, lineWidth2y
Value list of numbers
Description Controls the line widths in plots for datasets plotted on the main y (left)
and 2y (right) axes.
Aliases width, lw
System default 0.3
Use This keyword sets all line widths in the plot to the given values. The list
controls the line widths for successive curves in a custom-based plot. The
position of the entry used is based on the corresponding position of the
variable name in the lines keyword. The list is recycled as necessary. The
actual line width drawn is determined by the units in operation. The sys-
tem default units are mm.
A value of 0.0 means that no line will be drawn.
A negative value draws a dashed line of width ABS(lineWidth) with 10
dashes per inch by default.
The number of dashes per inch to use for a dashed line is set by dashesPer-
Inch.
The width of lines separating fields in predominance diagrams is 0.66
times lineWidth(1).
Examples 60, 54, 23

log
Value logical
Description Determines whether a log file is produced.
Aliases logFile
System default T

Use The log file is a text file containing feedback about the run and is espe-
cially useful for debugging. The amount of information sent to the log file
is controlled by the debug parameter. This increases as debug is changed
from -1 or 0, 1, 2 and 3. It can be a very large file when debug = 3.
The default value is TRUE and so some output may be sent to the log file
before the redefined value comes into effect. Set the log setting in the
pp.set file to avoid this early output being sent to the log file.
 Keywords 191

logDepVariable
Value 0 or 1 or -1
Description During fitting, determines whether the calculated values of the dependent
variable returned by PHREEQC should be log-transformed or un-log-
transformed (exponentiated) before being used or not
Aliases
System default 0
Use If logDepVariable is set to 1, then the calculated value of the dependent
variable returned by PHREEQC is log-transformed before being used in
the objective function. This option avoids having to store log-transformed
values of the dependent in the data file. Similarly if logDepVariable is -1,
the value of the dependent variable returned by PHREEQC is un-log-
transformed, i.e. 10^x.
If logDepVariable iz 0, the calculated value is used without transforma-
tion.
Note that the observed values of the dependent variable must be on the
same scale.
log transforming the dependent variable has approximately the same
effect as using a relative error weighting.
It is possible to return log values of the dependent variable by using the
log10 function in the USER_PUNCH data block. In this case, logDep-
Variable should usually be set to zero since no need further transformation
need be applied.
There are a number of examples of logDepVariable in the
\demo\iso\isologx.ppi series of files.

logVariableIn
Value A list of 0, 1, -1, -, X (or x)
Description Determines the format by which to read columns of data from the data
files used by fit and simulate, and whether to transform these data or not.
Aliases
System default ‘’ (empty string)
Use The default, an empty list, means that the format is determined by the
first row of data in the data file. This classifies each column as either
numeric or character depending on the data found. If anything other than
this is wanted, for example forcing a numeric value to be read as a charac-
ter or transforming the data, or skipping columns, then the format must
be specified explicitly.
Format options for each column are:
0=numeric data
192 PhreePlot Guide

1=numeric and positive data; apply a log10 transformation

-1=numeric data, apply an anti-log10 (10**x) transformation
X=character data (X is not case sensitive)
-=skip column
The default empty list means that each column of data is read according
to the formats derived from the first row of data. Reading in character
data with a numeric format will produce a fatal error (the first 10 such
errors will be reported).
If a list of formats is given this overrides the format derived from the first
data row. If this list contains n items and is shorter than the number of
columns found then only the first n columns will be read. If n is greater
than the number of columns found, then only the first n items in the for-
mat list will be used.
The above list will also determine which columns of data are transferred
to the ‘out’ and ‘pts’ files.
If requested, the data are transformed immediately on reading in. No
knowledge of this is used further on in the processing.
If the dependent variable is to be read in from the file (i.e. observations
are present), then its column should be given by the dependentVaria-
bleColumnObs setting and the logDepVariable should be used to indicate
whether this variable needs to be log-transformed or not. However, the
appropriate logVariableIn setting should also be set correctly. Care should
be taken to ensure that both the observations and the calculated values of
the dependent variable are on the same scale. It is not possible for
PhreePlot to check this at run time.
In a simulation (calculationType simulate), the dependent variable may or
may not be present in the fit data file. If it is absent, then the logDepVari-
able will determine whether the calculated value is transformed or not.
There are a number of examples of different logVariableIn settings in the
\demo\iso\isologx.ppi series of files.

loopFile
Value valid file path to an existing loop file [data separator]
Description Optional name of a file containing a list of loop values.
Aliases
System default ‘’ (empty string)
Use If loopFile is defined and present then loop values are read from this file
and the data are associated with loop tags, <loop1>, <loop2>, ... for values
in column 1, 2, ... This will take preference over the single <loop> tag as
generated from loopMin, loopMax and loopInt.
If a header line is present in the file, this is used to name the tags instead
of <loop1> etc. These column header names must be unique – they
should not clash with the names of other tags.
The header line (if present) and the remaining part of the file will be
 Keywords 193

parsed, by default, according to the separator(s) specified by the first entry

in the dataSeparators keyword. If the optional data separator string is
specified with the loop file name, then this is used. The options for this
separator are given in Section 5.2.4.
Columns can consist of numeric or character data. The type of column is
determined from the type of data found in the first non-header row.
If the first two rows of the first column contains character variables (up to
30 characters), the rows are assumed to contain row names in the first col-
umn. These are used for annotating the plot. However, if label names
have been assigned by the labels keyword then these are used in prece-
dence over any defined by a loop file.
If numeric values like 1 2 3... are wanted as loop names, put them in
parentheses, “1” “2” “3” ..., to force them to be read as character strings.
The key feature of a loop file is that it ‘loops’. A new row of loop values
will be associated with the appropriate tags on each iteration of the z- loop
variable. This includes row names (potential labels) if present.
loopLogVar operates as normal but it operates over all of the numeric
variables.
The normal search path is used for locating the specified loop file.
If loopFile is defined but the specified file is not found, then this is treated
as a fatal error.
Normal conventions for reading input files apply to the loop file. This
includes not using # or ; in label names. Comment lines can be included
and will be skipped.
The values of the loop variables read from the loop file will be written to
the log file and can be checked there.
Example 64

loopIndexStartNumber
Value positive integer
Description The initial z-loop number used to define a filename
Aliases zstart, loopStartNumber
System default 1
Use By default this 1. This specifies the starting number used in the file exten-
sion when a series of files is output. This enables single plots to be created
with any number, thus enabling the replotting of just one file when many
were produced in a series (not tested).

loopInt
Value non-negative number
Description The value of the z-loop interval (>=0) used to calculate the value of the z-
194 PhreePlot Guide

loop variable, <loop>.

Aliases zint
System default UNDEFINED

Use If loopInt > 0, then the value of the <loop> variable is varied from loop-
Min to loopMax in steps of loopInt. For example, given the following
loop parameters (loopMin, loopMax, loopInt, the <loop> values gener-
ated will be:
262,loop values generated: 2, 4, 6
263,loop values generated : 2, 5
If loopInt=0, then <loop> is set to loopMin and only one iteration is
made. loopMax is therefore not be used and should not be defined other-
wise a fatal error will be signalled (unless loopMin = loopMax).
loopInt<0 is incorrect if loopMax>loopMin but will be corrected using:
LOOPINT = sign(LOOPINT,LOOPMAX-LOOPMIN).

The above assumes that loopLogVar is 0 (linear scale). If loopLogVar=1

then the loop variable will be set to 10^<loop>. <logloop> always contains
the current value of log10<loop>.
If <loop> is used in an input file and if loopint (or loopMin or loopMax)
is undefined, then an error is reported.
Example 60

loopLogVar
Value 0 or 1
Description Determines whether the z-loop variable and z-loop interval are based on a
log10 scale or not
Aliases zvar, looplog
System default 0
Use Either has a value of 0 or 1.
0 = a linear scale; 1 = log10 scale.
The following examples show how loopLogVar controls the z-loop vari-
able, <loop>, given the values of loopMin, loopMax, loopInt shown
below:
loopLogVar = 0
0, 10, 2 will generate values of 0, 2, 4, 6, 8, 10
loopLogVar = 1
-2, 2, 1 will generate values of 0.01, 0.1, 1, 10, 100
Example 60
 Keywords 195

loopMax
Value number
Description Maximum value of the z-loop variable
Aliases zmax
System default not defined
Use Determines the finishing value of the z-loop variable. loopMax must be
defined if loopInt is non-zero.
Example 60

loopMin
Value number
Description Minimum value of the z-loop variable
Aliases zmin
System default not defined
Use Determines the starting value of the z-loop variable.
Example 60

mainLoop
Value integer or ‘auto’ or ‘last’ [logical]
Description Defines the division, if any, between ‘pre-loop’ PHREEQC simulations
and ‘main loop’ simulations and, optionally, the oneSimulationAtaTime
switch which determines whether the main loop simulations should all be
executed in one run or as individual simulations.
Aliases loopSimulationStartNumber, simulationStartNumber, simulationStart,
start
System default ‘auto’ [FALSE]
Use mainLoop defines the division between ‘pre-loop’ simulations and ‘main
loop’ simulations. The number given defines the first of the main loop
PHREEQC simulations numbered from the top of the appropriate block
of simulations downwards. Where a data file is used to specify a separate
block of simulations for each line of data as in fitting, mainLoop is always
counted relative to the top of the block not the absolute simulation
number, i.e. 1 will always point to the first simulation.
‘auto’ is set by PhreePlot: normally it refers to the last simulation but for
calculationType’s ‘fit’ and ‘simulate’ it is set to 1. ‘last’ refers to the last
simulation.
The optional second parameter is the oneSimulationAtaTime switch
196 PhreePlot Guide

which if set to TRUE will run each main loop simulation separately. The
default is FALSE which means that all the main loop simulations are run in
a single call to PHREEQC. Running each simulation separately enables
tags to be defined and used between simulations.
The mainLoop simulation and all subsequent simulations will be ‘looped’
over by the x- and y-axis loops as controlled by the <x_axis> and
<y_axis> tags. These main loop iterations are intended to be run fast,
with minimum overheads, trying to avoid the repeating of unnecessary
calculations. This distinction also affects what output is stored and in par-
ticular eliminates the accumulation of unwanted output data in the ‘out’
file. The ‘out’ file has to be well-formed to go into the plotting or fitting
phases successfully.
With the second oneSimulationAtaTime parameter set to FALSE, as by
default, all simulations within the ‘main loop’, i.e. those simulations num-
bered mainLoop and greater, will be executed in one call to PHREEQC,
or one ‘run’. Tags are only substituted before entering this block of code
and only updated after exiting it. They cannot be updated between these
simulations since execution is not returned from PHREEQC to
PhreePlot until all the simulations sent for the run have been executed. If
tag values need to be passed from one simulation to another, set oneSimu-
lationAtaTime to TRUE.
Output is normally only sent to the ‘out’ file at the end of a run. The
number of lines sent for each simulation is controlled by selectedOutput-
Lines. When more than one simulation is executed in one run, the total
number of lines output is the sum of the expected lines from each simula-
tion.
‘Pre-loop’ PHREEQC simulations are processed one-by-one with tags
generated between simulations but no output is sent to the ‘out’ file.
‘Pre-loop’ simulations are intended to be one-off simulations in which
solutions, equilibrium phases, surfaces, reactions etc. are defined and ini-
tialised while the main loop is where the PhreePlot-style iterations are
done.
This strategy gives the main loop advantages in terms of speed in that the
overheads are reduced when as many PHREEQC simulations are exe-
cuted in one PHREEQC run as possible and when calculations that do
not need to be repeated are not. The price paid is that the tags are not
updated between the individual simulations making up the main loop
(just before and after) and so cannot be used to pass newly-acquired out-
put data from one simulation to a later one. This type of calculation
should be done wherever possible in the pre-loop section.
If there are no tags in an input file, the mainLoop should make no differ-
ence to the results although in principle the calculations should be some-
what faster with a setting of 1.
There is only one set of SELECTED_OUTPUT from each PHREEQC run.
This will accumulate output from all the simulations that occur from its
point of definition forward. It is however still necessary to specify one set
of selected output lines per simulation in the selectedOutputLines. The
appropriate lines will be picked off at the end of each run. The lines spec-
ified should refer to the line numbers in the accumulated
SELECTED_OUTPUT ‘file’ not the line numbers for the individual simula-
tions – a trial run should quickly establish the lines required.
 Keywords 197

With fits and simulations, the mainLoop setting may be set individually
for the blocks of simulations associated with each data point. This over-
rides any setting with mainLoop although the value of oneSimulationAta-
Time is still inherited from mainLoop. Here, mainLoop refers to the
position relative to the start of the specified block of simulations not to
the position in the input file.

mainLoopColumn
Value integer, string
Description Defines the column number or name in the ‘fit’ data file which contains
the mainLoop number
Aliases
System default 0
Use Defines the column number or name in the ‘fit’ data file which contains
the mainLoop number. The string should refer to a column header in the
‘fit’ data file.

mainspecies
Value list of strings (maximum length 32 characters each)
Description Determines the ‘main species’ used in the calculation of predominance
and species diagrams
Aliases main
System default ‘’ (empty string)
Use This setting controls the outermost (slowest moving) loop in a predomi-
nance diagram (ht1 and grid plots). The setting specifies a list of main
‘species’, e.g. “Fe” “Mn” “Zn” (quotes are optional). It also controls the
‘element’ analysed in a species plot.
The ‘main species’ is the species for which predominance is to be calcu-
lated, e.g. Fe will given a diagram containing only Fe species while Cu
would give a diagram with only Cu species. Actually the ‘main species’ is
not a normal chemical species but a component or ‘master species’ in
PHREEQC terminology. It should not include secondary master species
such as Fe(+2) or Cu(+2).
At least one main species must be defined to create a predominance dia-
gram. A list of up to 50 main species can be entered. They will be looped
in the order given. Separate by spaces or commas.
A special main species is ‘minerals’ which acts as a ‘superspecies’ - actually
more like a ‘do nothing’ species. If used in conjunction with an appropri-
ate script, e.g. minstab1.inc, it can be used to produce a ‘minerals only’
or mineral stability plot. This will plot the most abundant mineral no
matter what elements it contains.
Examples1, 3, 53
198 PhreePlot Guide

minimumAreaForLabeling
Value non-negative number
Description Either defines the minimum percentage of the plot area that is necessary
for a field to be labelled with ht1 or defines the minimum y-value for a
line to be plotted in a species or custom plot.
Aliases minArea, minimumArea
System default 0.1

Use Sometimes some very small fields are found by the hunt and track algo-
rithm either because they actually exist or because they are produced as a
result of the numerical error inherent in the numerical method employed
in calculating the speciation. This setting can be used to prevent them
being labelled (but not from being plotted).
In species plots, there may be many minor species present. These would
obscure the plot so this setting can be used to ignore all species for which
the maximum value (% species or log concentration) is less than the set
value. Neither the line nor the label are plotted in such cases.
Example 23

minimumYValueForPlotting
Value number [number]
Description Defines the minimum y-value for a dataset to be plotted in a species or
custom plot. The optional second parameter applies the same test to data-
sets plotting according to the 2y axis.
Aliases minY
System default UNDEFINED UNDEFINED

Use Points or lines datasets will only be plotted if the maximum value in the
dataset is equal to or greater than this value. Each dataset is initially
clipped to the plotting domain insofar as it is known at the time.
A ‘dataset’ in this context is a whole column of data as read in from a data
file. This dataset may contain line breaks (internally represented by
–99998) and so may consist of more than one line (plotted curve). It is not
possible to apply this criterion to each separate line in a dataset.
This setting can be used to exclude the plotting of datasets where all the
data are close to zero, for example.
A setting of UNDEFINED means that no test is applied.
Example 74
 Keywords 199

missingValue
Value integer
Description A value used in data files to signify a missing data value
Aliases miss
System default -99999

Use Missing values are substituted as place markers in some data output files
where a proper value is not available, e.g. because the speciation has failed
so no valid concentration can be written.
PhreePlot also uses an UNDEFINED value in other places when it has to
print a value without having a value. This is currently set as -99999 and
cannot be changed.

multipageFile
Value logical
Description Where more than one plot is produced, determines whether a separate
plot file is produced for each file or a single, multipage plot file is pro-
duced.
Aliases multipage
System default F

Use Looping through multiple ‘main species’ produces multiple plots which
can either be stored separately one file per plot or as a single multiple page
file.
This is also true for multiple predominance plots produced with the
<loop> variable. However, for custom plots the <loop> variable is used to
produce multiple curves per plot and so the <loop> variable does not trig-
ger the production of a multipage file.
Such files can be viewed with Ghostcript and Adobe Illustrator and and
can be translated to multiple page pdf files. These are very compact and
can be viewed with Adobe Reader.
Set to TRUE for a multipage file. It is often best to produce single page files
initially as these will be stored as soon as they are produced in a run and
can be viewed separately. It is also only possible to follow progress with a
tracking plot if this setting is set to FALSE. Once the set of plots is com-
plete, a multipage file can be generated quickly by setting calculation-
Method 2 and multipageFile to TRUE and replotting.
This setting applies to ps, pdf and png files. It may not be possible to
view multipage png (mng) files as most png viewers, including GhostView,
only render the first page. epsi files are intrinsically single page.
For an example of the making of a multipage file see \demo\multipage-
file\multipagefile.ppi.
200 PhreePlot Guide

nameSpeciationProgram
Value string
Description The name of the speciation program being used
Aliases program
System default PHREEQC

Use Since the speciation program used is currently fixed, the default value
should not be changed. It is only used in the log file as a matter of record.

numberOfFitParameters
Value non-negative integer
Description Defines the number of parameters specified in a ‘fit’ calculation (the
number can also be implicitly defined by the length of the various fit
parameter lists).
Aliases
System default 0 (but set to 2 in the distributed pp.set file)
Use This specifies the number of parameters, each with its own tag, that will
be defined and which may be used in the Chemistry section of the input
file. These parameters may be fixed or adjustable.
If this setting is used, it should precede all of the other fit parameter lists
in the input file since if it has a positive value, it will reset the values of all
the parameter lists to their system defaults. There are six such lists (all
must have a length of numberOfFitParameters): fitParameterNames, fit-
LogParameters, fitAdjustableParameters, fitParameterValues, fitLowerPa-
rameterValues, and fitUpperParameterValues.
Example 79

numericTags
Value A list of tag definitions, all on one logical line
Description Numeric tags can be used to substitute numeric values within the
PHREEQC part of the input file, and used in plots.
Aliases numberOfNumericTags
System default ‘’
Use The general form for the definition of a tag with the name ‘mytag’, say, is:
<mytag> = “tag expression”

where the spaces surrounding the ‘=’ are optional. The tag expression can
itself contain numeric tags providing that they have already been defined.
Tags are defined and evaluated in the order of their definitions, effectively
 Keywords 201

‘top down’. Numeric tag names are case sensitive.

Any number of tag definitions can be included on a line. While the tags
and their definitions must all be on a single logical line, it improves legi-
bility if they are split, one definition per physical line, e.g.
numericTags <tag1> = 20 \
<tag2> = “2*<tag1>”

The tag expression must be one ‘word’ so if it contains spaces, it should be

embedded in quotes. Otherwise the quotes are optional. The tag expres-
sions can contain the mathematical functions, abs, exp, log10, log, sqrt,
sinh, cosh, tanh, sin, cos, tan, asin, acos, atan, rand and nrand.

For historic reasons, the list of tag definitions may optionally be preceded
by an integer giving the number of tag definitions to follow. This option
will be removed at some date.
Example 62

omitAccumulate
Value list of strings, each up to 32 characters long
Description Filters out lines of PHREEQC input if it contains any of the strings (case
sensitive).
Aliases
System default “”

Use If any of the strings defined with this keyword is found in the PHREEQC
input, then the entire logical line is omitted from input to the
PHREEQC processor.
Trailing blanks are not significant. Leading blanks are.
This can be used to omit lines containing the word UNDEFINED which
could have been introduced when a tag to be substituted is UNDEFINED.

onePass
Value logical
Description Used by ‘fit’ and ‘simulate’ to determine if the all the values of the
dependent variable are calculated in one pass through the PHREEQC
code or not.
Aliases
System default F

Use This keyword only has any effect during ‘simulate’ or ‘fit’ calculations.
This switch affects how the simulations are run and how the selected out-
put is read.
If onePass is TRUE, the PHREEQC code should deliver at least n lines of
selected output (excluding the header) where n = number of data points
(the last n lines will be picked).
202 PhreePlot Guide

If onePass is FALSE, the PHREEQC code should deliver just 1 line of

selected output (excluding the header). The code block is iterated n times
to produce the required data.
onePass might be appropriate because internal PHREEQC looping pro-
duces multi-line selected output (e.g. the KINETICS, REACTION or TRANS-
PORT keyword data blocks) or because the PhreePlot CHEMISTRY
section contains multiple simulations that between them produce the
required number of lines of output.
The actual lines picked from the selected output produced by each simu-
lation can be specified with the selectedOutputLines keyword. ‘auto’ will
attempt to pick the correct number but if this does not work it should be
entered explicitly.
Fitting is usually considerably faster with the onePass TRUE setting since
this requires fewer calls to PHREEQC and less overheads. However, this
is at the expense of a more complex set up. The input file pre-processor
may reduce the effort in setting up repetitive parts of the input file.
Also since tag values can only be updated when execution is returned from
PHREEQC, simulations containing tags that need to be updated every
iteration must be included in the main loop simulations. It may therefore
be necessary to use mainLoop (or mainLoopColumn) to ensure that the
required simulations are included in the main loop and so updated on
every iteration.
It is also possible to force PhreePlot to run each simulation within a
block of simulations used to calculate a data point separately, even with
the onePass set to TRUE. This is done by setting the optional oneSimula-
tionAtATime switch of mainLoop to TRUE.

Example 80

out
Value logical
Description Determines if the out output file is created
Aliases outputFile, output, outFile
System default T

Use This file contains a summary of the output sent by the selected output file
in a tabular form. Its form depends on the type of plot made.
Output is only sent to the out file for main loop simulations (not pre-loop
simulations) and only one line of output is sent per main loop simulation,
i.e. if there is more than one main loop simulation and these are executed
oneSimulationAtaTime (see mainLoop), output is only sent from the last
simulation.
A new file is started whenever the main loop value (iz) is 1. ‘species’ cal-
culations also begin a new file on every iteration of the z-loop.
With ht1 plots, it first prints five integers, the counts for the five blocks of
variables output from the selected output and sent by ‘ht1.inc’ or equiva-
lent. Then follows the species–value pairs in the number and order speci-
 Keywords 203

fied by the counts. There is no header line.

With custom and fit plots, the file contains the accumulation of the
selected ‘selected output’ with the headings that were sent to the selected
output. A blank line separates custom datasets with different loop values.
Other methods are available for inserting blank lines (see dataSeparators).
The selection of ‘selected output’ lines is controlled by the type of calcula-
tion and the selectedOutputLines keyword.
Example

pageOrientation
Value 0 or 1
Description Determines the page orientation of plot files.
Aliases
System default 0

Use 0 signifies portrait mode while 1 signifies landscape mode.

Example

paperSize
Value One of the standard paper sizes given by the codes below (case not signifi-
cant).
Description Determines the paper size written to the Postscript file.
Aliases paper
System default a4

Use Sets the paper size. The following paper sizes are available:

Table 14.3. Standard paper sizes

Code Dimension (width x height)

11x17 11 x 17 inch
A0 841 x 1189 mm
A1 594 x 841 mm
A2 420 x 594 mm
A3 297 x 420 mm
A4 210 x 297 mm
A5 148 x 210 mm
B4 250 x 353 mm
B5 176 x 250 mm
Ledger 17 x 11 inch
Letter 8.5 x 11 inch
Legal 8.5 x 14 inch
Note 8.5 x 11 inch
204 PhreePlot Guide

Example

pdf
Value logical
Description Determines whether the plot output (if any) is converted to a file in the
Adobe Portable Document (pdf ) format.
Aliases pdfFile
System default F

Use A pdf file can only be produced if Ghostscript/GSview is installed.

PhreePlot makes use of the Ghostscript ps2pdf14 utility to produce this
file. pdf files are compact graphics files that can be viewed using GSview,
Adobe Reader and other software. The file created is given the extension
pdf. It is also possible to create a pdf file from GSView directly using its
Convert facility. An example of pdf output is given below.

Fe-O2-H2O
(only HFO precipitates. Native y scale)

O2(g) > 0.21 atm

-10 Fe2(OH)2
Fe3+
4+
Fe

-30 Fe(OH)3(a)
log f O2(g)

-50

Fe2+

-70
0.1 mol/kgw NaCl
25oC
-
FeOH+ Fe(OH)3
H2(g) > 1 atm
-90
2 4 6 8 10 12
pH

Example 78

pdfMaker
Value filename
Description filename of executable file for converting the ps file to a pdf file
Aliases
System default “C:\Program Files (x86)\gs\gs8.64\lib\ps2pdf14.bat”

Use If Ghostscript is installed, this should give the path to the Ghostcript
batch file, ps2pdf14.bat. This is used to do the ps to pdf file conversion.
The full file path should be given, as above or with the shortened 8.3
filename, e.g. "C:\PROGRA~1\gs\gsx.xx\lib\ps2pdf14.bat" where x.xx
refers to the current version. If there are spaces in the path, then it must
be embedded in quotes.
 Keywords 205

The setting also tells PhreePlot the path to the Ghostscript executable,
gswin**c.exe, which is used for the non-pdf plot file conversions.

If the setting is empty, “”, then no attempt is made to find the required
Ghostcript batch file. If the setting is not empty, and the specified file
found, then this is used for further processing. If the specified file cannot
be found then a further search is made (see the Installation notes).
If the required ps2pdf.bat file is then found, the pdfMaker setting in the
pp.set file should be updated with this path.

PhreePlotVersion
Value string
Description PhreePlot version
Aliases
System default current version
Use Not currently used.

PLOT
Value none (section heading)
Description Optional section heading for input file
Aliases
System default
Use None other than to offer chance to structure file

plotFactor
Value non-negative number
Description Scaling factor for all plot dimensions
Aliases factor
System default 1.0
Use All plot dimensions (titles, axis lengths, line widths, symbol sizes etc) but
excluding xoffset and yoffset are scaled by this factor. This scaling is done
just before plotting and so if more than one plotFactor has been specified,
only the latest is used. A value of zero will prevent any plotting.
Example 70
206 PhreePlot Guide

plotFrequency
Value positive integer
Description Frequency of automatically writing the plot.ps file during computations
Aliases plotFreq, plotx
System default 1000000
Use Determines the frequency with which the plot.ps file is automatically
written during computations. The file is written every plotFrequency’th
point calculated. This file can be used to view the status of the ht1 and
grid calculations. A large number means very infrequently; the default
effectively means ‘never’. This file can also be forced to be written using
the interrupt key (Esc).

plotTitle
Value string (maximum 200 characters)
Description Title at the top of a plot
Aliases title
System default ‘’ (empty string)
Use Gives the title string placed at the top of the plot. This can contain text
tags such as ^.... Its placement is fixed. Use extraText for other
placements.
A blank string means that an auto-generated title will be used. Turn-off by
setting plotTitleColor to ‘nd’, plotTitleSize to 0 or setting the title to a
non-printing character such as ‘¬’.
Example 54

plotTitleColor
Value Cohort colour
Description Colour of the plot title
Aliases titleColor
System default blue4

Use Colour of the plot title.

plotTitleSize
Value A non-negative number
 Keywords 207

Description Size of the plot title

Aliases titleSize
System default 3

Use Uses the length units in force at the time of plotting

png
Value logical
Description Make a png (portable network graphics) copy of the plot
Aliases pngFile
System default F

Use Uses Ghostscript to convert from the ps file. The Ghostscript path for
the conversion script is taken from pdfMaker and assumes that the default
Ghostscript directory structure given by the installation of a recent
release Ghostscript is unchanged.
An example of output in png format is given below.

Example 78

pointColor, pointColor2y
Value list of colours
Description Symbol colours used for plotting points
Aliases symbolColor
System default red4

Use These define the colour of any points that are to be plotted. Whether the
colour changes for later datasets depends on the changeColor setting
(q.v.). Point colours can be changed by editing the line colour dictionary
208 PhreePlot Guide

and forcing the dictionary to be used by setting useLineColorDictionary

to a value of 1 or more. The line colour dictionary is automatically writ-
ten and updated as plotting takes place so it may be necessary to generate
the plot first then edit the line colour dictionary and replot.
The colours specified by pointColor are promoted to be the first colours
used. If further colours are needed, these are taken successively from the
auto-generated list of colours (see Section 7.9).
If useLineColorDictionary is set to a value of 0, the line colour dictionary
is not used and the colour sequence for points is either taken from the
pointColor setting, or if that list is exhausted, automatically set by
PhreePlot.

points, points2y
Value character list
Description Specifies which columns should be plotted as points on the main y and 2y
axes.
Aliases plotPoints, plotPoints2y, 2ypoints
System default ‘’

Use The list should contain the column names or column numbers of col-
umns for which the points are to be plotted. The names are case depend-
ent. The names or numbers refer to the column of the file being used for
plotting, e.g. the ‘out’ file for custom plots or the ‘pts’ file for fit plots.
The names can contain tags, most usefully character tags.
Additional files can be added to the search path using the extradat key-
word. These files must be in tabular format with a single header row
defining the column names. One of these columns must be the same as
the customXcolumn defined elsewhere.
Points can be added to predominance diagram plots as well as custom
plots (including fit and species plots).
The 2y axis is the right-hand y axis which can have a different scale from
the left-hand or main y axis.
Examples 54, 79

pointsSameColor
Value logical
Description Determines if the colour used for points is the same as that use for the
corresponding lines
Aliases symbolSameColor, sameColor
System default F

Use When both lines and points are drawn for a particular column/curve, set-
ting this to TRUE will force the lines and points for a particular column to
 Keywords 209

use the same colour. This will be the colour of the lines irrespective of the
pointColor setting (see Section 7.9).
This only applies to datasets plotted on the main y axis.

pointSize, pointSize2y
Value list of non-negative numbers
Description Sets the size of points (symbols) for each dataset plotted on the main y
(left) and 2y (right) axes for custom plots
Aliases symbolSize, symbol
System default 2

Use Symbols are used to plot points in custom plots (including fit plots) and
their size, and that of all other symbols, are controlled by the pointSize
setting. The actual size of a plotted symbol depends on the length units in
force at plotting time and the way that the symbol fills the allotted symbol
space.
The rimFactor and rimColor settings, and their 2y counterparts, control
the widths and colours of the rim around each filled circle, respectively.
The rim factors are specified as a fraction of the corresponding symbol
sizes.
Example 54

pointType, pointType2y
Value list of symbol numbers or names
Description Used to define the symbols used in custom plots
Aliases symbolSize, symbol
System default 2

Use Symbols are used to plot points in custom plots (including fit plots) and
the symbols used are controlled by the pointType (main y axis) and
pointType2y (2y axis) settings.
The y and 2y lists are maintained and used separately.
Symbols can either be specified by their symbol numbers (see Figure 7.4)
or by their symbol names (Appendix 3).
Example

pol
Value logical [exclude list]
Description Determines if a polygon file is created during predominance plot calcula-
tions, and whether any polygons should be excluded from plotting in pre-
210 PhreePlot Guide

dominance diagrams.
Aliases polygonFile, polygon
System default T

Use Controls the creation and deletion of the polygon (*.pol) file that is used
by ht1 and grid. The polygon file contains the x, y coordinates of field
boundaries used to plot the predominance fields. The header also con-
tains the resolution used to generate the file (e.g. x500) and the pe for each
point.
Since this file is essential for the operation of ht1 and grid, the polygon
file is automatically created and saved for these plots. This means that the
setting of this logical switch is ignored.
The ‘exclude list’ is a list of polygon/species names (from the list of names
appearing in the labels file) that are not to be plotted. An alternative
approach to excluding a polygon from plotting is to set the species num-
bers for the excluded polygons to 0 or less in the polygon file.
The labelling of a polygon (but not the plotting of the polygon) can also
be suppressed by using the minimumAreaForLabeling criterion or more
generally by setting the species number to a negative value in the plot file
and replotting without recalculating the labels (calculationMethod = 2).

post
Value list of strings (up to 30 characters each) or a single column name from one
of the plotting data files.
If two strings are present and the second one is an integer, then this inte-
ger is interpreted as the number of significant figures to use when printing
floating point numbers (see below).
Description Can be used to ‘post’ a numeric value or character string next to each plot-
ted point in custom and fit plots.
Aliases postName, postNames
System default ““ (use default names)
Use This only applies to variables plotted using the points or point2y key-
words.
The behaviour of this setting is somewhat similar to the labels setting but
it offers the possibility of posting values to individual points (symbols) in
custom and fit plots, most commonly using another variable column to
provide the posted character string.
Posted values will always be written above and to the right of (‘NE’) of the
associated symbol.
If there is either one post name, or two with the second being an integer,
then the first name is tested to see if it corresponds with a column name
in one of the plot data files (the ‘out’ or ‘pts’ file or an extradat file). This
test is case-sensitive.
If it does, then posted values for each point are taken from the specified
column and the corresponding row of the identified file. Both posted vari-
able and data variable must come from the same file, i.e. be of similar
 Keywords 211

length. If the posted variable exists in more than one file, as would the x
column, only the points from the post file are used.
The post column pointed to can be numeric or character.
If more than one post name is specified, then these are assumed to be a list
of character strings to post against each point. These are recycled as neces-
sary starting with the first string specified above always starting the cycle
for each new dataset.
The interpretation of post strings as PHREEQC formulae is automati-
cally turned off.
If multiple points data sets are defined from the same file as the posted
column, each set is posted with the same list of posted values.
Floating point values are reduced to 3 significant figures unless the second
(and last) item in the post list is an integer with an absolute value between
1 and 7 whereupon that value is used for the number of significant fig-
ures, e.g. if the mass value is 12.764897
post mass will print ‘12.8’
post mass 2will print ‘13’
Trailing zeros are removed to save space, even if deemed ‘significant’ by
the above definition if the number of significant figures specified above is
negative, i.e. between -1 and -7.
‘Large’ and ‘small’ numbers will be printed in E format. In this case, the
second item absolute value if present will control the number of figures
after the decimal point. For example, 1.2345678E-09 will print ‘1.235E-9’
for a second item value of 3.
The size of the posted text is given by postSize. The colour of the text is
always black.
Posted text is always printed last and so will overprint any other text.

postSize
Value number
Description The size of the posted text in the units of length in force at the time of
reading.
Aliases
System default 2
Use Used with post to post text alongside plotted symbols. The colour of the
text is always black and the text is always placed to the top right of the
symbol.

ppa
Value logical
212 PhreePlot Guide

Description
Aliases ppaFile
System default F

Use Determines if an archive file is written or not.

An archive file is a copy of the input file with all the settings included (as
in the pp.set file). The values written are those in force at the end of the
computations and so include all the changes made by the input and over-
ride files.
Comments are removed.
Useful for debugging as there are no hidden settings.

pplog
Value logical
Description Controls whether a line is written to the pp.log file or not
Aliases pplogFile
System default T

Use The pp.log file keeps a summary of each PhreePlot run. It is especially
useful for seeing the results of multiple runs executed from a batch file,
such as demo.bat.
This setting should be set to FALSE if several instances of PhreePlot are
run simultaneously to minimise interfering interactions.

printScreenFrequency
Value integer
Description Frequency of automatically writing a summary of the output to the screen
during computations
Aliases screenx
System default 1
Use The absolute value of printScreenFrequency determines the frequency
with which summary results are automatically written to the screen dur-
ing computations. Output is written every abs(printScreenFre-
quency)’th point calculated. This output can be used to view the status of
the ht1 and grid calculations, and to monitor progress during fitting. A
large number means very infrequently.
A value of 0 during fitting means that the value is temporarily set to the
number of adjustable parameters. This is because a new direction is only
chosen every n’th function evaluation, where n is the number of adjustable
parameters.
A negative value turns off the continual updating of the pp.log file that
occurs on every iteration of a run.
 Keywords 213

ps
Value logical
Description Turns on or off the output to the Postscript (ps) file
Aliases psFile
System default T

Use This is the native format for graphical output in PhreePlot.

Since several other file formats are derived from the ps file, this file will be
produced as an intermediate file if necessary even when this parameter is
set to F(ALSE). In such cases, the file is deleted at the end of the run.
If set to T(RUE), a copy of the latest ps file is also stored as plot.ps.
If ps is set to F(ALSE), then not only will the ps file not be produced but if
a ps file of the same name is present, then this will be deleted. The same is
true of the plot.ps file.

pts
Value logical
Description Make (and deletes) a points file
Aliases pointsFile
System default F

Use The input value is overridden where a points file is necessary, e.g. in fit,
species and ht1 plots.

pxdec
Value integer
Description Determines the number of digits after the decimal point for x-axis num-
bers
Aliases xaxisDecimalPts
System default auto

Use Can be used to override the value automatically assigned. A value of -1

indicates will write a number without a decimal point (i.e. an integer).
‘auto’ supplies a default value.
214 PhreePlot Guide

pxmajor
Value number
Description Plot x-axis interval between axis numbers
Aliases pxint, xaxisint
System default auto

Use Defines the separation of the major tick (labelled) interval in plot units on
the x axis. ‘auto’ supplies a default value.
Example 63

pxmax
Value number
Description Plot x-axis maximum value
Aliases xaxismax
System default auto

Use Defines the maximum value of the x axis. ‘auto’ supplies a default value.
Example 63

pxmin
Value number
Description Plot x axis minimum value
Aliases xaxismin
System default auto

Use Defines the minimum value of the x axis. ‘auto’ supplies a default value.
The x axis is always started at pxmin so it is best to make it a round
number.
Example 63

pxminor
Value non-negative number
Description Plot x-axis interval between minor (unlabelled) ticks
Aliases xaxisMinorTickInt
System default auto

Use Defines the axis interval of the minor ticks on the x axis. Choosing half
 Keywords 215

the major tick interval is often sensible. ‘auto’ supplies a default value.
A value of 0 turns off the minor x-ticks.
Example 74

pydec, p2ydec
Value positive integer
Description Determines the number of digits after the decimal point for y(2y) axis
numbers
Aliases yaxisDecimalPts, 2yaxisDecimalPts
System default auto

Use Can be used to override the value automatically assigned. A value of -1

indicates will write a number without a decimal point (i.e. an integer).
‘auto’ supplies a default value.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
and lines2y.
Example 82

pymajor, p2ymajor
Value number
Description Plot y(2y)-axis interval between axis numbers
Aliases pyint, yaxisInt, p2yInt, 2yaxisInt
System default auto

Use Defines the separation of the major tick (labelled) interval in plot units on
the y axis. ‘auto’ supplies a default value.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
and lines2y.

pymax, p2ymax
Value number
Description Plot y(2y)-axis maximum value
Aliases yaxisMax, 2yaxisMax
System default auto

Use Defines the maximum value of the y axis. ‘auto’ supplies a default value.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
216 PhreePlot Guide

and lines2y.

pymin, p2ymin
Value number
Description Plot y(2y)-axis minimum value
Aliases yaxisMin, 2yaxisMin
System default auto

Use Defines the minimum value of the y axis. ‘auto’ supplies a default value.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
and lines2y.
The y(2y)-axis is always started at p(2)ymin so it is best to make it a round
number.

pyminor, p2yminor
Value non-negative number
Description Plot y(2y)-axis interval between minor (unlabelled) ticks
Aliases yaxisMinorInt, 2yaxisMinorInt
System default auto
Use Defines the axis interval of the minor ticks of the y axis. Choosing half the
major tick interval is often reasonable. ‘auto’ supplies a default value.
A value of 0 turns off the minor y(2y)-ticks.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
and lines2y.

resolution
Value non-negative integer
Description Controls the x- and y axis step size used by the hunt and track algorithm
and ‘custom’ calculations. When ‘custom’ calculations are made and no
<x_axis> or <y_axis> tags are defined, the resolution defines the number
of iterations of the CHEMISTRY section that are made.
Aliases res, nres
System default 1
Use The given x- and y-ranges are divided into a rectangular grid with resolu-
tion-1 cells along each axis, i.e. resolution points or nodes on each axis.
ht1 uses a fixed step size (one grid cell) and so resolution is one of the pri-
mary determinants which determine the time to make a plot. The speed
 Keywords 217

of the chemical calculations and the length of the boundaries are the oth-
ers.
The larger the specified resolution, the more detailed the resolution of
boundaries but the slower the calculations. Normally a resolution in the
range 50-500 is reasonable. Although high resolutions produce more cal-
culation points than lower resolutions, the number of points retained
depends on the degree of simplification subsequently used and so will not
necessarily lead to significantly larger file sizes.
Resolutions of less than 10 are not allowed by the hunt and track routine.
Low resolutions may not be able to resolve certain junctions, particularly
close to the domain edges, and may lead to a failure of the ht1 algorithm
to close all the polygons. If this happens, it is not possible to colour the
polygons appropriately and so a black and white plot is produced from
the vector file. Try increasing the resolution or altering the domain
boundaries (xmin, xmax, ymin or ymax) to achieve polygon closure.
resolution also controls the number of iterations used in custom calcula-
tions and plots. If <x_axis> or <y_axis> are present in an input file, then
resolution + 1 iterations are made with the following values:
xint = (xmax-xmin)/resolution

for (i in 0:resolution) {xi = xmin + i*xint}

where xint is the x interval and xi is the value of x taken on successive
iterations.
e.g. xmin=0, xmax=10, resolution=5 will give values of xi= 0, 2, 4, 6, 8,
10.
If <x_axis> or <y_axis> are not defined, then the interval is set to 0.
Some PHREEQC keywords generate their own iterations internally and
so produce a SELECTED_OUTPUT file with multiple lines of data suitable for
plotting, e.g. the REACTION keyword can do this.
If a full listing of the normal PHREEQC output file is wanted, set
debug=2 or 3 which will then create the phreeqcall.out file which con-
tains the output from all of the iterations.
resolution = 1 will give a single iteration and automatically forces output
of the phreeqc.out file. This is useful for checking PHREEQC output.
With predominance plot calculations, this will also produce a list of all
possible mineral phases in the phreeqc.out file ready for pasting into the
CHEMISTRY section of an input file. A resolution of 1 should normally be
used when simple looping calculations are being undertaken and no plot
is produced, i.e. when the <loop> tag has been used but the <x_axis> and
<y_axis> tags have not and when plotFactor has been set to 0.

resolution = 0 will cause an immediate exit from the calculations and will
produce no plot and no error messages.
Examples 3, 54

restartColorSequence
Value logical
218 PhreePlot Guide

Description When there are multiple plots per run, determines whether the line color
sequence in effect for auto-generated colours is restarted from the begin-
ning or not for each plot.
Aliases
System default FALSE

Use If the colours for auto-generated colours symbols and lines in multiple
plots need to follow the same sequence, then setting this keyword to TRUE
ensures that the colour sequence is started at the beginning for each plot.
If the various plots need lines and symbols to have different colours
between plots, then this should be set to FALSE. This will ensure the con-
tinuation of the two sequences from where they left off in the previous
plot.
A more precise determination of colours can be made by editing the line
colour dictionary and setting useLineColorDictionary to 1 or 2.

rewriteInputFile
Value logical
Description Determines whether the input file is reformatted and rewritten back to
the original file.
Aliases rewrite
System default F

Use A reformatted input file is normally written to the end of the log file and
can be cut and pasted from there. However, if this setting is set to TRUE
and calculationMethod equals 1 and there is a successful exit to the calcu-
lations, then the original input file will be overwritten. Providing this file
does not already exist, the original ppi file will be copied to a file with
same filename but with the .bak extension. In any case, it is definitely wise
to store your own independent backup of the original input file.
All comments and blank lines will be removed in the reformatted file.
Continuation lines will be concatenated and lines containing more than
one logical line expanded.
This option can be used with updateFitParameters to write updated fit
parameters back to the input file.
Also the ppa keyword toggles the writing of an expanded input file to
disc.

rimColor
Value list of Cohort colors
Description Determines the rim colours for point (filled circles) symbols
Aliases
System default nd
 Keywords 219

Use Each set of points (or ‘curve’) defined by points can have its own symbol
with a separate rim. The colour of the rim is defined by this list and the
line width of the rim is given by rimFactor.
A rim is only drawn if the symbol itself is drawn.

rimFactor
Value list of non-negative numbers, normally less than one (fractional sizes)
Description Determines the line width used for rim colours with point (filled circle)
symbols
Aliases
System default 0.08

Use Each set of points (or ‘curve’) defined by points can have its own symbol.
If these are filled circles, they can have a separate rim. The line widths of
the rims are defined by this list. The factor given represents the width as a
fraction of the symbol size with the rim centered on the circumference of
the original filled circle. Normally a value of 0.05 to 0.1 is about right.
If the list of rim sizes is shorter than required, the list is recycled.
The rim colour is defined by rimColor. Open circles can be drawn by
making the point colour white and the rim colour some other colour.
A rim is only drawn if the symbol itself is drawn.

screen
Value logical [non-negative integer]
Description Turns on or off all screen output (except fatal errors during reading input
files). The optional second argument is the close down time in seconds.
Aliases
System default T 5

Use Set to FALSE to prevent any screen output. The system default is TRUE and
so any output that is sent before a FALSE has been set will normally be
output. This can be disabled by setting the screen setting in pp.set to
FALSE.

The optional integer value gives the close down time. This is the number
of seconds counted down at the end of a run that has ‘failed’ for some rea-
son. It allows the screen output to be inspected or paused before disap-
pearing from sight. If the Esc key is pressed during closedown, then
PhreePlot will stop immediately.
The width of the console window is best set to at least 85 characters wide.
This way the scrolling output during a predominance plot will not wrap.
The defaults can be set by right-clicking on the top frame of the console
window and changing the Defaults.
220 PhreePlot Guide

selectedOutputFile
Value filename [logical]
Description Gives the name of the selected output file, and optionally a logical ‘force’
switch which forces the selected output file to be written to a physical file
irrespective of any debug setting.
Aliases
System default “selected.out”

Use This should be set to the name of the selected output file set with the
SELECTED_OUTPUT -file identifier in the CHEMISTRY section of the input
file. This is not critical to the running of PhreePlot but ensures that the
selected output file is deleted from the working directory before executing
a PHREEQC simulation run. This provides better diagnostics when
PHREEQC fails to generate a new selected output file.
The second option setting is the optional ‘force’ switch. If present, this
overrides the default selected output file switch controlled by the debug
setting. If the force switch is set to TRUE, the selected output file(s) will be
written to disk irrespective of the debug setting (normally it is only writ-
ten for debug > 0). It can also be used to turn off the selected output file
for debug > 0.

selectedOutputLines
Value list of non-negative integers or auto’s
Description This list defines the number of lines to be read from the selected output
and sent to the ‘out’ file for each PHREEQC simulation.
Aliases selectedOutput
System default auto
Use The list of integers should have the same length as the number of
PHREEQC simulations and should consist of the number of lines of
selected output to pick from each simulation. If the list is shorter than the
number of simulations, the list is recycled from the beginning. The num-
bers are then picked off the full list, one per PHREEQC simulation.
The lines to be read are counted backwards from the last line in the
selected output so a value of 1 will pick off the last line and send it to the
‘out’ file. Any preceding lines are ignored.
These settings do not affect the number of lines actually written to the
selected output file.
Setting a value to zero will turn off picking any selected output for that
simulation. If a value exceeds the number of lines produced, it will auto-
matically pick up all the lines produced.
If these data are part of the main loop calculations , then these data will be
sent to the ‘out’ file, potentially for plotting or use in fitting. No data
 Keywords 221

from the pre-loop calculations is sent.

Where more than one main loop simulation is fed to PHREEQC to be
run in a single call to PHREEQC, the number of selected output lines
picked off is given by the sum of the selectedOutputLines setting for the
simulations involved. PhreePlot does not know which simulation pro-
duced the output (though exporting the SIM_NO will give the relative posi-
tion in the block of simulations submitted).
Sometimes more than one line must be sent to the ‘out’ file and selected-
OutputLines enables this to be specified. The most important
PHREEQC keywords generating such multiline files are REACTION,
KINETICS and TRANSPORT.

The value of ‘auto’ will ensure that all lines found in the selected output
are sent.
The ‘auto’ option setting is also set internally for ‘simulate’ and ‘fit’ cal-
culations with the onePass option. When onePass is FALSE, only one value
must be exported per full iteration of the PHREEQC code; when onePass is
TRUE, at least n lines must be sent where n is the number of observations.
In this case, if there are more lines than needed only the last n are used. It
is up to the selectedOutputLines settings to ensure that this is the case.
‘ht’ and ‘grid’ calculations automatically set selectedOutputLines to a
value of 1 as this is what is expected by PhreePlot.
It is often easier to make sure that no redundant output is sent to the
selected output in the first place. This can be done by using
PRINT
-selected_output FALSE

for all simulations where no output is wanted and then by turning on the
output for simulations where it is wanted
PRINT
-selected_output TRUE

simplify
Value non-negative number
Description Controls the degree of simplification of the field boundaries in predomi-
nance diagrams
Aliases simplificationFactor, simplification
System default 1

Use This is mainly used for ht1 and contour plots. In grid plots, the only line
simplification that is done is the removal of ‘in line’ or redundant vertices.
The grid stepping is still retained. Line simplification is applied for all
simplify’s greater than 0.0.
For ht1 diagrams and contour plots, a value of simplify of 1 often pro-
vides reasonable plots. Larger numbers, say 3, introduce more simplifica-
tion and may be useful for removing low-angled, jagged boundaries.
Smaller values, say 0.1, retain many more points. Somewhere in the range
of 0.1 to 10 is usually reasonable.
Simplification can significantly reduce the size of output files (data and
222 PhreePlot Guide

plot files) and can produce more visually pleasing plots by eliminating
unwanted noise. However, for the most accurate plots, it is usually better
to reduce the ‘steppiness’ by increasing the resolution of the calculations
rather than by increasing the simplification factor.
The retained points can be viewed by making the track symbol viewable
(trackSymbolSize >0 and trackSymbolColor not ‘nd’). Setting simplify to
0.0 will show the result without any line simplification.

skip
Value non-negative integer
Description Keep every skip’th data record when reading in data for fitting or simula-
tion.
Aliases numberOfSkipRecords
System default 1
Use Used to select a small subset of the data for more rapid fitting. Useful
when exploring the initial estimates of the adjustable parameters. The
records to be skipped are calculated from mod(ndatar-nstart,skip)/=0
where ndatar is the number of data records read, nstart is the sequential
number of the first record read (normally 1) of the data block and skip is
the defined parameter.
New data blocks begin after a blank line so the first record after a break is
normally included providing the number of records in the block is equal
to or greater than skip.
Only valid data lines are counted for skipping, i.e. blank and comment
lines are filtered out first before counting for skip. To keep all data use
skip 1. To keep roughly 1 in 10 use skip 10, etc.

A skip value of zero is treated as 1.

SPECIATION
Value none (section heading)
Description Section heading only
Aliases
System default
Use Optional; does nothing.

speciationProgram
Value string
Description The name of the speciation program to use
 Keywords 223

Aliases program
System default PHREEQC

Use The name of the speciation program to use for speciation calculations.
Currently only PHREEQC.

speciationProgramVersion
Value string
Description Specifies the current version of the speciation program being used
Aliases dateProgram
System default ‘’
Use None specified by the program but usually given in pp.set. Only used for
printing in log file and info data block.

startTemperature
Value positive number
Description The starting ‘temperature’ for the simulated annealing option for fitting
(not implemented)
Aliases
System default 100
Use This is no longer used.

tickColor
Value Cohort colour
Description Specifies the colour of the major and minor axis ticks
Aliases tickCol
System default black

Use The minor and major axis ticks always have the same colour as specified
by this keyword. The ticks can also be used to produce a grid over the
whole plot area (see tickSize below).
Example 38

tickSize
Value number
Description Sets the length of the major ticks
224 PhreePlot Guide

Aliases tick
System default 2
Use Sets the length of the major ticks (the ones by the numbers).
Positive tick sizes means the ticks are plotted inside the axis; negative sizes
outside. Zero turns off the ticks. Minor ticks are 2/3 the length of major
ticks and are by default always placed half way between the major ticks.
If the tick size is positive (= ‘inside’ ticks) and equal to 0.5 or more the
length of the shorter of the x and y axis lengths (xaxisLength, yaxisLength,
respectively), then the ticks are extended (or shortened) to become a full
grid. The line thickness of the major grid lines is given by axisLineWidth
and the thickness of the minor grid lines is 0.4 x axisLineWidth.
If the length of an outside tick exceeds the length of the corresponding
axis (x-axis length for y tick and vice versa), it is shortened to that axis
length.
Example 38

trackSymbolColor
Value Cohort colour
Description The colour of the tracking symbol used in the intermediate plot.ps file
produced when a plot is created by a manual or automatic interrupt of a
plotting calculation.
Aliases trackCol
System default red4

Use Used for indicating visited sites in the intermediate plot.ps file produced
when calculations are interrupted (‘Esc’)during a predominance plot (see
definition of plotFrequency).
trackSymbolColor is also used for plotting the label anchor in custom
plots and for showing the vector vertices in ‘ht1’ plots.
The track symbols can be turned off by setting the colour to ‘nd’ or the
size to zero.

trackSymbolSize
Value non-negative number [non-negative number]
Description Size of the track symbol used to monitor plotting and optionally the size
of the symbol used to show either the vertices in predominance plots or
the label centres in custom plots.
Aliases tracksize
System default 1.0 0.0

Use In custom plots, the track symbol shows the the position of the label
anchor. This only applies to labels that have been placed in the current
plot (calculationMethod 1). In contour plots and with contourShiftLabel
 Keywords 225

set to ‘n’ (for number), the track symbol (1) is drawn at all the vertices to
aid deciding by how many vertices to shift the label.
The track symbol is also used in the plot.ps file that is produced by
pressing ‘P’ during predominance diagram calculations and shows the
progress so far. In ‘grid’ mode, only the perimeter vertices of the visited
cells are shown. A double-sized blue or red circle highlights the last calcu-
lated point.
The first trackSymbolSize number gives the size of both of these symbols.
The second optional trackSymbolSize number either gives (i) the size of
the symbols used to show the vertices that have been written to the poly-
gon file, i.e. those that remain after any line simplification in predomi-
nance plots, or (ii) the size of the anchor symbol (a filled circle) showing
the centre of the plotted labels. These anchor symbols have the colour
specified by trackSymbolColor.
In a grid plot, the vertices on the domain boundary will be clipped since
the grid is offset by half a cell and so extends beyond the domain bounda-
ries. This means that the boundary vertices are not on the domain bound-
aries and consequently will not be shown.
Example 43

trk
Value logical
Description Determines if the ‘track’ file is retained or not
Aliases track, trackFile
System default F

Use The track file keeps a record of the summary results of each speciation cal-
culation and records the top three species in terms of molar abundance for
the purposes of predominance calculations. This is a more complete ver-
sion of the summary output that is sent to the screen during a predomi-
nance plot calculation.
Output is only sent to the track file for main loop simulations (not pre-
loop simulations) and only one line of output is sent per main loop simu-
lation, i.e. if there is more than one main loop simulation and these are
executed oneSimulationAtaTime (see mainLoop), output is only sent
from the last simulation.
The file includes the three system variables (pH, pe and temperature). If
any ‘carry variables’ are specified, these are appended.
The track file is the primary data file that is used to prepare a ‘grid’ type
of predominance plot.

units
Value ‘mm’, ‘inch’, ‘pt’
226 PhreePlot Guide

Description Units used for all length measurements (mm, inch, pt)
Aliases
System default mm
Use Choose between ‘mm’, ‘inch’ or ‘pt’ (one point = 1/72 inch). It is best to
decide on the units at the outset and set this in the pp.set file or at the
top of an input file.
All settings with a length dimension are read in as pure numbers without
dimensions but are immediately converted to the units in force at the
time of reading.
Internally all dimensions are converted to inches for plotting.

updateFitParameters
Value logical
Description Determines whether after an optimization the updated parameter values
are used when rewriting the input file (TRUE) as opposed to using the orig-
inal values (FALSE).
Aliases
System default F

Use If updateFitParameters is set to TRUE and if a line containing fitParameter-

Values was present in the original input file, as it normally would be for a
fit, then the final fit values are written to the reformatted copy of the
input file which can be found at the end of the log file. This could be cut
and pasted into a new file.
If you want the final parameter values in the input file to be overwritten,
then this can be done by also setting rewriteInputFile to TRUE but be
aware that this will reformat the entire input file and remove all com-
ments. However, the original input file is copied and saved with the exten-
sion .bak.ppi providing that this file does not already exist.
Clearly it is wise to make an independent backup of all important input
files.

useLineColorDictionary
Value 0, 1 or 2
Description Determines whether the line colour dictionary is used to determine the
line and points (symbol) colours, and label positions, or not.
Aliases useColorDictionary, coldict
System default 0
Use Increasing numbers indicate increasing dependence on the line colour
dictionary, if present.
0= do not use the line colour dictionary. Use the lineColor setting first of
all. If there is more than one line and changeColor is FALSE use the auto-
 Keywords 227

selected colour sequence defined by PhreePlot.

1 = use the line colour dictionary if present but only for colours
2 = use the line colour dictionary if present for both colours and label
positions. Labels are only used for lines. Use post for points.
Example 82

vec
Value logical
Description Determines if a vector file created during ‘hunt and track’ calculations is
retained at the end of computations.
Aliases vectors, vectorsFile
System default F

Use The vectors file will always be created in ht1 calculations but this setting
will determine if it is deleted at the end of the calculations. It can be
regenerated from the points file using the re-process data option (calcula-
tionMethod 3).

weightColumn
Value non-negative integer or column name (case sensitive)
Description Column number of the weight variable for the fit method
Aliases weightPosition
System default 0
Use Only used in fitting mode. If it is not a positive number, i.e. zero, then the
default weighting (unit weighting) is used.
Example 80

xaxisLength
Value positive number
Description Length of x axis
Aliases xlength
System default 90
Use The length is used to determine the length of the x axis in the units in
operation (see units).
Example
228 PhreePlot Guide

xmax
Value number
Description Maximum value of the x-axis variable used during the calculations
Aliases
System default UNDEFINED

Use Controls the final value for the <x_axis> variable.

Example 3

xmin
Value number
Description Minimum value of the x-axis variable used during the calculations
Aliases
System default UNDEFINED

Use Controls the starting value for the <x_axis> variable.

Example 3

xoffset
Value non-negative number
Description Distance of the origin of the plot (lower left-hand corner) from the left
side page margin
Aliases
System default 30
Use Distance of the origin of the plot (lower left-hand corner) from the left
side page margin.
Example 39

xtitle
Value string ([second string ]
Description Title of the x axis
Aliases
System default ‘auto’ ‘’
Use The first string is the main x-axis title.
 Keywords 229

The second string is appended to the first string with the ‘exponential’
scaling factor placed in between. For example if the x-data range from 0 to
1200 then the data could be automatically rescaled by dividing by 1e2.
For example,
xtitle ‘Distance (’ ‘ m)’

gives
Distance ( /102 m)

or in general, trim(string)//trim(exptext)//trim(second
string) where // is the concatenation operator.
The title strings can be of any length but their maximum combined
length including any text tags and the inserted scale factor is 200 charac-
ters.
‘auto’ gives a blank title for predominance plots. For custom, fit and spe-
cies plots ‘auto’ takes the value of customXcolumn label.
A blank string means that an auto-generated title will be used. Turn-off by
setting axisTitleColor to ‘nd’, axisTitleSize to 0 or setting the title to a
non-printing character such as ‘¬’.
Example 65

yaxisLength
Value non-negative number
Description Length of x axis
Aliases ylength
System default 90
Use The length is used to determine the length of the y axis in the units in
operation (see units).

ymax
Value number
Description Maximum value of the y-axis variable used during the calculations
Aliases
System default UNDEFINED

Use Controls the final value for the <y_axis> variable.

ymin
Value number
Description Minimum value of the y-axis variable used during the calculations
230 PhreePlot Guide

Aliases
System default UNDEFINED

Use Controls the starting value for the <y_axis> variable.

Example

yoffset
Value non-negative number
Description Distance of the origin of the plot (lower left-hand corner) from the bot-
tom page margin
Aliases
System default 140
Use Distance of the origin of the plot (lower left-hand corner) from the bot-
tom page margin.
Example 39

yscale
Value character
Description Determines the y-scale to use for predominance plots
Aliases
System default “native”
Use The y-scaling during the plotting of predominance diagrams has the fol-
lowing three options:
“native” scale determined by the y-axis variable
“pe” uses the pe scale
“Eh” uses the Eh scale (in V)
“mV” uses the Eh scale (in mV)
If one of the pe-related scales is used, then the calculated pe value is used
rather than the y-axis variable.
The calculated pe values are stored in all of the critical output files. If
requested, the Eh values to be plotted are calculated from the pe values
just before plotting. Since Eh values are not stored in the output files
including the labels file, adjustment of any label positions has to be done
in terms of pe (Eh in V = 0.0591 pe at 25oC) rather than Eh.
The y-scale setting can be changed either before a plot is generated or
before replotting. If replotting, use calculationMethod = 3 to ensure that
the label positions are also recalculated.
In order to make plots using one of the pe-related scales, it is necessary to
estimate the pe where the speciation has failed. This is not always possible
to do reliably and it may therefore not be able to close the various poly-
gons outlining the fields properly. Either reduce the domain to one where
 Keywords 231

the pe can be estimated reliably at all times or drive the yaxis variable with
the pe directly using the pe, i.e. use ‘Fix_e-’ analagous to ‘Fix_H+’. If this
is done, set the yscale to ‘native’. There is then no ambiguity over the
intended pe value.
Example 18

ytitle, 2ytitle
Value string [[second string ] third string (max. 40 characters)]
Description Title of the y(2y)-axis, its units and the character attached to label names
to indicate that they refer to the 2y axis.
Aliases title2y
System default ‘auto’ ‘’ ‘*’

Use The title strings can be any length but a maximum of 200 characters
including any text tags are used for plotted.
It behaves the same as for xtitle except that for predominance plots, if
yscale is set to “pe” and ytitle is ‘auto’, then ytitle will be automatically set
to “pe”. Similarly for yscale and “Eh” or “mV”.
For custom plots with ytitle set to ‘auto’, the first label name is used for
the y-title. Similarly for 2ytitle.
The 2y axis is the right-hand y axis which can be separately defined from
the main y axis. The 2y axis is used for variables defined with points2y
and lines2y.
See xtitle for the meaning of the optional second string.
A blank string means that an auto-generated title will be used. Turn-off by
setting axisTitleColor to ‘nd’, axisTitleSize to 0 or setting the title to a
non-printing character such as ‘¬’.
The optional third parameter is a character string that is appended to all
label names that refer to variables plotted according to the 2y axis. It is an
asterisk by default but it can be set to null (‘’) if no character is wanted or
can include plot tags. This means that ⁺ would be valid.
Examples 3, 65
232 PhreePlot Guide
 Examples 227

Examples

These examples are included in the \demo directory and can be run individually or they can all
be run with the demo.bat file. The plot filename can be seen at the bottom left-hand corner of
each plot.
The examples are arranged in sections based on the type of calculations undertaken. The sec-
tions are themselves ordered in terms of the calculationType.
The PhreePlot code that produced each plot is shown below each plot. Note that long lines in
the the code may wrap to a second line so be careful if copying. If in doubt, refer to the origi-
nal file in the demo directory.
The examples demonstrate many of the features built into PhreePlot and are intended as tem-
plates to be modified for your own particular problem. In most cases, the choice of concentra-
tions etc. are arbitrary and are not intended to have any environmental significance.
The results of geochemical calculations are entirely dependent on the choice of thermody-
namic database. PHREEQC makes it easy to select different databases, and to modify them
either temporarily or permanently. In some cases, we have mixed databases in order to extend
them. This can be dangerous and will almost certainly introduce inconsistencies. We have not
made any effort to re-evaluate log K’s in order to achieve internal consistency though in any
real application this should be seriously considered.
The other side of the coin is almost equally bad – to accept the status quo and to ignore a sig-
nificant reaction because it cannot be modelled perfectly can also lead to serious errors – errors
of omission rather than commission. If something is important to you, check it out carefully
and if necessary, try and improve it. Pass your experiences on to others. Ultimately of course
the database you use is your responsibility and you have to be able to defend its use – caveat
empor.
 Examples 228

Predominance plots (grid approach)

Predominance plots are a type of two-dimensional plot showing the predominant species as a
function of two master variables plotted on the x- and y-axes.
PhreePlot uses a full speciation approach (based on PHREEQC) to calculate the predomi-
nant species. These examples use the ‘grid’ or brute force approach (Section 8.2).
Examples 229
 Examples 230

1 Fe-H2O (grid approach)

Fe-H2O
(grid approach)

O2(g) > 0.21 atm

-10 Fe23+(OH)24+
Fe
Fe
log f O2(g) (atm)

-30 Fe(OH)3(a)

-50

Fe2+

-70
0.1 mol/kgw NaCl
25oC -
FeOH+ Fe(OH)3
H2(g) > 1 atm
-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\grid\gridhfo_Fe1.ps

This is a predominance diagram for the Fe-H2O system. Only Fe(OH)3(a) (also known as
hydrous ferric oxide and ferrihydrite) has been allowed to precipitate in this example – the
more stable iron oxides such as goethite and hematite would take precedence if they were
included in the list of minerals considered. The diagram shows that Fe(OH)3(a) dissolves
under both acidic and reducing conditions.
The grid approach is the simplest way of calculating such predominance diagrams. Just calcu-
late the speciation on a regular grid and plot the results directly, here on a 101 x 101 grid.
However, there is much ‘wasted’ effort away from the boundaries and it takes quite a high grid
resolution to make a good plot. The resultant plot file size is also quite large especially if the
boundaries are not vectorised and simplified. Here the basic pixel map that is produced by the
grid approach has been vectorised to give the polygon boundaries. This reduces the resultant
file size. However, the boundaries have not been simplified, hence the ‘jaggies’.
It is natural to want to refine the boundaries with a finer grid. This can be done but is expen-
 Examples 231

sive – the computational load increases with the square of the resolution. This logically leads
to a search for a more efficient approach such as the ‘hunt and track’ approach. However, the
grid approach is the most reliable approach (see the caution about the ‘hunt and track’
approach, Section 8.3). Its quality is only limited by the resolution
The main task of the input file is to define what PHREEQC calculations do and what and
how the results are plotted. calculationType defines the type of calculations to be done, here
‘grid’ specifies a predominance diagram using the grid approach. mainspecies defines the ‘spe-
cies’ or component for which the diagram is to be produced, here Fe. There could be a list of
main species in multi-component systems, one for each ‘species’ present (other than H and
O).
xmin, xmax, ymin and ymax define the range of the <x_axis> and <y_axis> tags, the
domain of the calculations (not necessarily of the plotting - they are controlled by pxmin etc).
resolution controls the size of the grid over which speciation calculations will be made, here
101 x 101.
The ‘title’ keywords control the various titles placed on the plot while extraText specifies a file
which contains information from which to plot additional, user-supplied text anywhere on
the page.
The PHREEQC code starts with the ht1.inc include file which writes data to the selected
output ‘file’ in the format expected by PhreePlot for a predominance-type calculation. Note
that while this file is called ht1.inc, it works equally well for both grid- and ht1-type calcula-
tions.
The rest of the code defines the total concentrations in the system and any minerals or gases
that should be considered. Note that the initial pH of the solution (pH 1.8) is lower than the
lowest pH of the plot (pH 2). This ensures that Fix_H+ will be able to reach any required pH
by the addition of NaOH. If the consequences of this are not wanted then the initial solution
would need to have sufficient Na in it to support negative additions of NaOH.
The code is split into two simulations for speed. The first simulation does the initial solution
calculation while the second simulation does the individual speciation calculations for each
point on the plot. By default, PhreePlot only loops on the final simulation in a multi-simula-
tion file. That is why <x_axis> and <y_axis> are found in the final simulation.
Note that the small, dark blue field (‘FeOH2+’) at pH = 2.8 and log fO2(g) = -22 has not been
labelled. This is because it occupies less than 0.1% of the plot area, the default value of mini-
mumAreaForLabeling.
 Examples 232

# produces a predominance diagram for the Fe-H2O system using the grid approach

SPECIATION
JobTitle “Fe-H2O”
# uses the ‘grid’ or brute force approach - slow but more reliable than ‘hunt and
# track’
calculationType “grid”
calculationMethod 1
mainSpecies Fe # diagram is for Fe
xmin 2.0 # pH range
xmax 12.0
ymin -90.0 # fO2(g) range (controls the redox)
ymax 0.0
resolution 101 # 101 x 101 grid

PLOT
plotTitle \
“Fe-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(grid approach)”
xtitle pH
# this will produce a plot with the native y-scale, fO2(g)
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g) (atm)”
# can use the ‘yscale’ keyword to plot using pe, mV or Eh scales
extraText ..\Fe\extratextFeOH.dat

CHEMISTRY

include ‘ht1.inc’ # standard file for calculating predominant species

# same as used by the hunt and track approach
SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
# N.B. this works because &lt;x_axis&gt; is substituted without any leading spaces
Fix_H+ -&lt;x_axis&gt; NaOH 10
# for negative values of &lt;x_axis&gt; would have to form a new tag to avoid
# --value
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

# the only mineral allowed to form - must be in the database used

Fe(OH)3(a) 0 0
END # 0 0 means achieve SI=0 and size of initial reservoir is 0 mol Fe(OH)3(a)
# i.e. allow to precipitate but none there to dissolve
Examples 233
 Examples 234

2 Cu-S-C (‘island’ found with ‘grid’)

Cu-S-C-H2O
(no minerals)

0 O2(g) > 0.21 atm

Cu
-20 Cu2(OH)22+ Cu(OH)2
Cu2+ Cu(CO3)22-
log f O2(g)

-40

-60 CuCl2-
Cu+

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\island\CuSgrid_Cu1.ps

This predominance diagram is for solution-only species; no minerals have been allowed to
precipitate.
The diagram has been produced with the ‘grid’ approach. It illustrates an example where the
‘hunt and track’ approach fails to find all fields (see the next Example). The field not found is
the Cu+ field in the lower part of the diagram. This ‘island’ is not accessible from any of the
domain boundaries and so the hunting part of the ht1 algorithm fails to find it.
Sections through the island at log f O2(g) = -63 atm showing the Cu (Figure Ex2.1) and Cl
(Figure Ex2.2) speciation as a function of pH indicate that the island occurs where the only
two significant Cu species are Cu+ and CuCl2-. The Cl speciation is also dominated by the
CuCl2- species and so the Cl concentration fixes the CuCl2- concentration which in turn fixes
the Cu+ concentration.
It appears in practice that such ‘islands’ are not that common. None of the other ‘ht1’ exam-
ples in this guide have an ‘island’. Nevertheless, it is always wise to check an ‘ht1’ diagram
 Examples 235

Distribution of Cu species with pH

log f O2 = -63 atm
-1 Cu+
• • Cu2+
-
Cu+ CuCl2 CuCO3
Cu(CO3)22-

log concentration (mol/kgw)

CuCl+
-2 CuCl2-
CuCl32-
Cu(CO3)22-•
Cu(OH)2
CuSO4

-3 •
CuSO4

•
CuCl32-
•
Cu2+ Cu(OH)2
-4 •

•
CuCl+
•
CuCO3

-5
2 4 6 8 10
pH

C:\Program Files\PhreePlot\0.01\demo\island\Cusection.ps

Figure Ex2.1. Variation of Cu speciation with pH. The pH section at log f O2(g) = -63
passes through the Cu+ ‘island’ between pH 6.3 and pH 8.3.

Distribution of Cl species with pH

log f O2 = -63 atm
-1 CuCl2- Cl-
CuCl+
CuCl2-
CuCl32-
log concentration (mol/kgw)

-2

Cl-

-3 CuCl32-

-4

CuCl+

-5
2 4 6 8 10
pH

C:\Program Files\PhreePlot\0.01\demo\island\Cusection(Cl).ps

Figure Ex2.2. Variation of Cl speciation with pH. The pH section at log f O2(g) = -
63 passes through the Cu+ ‘island’ between pH 6.3 and pH 8.3.

using the ‘grid’ approach just to be sure.

Thanks to Hans Meeussen for finding this example.
 Examples 236

SPECIATION
calculationType grid
calculationMethod 1
mainSpecies Cu
xmin 2
xmax 10 # upper pH
ymin -80.0
ymax 0.0
resolution 100 #
PLOT
plotTitle \
“Cu-S-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(no minerals)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextCuS.dat”

CHEMISTRY

include ‘ht1.inc’ # standard hunt and track file also works for grid plots

SOLUTION 1
Temp 20
pH 1.8 # set just below lowest pH
units mol/kgw
Cu 1e-1 # total concns
S(6) 1e-1
Na 1e-1 # background electrolyte
Cl 1.032e-1
END

USE solution 1 # loop on last simulation by default

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0 # N.B. no minerals
END
 Examples 237

Predominance plots (ht1 approach)

These examples use the ‘ht1’ or ‘hunt and track’ approach (Section 8.3) for calculating pre-
dominance diagrams.
 Examples 238

3 Fe-H2O (‘Hunt and track’ approach)

Fe-H2O
(hunt and track approach)

O2(g) > 0.21 atm

-10 Fe2(OH)24+
Fe3+
Fe
log f O2(g) (atm)

-30 Fe(OH)3(a)

-50

Fe2+

-70
0.1 mol/kgw NaCl
25oC
-
FeOH+ Fe(OH)3
H2(g) > 1 atm
-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Fe\hfo_Fe1.ps

This figure is for the same system as in the previous example but has been calculated using the
‘hunt and track’ approach rather than the ‘grid’ approach. This approach seeks out the change
in predominant species along the domain boundaries (outside edges) and from these intersec-
tions tracks inside, bouncing along the boundary. Ultimately all the internal boundaries have
been tracked and linked together to give the required polygons or fields. This approach
assumes that there are no ‘islands’ – fields that cannot be reached from the edges – an assump-
tion that is often but not always valid (see Example 42) so care is needed when applying this
approach.
This approach is quicker than the grid approach for high quality plots. The effort depends on
the length of the boundaries and varies more or less linearly with the resolution (not the
square as with the grid approach).
The only change required from the previous example is to change the calculationType from
‘grid’ to ‘ht1’.
 Examples 239

# produces a predominance diagram for the Fe-H2O system using the hunt and track \
approach, uses native y-scale

SPECIATION
JobTitle “Fe-H2O”
# uses the ‘hunt and track’ approach - fast but not as reliable as the ‘grid’
# approach
calculationType “ht1”
calculationMethod 1
mainSpecies Fe # diagram is for Fe
xmin 2.0 # pH range
xmax 12.0
ymin -90.0 # fO2(g) range (controls the redox)
ymax 0.0
resolution 250 # jumps around on a 250 x 250 grid

PLOT
plotTitle \
“Fe-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(hunt and track approach)”
xtitle pH
# this will produce a plot with the native y-scale, fO2(g)
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g) (atm)”
# can use the ‘yscale’ keyword to plot using pe, mV or Eh scales
extraText extratextFeOH.dat

CHEMISTRY

include ‘ht1.inc’ # standard file for calculating predominant species

# same as used by the grid approach
SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
# N.B. this works because &lt;x_axis&gt; is substituted without any leading spaces
Fix_H+ -&lt;x_axis&gt; NaOH 10
# for negative values of &lt;x_axis&gt; would have to form a new tag to avoid
# --value
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

# the only mineral allowed to form - must be in the database used

Fe(OH)3(a) 0 0
END # 0 0 means achieve SI=0 and size of initial reservoir is 0 mol Fe(OH)3(a)
# i.e. allow to precipitate but none there to dissolve
 Examples 240

4 Fe-H2O: close-up (predominance crite-

rion)

Fe-O2-H2O
(closeup)

0 O2(g) > 0.21 atm

Fe
-5

-10
Fe2(OH)24+ Fe3(OH)45+
log f O2(g)

Fe3+
Fe(OH)3
-15

-20
FeOH2+

-25
Fe2+

-30
2.0 2.5 3.0 3.5 4.0
pH

C:\PhreePlot\demo\Fe\hfocloseuppredllnl_Fe1.ps

Close-up of a portion of an interesting part of the predominance diagram from the previous
figure but this time using the llnl.dat database.
This database file is specified with the database keyword. The database file should either be in
the system directory or in the ppi directory or in a directory for which the full file path is spec-
ified with the keyword.
The llnl.dat database has a more extensive set of polynuclear Fe species than wateq4f.dat.
However, the larger database makes the calculations significantly slower.
Note the appearance of a second very small and unlabelled FeOH2+ field to the right of the
main FeOH2+ field.
It is best to recalculate close-ups anew rather than merely replotting them by using a changed
pxmin etc.
 Examples 241

# closeup of the Fe-H2O system based on the llnl.dat database

SPECIATION
JobTitle “Fe-H2O-O2”
calculationType ht1
calculationMethod 1
# species and their names vary with database
database llnl.dat
fillColorDictionary fillcolorllnl.dat
mainSpecies Fe
# pH range (x-axis) from 2-4 in 250 steps
xmin 2.0
xmax 4.0

# log f(O2(g)) range (y-axis) from -20 to 0 in 250 steps

ymin -30.0
ymax 0.0
resolution 250

PLOT
plotTitle \
“Fe-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(closeup)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextFeOHclose.dat”

CHEMISTRY

# first simulation - initial solution calculation

# special predominance diagram file that adds “(s)” to the names of all minerals
include ‘ht1s.inc’
# this is helpful because in the llnl.dat database, “Fe(OH)3” could be confused
# with an aqueous species
SOLUTION 1
pH 1.8 # initial solution pH is less than pHmin
units mol/kgw
Fe(3) 1e-2 # total Fe
Na 1e-1 # background electrolyte
Cl 1e-1
END

# second simulation - iterate on this final simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt;

Fe(OH)3 0 0 # note the mineral is Fe(OH)3 not Fe(OH)3(a) in this database

END
 Examples 242

5 Fe-H2O: close-up (stability criterion)

Fe-O2-H2O
(closeup)

0 O2(g) > 0.21 atm

Fe
-5

-10
Fe2(OH)24+ Fe3(OH)45+
log f O2(g)

Fe3+
Fe(OH)3
-15

-20
FeOH2+

-25
Fe2+

-30
2.0 2.5 3.0 3.5 4.0
pH

C:\PhreePlot\demo\Fe\hfocloseupstabllnl_Fe1.ps

This is the same as in the previous Example but calculated using the ‘stability’ criterion.
Note the slightly different diagram with the appearance of an aqueous Fe(OH)3 field.
 Examples 243

# closeup of the Fe-H2O system based on the llnl.dat database

SPECIATION
JobTitle “Fe-H2O-O2”
calculationType ht1
calculationMethod 1
# species and their names vary with database
database llnl.dat
fillColorDictionary fillcolorllnl.dat
mainSpecies Fe
# pH range (x-axis) from 2-4 in 250 steps
xmin 2.0
xmax 4.0

# log f(O2(g)) range (y-axis) from -20 to 0 in 250 steps

ymin -30.0
ymax 0.0
resolution 250

PLOT
plotTitle \
“Fe-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(closeup)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextFeOHclose.dat”

CHEMISTRY

# first simulation - initial solution calculation

include ‘ht1stability.inc’ # standard stability diagram file

SOLUTION 1
pH 1.8 # initial solution pH is less than pHmin
units mol/kgw
Fe(3) 1e-2 # total Fe
Na 1e-1 # background electrolyte
Cl 1e-1
END

# second simulation - iterate on this final simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt;

Fe(OH)3 0 0 # note the mineral is Fe(OH)3 not Fe(OH)3(a) in this database

END
 Examples 244

6 Fe-H2O (pe scale)

Fe-O2-H2O
(only HFO precipitates: pe scale)

Fe3+
15 Fe2(OH)24+
O2(g) > 0.21 atm

5 Fe(OH)3(a)
pe

Fe2+

-5
H2(g) > 1 atm
FeOH+
Fe(OH)3-

-15
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Fe\hfope_Fe1.ps

Same as in Example 2 but plotted with the pe scale rather than the O2(g) fugacity scale. This is
set with the yscale keyword. pymin and pymajor have also been set to ensure a reasonable y-
scale. If yscale is set to “pe”, then the default y-axis title is automatically set to “pe”.
 Examples 245

# produces a predominance diagram for the Fe-H2O system using the hunt and track \
approach, pe scale
#

SPECIATION
jobTitle “Fe-H2O-O2”
calculationType ht1 # the ‘hunt and track’ method
# 1=calculate, 2=replot, 3=resimplify and replot
calculationMethod 1
mainSpecies Fe # make a Fe diagram

xmin 2.0 # pH range (x-axis) 2-12

xmax 12.0

# log f(O2(g)) range (y-axis) -90 to 0

ymin -90.0
ymax 0.0
# searching takes place over a 250 x 250 grid
resolution 250

PLOT
plotTitle \
“Fe-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(only HFO
\
precipitates: pe scale)”
xtitle pH
yscale pe # use pe scale - default title is ‘pe’
pymin -15 # min y value on plot scale
# pymajor 5 # interval between \
major ticks and labels on y-scale
# make a pdf file (assumes Ghostscript installed)
pdf T

CHEMISTRY

# first simulation - initial solution calculation only calculated once

include ‘ht1.inc’

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2 # total Fe in system
Na 1e-1
Cl 1e-1
END

# second (final) simulation - the final simulation is iterated many times as \

required by the hunt and track procedure
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt;

Fe(OH)3(a) 0 0 # the only mineral considered

END
 Examples 246

7 Fe-H2O (Eh scale)

Fe-O2-H2O
(only HFO precipitates: Eh (V) scale)

1.5

1.0 Fe3+
Fe2(OH)24+
O2(g) > 0.21 atm

0.5
Eh (V)

Fe(OH)3(a)

0.0 Fe2+

H2(g) > 1 atm

-0.5 FeOH+
Fe(OH)3-

-1.0
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Fe\hfoeh_Fe1.ps

Same as in Example 2 but plotted with an Eh scale rather than the O2(g) fugacity scale. This
makes use of the yscale setting. pymin and pymajor have been set to ensure a reasonable y-
scale. If yscale is set to “Eh”, then the default y-axis title is set to “Eh (V)”. If it is preferred to
have the yscale in mV rather than ‘V ’, set yscale to ‘mV ’.
 Examples 247

# produces a predominance diagram for the Fe-H2O system using the hunt and track \
approach, Eh (V) scale
#

SPECIATION
jobTitle “Fe-H2O-O2”
calculationType ht1 # the ‘hunt and track’ method
# 1=calculate, 2=replot, 3=resimplify and replot
calculationMethod 1
mainSpecies Fe # make a Fe diagram

xmin 2.0 # pH range (x-axis) 2-12

xmax 12.0

# log f(O2(g)) range (y-axis) -90 to 0

ymin -90.0
ymax 0.0
# searching takes place over a 250 x 250 grid
resolution 250

PLOT
plotTitle \
“Fe-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(only HFO
\
precipitates: Eh (V) scale)”
xtitle pH
# use Eh scale (V) - default title is ‘Eh (V)’
yscale Eh
pymin -1 # min y value on plot scale
# interval between major ticks and labels on y-scale
pymajor 0.5
# make a pdf file (assumes Ghostscript installed)
pdf T

CHEMISTRY

# first simulation - initial solution calculation only calculated once

include ‘ht1.inc’

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-2 # total Fe in system
Na 1e-1
Cl 1e-1
END

# second (final) simulation - the final simulation is iterated many times as \

required by the hunt and track procedure
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt;

Fe(OH)3(a) 0 0 # the only mineral considered

END
 Examples 248

8 As-O2(g)-H2O

As-H2O-O2-H2O
(dominant species)

O2(g) > 0.21 atm

-10 As
H3AsO4
H2AsO4-
-30 HAsO42-
AsO43-
log f O2(g)

-50

H3AsO3
-70
H2AsO3-

H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Assolution\As_As1.ps

A classical predominance diagram for arsenic showing the change of arsenic species with both
pH and redox. This diagram is only solution for solution species since no minerals have been
included in the EQUILIBRIUM_PHASES data block.
 Examples 249

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 12.0
ymin -90.0
ymax 0.0
resolution 200

PLOT
plotTitle \
\
“As-H&lt;sub&gt;2&lt;/sub&gt;O-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&g \
t;O&lt;br&gt;(dominant species)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextAs.dat”

CHEMISTRY

include ht1.inc # standard ‘hunt and track’ file

SOLUTION 1
temp 20
units mol/kgw
As 1e-3 # total As
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # &lt;x_axis&gt; is pH so reverse sign
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
END
 Examples 250

9 As-O2(g)-H2O (sub-dominant)

As-H2O-O2-H2O
(sub-dominant species)

O2(g) > 0.21 atm

-10 As
H3AsO4
HAsO42-
-30 H2AsO4-
AsO43-
log f O2(g)

HAsO42-

H3AsO3
-50
H2AsO4-

H2AsO3-

-70 H4AsO3+
H2AsO3- AsO43-
H3AsO3
HAsO32-

H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\Assolution\Assubdom_As1.ps

This diagram has been calculated for the same system as for the previous diagram but this time
the sub-dominant species (the second most abundant species) have been plotted.
The dominant species is still included in the calculations but it has been demoted so that it is
not selected. Note that this often produces six-way intersections as opposed to the three-way
intersections of the classical plots.
This type of plot may not be terribly enlightening but if the dominant species is of interest,
then the sub-dominant species might also be of some interest. As with the normal predomi-
nance diagram, the diagram triggers questions about why particular fields are where they are
and this in itself can aid understanding of the processes involved.
It is not possible to calculate this type of diagram with the classical (analytical ) approach for
calculating predominance diagrams.
 Examples 251

# sub-dominant plot (second most abundant species - a bit different from normal!)
SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 12.0
ymin -90.0
ymax 0.0
# need a high resolution to get good straight sloping lines - otherwise use
# ‘simplify 10’
resolution 500
dominant F # this picks the sub-dominant species

PLOT
plotTitle \
\
“As-H&lt;sub&gt;2&lt;/sub&gt;O-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&g \
t;O&lt;br&gt;(sub-dominant species)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextAs.dat”

CHEMISTRY

# use standard predominance file which returns top three species - PhreePlot deals
# with this
include ‘ht1.inc’

SOLUTION 1
temp 20
units mol/kgw
As 1e-3
Na 1e-1
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # &lt;x_axis&gt; is pH so reverse sign
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
END
 Examples 252

10 Fe-As-C-S

(minerals but no sorbed As)

20

As
15 O2(g) > 0.21 atm
H3AsO4

10 H2AsO4-
pe

5 HAsO42-

Realgar H3AsO3
0

-5 CH4(g) > 1 atm

H2AsO3-

-10
2 4 6 8 10
pH

C:\PhreePlot\demo\FeAsCS\FeAsCS_As1.ps

This is the pe-pH diagram for As in a Fe-As-C-S system. This is a complex system with Fe, As,
C and S minerals precipitating in various places.
Note that the ppi code (see next page) that produced this diagram actually produces diagrams
for all four ‘main species’ or components (Fe, As, C and S). These are produced in a single ps
file since multipageFile has been set to true. Looking at all four diagrams together gives a good
indication of the interactions involved. and the reasons why the minerals predominate where
they do.
For example, realgar is only stable in highly acidic and reducing systems where HS- and
H3AsO3 activities are relatively high. It does not therefore predominate when pyrite is present
since this drops the sulphide activity too low or in oxidising conditions where SO42- and
As(V) species predominate.
 Examples 253

SPECIATION
calculationType ht1
calculationMethod 1
# produce predominance diagrams for these four elements
mainSpecies Fe As C S
xmin 2.0
xmax 10.0
ymin -85.0
ymax 0.0
resolution 200

PLOT
plotTitle “Fe-As-C-S&lt;br&gt;(minerals but no \
sorbed As)”
xtitle pH
ytitle pe
pymin -10.0
yscale pe # this changes to the pe scale
extraText “extratextFeAsCS.dat”

# put all the plots into a single file - only applies to ps and pdf
multipagefile t

CHEMISTRY

INCLUDE ‘ht1.inc’

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
S(6) 5e-3
Fe 5e-3
As 1e-2
Na 1e-1
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 10

Realgar 0 0
Orpiment 0 0
As2S3(am) 0 0
Halite 0 0
Arsenolite 0 0
Claudetite 0 0
Pyrite 0 0
Mackinawite 0 0
FeS(ppt) 0 0
Sulfur 0 0
Fe(OH)2.7Cl.3 0 0
# Goethite 0 0
Fe(OH)3(a) 0 0
# Hematite 0 0
Greigite 0 0
Magnetite 0 0
Nahcolite 0 0
Siderite 0 0
Maghemite 0 0
Siderite(d)(3) 0 0
Scorodite 0 0
Natron 0 0
Thermonatrite 0 0
Fe3(OH)8 0 0
Thenardite 0 0
 Examples 254

Melanterite 0 0
Mirabilite 0 0
As2O5(cr) 0 0
Trona 0 0
Jarosite-Na 0 0
JarositeH 0 0
END
Examples 255
 Examples 256

11 Fe-As

Fe-As-O2-H2O

20

Scorodite O2(g) > 0.21 atm As

10
H3AsO4
H2AsO4-

HAsO42-

AsO43-
pe

0 H3AsO3

H2(g) > 1 atm

H2AsO3-
-10
log FeT = -4
log P CO2(g) = -3.5
T = 25o C
Database = wateq4f.dat

-20
2 4 6 8 10 12
pH

C:\PhreePlot\demo\scorodite\scorodite_As1.ps

This the classical pe-pH diagram for As in Fe-As systems – it does not take into account any
possible adsorption of As by Hfo which is precipitated above pH 4 and at high pe.
Scorodite is only stable below pH 4 and high pe since precipitation of Hfo reduces the Fe3+
activity at higher pH values. Reduction of Fe3+ to Fe2+ reduces Fe3+ activities at low pe and so
scorodite is not stable there either.
 Examples 257

SPECIATION
jobTitle “Fe-As-O2-H2O” # aqueous and minerals
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 12.0
ymin -85.0
ymax 0.0
resolution 200

PLOT
plotTitle \
“Fe-As-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O”
xtitle “pH”
pymin -20 # force the minimum axis y-scale
yscale pe
extraText “extratextscorodite.dat”

CHEMISTRY

# first simulation

include ‘ht1.inc’

SOLUTION 1
pH 1.8 # start at a low pH (less than xmin)
units mol/kgw
Fe(3) 1e-1
Na 1e-1
Cl 1e-1
As 1e-2 # total As
END

# second simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
Fe(OH)3(a) 0 0 # but no adsorbed As

Arsenolite 0 0 # possible As minerals

Claudetite 0 0
Scorodite 0 0
As2O5(cr) 0 0
END
 Examples 258

12 Fe-As-Hfo (ht1.inc)

Fe-As-O2-H2O
(represented by individual adsorbed species)

20

Scorodite O2(g) > 0.21 atm As

Hfo_wH2AsO4
10
H3AsO4
Hfo_wHAsO4-
H2AsO4 -

Hfo_wOHAsO43-
pe

0 H3AsO3
AsO43-
Hfo_wH2AsO3

H2(g) > 1 atm

H2AsO3-
-10
log FeT = -4
log P CO2(g) = -3.5
T = 25o C
Database = wateq4f.dat

-20
2 4 6 8 10 12
pH

C:\PhreePlot\demo\scorodite\scoroditehfo3_As1.ps

This diagram is for a similar chemistry to the previous example but uses the Dzombak &
Morel (1990) DL model for Hfo to estimate As adsorption by Hfo. The adsorbed As consists
of one As(III) and three As(V) species.
The adsorbed species have been included by using the hfo.inc file which links the precipita-
tion of Fe(OH)3(a) to the Hfo surface.
In working out the predominant species, this example counts and displays each adsorbed spe-
cies separately. This is how the ht1.inc include file has been coded.
 Examples 259

SPECIATION
# aqueous, minerals and surface species
jobTitle “Fe-As-O2-H2O”
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 12.0
ymin -85.0
ymax 0.0
resolution 200

PLOT
plotTitle \
“Fe-As-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(repre-
sented \
by individual adsorbed species)”
xtitle pH
pymin -20
yscale pe
extraText “extratextscorodite.dat”

CHEMISTRY

# first simulation

# ht1.inc treats all Hfo-As surface species as separate species for plotting
include ‘ht1.inc’

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
Na 1e-1
Cl 1e-1
As 1e-2 # total As
END

# second simulation

include ‘hfo.inc’ # add Hfo surface

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
Fe(OH)3(a) 0 0 # only consider this oxide

Arsenolite 0 0 # possible As minerals

Claudetite 0 0
Scorodite 0 0
As2O5(cr) 0 0
END
 Examples 260

13 Fe-As-Hfo (ht1c.inc)

Fe-As-O2-H2O
(represented by a single adsorbed species)

20

Scorodite O2(g) > 0.21 atm As

10
H3AsO4
H2AsO4-
Hfo-As
pe

0 H3AsO3
AsO43-

H2(g) > 1 atm

H2AsO3-
-10
log FeT = -4
log P CO2(g) = -3.5
T = 25o C
Database = wateq4f.dat

-20
2 4 6 8 10 12
pH

C:\PhreePlot\demo\scorodite\scoroditehfo_As1.ps

This is the same system as in the previous example but all the adsorbed As species have been
lumped together into a single adsorbed species, Hfo-As. This change is made by using the
ht1combined.inc include file rather than ht1.inc file.

The adsorbed species have been included by including the hfo.inc file which links the
amount of Hfo surface to the amount of precipitated Fe(OH)3(a), as often occurs in nature.
The Hfo-As field closely follows the combined boundaries of the four adsorbed As species. It
is actually very slightly larger than the sum of the four fields because of the larger number of
moles of As in the combined Hfo-As field than in individual fields and hence its greater com-
petitiveness against other As species.
 Examples 261

SPECIATION
# aqueous, minerals and surface species
jobTitle “Fe-As-O2-H2O”
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 12.0
ymin -85.0
ymax 0.0
resolution 200

PLOT
plotTitle \
“Fe-As-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(repre-
sented \
by a single adsorbed species)”
xtitle pH
pymin -20
yscale pe
extraText “extratextscorodite.dat”

CHEMISTRY

# first simulation

# treat all Hfo-As surface species as one ‘super’ species for plotting
include ‘ht1combined.inc’

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
Na 1e-1
Cl 1e-1
As 1e-2 # total As
END

# second simulation

include ‘hfo.inc’ # add Hfo surface

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
Fe(OH)3(a) 0 0 # only consider this oxide

Arsenolite 0 0 # possible As minerals

Claudetite 0 0
Scorodite 0 0
As2O5(cr) 0 0
END
 Examples 262

14 Fe-S-As (without sorption)

Fe-As-S-H2O (HFO DLM)

O2(g) > 0.21 atm

-10 As
Hfo_wH2AsO4
Hfo_wHAsO4-

-30Scorodite
Hfo_wOHAsO43-
log f O2(g)

H3AsO4
H2AsO4-

-50

H3AsO3
Hfo_wH2AsO3
-70 H2AsO3-
As_native

20.0oC H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\FeAsS\FeAsS_As1.ps

This example involves Fe-S-As and allows precipitation of the Fe(OH)3(a) which is linked to
the Hfo mineral phase. However, there is no code to link arsenic adsorption to this phase, i.e.
no ‘include hfo.inc’ line, or similar. In this example, arsenic minerals only predominate
under strongly reducing conditions.
There were a few ‘beeps’ when running this example with the default convergence parameters.
PHREEQC repeatedly failed to converge at a point around pH 9.55 and log fO2(g) -84.7. No
selected output was received by PhreePlot and the failed region was recorded as an ‘NA’ field.
The problem was solved by relaxing the convergence tolerance from its default value of 1e-12
to 1e-10. This was done by changing the -convergence_tolerance setting of the KNOBS
keyword data block for the second simulation.
 Examples 263

# predominance diagram for As in the presence of HFO which adsorbs As according \

to the Dzombak & Morel DL adsorption model

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0 # range of pH
xmax 12.0
# range of log fO2(g) to control redox
ymin -90.0
ymax 0.0
# controls the resolution (big resolution means small step size)
resolution 500

PLOT
plotTitle “Fe-As-S-H&lt;sub&gt;2&lt;/sub&gt;O (HFO \
DLM)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extratext extratextFeAsS.dat

CHEMISTRY

# simulation 1

include ‘ht1.inc’ # standard predominance-calculating file

SOLUTION 1 # initial solution calculation

Temp 20
pH 1.8
units mol/kgw
Fe(2) 3.5e-1 # total concns
As 1e-2
S(6) 1e-2 # sulphide minerals can form but not adsorb
Na 1e-1
Cl 1e-1
END

include ‘hfo.inc’

KNOBS # NB this only applies to this (2nd) simulation

# the default 1e-12 causes a lack of convergence at pH 9.55 and logO2(g) -84.7
-convergence_tolerance 1e-10

# simulation 2
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

As_native 0 0 # most likely minerals given the database

# hematite, magnetite removed to make goethite stable
Orpiment 0 0
Realgar 0 0
As2S3(am) 0 0
Pyrite 0 0
Arsenolite 0 0
Claudetite 0 0
Mackinawite 0 0
FeS(ppt) 0 0
Sulfur 0 0
Fe(OH)3(a) 0 0
Greigite 0 0
Scorodite 0 0
Mirabilite 0 0
Melanterite 0 0
Thenardite 0 0
 Examples 264

As2O5(cr) 0 0
Jarosite-Na 0 0
JarositeH 0 0
# Goethite 0 0

END
Examples 265
 Examples 266

15 Fe-S-As (low Fe, without surface specia-

tion)

Fe-As-S-H2O (HFO DLM)

O2(g) > 0.21 atm

-10 As

-30Scorodite Hfo-As
log f O2(g)

H3AsO4
H2AsO4-

-50

H3AsO3

-70
As_native

20.0oC H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\FeAsS\FeAsSall_As1.ps

Similar to the previous example but calculated using the ht1combined.inc file which bulks
together all As species adsorbed by Hfo into a single species, Hfo-As. This includes both As(V)
and As(III) surface species.
 Examples 267

# predominance diagram for As in the presence of HFO which adsorbs As according \

to the Dzombak & Morel DL adsorption model

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0 # range of pH
xmax 12.0
# range of log fO2(g) to control redox
ymin -90.0
ymax 0.0
# controls the resolution (big resolution means small step size)
resolution 500

PLOT
plotTitle “Fe-As-S-H&lt;sub&gt;2&lt;/sub&gt;O (HFO \
DLM)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extratext extratextFeAsS.dat

CHEMISTRY

# simulation 1

include ‘ht1combined.inc’ # standard predominance-calculating file

SOLUTION 1 # initial solution calculation

Temp 20
pH 1.8
units mol/kgw
Fe(2) 3.5e-1 # total concns
As 1e-2
S(6) 1e-2 # sulphide minerals can form but not adsorb
Na 1e-1
Cl 1e-1
END

include ‘hfo.inc’

KNOBS # NB this only applies to this (2nd) simulation

# the default 1e-12 causes a lack of convergence at pH 9.55 and logO2(g) -84.7
-convergence_tolerance 1e-10

# simulation 2
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

As_native 0 0 # most likely minerals given the database

# hematite, magnetite removed to make goethite stable
Orpiment 0 0
Realgar 0 0
As2S3(am) 0 0
Pyrite 0 0
Arsenolite 0 0
Claudetite 0 0
Mackinawite 0 0
FeS(ppt) 0 0
Sulfur 0 0
Fe(OH)3(a) 0 0
Greigite 0 0
Scorodite 0 0
Mirabilite 0 0
Melanterite 0 0
Thenardite 0 0
 Examples 268

As2O5(cr) 0 0
Jarosite-Na 0 0
JarositeH 0 0
# Goethite 0 0

END
Examples 269
 Examples 270

16 Fe-S-As (goethite, CD-MUSIC)

Fe-As-S-H2O (CD-MUSIC)

O2(g) > 0.21 atm

-10 As
(Goe_uniO)2AsOOH-
Goe_uniOAsO2OH1.5-
-30 (Goe_uniO)2AsO22-
log f O2(g)

-50
Goe_uniOAs(OH)20.5-
H3AsO3

-70 (Goe_uniO)2AsOH-

As_native

20.0oC H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\FeAsS-cd-music\FeAsS(cd-music)_As1.ps

An example of a predominance diagram for As in which the CD-MUSIC model has been
used to calculate the adsorption of As(V) and As(III) species on goethite. The CD-MUSIC
model parameters were taken from Stachowicz et al. (2006).
This diagram differs from the previous diagram in two main ways: (i) As adsorption has been
calculated using the CD-MUSIC model rather than the diffuse layer model; (ii) adsorption is
linked to goethite not HFO. Goethite is far less soluble than HFO.
The very insoluble nature of goethite and the strong adsorption of As species to goethite
means that adsorbed As predominates throughout most of the domain, more so than for the
more soluble HFO. Only under strongly reducing conditions at low pH, and at very high pH,
do soluble As species predominate. Reducing conditions and a low pH leads to a marked
increase in goethite solubility by reductive dissolution while a high pH leads to a strong elec-
trostatic repulsion of the negatively-charged adsorbed As(V) species and the negatively-
charged goethite surface at high pH. This reduces adsorption and so increases the apparent
solubility.
 Examples 271

# predominance diagram for As in the presence of goethite which adsorbs As \

according to the CD-MUSIC adsorption model

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0 # range of pH
xmax 12.0
# range of log fO2(g) to control redox
ymin -90.0
ymax 0.0
# controls the resolution (big resolution means small step size)
resolution 101

PLOT
plotTitle “Fe-As-S-H&lt;sub&gt;2&lt;/sub&gt;O \
(CD-MUSIC)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extratext extratextFeAsS.dat

CHEMISTRY

# simulation 1

# standard predominance-calculating file, also sets -high_precision true

include ‘ht1.inc’

# CD-MUSIC database, resets convergence criterion, therefore must FOLLOW ht1.inc

include ‘cdmusic_hiemstra.dat’

SOLUTION 1 # initial solution calculation

Temp 20
pH 1.8
units mol/kgw
Fe(2) 3.5e-1 # total concns
As 1e-2
S(6) 1e-2 # sulphide minerals can form but not adsorb
Na 1e-1
Cl 8e-1 charge
END

# simulation 2
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

As_native 0 0 # most likely minerals given the database

# hematite, magnetite removed to make goethite stable
Orpiment 0 0
Realgar 0 0
As2S3(am) 0 0
Pyrite 0 0
Arsenolite 0 0
Claudetite 0 0
Mackinawite 0 0
FeS(ppt) 0 0
Sulfur 0 0
Fe(OH)3(a) 0 0
Greigite 0 0
Scorodite 0 0
Mirabilite 0 0
Melanterite 0 0
Thenardite 0 0
As2O5(cr) 0 0
 Examples 272

Jarosite-Na 0 0
JarositeH 0 0
# common Fe oxide under oxidising conditions
Goethite 0 0
# Magnetite 0 0 # stable below log fO2(g) = -60 \
but not in cd-music database (yet) so ignore!!

SURFACE 1
# 3.5 sites/nm2, 98 m2/g, MWt = 88.855 g/mol
Goe_uniOH1.5 Goethite 0.049886874 8707.79
Goe_triOH0.5 Goethite 0.039041901 8707.79 # 2.7 sites/nm2
-cd_music
-cap 0.85 0.75 # C1 C2 (in F/m2)
-equil 1
END
Examples 273
 Examples 274

17 Fe-As-S (high Fe)

Fe-As-S-O2-H2O
(with individual sorbed As species)

O2(g) > 0.21 atm

-10 As
Hfo_wH2AsO4
H3AsO4 Hfo_wHAsO4-

-30 Hfo_wOHAsO43-
HAsO42-
H2AsO4- AsO43-
log f O2(g)

-50

H3AsO3 Hfo_wH2AsO3

-70Realgar
o
H2AsO3-
20 C
As_native

H2(g) > 1 atm

-90
2 4 6 8 10 12
pH

C:\PhreePlot\demo\FeAsS2\FeAsS2_As1.ps

This is similar to Example 13 except that the Fe/As mole ratio is 10:1 rather than 35:1 and the
As, Fe and S concentrations are an order of magnitude lower. This means that the region
where adsorbed As is a dominant species is much smaller and there is also insufficient SO42- to
lead to the precipitation of scorodite. However, realgar – an arsenic sulphide – has a small field
at low pH and under strongly reducing conditions.
 Examples 275

# predominance plot for As including As sorbed by Hfo

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies As Fe # plots for these two species
xmin 2.0
xmax 12.0
ymin -90.0
ymax 0.0
resolution 200

PLOT
plotTitle \
“Fe-As-S-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(with
\
individual sorbed As species)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextFeAsS2.dat”

CHEMISTRY

# first simulation

SOLUTION 1
Temp 20
pH 1.8
units mol/kgw
Fe 1e-2
As 1e-3 # total concns
S(6) 1e-3
Na 1e-1
Cl 1e-1
END

# second simulation

include ‘ht1.inc’ # standard predominance plot file

# this includes adsorbed species (calcd according to the D&M DLM)
include ‘hfo.inc’

KNOBS # NB this only applies to this (2nd) simulation

# the default 1e-12 causes a lack of convergence at pH 9.55 and logO2(g) -84.7
-convergence_tolerance 1e-10

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1

As_native 0 0
Orpiment 0 0
Realgar 0 0
As2S3(am) 0 0
Pyrite 0 0
Arsenolite 0 0
Claudetite 0 0
Mackinawite 0 0
FeS(ppt) 0 0
Sulfur 0 0
Fe(OH)3(a) 0 0
Greigite 0 0
Scorodite 0 0
Mirabilite 0 0
Melanterite 0 0
 Examples 276

Thenardite 0 0
As2O5(cr) 0 0
Jarosite-Na 0 0
JarositeH 0 0
END
Examples 277
 Examples 278

18 Fe-CO2-SO4-H2O with sample points

Site 10

20
FeSO4+
O2(g) > 0.21 atm
Fe
15 FeOH2+
Fe(OH)2+

10
Fe(OH)3(a)
pe

5
Fe2+

0
CH4(g) > 1 atm FeCO3
Fe(HS)2
-5

-10
3 4 5 6 7 8 9 10
pH

C:\PhreePlot\demo\samplepoints\Fesite10_Fe1.ps

This is a customised predominance plot using the analytical concentrations of elements from a
specific groundwater source (shown by the large red filled circle) to construct the predomi-
nance diagram. The diagram shows the stability fields for Fe for this water.
It is possible to overlay the plot with symbols designating the pe-pH location of a sequence of
sample points, as here, using the extra keyword. This names a file containing the pH-pe coor-
dinates of the groundwater source in question (in red) as well as of other sources in the same
aquifer (displayed in blue).
Because the pH of the various sources is near neutral and the sodium concentration in many
of the waters is low, it is necessary to add a source of Na in order to achieve the low pHs by
subtracting NaOH. This is achieved by adding a nominal source of ‘salt’, NaCl. The code for
this is in the PHASES and EQULIBRIUM_PHASES data blocks. If the interactions of Na or Cl are
important in defining the chemistry of interest, perhaps through an ionic strength effect, then
non-interacting pseudo-elements can be used instead of Na and Cl (see Section 6.5.4).
 Examples 279

# demonstrates how to add sample points to a predominance diagram

SPECIATION
jobtitle “Fe at Site 10 compared with other groundwater \
sources”
calculationType ht1
calculationMethod 1
mainspecies Fe
xmin 3
xmax 10
ymin -80.0
ymax 0.0
resolution 200

PLOT
plottitle “Site 10”
xtitle pH
extrasymbolslines “extrasymbolslincslst.dat”
extratext “extratextmainspecies.dat”
yscale pe

pxmin 3
pxmax 10
pxmajor 1
pymin -10
pymax 20

CHEMISTRY

include ‘ht1.inc’ # standard file for making a predominance plot

PHASES
Salt
NaCl = Na+ + Cl-
log_k 0

# calculates predominance diagram according to these total concns - but only \

based on the 1 sample is not commented out
# this approach means that it is easy to calculate diagrams for the whole set by \
removing the comment from one sample at a time

SOLUTION_SPREAD
DescriptiontemppHpeBaCaClO(0)FFeC(4)KMgMnNaN(3)N(5)SiS(6)Sr
mg/kgwmg/kgwmg/kgwmg/kgwmg/kgwmg/kgwmg/kgw as \
HCO3mg/kgwmg/kgwmg/kgwmg/kgwmg/kgwmg/kgwmg/kgwmg/kgw as SO4mg/kgw
# Site \
111.27.083.630.03691761140.30.2940.673443.45130.029475.30.120.07 \
73.961660.816
# Site \
27.17.033.380.04222091020.170.2030.853554.5412.40.034793.50.0987 \
0.2653.72720.713
# Site \
310.27.043.020.040818986.20.170.1450.5583456.3611.20.030642.80.03 \
230.2643.382010.573
# Site \
410.17.014.580.009816855.90.110.2630.03383324.74110.007838.30.051 \
22.553.371680.694
# Site \
510.07.063.920.013618459.50.110.3760.1233533.3612.10.011448.60.12 \
30.3413.591960.947
# Site \
610.87.181.670.027213246.60.140.5580.4133122.8913.20.006651.90.23 \
9-0.054.021421.13
# Site \
79.97.141.480.016914246.30.170.2250.6433403.2524.60.006853.90.347 \
-0.054.91991.85
# Site \
86.07.033.030.03892041020.310.210.8993794.4312.30.0406910.09750. \
2093.472620.695
 Examples 280

# Site \
910.37.057.630.00717055.52.180.10.00253102.717.060.0006626-0.007 \
4.53.221270.373
Site \
1010.07.095.200.008317855.62.820.0840.02523102.96.570.003926.7-0. \
0075.233.371310.348
# Site \
1110.37.296.470.0091176561.890.0950.00253152.857.370.0005327.50.0 \
1464.233.341340.39
# Site \
1210.27.13.810.006817371.61.340.1350.02513073.076.880.0009540.40. \
0194.493.111370.404
# Site \
1311.07.093.500.0123169588.740.0590.00252634.597.380.0000823.6-0. \
00716.32.91100.27
# Site \
1410.27.221.930.0132176420.210.2720.2093072.688.090.005622.30.074 \
7-0.052.741710.679
# Site \
1510.27.183.400.014216845.10.210.3550.1323183.338.480.004729.90.0 \
924-0.052.871630.698
# Site \
166.27.093.150.013516055.70.140.2534.233462.6215.10.065736.60.1- \
0.054.241530.81
# Site \
1710.26.513.900.012416645.20.210.3620.3363173.198.330.008429.30.0 \
911-0.052.91590.708
# Site \
1810.47.033.060.015917346.70.220.3980.1543143.489.260.004733.20.1 \
06-0.053.11670.803
# Site \
199.37.237.530.007818145.40.10.2131.363113.17.040.018419.60.0232 \
-0.052.921780.538
# Site \
2010.17.076.860.008918344.90.10.2410.1323173.097.390.005920.40.03 \
3-0.052.911750.602

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 10
CO2(g) -3.5 # atmospheric CO2
# this ensures that Na does not run out when fixing low pH’s
Salt -12 10 dissolve

Calcite 00 # list of the most probable minerals that might form

Gypsum 00
Dolomite 00
Siderite 00
Quartz 00
Fe(OH)3(a) 00
Hausmannite 00
Pyrolusite 00
Manganite 00
Rhodochrosite(d) 0 0 # disordered
Pyrochroite 00
# Birnessite 00 # more stable than \
Pyrolusite -
Bixbyite 0 0
Fluorite 0 0
Barite 0 0
END
Examples 281
 Examples 282

19 Fe-Ni-S

Fe-Ni-S
(using llnl.dat)

O2(g) > 0.21 atm

Ni
-15

Ni2+
Trevorite
log f O2(g)

-35

-55
Vaesite
Polydymite
Heazlewoodite

H2(g) > 1 atm

-75
2 4 6 8 10 12
pH

C:\PhreePlot\demo\FeNiS\FeNiS_Ni1.ps

This example shows an example of the Fe-Ni-S system with the low-angled wedges character-
istic of predominance diagrams involving sulphide minerals.
The ‘steppy’ nature of the low-angled boundaries could be reduced either by increasing the
resolution from 200 to say 500, or by increasing the simplification factor, say from 1 to 3.
If the resolution is increased then it is necessary to start the calculations from scratch.
If only the simplification factor is changed, then it is not necessary to recalculate the specia-
tion rather change calculationMethod to 3 (resimplify and replot) and change simplify to 3.
 Examples 283

SPECIATION
# this is a larger database, meaning more species, meaning slower
Database llnl.dat
calculationType ht1
calculationMethod 1
mainSpecies “Ni”
xmin 2.0
xmax 12.0
ymin -75.0
ymax 0.0
resolution 200

PLOT
plotTitle “Fe-Ni-S&lt;br&gt;(using llnl.dat)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
pointSize 1.5
# file with additional text to be added to plot
extraText “extratextFeNiS.dat”

CHEMISTRY

include ‘ht1.inc’ # standard predominance plot file

# first simulation - initial colution calculation

PHASES
SOLUTION 1
Temp 80
pH 1.8
units mol/kgw
density 1
Fe(2) 1e-3
Na 1e-1
Ni 1e-3 # total concns
S(6) 1e-2
Cl 1e-1 charge
END

# second simulation - only repeats this simulation while tracking

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # drives the x-axis
-force_equality true
O2(g) &lt;y_axis&gt; 0.1 # drives the y-axis

Polydymite 0 0 # list of possible minerals

Vaesite 0 0
Pyrite 0 0
Millerite 0 0
Heazlewoodite 0 0
Troilite 0 0
Pyrrhotite 0 0
Ni 0 0
S 0 0
Nickelbischofite 0 0
NiCl2:4H2O 0 0
NiCl2:2H2O 0 0
FeO 0 0
Fe(OH)2 0 0
Wustite 0 0
Goethite 0 0
Bunsenite 0 0
Lawrencite 0 0
Ni(OH)2 0 0
Fe 0 0
NiCl2 0 0
Fe(OH)3 0 0
Hematite 0 0
 Examples 284

Magnetite 0 0
NaFeO2 0 0
Trevorite 0 0
Molysite 0 0
Melanterite 0 0
Mirabilite 0 0
Morenosite 0 0
NiSO4:6H2O(alpha) 0 0
Na 0 0
Thenardite 0 0
FeSO4 0 0
NiSO4 0 0
Na2O 0 0
Na3H(SO4)2 0 0
Jarosite-Na 0 0
Fe2(SO4)3 0 0
END
Examples 285
 Examples 286

20 Fe-Zn-C-H2O (HFO)

Fe-Zn-C-H2O
(showing individual sorbed species)

O2(g) > 0.21 atm

Zn
-15

Hfo_sOZn+
Hfo_sOZn+
log f O2(g)

Hfo_wOZn+
-35
Zn2+

-55

0.1 mol/kgw NaCl Zn(CO3)22-

Zn5(OH)8Cl2
25oC ZnO(a)
CH4(g) > 1 atm
-75
2 4 6 8 10
pH

C:\PhreePlot\demo\hfoZnC\hfoZnC_Zn1.ps

This is a predominance diagram for the Zn-Fe-C-H2O system with adsorption of Zn by Hfo
and precipitation of ZnO(a).
log f CO2(g) has been fixed at -3.5 subject to the constraint that not more than 1 mole of
CO2(g) is used. Many minerals, including many more stable forms of iron oxide and siderite
(FeCO3), have been suppressed for this example. Zn is adsorbed by the Hfo when it is stable.
This example uses the ‘ht1.inc’ include file for sending PHREEQC output to PhreePlot. All
Zn species adsorbed by Hfo have been treated as individual species for the purposes of rank-
ing.
If a combined adsorbed Zn field had been wanted, then the ‘ht1combined.inc’ include file
should have been used rather than ‘ht1.inc’ (see the next Example).
 Examples 287

# Zn predominance diagram with Zn adsorbed onto Hfo

# all adsorbed Zn on Hfo are treated as separate species in terms of \
predominance (mol) counting

SPECIATION
pdf T
calculationType ht1
calculationMethod 1
mainSpecies Zn # diagram for Zn

xmin 2.0 # pH (x-axis) range 2-10

xmax 10.0
ymin -75.0 # log fO2(g) from -75 to 0
ymax 0.0

# jumps about on a 500 x 500 grid when tracking

resolution 500

PLOT
plotTitle \
“Fe-Zn-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(showing individual sorbed species)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratexthfoZnC.dat”

CHEMISTRY

include ‘ht1.inc’ # this standard file calculates the predominant species based on
# treating all sorbed species as separate species
SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
Zn 1e-3
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10 # driven by the x-axis parameters defined above
-force_equality true
O2(g) &lt;y_axis&gt; # driven by the y-axis parameters defined above
CO2(g) -3.5 1 # fix log PCO2(g) at -3.5 subject to the constraint that
# a maximum of 1 mol CO2 is supplied

Fe(OH)3(a) 0 0 # list of possible minerals (many are commented out)

#Magnetite 0 0
# Hematite 0 0 # this is likely to be
# the stable Fe(III)-oxide mineral
#Goethite 0 0
#Fe(OH)2.7Cl.3 0 0
#Fe3(OH)8 0 0
#Siderite 0 0
#Maghemite 0 0
#Siderite(d)(3) 0 0
Trona 0 0
Natron 0 0
Thermonatrite 0 0
Nahcolite 0 0
#Zincite(c) 0 0
ZnO(a) 0 0
#ZnCO3:H2O 0 0
#Zn(OH)2-e 0 0
Smithsonite 0 0
#Zn(OH)2-g 0 0
#Zn(OH)2-b 0 0
#Zn(OH)2-c 0 0
#Zn(OH)2-a 0 0
 Examples 288

#Halite 0 0
Zn2(OH)3Cl 0 0
Zn5(OH)8Cl2 0 0
ZnCl2 0 0
ZnMetal 0 0

SURFACE 1
# Dzombak & Morel (1990) Hfo database
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2
END
Examples 289
 Examples 290

21 Fe-Zn-C-H2O (HFO)

Fe-Zn-C-H2O
(using ht1combined.inc)

O2(g) > 0.21 atm

Zn
-15
log f O2(g)

Hfo-Zn
-35
Zn2+

-55

0.1 mol/kgw NaCl Zn(CO3)22-

Zn5(OH)8Cl2
25oC ZnO(a)
CH4(g) > 1 atm
-75
2 4 6 8 10
pH

C:\PhreePlot\demo\hfoZnC\hfoZnCcomb_Zn1.ps

This is the same as the previous example except that all adsorbed Zn species have been com-
bined into a single composite species, Hfo-Zn, for the purposes of ranking. This makes the
diagram somewhat more straightforward in appearance and avoids the division into individual
surface species which in many cases is poorly constrained and in any case may only be of inter-
est to the surface chemist. This approach uses the ‘ht1combined.inc’ include file. The overall
area of predominance of the adsorbed species is very similar.
The longer BASIC script required for this approach makes the calculations significantly slower
per iteration (some 20% slower), but because the total length of the boundaries is less in the
composite approach, the overall computation time is actually slightly faster
 Examples 291

# Zn predominance diagram with Zn adsorbed onto Hfo

# all adsorbed Zn on Hfo are treated as separate species in terms of \
predominance (mol) counting

SPECIATION
pdf T
calculationType ht1
calculationMethod 1
mainSpecies Zn # diagram for Zn

xmin 2.0 # pH (x-axis) range 2-10

xmax 10.0
ymin -75.0 # log fO2(g) from -75 to 0
ymax 0.0

# jumps about on a 500 x 500 grid when tracking

resolution 500

PLOT
plotTitle \
“Fe-Zn-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(showing individual sorbed species)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratexthfoZnC.dat”

CHEMISTRY

include ‘ht1.inc’ # this standard file calculates the predominant species based on
# treating all sorbed species as separate species
SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) 1e-1
Zn 1e-3
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10 # driven by the x-axis parameters defined above
-force_equality true
O2(g) &lt;y_axis&gt; # driven by the y-axis parameters defined above
CO2(g) -3.5 1 # fix log PCO2(g) at -3.5 subject to the constraint that
# a maximum of 1 mol CO2 is supplied

Fe(OH)3(a) 0 0 # list of possible minerals (many are commented out)

#Magnetite 0 0
# Hematite 0 0 # this is likely to be
# the stable Fe(III)-oxide mineral
#Goethite 0 0
#Fe(OH)2.7Cl.3 0 0
#Fe3(OH)8 0 0
#Siderite 0 0
#Maghemite 0 0
#Siderite(d)(3) 0 0
Trona 0 0
Natron 0 0
Thermonatrite 0 0
Nahcolite 0 0
#Zincite(c) 0 0
ZnO(a) 0 0
#ZnCO3:H2O 0 0
#Zn(OH)2-e 0 0
Smithsonite 0 0
#Zn(OH)2-g 0 0
#Zn(OH)2-b 0 0
#Zn(OH)2-c 0 0
#Zn(OH)2-a 0 0
 Examples 292

#Halite 0 0
Zn2(OH)3Cl 0 0
Zn5(OH)8Cl2 0 0
ZnCl2 0 0
ZnMetal 0 0

SURFACE 1
# Dzombak & Morel (1990) Hfo database
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2
END
Examples 293
 Examples 294

22 Ca-Fe-Na-X-HFO (adsorption and ion

exchange)

Ca-Fe-Na with sorption and ion exchange

(includes Fe(OH)2(s) from llnl.dat)

0 O2(g) > 0.21 atm

Ca
-20
log f O2(g)

CaX2 Calcite
-40

-60
FeT = 0 mol/kgw

0.01 mol/kgw NaCl CH4(g) > 1 atm

25oC
-80
2 4 6 8 10
pH

C:\PhreePlot\demo\Fe\hfoCaX_Ca1.ps

0 O2(g) > 0.21 atm

CaX2
Ca
-20
log f O2(g)

Calcite
Ca2+
-40

-60
FeT = 0.05 mol/kgw

0.01 mol/kgw NaCl CH4(g) > 1 atm

25oC
-80
2 4 6 8 10
pH

C:\PhreePlot\demo\Fe\hfoCaX_Ca2.ps

( ( ) ( ) )

0 O2(g) > 0.21 atm

CaX2 Ca
-20 Hfo_sOHCa2+
log f O2(g)

Ca2+ Calcite
-40

-60
FeT = 0.1 mol/kgw

0.01 mol/kgw NaCl CH4(g) > 1 atm

25oC
-80
2 4 6 8 10
pH

C:\PhreePlot\demo\Fe\hfoCaX_Ca3.ps

Shows how Fe, mostly as Fe2+, indirectly affects the dominant Ca speciation through Ca2+-
Fe2+ competition on the cation exchanger and on Hfo surface sites.
In principle, by combining one or more ion exchangers, some adsorbed species and some min-
eral species, it is possible to simulate the active species in many soils and sediments.
 Examples 295

# produces a set of predominance diagrams for Ca using the &lt;loop&gt; variable \

to systematically vary the total Fe in the system
# system contains a reduced Fe mineral

# Ca is present in solution, on an ion exchanger (eg clay), sorbed by Fe(OH)3(a) \

and potentially in a mineral (calcite)

SPECIATION
jobTitle “Fe-Ca-H2O redox”
# produce a predominance diagram using the hunt and track approach
calculationType ht1
calculationMethod 1
mainSpecies Ca Fe # diagram for Ca
# pH range adjusted through the &lt;x_axis&gt; variable
xmin 2.0
xmax 10.0
# f(O2(g)) range adjusted through the &lt;y_axis&gt; variable
ymin -80.0
ymax 0.0
# low resolution - jumps around on a 50 x 50 grid
resolution 50

# min, max and step size for FeT (the z-loop variable)
loopMin 0.0
loopMax 0.1
loopInt 5.0E-02

PLOT
plotTitle “Ca-Fe-Na with sorption and ion \
exchange&lt;br&gt;(includes Fe(OH)2(s) from llnl.dat)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
pxmax 10.0
# additional text on the plot
extraText “extratextFeOHCa.dat”

multipageFile F # each plot in a separate file

CHEMISTRY

include ‘ht1.inc’ # standard predominance calculating file

PHASES # temporarily add this to the database

Fe(OH)2(a) # from llnl.dat (NB approximate only - not checked for consistency)
Fe(OH)2 + 2.0000 H+ = + 1.0000 Fe++ + 2.0000 H2O
log_k 13.9045
-delta_H -95.4089 kJ/mol # Calculated enthalpy of reaction
-analytic -8.6666e+001 -1.8440e-002 7.5723e+003 3.2597e+001 1.1818e+002

SOLUTION 1
temp 25
pH 1.5
units mol/kgw
Fe(3) &lt;loop&gt; # FeT is controlled by the &lt;loop&gt; variable
Na 1e-2
Cl 1e-2 charge
Ca 1e-3 # CaT

EXCHANGE
-equilibrate 1
X 0.02 # 0.02 equiv of an exchanger

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # x-axis is pH
-force_equality true
O2(g) &lt;y_axis&gt; # y-axis is log fO2(g)
CO2(g) -2 0.3 # soil PCO2 - max CO2 supplied is 0.3 mol
 Examples 296

Fe(OH)3(a) 0 0 # possible minerals

Fe(OH)2(a) 0 0 # ... added to database above
Calcite 0 0

SURFACE 1
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2
END
Examples 297
 Examples 298

23 Acid mine drainage

Wheal Jane AMD

20
As
15
H3AsO4
Hfo_wH2AsO4
H2AsO4- Hfo_wHAsO -
10 4

Hfo_wOHAsO43-
pe

5
H3AsO3

0 Orpiment
Hao_wOHAsO43-
CH4(g) > 1 atm
AsS(OH)(HS)-
-5 H2AsO3-
21.6oC

-10
2 4 6 8 10
pH

C:\PhreePlot\demo\wj\wjAs_As1.ps

This example shows the results of a predominance calculation starting with a water with a
complex composition – it starts with some acid mine drainage (AMD). It is assumed that
there is adsorption of As by HFO (hydrous ferric oxide) and HAO (hydrous aluminium
oxide) and equilibrium with CO2(g) subject to a constraint on the total amount of CO2(g)
used (simulating poor pathways for gas migration).
The wateq4f.dat database is used for most of the thermodynamic data. There is no estab-
lished database for metal adsorption by HAO and so we have adjusted the HFO database for a
higher pzc and reduced specific surface area. This is only very approximate but is included to
show the possible impact of HAO. In this case, HAO becomes the dominant As species under
reducing conditions where HFO is no longer stable. An optimised HAO database is required
before taking the results of these calculations any further. This example is slow to calculate
because of the complexity of the calculations – there are many mineral and adsorbed species.
This diagram is just for As but a better appreciation of the reactions can be achieved by view-
ing the diagrams for other elements. The following example is a diagram for C calculated for
the same overall conditions as for As above.
 Examples 299

SPECIATION
jobTitle “WJ AMD”
Database “wateq4fhao.dat”
calculationType ht1
calculationMethod 1
mainSpecies As
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 200

PLOT
plotTitle “Wheal Jane AMD”
xtitle pH
yscale pe
pymin -10
lineWidth 0.1
minimumAreaForLabeling 1
extraText “extratextwj.dat”

CHEMISTRY

include ‘ht1.inc’

KNOBS
-conv 1e-12 # Default is 1e-12 for high_precision
-iterations 500 # Default is 100. Increase for some complex problems
# For complex systems, eg with several surfaces decrease to 2. Default is 10
-pe_step_size 2
PRINT
-reset false
reset true
PHASES
Hydrozincite
Zn5(OH)6(CO3)2 + 10H+ = 5Zn+2 + 2CO2 + 8H2O
log_k 45.75 #9.15
-delta_H -256.5 kJ #Preis & Gamsjager 2001

SOLUTION 1 WJ1 # complex water chemistry

temp 21.6
pH 3.5
pe 1.69 #100mV from other sample
# redox pe
units mg/L
density 1
# Alkalinity 12.7 as HCO3- #probably Al
C 10 as H2CO3 CO2(g) -2
Cl 179
F 44
S(6) 1390 as SO4 #reduction of this produces a lot of OH- 1390
Ca 191
Mg 43
Na 93
K 12
Al 25 #25 really
Si 11.0
Sr 1.87
Ba 0.052
Li 2.7
Fe 346
Mn 19.7
As 2.1
Zn 125
-water 1 # kg
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
 Examples 300

-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 0.01 # gives CH4 and can reduce to native As
Halite -6.34 10 # maintains Na in the system for functioning of Fix_H+

Al(OH)3(a)0 0
As_native0 0
Ba3(AsO4)20 0
Barite 0 0
Calcite 0 0
Dolomite0 0
Fe(OH)3(a)0 0
Fluorite0 0
Halloysite0 0
Hausmannite0 0
Hydrozincite0 0
Jarosite(ss)0 0
JarositeH0 0
Jarosite-Na0 0
Manganite0 0
Orpiment0 0
Pyrite 0 0
Pyrochroite0 0
Pyrolusite0 0
Realgar0 0
Rhodochrosite0 0
Siderite0 0
Sphalerite0 0
Strontianite0 0
ZnO(a)0 0

SURFACE 1
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300 # standard Hfo of D&M
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2

# glorified guesswork only

Hao_sOH Al(OH)3(a) equilibrium_phase 0.005 7800
Hao_wOH Al(OH)3(a) equilibrium_phase 0.2
END
Examples 301
 Examples 302

24 AMD (carbon)

Wheal Jane AMD

20
C
15 O2(g) > 0.21 atm

10
CO2 Hydrozincite
HCO3-
HCO3- Calcite
pe

5 HCO3-
Dolomite
Rhodochrosite Calcite

0
Siderite
CH4(g) > 1 atm
-5 Dolomite
21.6oC

-10
2 4 6 8 10
pH

C:\PhreePlot\demo\wj\wjC_C1.ps

This diagram has been calculated for the same conditions as in the previous example but is for
C rather than As. This has been done by changing the value of mainspecies from As to C.
The computations are slow because of the large number of mineral boundaries and possible
minerals.
There are many fields close together at high pH which makes labelling difficult. Some of the
species have several fields, e.g. HCO3- and the fields are small. Therefore the number of labels
plotted has been reduced by changing the minimumAreaForLabeling from 0.1% (the default
set in pp.set) to 1%.
 Examples 303

SPECIATION
jobTitle “WJ AMD”
# includes Hao surface definitions
Database “wateq4fhao.dat”
calculationType ht1
calculationMethod 1
mainSpecies C
xmin 2.0
xmax 10.0
ymin -80.0 # use PO2(g) to control redox
ymax 0.0
resolution 250

PLOT
plotTitle “Wheal Jane AMD”
xtitle pH
yscale pe # use pe scale
pymin -10 # minimum pe on plot
lineWidth 0.1
# don’t label small fields (diagram v complex)
minimumAreaForLabeling 1
extraText “extratextwj.dat”

CHEMISTRY

include ‘ht1.inc’

KNOBS
-conv 1e-12 # Default is 1e-12 for high_precision
-iterations 500 # Default is 100. Increase for some complex problems
# For complex systems, eg with several surfaces decrease to 2. Default is 10
-pe_step_size 2
PRINT
-reset false

PHASES
Hydrozincite # a possibility
Zn5(OH)6(CO3)2 + 10H+ = 5Zn+2 + 2CO2 + 8H2O
log_k 45.75 #9.15
-delta_H -256.5 kJ #Preis & Gamsjager 2001

SOLUTION 1 WJ1
temp 21.6
pH 3.5
pe 1.69 # 100 mV from other sample
# redox pe
units mg/L
density 1
# Alkalinity 12.7 as HCO3- # probably Al
C 10 as H2CO3 CO2(g) -2
Cl 179
F 44
S(6) 1390 as SO4 #reduction of this produces a lot of OH- 1390
Ca 191
Mg 43
Na 93
K 12
Al 25 # 25 really
Si 11.0
Sr 1.87
Ba 0.052
Li 2.7
Fe 346
Mn 19.7
As 2.1
Zn 125
-water 1 # kg
END

USE solution 1
 Examples 304

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 0.01 # gets CH4 and native As
Halite -6.34 10

Al(OH)3(a)0 0 # possible minerals

As_native0 0
Ba3(AsO4)20 0
Barite 0 0
Calcite 0 0
Dolomite0 0
Fe(OH)3(a)0 0
Fluorite0 0
Halloysite0 0
Hausmannite0 0
Hydrozincite0 0
Jarosite(ss)0 0
JarositeH0 0
Jarosite-Na0 0
Manganite0 0
Orpiment0 0
Pyrite 0 0
Pyrochroite0 0
Pyrolusite0 0
Realgar0 0
Rhodochrosite0 0
Siderite0 0
Sphalerite0 0
Strontianite0 0
ZnO(a)0 0

SURFACE 1 # two surfaces

Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2

# mainly guesswork but would be wrong to ignore completely

Hao_sOH Al(OH)3(a) equilibrium_phase 0.005 7800
Hao_wOH Al(OH)3(a) equilibrium_phase 0.2
END
Examples 305
 Examples 306

25 Ca-Mg-Zn-CO3

Ca-Mg-Zn-CO3

-1
C
Smithsonite
-2
HCO3-
log f CO2(g)

CO3 > 0.3 mol/kgw

-3 CO2
Hydrozincite

Calcite
-4 HCO3- Dolomite NaCO3-

CO32-

-5
4 6 8 10 12
pH

C:\PhreePlot\demo\CaMgZnC\carbonates_C1.ps

This example shows the use of a user-defined constraint to cut off part of the diagram, namely
the region at high pH where the total carbonate concentration is greater than 0.3 mmol/kg
water. This is done in the ht1combinedCO3.inc file by adding an additional constraint to the
type 3 (constraints) section of the ht1 code:
581 IF(TOT("C")/h2o > 0.3) THEN 582 ELSE 590
582 PUNCH "CO3 > 0.3 mol/kgw",TOT("C")/h2o
583 nout3 = nout3+1

This approach is exactly the same as that used for identifying the normal oxygen and hydrogen
constraints for defining the ‘water limits’. The area where the constraint applies is treated just
like any other field. It inherits its name from the column heading written by the
ht1combinedCO3.inc file and the colour from the fill colour dictionary.

The simplify keyword could be used to reduce the steps seen in some of the field boundaries.
This is done by changing the simplify setting from its default value of 1 to a greater value, say
2.
 Examples 307

SPECIATION
jobTitle “C predominance in the presence of \
selected Ca, Mg and Zn carbonates”
calculationType ht1
calculationMethod 1
mainSpecies C
xmin 4.0
xmax 12.0
ymin -5.0
ymax -1.0
resolution 200
PLOT
plotTitle “Ca-Mg-Zn-CO&lt;sub&gt;3&lt;/sub&gt;”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
CO&lt;sub&gt;2&lt;/sub&gt;(g)”
simplify 1.0
extraText “extratextcarbonates.dat”

CHEMISTRY

PHASES
Fix_H+
H+ = H+
log_k 0.0
Hydrozincite
Zn5(OH)6(CO3)2 + 10H+ = 5Zn+2 + 2CO2 + 8H2O
log_k 45.0 #9.0
-delta_H -256.5 kJ #Preis & Gamsjager 2001
SELECTED_OUTPUT
-high_precision true
-reset false

include ‘ht1combinedCO3.inc’ # includes CO2 constraint

SOLUTION 1
temp 25
pH 7
pe 5
redox pe
units mmol/kgw
density 1
-water 1 # kg
Ca 5
Mg 2
Zn 5
Cl 24 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
# ... but no Na present as a background electrolyte
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) -0.68 0.1
CO2(g) &lt;y_axis&gt; 2 # limit at high pH (corners)

# This is necessary to provide a source of Na for Fix_H+ when it goes -ve

Halite -12 0.1

#ZnCO3:H2O 0 0
Dolomite 0 0
Calcite 0 0
Smithsonite 0 0
#Aragonite 0 0
#Dolomite(d) 0 0
Magnesite 0 0
Zincite(c) 0 0
ZnO(a) 0 0
#Zn(OH)2-e 0 0
 Examples 308

#Zn(OH)2-g 0 0
#Zn(OH)2-b 0 0
#Natron 0 0
#Zn(OH)2-c 0 0
#Nesquehonite 0 0
#Zn(OH)2-a 0 0
Hydrozincite 0 0
#Huntite 0 0
Brucite 0 0
#Artinite 0 0
Portlandite 0 0
#Zn2(OH)3Cl 0 0
#Hydromagnesite 0 0
#Zn5(OH)8Cl2 0 0
#ZnCl2 0 0
#ZnMetal 0 0
END
Examples 309
 Examples 310

26 U-CO3

Uranium hydrolysis and redox

(low resolution=50)

0 O2(g) > 0.21 atm

UT = 10-6M
U
(UO2)3(OH)5+
-20 UO2OH+ UO (CO ) 2-
2 3 2
UO22+
UO2(CO3)34-
log f O2(g)

-40
U3O8(c)
U4O9(c)

-60
Uraninite(c)

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UCO3\UCO3_U1.ps

This is a low resolution plot (resolution = 50), hence the uneven boundaries. A low resolution
is useful for quickly seeing what is involved before replotting at a higher resolution.
 Examples 311

SPECIATION
jobTitle “Uranium redox and speciation”
calculationType “ht1”
calculationMethod 1
mainSpecies “U”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
loopmin -6
loopmax -6
loopint 0
looplogvar 1
resolution 50
PLOT
plotTitle “Uranium hydrolysis and \
redox&lt;br&gt;(low resolution=50)”
xtitle “pH”
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextUCO3.dat”

CHEMISTRY

include ‘ht1.inc’

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
U &lt;loop&gt;
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

B-UO2(OH)2 0 0
Gummite 0 0
Na4UO2(CO3)3 0 0
Nahcolite 0 0
Natron 0 0
Rutherfordine 0 0
Schoepite 0 0
Thermonatrite 0 0
Trona 0 0
U3O8(c) 0 0
U4O9(c) 0 0
UO2(a) 0 0
UO3(gamma) 0 0
Uraninite(c) 0 0
END
 Examples 312

27 Ca-Mg-CO3 at high T

Ca-Mg-CO3 at a given temperature

0
Ca
-2 Dolomite
log f CO2(g)

-4
Ca2+

Calcite
-6

T = 70oC
-8
5 6 7 8 9 10
pH

C:\PhreePlot\demo\Ca(t)\calcite_Ca8.ps

This example shows how temperature affects calcite-dolomite stability as a function of pH and
CO2(g) partial pressure. The results are shown as a series of predominance diagrams. The tem-
perature varies from 0 to 80oC in increments of 10oC. This is achieved by using loopMin,
loopMax and loopInt to define the looping variable <loop>. This loop variable is then equated
to <temp> in the numericTags definition (for convenience) and <temp> is substituted in the
appropriate place in the SOLUTION definition below.
The extraText file includes a line which uses <temp> to write the current temperature in the
bottom left of each plot.
The multiPageFile setting has been set to true so that only one plot file is recorded. This con-
tains the nine plots, page by page. The plot above is for the eighth plot which is for 70oC.
 Examples 313

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies Ca
xmin 5.0
xmax 10.0
ymin -8.0
ymax 0.0
loopMin 0
loopMax 80
loopInt 10
resolution 200
# change this for different temperatures
numericTags &lt;temp&gt; = &lt;loop&gt;

PLOT
multiPageFile true
plotTitle “Ca-Mg-CO&lt;sub&gt;3&lt;/sub&gt; at a \
given \
temperature”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
CO&lt;sub&gt;2&lt;/sub&gt;(g)”
# includes the &lt;temp&gt; tag for putting temperature on plot
extraText “extratextcalcite.dat”

CHEMISTRY

include ht1.inc # standard ‘hunt and track’ file

SOLUTION 1
temp &lt;temp&gt;
pH 7
units mmol/kgw
density 1
-water 1 # kg
Ca 1
Mg 1
Na 100
Cl 100
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
CO2(g) &lt;y_axis&gt; 1 # limit CO2 supply at high pH

Brucite 0 0
Calcite 0 0
Aragonite 0 0
Magnesite 0 0
Dolomite 0 0
#Dolomite(d) 0 0
Artinite 0 0
Nesquehonite 0 0
Portlandite 0 0
Huntite 0 0
Nahcolite 0 0
Hydromagnesite 0 0
Natron 0 0
Thermonatrite 0 0
Trona 0 0
END
 Examples 314

28 P-Ca-Mg-CO3(aq)

P-Fe-Al-Ca
(only aqueous species)

0 O2(g) > 0.21 atm

P
H2PO4-
FeH2PO42+
CaHPO4
-20
log f O2(g)

CaPO4-

-40

FeH2PO4+
FeHPO4
-60

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\P\Paq_P1.ps

A log fO2(g)-pH predominance diagram for phosphorus in the P-Fe-Al-Ca system. It is for
aqueous species only – this is determined by the lack of any P (or other) minerals in the
EQUILIBRIUM_PHASES data block. In that sense, the diagram is unrealistic since many minerals
would precipitate at various places within the domain explored. This can be seen in the next
example.
 Examples 315

SPECIATION
jobTitle “Fe-Al-Ca-P”
calculationType ht1
calculationMethod 1
mainSpecies “P”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 500

PLOT
plotTitle “P-Fe-Al-Ca&lt;br&gt;(only aqueous \
species)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextP.dat”

CHEMISTRY

include ‘ht1.inc’

# first simulation - initial solution calculation

SOLUTION 1
Temp 20
pH 1.8
units mol/kgw
density 1
P 1e-3
Ca 1e-1
Fe 1e-1
Al 1e-1
Na 1e-1
Cl 1e-1 charge
END

# second simulation - reaction and equilibration

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt;
CO2(g) -3.5 # no minerals - aqueous species only
END
 Examples 316

29 P-Ca-Mg-CO3 (with solids)

P-Fe-Al-Ca
(including mineral and adsorbed species)

0 O2(g) > 0.21 atm

P
-20

H2PO4-
log f O2(g)

HPO42-
Hydroxyapatite
NaHPO4-
-40

-60
FeH2PO4+

Vivianite

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\P\P_P1.ps

This diagram is for similar conditions to the previous example but crucially a variety of miner-
als has been allowed to precipitate and P adsorption onto HFO has been taken into account.
There has been a deliberate policy of only allowing the more soluble (less stable) minerals to
precipitate so for example, the more stable iron oxides such as hematite and goethite have been
removed from consideration by commenting them out.
Adsorbed P dominates in the region where Fe(OH)3(a) is stable. Under acid, oxidising condi-
tions where Fe(OH)3(a) dissolves, strengite (Fe(III)PO4.2H2O) is stable. Under reducing con-
ditions, vivianite (Fe(II)3(PO4)2.8H2O) and hydroxyapatite (Ca5(PO4)3OH) precipitate.
Dissolved P species only predominate under some of the most extreme conditions of high pH
and strongly reducing conditions The presence of CO2(g) leads to calcite precipitation above
pH 7.6 which ultimately leads to the lowering of the Ca2+ activity to such an extent that
hydroxyapatite becomes unstable.
 Examples 317

SPECIATION
jobTitle “Fe-Al-Ca-P”
calculationType ht1
calculationMethod 1
mainSpecies “P”
xmin 2.0 # x-axis calculation range
xmax 10.0
ymin -80.0 # y-axis calculation range
ymax 0.0
resolution 500 # tracks on a 500 x 500 grid
PLOT
plotTitle “P-Fe-Al-Ca&lt;br&gt;(including mineral \
and adsorbed species)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextP.dat”

CHEMISTRY

include ‘ht1.inc’

# first simulation - initial solution calculation

SOLUTION 1
Temp 20
pH 1.8
units mol/kgw
density 1
P 1e-3
Ca 1e-1
Fe 1e-1
Al 1e-1
Na 1e-1
Cl 1e-1 charge
END

# second simulation - reaction and equilibration

USE solution 1

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # fix the pH
-force_equality true
O2(g) &lt;y_axis&gt;
CO2(g) -3.5 # atmospheric PCO2(g)

# choose the minerals you want (from the database)

Hydroxyapatite 0 0
# Magnetite 0 0
Hematite 0 0
Vivianite 0 0
# Fe3(OH)8 0 0
# Goethite 0 0
# Fe(OH)2.7Cl.3 0 0
# Diaspore 0 0
# Gibbsite 0 0
# Maghemite 0 0
# Boehmite 0 0
Al(OH)3(a) 0 0
Fe(OH)3(a) 0 0 # assumed the metastable Fe-oxide mineral
Portlandite 0 0
Strengite 0 0
Calcite 0 0
Siderite 0 0

SURFACE
# phosphate adsorbed by Hfo
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2
END
Examples 318
Examples 319
 Examples 320

30 Mn-CO2-H2O (no minerals)

Mn-CO2-H2O
(CO2(g) but no minerals)

15 O2(g) > 0.21 atm

Mn
MnO4-

Mn2+
5
pe

MnCO3

-5 CH4(g) > 1 atm

-15
2 4 6 8 10
pH

C:\PhreePlot\demo\Mn\Mn_Mn1.ps

This is a pe-pH predominance diagram for Mn in which no minerals have been allowed to
precipitate. The system is in equilibrium with CO2(g) at close to its atmospheric partial pres-
sure making MnCO3(aq) stable at high pH where carbonate activities are high.
Permanganate (MnO4-) becomes stable in a small region at high pH and under strongly oxi-
dising conditions.
This is an example where the hunt and track algorithm has to automatically readjust the reso-
lution in order to track the boundaries properly. It increases the resolution from 400 to 746.
 Examples 321

# Mn predominance diagram for aqueous species only - CO2 included

SPECIATION
jobTitle “Mn-CO2-H2O”
calculationType ht1
calculationMethod 1
mainSpecies “Mn” # diagram for Mn
xmin 2.0 # pH range 2-10
xmax 10.0
ymin -90.0 # log f(O2(g)) range -90 to 0
ymax 0.0

resolution 300 # track on a 300 x 300 grid

PLOT
plotTitle \
“Mn-CO&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(CO&lt;sub&gt \
;2&lt;/sub&gt;(g) but no minerals)”
xtitle pH
# drive redox with fO2(g) but use pe for plot yscale
yscale pe
pymin -15 # force plot y min at pe = -15
extraText “extratextMn.dat”

CHEMISTRY

include ‘ht1.inc’ # standard predominance calculating code

# first simulation - initial solution calculation

SOLUTION 1
Temp 20
pH 1.8 # initial pH is less than pHmin so adding NaOH should always work
units mol/kgw
Mn 1e-2 # total Mn
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

# second (final) simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # add NaOH to get to specified logH
-force_equality true
O2(g) &lt;y_axis&gt;
CO2(g) -3.5 1 # NB no minerals specified
END
 Examples 322

31 Mn-H2O (with minerals)

Mn-H2O
(oxide minerals included)

15 O2(g) > 0.21 atm

Mn
Pyrolusite

Manganite
5
Mn2+
pe

Hausmannite

-5 Pyrochroite
H2(g) > 1 atm

-15
2 4 6 8 10
pH

C:\PhreePlot\demo\Mn\Mnox1_Mn1.ps

This is somewhat similar to the previous example except that minerals have been allowed to
precipitate and no CO2(g) is present. It shows the stability region of the various Mn oxides,
some of which contain Mn in a mixed valence state.
 Examples 323

# Mn predominance diagram including Mn oxide minerals (see Mn.ppi for aqueous \

species only)

SPECIATION
jobTitle “Mn-CO2-H2O”
calculationType ht1
calculationMethod 1
mainSpecies “Mn” # diagram for Mn
xmin 2.0 # pH range 2-10
xmax 10.0
ymin -90.0 # log f(O2(g)) range -90 to 0
ymax 0.0

resolution 400 # track on a 400 x 400 grid

PLOT
plotTitle \
“Mn-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(oxide minerals included)”
xtitle pH
# drive redox with fO2(g) but use pe for plot yscale
yscale pe
pymin -15 # force plot y min at pe = -15
extraText “extratextMn.dat”

CHEMISTRY

include ‘ht1.inc’ # standard predominance calculating code

# first simulation - initial solution calculation

SOLUTION 1
Temp 20
pH 1.8 # initial pH is less than pHmin so adding NaOH should always work
units mol/kgw
Mn 1e-2 # total Mn
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

# second (final) simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt;

Pyrochroite 0 0 # this list of minerals is considered

Manganite 0 0
Pyrolusite 0 0
Nsutite 0 0
Birnessite 0 0
Bixbyite 0 0
Hausmannite 0 0
END
 Examples 324

32 Mn-CO2-H2O

Mn-H2O
(oxide minerals included)

15 O2(g) > 0.21 atm

Mn
Pyrolusite

Manganite
Mn2+
5
pe

Rhodochrosite

-5 CH4(g) > 1 atm

-15
2 4 6 8 10
pH

C:\PhreePlot\demo\Mn\Mnox2_Mn1.ps

This is similar to the previous example but in this case, CO2(g) is present. This leads to the
formation of rhodochrosite (MnCO3) at high pH and under moderately to strongly reducing
conditions. In this case, Hausmannite and Pyrochroite are no longer predominant Mn miner-
als.
The CO2(g) is reduced to CH4(g) under strongly reducing conditions.
 Examples 325

# Mn predominance diagram including Mn oxide and carbonate minerals (see Mn.ppi \

for aqueous species only)

SPECIATION
jobTitle “Mn-CO2-H2O”
calculationType ht1
calculationMethod 1
mainSpecies “Mn” # diagram for Mn
xmin 2.0 # pH range 2-10
xmax 10.0
ymin -90.0 # log f(O2(g)) range -90 to 0
ymax 0.0

resolution 400 # track on a 400 x 400 grid

PLOT
plotTitle \
“Mn-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(oxide minerals included)”
xtitle pH
# drive redox with fO2(g) but use pe for plot yscale
yscale pe
pymin -15 # force plot y min at pe = -15
extraText “extratextMn.dat”

CHEMISTRY

include ‘ht1.inc’ # standard predominance calculating code

# first simulation - initial solution calculation

SOLUTION 1
Temp 20
pH 1.8 # initial pH is less than pHmin so adding NaOH should always work
units mol/kgw
Mn 1e-2 # total Mn
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

# second (final) simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt;
CO2(g) -3.5 1 # atmospheric pCO2(g) - include up to 1 mole CO2 max

MnCl2:4H2O 0 0
Pyrochroite 0 0
Rhodochrosite 0 0
Rhodochrosite(d) 0 0
Manganite 0 0
Pyrolusite 0 0
Nsutite 0 0
Birnessite 0 0
Bixbyite 0 0
Hausmannite 0 0
END
 Examples 326

33 Pu-F-H2O

Plutonium hydrolysis and redox

(using llnl.dat database)

0 O2(g) > 0.21 atm

PuO2(CO3)22-
PuO2F4 2-
PuO2F3-
Pu
-20
PuF22+
log f O2(g)

-40 PuO2

-60 Pu3+

PuT = 10-12M

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\Pu\Pu_Pu1.ps

This log fO2(g)-pH predominance diagram for plutonium (10-12 mol/kgw PuT) in the pres-
ence of fluoride and carbonate demonstrates the extreme insolubility of PuO2 under a wide
range of conditions. It also shows that fluoride and carbonate form strong complexes with
Pu(IV) and can maintain relatively high concentrations of Pu in solution. Reduction of
Pu(IV) to Pu(III) under reducing and acidic conditions also enhances Pu solubility.
 Examples 327

SPECIATION
jobTitle “Plutonium redox and speciation”
Database llnl.dat
epsi T
calculationType ht1
calculationMethod 1
mainSpecies “Pu”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 100

PLOT
plotTitle “Plutonium hydrolysis and \
redox&lt;br&gt;(using llnl.dat database)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
labelSize 2.0
simplify 10
extraText “extratextPu.dat”

CHEMISTRY

include ‘ht1.inc’

KNOBS
# -conv 1e-12 # Default is 1e-12 \
for high_precision but noisy boundaries - jump across
# -iterations 500 # Default is 100. \
Increase for some complex problems
# -pe_step_size 10 # For complex \
systems, eg with several surfaces decrease to 2. Default is 10

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
Pu 1e-12
Na 1e-1
Cl 1e-1
S 1e-3
F 1e-3
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

PuO2 0 0
Pu(OH)4 0 0
Nahcolite 0 0
Natron 0 0
Na2CO3:7H2O 0 0
Thermonatrite 0 0
Pu(OH)3 0 0
PuO2OH(am) 0 0
Na2CO3 0 0
PuO2(OH)2 0 0
C 0 0
Pu2O3 0 0
Na 0 0
Na2O 0 0
Pu 0 0
END
 Examples 328

34 U-C-H2O (wateq4f.dat)

Uranium hydrolysis and redox: wateq4f.dat

0 O2(g) > 0.21 atm

UT = 10-6M
U
(UO2)3(OH)5+
-20 UO2OH+ UO (CO ) 2-
2 3 2
UO22+
UO2(CO3)34-
log f O2(g)

-40
U3O8(c)
U4O9(c)

-60
Uraninite(c)

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UCO3\UCO3wq_U1.ps

This is one of three log fO2(g)-pH predominance diagrams for U (10-6 mol/kgw UT) which
demonstrate how predominance diagrams provide a useful way of comparing thermodynamic
databases, here made with wateq4f.dat.
Uranium speciation is strongly dependent on the pH and redox conditions with the highly
insoluble mineral Uraninite dominating reducing conditions. Uranium(VI) forms strong
complexes with carbonate which enhances U solubility in the presence of CO2(g) and high
pH.
The extraText file, extratextUCO3.dat, also adds the text in the top left corner of the diagram
and demonstrates features such as subscripts, superscripts, italics, line breaks (<br>) and the
use of multiline input through the use of the \ continuation character..
 Examples 329

SPECIATION
jobTitle “Uranium redox and speciation”
Database “wateq4f.dat”
calculationType “ht1”
calculationMethod 1
mainSpecies “U”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
loopmin -6
loopmax -6
loopint 0
looplogvar 1
resolution 500
PLOT
plotTitle “Uranium hydrolysis and redox: wateq4f.dat”
xtitle “pH”
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextUCO3.dat”

CHEMISTRY

include ‘ht1.inc’

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
U 1e-6
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Uraninite(c) 0 0
UO2(a) 0 0
U4O9(c) 0 0
Schoepite 0 0
B-UO2(OH)2 0 0
UO3(gamma) 0 0
Nahcolite 0 0
Gummite 0 0
Rutherfordine 0 0
Natron 0 0
Thermonatrite 0 0
U3O8(c) 0 0
Trona 0 0
Na4UO2(CO3)3 0 0
END
 Examples 330

35 U-C-H2O (NAPSI)

Uranium hydrolysis and redox (NAPSI)

0 O2(g) > 0.21 atm

UT = 10-6M
U
-20
UO2OH+
UO22+ (UO2)2CO3(OH)3-
log f O2(g)

UO2(CO3)22-
UO2(CO3)34-
-40

-60
UO2+
U(OH)4
UOH3+
CH4(g) > 1 atm
-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UCO3\UCO3psi_U1.ps

The same as for the previous diagram but here made with the NAPSI database.
 Examples 331

SPECIATION
jobTitle “Uranium redox and speciation”
Database “NAPSI_290502(260802).DAT”
calculationType “ht1”
calculationMethod 1
mainSpecies “U”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
loopmin -6
loopmax -6
loopint 0
looplogvar 1
resolution 500

PLOT
plotTitle “Uranium hydrolysis and redox (NAPSI)”
xtitle “pH”
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextUCO3.dat”

CHEMISTRY

include ‘ht1.inc’

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
U 1e-6
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

END
 Examples 332

36 U-C-H2O (llnl.dat)

Uranium hydrolysis and redox: llnl.dat

0
UT = 10-6M
U
-20
UO2(OH)2
UO22+
UO2(CO3)34-
log f O2(g)

-40

UO2.25

-60
Uraninite

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UCO3\UCO3llnl_U1.ps

The same as for the previous diagram but here made with the llnl.dat database.
Note that one of the fields in the centre of the diagram has not been labelled (light grey,
UO2.3333(beta)) because it occupies less than the minimum area required to plot a label (as
given by the keyword minimumAreaForLabeling which is 1 % by default).
This sequence of diagrams demonstrates the quite large differences in speciation models for U
in the various databases. This applies not only to the minerals but also the aqueous species.
 Examples 333

SPECIATION
jobTitle “Uranium redox and speciation”
Database “llnl.dat”
calculationType “ht1”
calculationMethod 1
mainSpecies “U”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
loopmin -6
loopmax -6
loopint 0
looplogvar 1
resolution 500
PLOT
plotTitle “Uranium hydrolysis and redox: llnl.dat”
xtitle “pH”
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
minimumAreaForLabeling 1.0
extraText “extratextUCO3.dat”

CHEMISTRY

include ‘ht1.inc’

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
U 1e-6
Na 1e-1
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Ice 0 0
Uraninite 0 0
UO2.25 0 0
UO2.25(beta) 0 0
UO2.3333(beta) 0 0
UO2(am) 0 0
Schoepite 0 0
UO3:2H2O 0 0
UO2(OH)2(beta) 0 0
Schoepite-dehy(.9) 0 0
UO3:.9H2O(alpha) 0 0
Schoepite-dehy(.85) 0 0
Schoepite-dehy(1.0) 0 0
UO2ClOH:2H2O 0 0
Schoepite-dehy(.648) 0 0
UO2.6667 0 0
UO2Cl 0 0
Schoepite-dehy(.393) 0 0
UO3(gamma) 0 0
UO3(beta) 0 0
UO3(alpha) 0 0
UO2Cl2:3H2O 0 0
NaUO3 0 0
UOCl2 0 0
UO2Cl2:H2O 0 0
U5O12Cl 0 0
UO2Cl2 0 0
 Examples 334

Na2U2O7 0 0
UOCl3 0 0
Na2UO4(alpha) 0 0
(UO2)2Cl3 0 0
UOCl 0 0
UCl4 0 0
UCl3 0 0
U2O2Cl5 0 0
Na 0 0
UCl5 0 0
Na3UO4 0 0
Na2O 0 0
UCl6 0 0
U 0 0
UH3(beta) 0 0
END
Examples 335
 Examples 336

37 U-Fe-C-H2O

U-Fe-C-H2O
(with adsorbed speciation)

20
U
15 O2(g) > 0.21 atm

10 UO22+
(Hfo_wO)2UO2
pe

5 UO2(CO3)34-
UO2OH+

3+ UO2+ (UO2)2CO3(OH)3-
0UOH
UO2(s)
CH4(g) > 1 atm
-5 log UT = -6
log FeT = -4
log P CO2(g) = -3.5
T = 25o C
Database = NAPSI_290502(260802).DAT/Luo et al. (2007)
-10
2 3 4 5 6 7 8 9
pH

C:\PhreePlot\demo\Uhfo\Uhfo_U1.ps

This is a uranium (log UT = -9) pe-pH predominance diagram with mineral formation and
adsorption of U and carbonate on hydrous ferric oxide (HFO). There is also competition
from carbonate complexation in solution at high pH.
The U adsorption is approximate in the sense that the U adsorption parameters have been
taken from a source that is not necessarily consistent with the aqueous speciation database
used here (see the code below for details). In principle, consistent databases should be used
although this is often not possible and can be difficult to maintain.
Carbonate species are also adsorbed by HFO although they never become the dominant C
species in the system. Maximum carbonate adsorption is at about pH 6.5.
 Examples 337

SPECIATION
jobTitle “Uranium redox and speciation”
mainSpecies “U”
calculationType ht1
calculationMethod 1
# relatively recently revised database for U
database NAPSI_290502(260802).DAT
fillColorDictionary “fillcolor.dat”
xmin 2.0 # minimum pH
xmax 9.0 # maximum pH
# minimum PO2(g) to generate variable redox
ymin -75.0
ymax 0.0 # maximum PO2(g)
resolution 400

PLOT
plotTitle \
“U-Fe-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(with adsorbed speciation)”
xtitle pH
yscale pe # use pe for the y-scale
pymin -10.0 # on the pe scale
extraText “extratextUhfo.dat”

CHEMISTRY

TITLE U Sorption to ferrihydrite according to DLM and database derived and used by
Luo et al. Journal of Contaminant Hydrology 92, 129–148 (2007)

include ‘U-Hfo.dat’
include ‘ht1.inc’

# first simulation - initial solution calculations

SOLUTION 1
temp 25
pH 1.8 # initial pH is just less than pHmin
units mol/kgw
Na 0.1
Fe 1e-4
U(6) 1e-6
Cl 0.1 charge

EQUILIBRIUM_PHASES
Fe(OH)3(am) 0 0 # NB name of related mineral is different from wateq4f.dat

SURFACE 1
Hfo_sOH Fe(OH)3(am) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(am) equilibrium_phase 0.2
SAVE surface 1
END

# second simulation - loops on the final simulation

USE solution 1
USE surface 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Graphite 0 0
UO2(s) 0 0
#Goethite 0 0
Siderite 0 0
FeCO3(pr) 0 0
#Fe(OH)3(mic) 0 0
Schoepite 0 0
Rutherfordine 0 0
Fe(OH)3(am) 0 0
#Fe(cr) 0 0
#Hematite 0 0
 Examples 338

#Magnetite 0 0

END
Examples 339
 Examples 340

38 U-Fe-C (risk colours)

U-Fe-C-H2O
(with adsorbed speciation)
Reduction/oxidation potential (pe)

20
U
15 Oxygen

10
May be mobile
Mobile

0
Immobile
log UT = -6 Methane
-5 log FeT = -4
log P CO2(g) = -3.5
T = 25o C
Database = NAPSI_290502(260802).DAT/Luo et al. (2007)

-10
2 3 4 5 6 7 8 9
Acidity (pH)

C:\PhreePlot\demo\Uhfo\Uhfo(risk)_U1.ps

The same as the previous example but with labelling and colouring more appropriate for con-
veying the risk of uranium mobilization to a non-technical audience.
Dissolved species are coloured red (‘Mobile’); adsorbed species are coloured orange (‘May be
mobile’) and the mineral species are coloured green (‘Immobile’).
Many of the axis settings have also been changed.
 Examples 341

SPECIATION
jobTitle “Uranium redox and speciation”
mainSpecies “U”
calculationType ht1
calculationMethod 1
# relatively recently revised database for U
database NAPSI_290502(260802).DAT
fillColorDictionary “fillcolor.dat”
xmin 2.0 # minimum pH
xmax 9.0 # maximum pH
# minimum PO2(g) to generate variable redox
ymin -75.0
ymax 0.0 # maximum PO2(g)
resolution 400

PLOT
plotTitle \
“U-Fe-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(with adsorbed speciation)”
xtitle “Acidity (pH)”
ytitle “Reduction/oxidation potential (pe)”
yscale pe # use pe for the y-scale
pymin -10.0 # on the pe scale

plotTitleColor red
plotTitleSize 5

axisNumberSize 4
axisNumberColor “blue”
axisTitleSize 4
axisTitleColor “blue”
axisLineWidth 0.4
axisLineColor “blue”

tickSize 3
tickColor “blue”

info “nd” “blue”

extraText “extratextUhfo(risk).dat”

CHEMISTRY

TITLE U Sorption to ferrihydrite according to DLM and database derived and used by
Luo et al. Journal of Contaminant Hydrology 92, 129–148 (2007)

include ‘U-Hfo.dat’
# this uses simple ‘traffic light’ classification for aqueous, adsorbed and mineral
# phases
include ‘risk.inc’

# first simulation - initial solution calculations

SOLUTION 1
temp 25
pH 1.8 # initial pH is just less than pHmin
units mol/kgw
Na 0.1
Fe 1e-4
U(6) 1e-6
Cl 0.1 charge

EQUILIBRIUM_PHASES
Fe(OH)3(am) 0 0 # NB name of related mineral is different from wateq4f.dat

SURFACE 1
Hfo_sOH Fe(OH)3(am) equilibrium_phase 0.005 53300
Hfo_wOH Fe(OH)3(am) equilibrium_phase 0.2
SAVE surface 1
END

# second simulation - loops on the final simulation

 Examples 342

USE solution 1
USE surface 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Graphite 0 0
UO2(s) 0 0
#Goethite 0 0
Siderite 0 0
FeCO3(pr) 0 0
#Fe(OH)3(mic) 0 0
Schoepite 0 0
Rutherfordine 0 0
Fe(OH)3(am) 0 0
#Fe(cr) 0 0
#Hematite 0 0
#Magnetite 0 0

END
Examples 343
 Examples 344

39 U-F-P (U)

U complexation in the presence of F and P

(loops on the main species)

0 O2(g) > 0.21 atm

U
UO2F+
-20 (Hfo_sO)2UO2
(Hfo_sO)2UO2CO32-
log f O2(g)

UO2F3- UO2(CO3)34-
-40 UO2F2

(Hfo_wO)2UO2

-60
UF4
UO2(s)

UT = 10-6M CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UPF\UPF_U1.ps

This is an example of a predominance diagram for U in a system containing many U species

including U adsorbed to HFO and other components. The input file also demonstrates how
to generate a number of diagrams (U, P, F, Fe, C) for the same system. The next two examples
give the corresponding fluoride and phosphorus outputs for this system.
The calculations were made using the NAPSI_290502(260802).DAT database for most species
but since this does not include surface species, it was combined with a revised database for
HFO-U surface species. This is found in U.dat. These data from Luo et al. (2007) use the
Dzombak and Morel (1990) DLM but the surface reaction for U is described in terms of
bidentate binding.
The NAPSI database does not include such an extensive set of minerals as the wateq4f.dat
database and is completely lacking in some trace elements. Therefore some second order inter-
actions may be missed.
The total uranium concentration is set by the loop variable although in this case only one
 Examples 345

value is selected, -6. This is converted to 10-6 before it is substituted by setting loopLogVar to
1. This value is then used in the SOLUTION data block with the <loop> tag.
 Examples 346

SPECIATION
jobTitle “Uranium complexation”
database NAPSI_290502(260802).DAT
calculationType ht1
calculationMethod 1
# calculate diagrams for these 5 elements
mainSpecies U P F Fe C
# minimum pH etc used to generate the plot
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
loopMin -6.0
loopMax -6.0
loopInt 1
loopLogVar 1
resolution 200

PLOT
plotTitle “U complexation in the presence of F and \
P&lt;br&gt;(loops on the main species)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
xoffset 20.0
yoffset 150.0
labelSize 1.7
extraText “extratextUPF.dat”
# make one ps file per element not one file overall
multiPagefile f

CHEMISTRY

# revised database for U surface species - also other surface species

include ‘U-Hfo.dat’
include ‘ht1.inc’ # standard code to generate predominance diagrams

SOLUTION 1
temp 25
pH 1.3
units mol/kgw
U &lt;loop&gt;
Na 1e-1
Cl 1e-1
F 1e-2
S(6) 1e-2
P 1e-4
Fe 1e-2

EQUILIBRIUM_PHASES 1
Fe(OH)3(am) 0 0
END

# second simulation - loops on the final simulation

#PRINT; reset true

USE solution 1
USE surface 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1

# PSI database
Pyrite 0 0
Troilite 0 0
UF4:2.5H2O(cr) 0 0
Graphite 0 0
 Examples 347

S(rhomb) 0 0
#Goethite 0 0
UO2(s) 0 0
#Fe(OH)3(mic) 0 0
Fe(cr) 0 0
Fe(OH)3(am) 0 0
Siderite 0 0
FeCO3(pr) 0 0
Chernikovite 0 0
#Hematite 0 0
Schoepite 0 0
#Magnetite 0 0
Melanterite 0 0
Rutherfordine 0 0
U(OH)2SO4(cr) 0 0
(UO2)3(PO4)2:4H2O(cr) 0 0
END
 Examples 348

40 U-F-P (F)

U complexation in the presence of F and P

(loops on the main species)

0 O2(g) > 0.21 atm

F
FeF2+

-20 FeF2+
FeF3
log f O2(g)

-40 F-

HF
-60

UT = 10-6M CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UPF\UPF_F1.ps

The fluoride view of the previous example.

Examples 349
 Examples 350

41 U-F-P (P)

U complexation in the presence of F and P

(loops on the main species)

0 O2(g) > 0.21 atm

P
Hfo_wH2PO4
-20
Hfo_wHPO4-
Hfo_wPO42-
log f O2(g)

-40
H2PO4-

-60
HPO42-

UT = 10-6M CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\UPF\UPF_P1.ps

The phosphorus view of the previous example. Phosphorus adsorption is calculated using the
DLM with default Dzombak & Morel (1990) model parameters.
Examples 351
 Examples 352

42 Cu-S-C (‘island’ not found with ‘ht1’)

Cu-S-C-H2O
(no minerals)

0 O2(g) > 0.21 atm

Cu
-20 Cu2(OH)22+ Cu(OH)2
Cu2+ Cu(CO3)22-
log f O2(g)

-40

-60 CuCl2-

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\island\CuSht1_Cu1.ps

This example was computed with the same conditions as in the previous example but used the
‘ht1’ approach rather than the ‘grid’ approach (the only difference was in the calculation-
Method setting; the same ht1.inc file was used for generating the predominant boundaries
in both diagrams.
This diagram has failed to identify the Cu+ field since it is an ‘island’ and is not accessible by
hunting along the domain boundaries or tracking internal boundaries. This field is found
using the ‘grid’ approach which provides a more reliable but slower approach.
 Examples 353

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies Cu
xmin 2
xmax 10
ymin -80
ymax 0
resolution 100
PLOT
plotTitle \
“Cu-S-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(no minerals)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText extratextCuS.dat
CHEMISTRY
include ‘ht1.inc’
SOLUTION 1
Temp 20
pH 1.8
units mol/kgw
Cu 1e-1
S(6) 1e-1
Na 1e-1
Cl 1.032e-1
END
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0
END
 Examples 354

43 Cu-S-C (simplification factor = 1)

Cu-S-C-H2O
(simplify = 1)

0 •• • O2(g)
• > 0.21 atm• ••

Cu
-20 Brochantite Tenorite
Antlerite
Cu2+
log f O2(g)

-40 •
••
• •
••
••
••
• Cuprite
• Nantokite • •
• • • • •• ••
•• •• •• CuMetal
-60 •• • • • •
• •• •
•• •• ••
•• •• ••
•• •• ••
• • • • • •• • Chalcocite ••
• •••••Djurleite
•• • •
•• • • •
•• •• •
Anilite • • • •••• • •
BlaubleiI • • • • •••
• •• •• •
•
• • • •••
••
CH4(g) > 1 atm
-80 • •

2 4 6 8 10
pH

C:\PhreePlot\demo\CuS\CuS_Cu1.ps

The regular ‘jagged’ lines for the Chalcocite-Djurleite and other boundaries, highlighted by
the red symbols (pointSize = 1.5), are because of the low angle of the slopes of the boundaries
in relation to the chosen resolution (resolution = 400). The resolution controls the spacing of
the imaginary grid where evaluations take place. Straight boundaries with a low angle there-
fore tend to result in regular steps. This is not a property of the underlying speciation program
but of the hunt and track algorithm used. The regular steps can be eliminated by increasing
the simplification factor (see the next example). This does not require recalculation of the data
just replotting (calculationType = 3) with a larger value of the simplification factor, simplify
which is set to 1 here. Alternatively, recalculating with a higher resolution will reduce the step
size.
Sometimes boundaries, especially mineral boundaries, can be ‘noisy’. This is a reflection of the
speciation program but again the boundaries can be smoothed by increasing the simplification
factor.
 Examples 355

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies Cu
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 400
PLOT
plotTitle \
“Cu-S-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(simplify = 1)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
# sets the sizes of the symbols used for an intermediate plot and
trackSymbolSize 1.5 1.5
# custom plot label anchor symbols
# normal default of 1 - but note the jaggies in some of the low-angled boundaries
simplify 1
extraText “extratextCuS.dat”

CHEMISTRY

include ‘ht1.inc’ # standard hunt and track file

SOLUTION 1
temp 20
pH 1.8
units mol/kgw
Cu 1e-1 # total concns
S(6) 1e-1
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0 # includes carbonate species

Chalcocite 0 0 # permitted minerals

Djurleite 0 0
Anilite 0 0
BlaubleiII 0 0
BlaubleiI 0 0
Covellite 0 0
CuMetal 0 0
Sulfur 0 0
Nantokite 0 0
Cuprite 0 0
Tenorite 0 0
Cu(OH)2 0 0
Melanothallite 0 0
Nahcolite 0 0
Atacamite 0 0
CuCO3 0 0
Natron 0 0
Thermonatrite 0 0
Thenardite 0 0
Mirabilite 0 0
Chalcanthite 0 0
Malachite 0 0
CuSO4 0 0
Cu2SO4 0 0
Trona 0 0
CuOCuSO4 0 0
Antlerite 0 0
 Examples 356

Azurite 0 0
Brochantite 0 0
Langite 0 0

END
Examples 357
 Examples 358

44 Cu-S-C (simplification factor = 3)

Cu-S-C-H2O
(simplify = 3)

0 •• • O2(g)
• > 0.21 atm• ••

Cu
-20 Brochantite Tenorite
Antlerite
Cu2+
log f O2(g)

-40 •
•
• •
•
••••
Cuprite
• Nantokite • •
• • CuMetal
-60 ••
Chalcocite
•
Djurleite •

BlaubleiI Anilite •
• ••
• • •••••
CH4(g) > 1 atm
-80 • •

2 4 6 8 10
pH

C:\PhreePlot\demo\CuS\CuS2_Cu1.ps

This is the same example as the previous example except that it uses a greater value of the sim-
plification factor, simplify, compared with the previous example has eliminated the obvious
stepping. The value of ‘simplify’ is normally set to 1. Values greater than 1 reduce the number
of vertices used to draw the polygons while a value less (normally in the range 0.1 to 1) will
give more. A value of 0 does no line simplification at all.
A value of 3 was chosen here which almost completely eliminates the intermediate points
although some of the boundaries seem unnaturally sharp suggesting that a greater resolution
would also help. Note that it is not necessary to recalculate the points in order to change the
simplification but it is necessary to use calculationMethod 3 not 2.
 Examples 359

SPECIATION
calculationType ht1
calculationMethod 1
mainSpecies Cu
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 400
PLOT
plotTitle \
“Cu-S-C-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(simplify = 3)”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
# sets the sizes of the symbols used for an intermediate plot and
trackSymbolSize 1.5 1.5
# custom plot label anchor symbols
# increase smoothing of field boundaries above normal default of 1
simplify 3
extraText “extratextCuS.dat”

CHEMISTRY

include ‘ht1.inc’ # standard hunt and track file

SOLUTION 1
temp 20
pH 1.8
units mol/kgw
Cu 1e-1 # total concns
S(6) 1e-1
Na 1e-1 # background electrolyte
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0 # includes carbonate species

Chalcocite 0 0 # permitted minerals

Djurleite 0 0
Anilite 0 0
BlaubleiII 0 0
BlaubleiI 0 0
Covellite 0 0
CuMetal 0 0
Sulfur 0 0
Nantokite 0 0
Cuprite 0 0
Tenorite 0 0
Cu(OH)2 0 0
Melanothallite 0 0
Nahcolite 0 0
Atacamite 0 0
CuCO3 0 0
Natron 0 0
Thermonatrite 0 0
Thenardite 0 0
Mirabilite 0 0
Chalcanthite 0 0
Malachite 0 0
CuSO4 0 0
Cu2SO4 0 0
Trona 0 0
CuOCuSO4 0 0
Antlerite 0 0
 Examples 360

Azurite 0 0
Brochantite 0 0
Langite 0 0

END
Examples 361
 Examples 362

45 Cu-EDTA-H2O

Cu-EDTA
(using minteq.v4.dat)

20
Cu
15 O2(g) > 0.21 atm

CuH2(Edta)
10 CuH(Edta)-

Cu(Edta)2-
pe

5
CuCl2-
0

CuMetal
-5
H2(g) > 1 atm
CuT = 10-4M
EDTA = 10-4M
-10
2 4 6 8 10
pH

C:\PhreePlot\demo\Cuedta\Cuedta_Cu1.ps

The wateq4f.dat database does not contain any data for EDTA so it is necessary to use the
minteq.v4.dat database which does. However, it is also necessary to add data for the aqueous
solubility of H2(g) since this is not included in the minteq.v4.dat database.
 Examples 363

SPECIATION
Database “minteq.v4.dat” # for EDTA
calculationType ht1
calculationMethod 1
mainSpecies Cu
xmin 2.0 # pH range
xmax 10.0
ymin -85.0 # O2(g) range
ymax 0.0
resolution 300
PLOT
plotTitle “Cu-EDTA&lt;br&gt;(using minteq.v4.dat)”
xtitle pH
pymin -10.0
# use pe scale even though redox controlled by PO2(g)
yscale pe
domain F # omit domain boundary lines
extraText “extratextCuedta.dat”

CHEMISTRY

PHASES
H2(g) # not in minteq.dat
H2 = H2
log_k -3.150 # solubility of H2(g)
delta_h -1.759 kcal

include ‘ht1.inc’ # standard hunt and track file

SOLUTION 1 # initial solution calculation

temp 25
pH 1.8 # start ing pH below minimum pH cos adding NaOH
units mol/kgw
Cu 1e-4 # total concentrations
Edta 1e-4
Na 1e-1 # background electrolyte
Cl 1e-1 #
END

USE solution 1 # faster split into two simulations as here

# - only loops on last simulation by default
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10 # negative sign converts pH to logH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1 # limit to 0.1 mol O2 max

Atacamite 0 0 # possible minerals

Cu(OH)2 0 0
CuMetal 0 0
Cuprite 0 0
Melanothallite 0 0
Nantokite 0 0
Tenorite 0 0
END
 Examples 364

46 Ca-F-P-C-H2O

Ca-F-P-CO2-H2O

-2.0
Calcite

Ca
-2.5
log f CO2(g)

-3.0 Ca2+ Fluorite Fluorapatite

-3.5

-4.0
4 5 6 7 8 9
pH

C:\PhreePlot\demo\CaF\CaF2_Ca1.ps

In this example, a predominance diagram is drawn but the y-axis is not related to redox but is
the partial pressure of CO2(g). The diagram is one way of showing the competition between
three Ca minerals as a function of CO2(g) and pH – at different points, a fluoride, a phos-
phate and a carbonate predominate.
 Examples 365

SPECIATION
jobTitle “Calcium in the presence of fluoride, \
phosphate and bicarbonate”
calculationType ht1
calculationMethod 1
mainSpecies Ca
xmin 4.0
xmax 9.0
ymin -4.0
ymax -2.0
resolution 200
PLOT
plotTitle \
“Ca-F-P-CO&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
CO&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextCaF.dat”

CHEMISTRY

include ‘ht1.inc’ # standard ‘hunt and track’ file

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
Ca 1e-2
F 1e-2
P 3e-3
Na 1e-1
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 1
-force_equality true
CO2(g) &lt;y_axis&gt; 1
-force_equality true

Calcite 0 0
Fluorite 0 0
Fluorapatite 0 0
Calcite 0 0
Aragonite 0 0
END
 Examples 366

47 Ni-S-C-H2O

Ni-S-C-O2-H2O at 20oC

0 O2(g) > 0.21 atm

Ni
-20
log f O2(g)

NiCO3 NiCO3
Ni2+ Ni(OH)2 Ni(CO3)22-
-40

-60

Millerite

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\NiS\NiS_Ni1.ps

A redox-pH predominance diagram for Ni in the presence of C and S. Since some of the Ni
minerals do not have mineral names in the database (e.g. Ni(OH)2), the ht1s.inc include file
has been used rather than ht1.inc file. This is the same as the ht1 file except that it appends
‘(s)’ to mineral names making it clear that Ni(OH)2(s) is a mineral whereas NiCO3 is not.
 Examples 367

# predominance diagram for Ni in the presence of S and C (employing the Halite \

ploy)

SPECIATION
jobTitle “Ni-S-C-H2O”
calculationType ht1
calculationMethod 1
mainSpecies “Ni”
xmin 2.0 # calculate pH 2-10
xmax 10.0
ymin -80.0 # calculate log f(O2(g)) -80 to 0
ymax 0.0

resolution 250 # track on a 250 x 250 grid

PLOT
plotTitle \
“Ni-S-C-O&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub&gt;O at \
20&lt;sup&gt;o&lt;/sup&gt;C”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextNiS.dat”

CHEMISTRY

# first simulation - initial solution calculation

include ‘ht1s.inc’ # standard predominance diagram code

SOLUTION 1
Temp 20
# initial pH less than pHmin to hope that Fix_H+ works (but see below)
pH 1.8
units mol/kgw
Ni 1e-2 # total Ni etc
S(6) 1e-2
Na 1e-1 charge # background electrolyte
Cl 1e-1
END

# second simulation

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH # Fix_H+ defined in ht1.inc
-force_equality true
O2(g) &lt;y_axis&gt;
CO2(g) -1.5 1 # limit max CO2 supplied to 1 mol

Millerite 0 0 # list of possible minerals

Sulfur 0 0
Ni(OH)2 0 0
# reduction of S(6) produces a lot of OH- so may actually need HCl
Halite -12 1 dis
# (or -NaOH) to adjust pH - can’t specify +NaOH and +HCl so use -NaOH.
Bunsenite 0 0
# This Halite phase ensures that there will always be some Na to take away.
NiCO3 0 0
# To avoid this, either reduce initial pH to pH 1 or add more Na(Cl) or add less
# S(6).
Nahcolite 0 0
Morenosite 0 0
Retgersite 0 0
Natron 0 0
Thermonatrite 0 0
Thenardite 0 0
Mirabilite 0 0
 Examples 368

Ni4(OH)6SO4 0 0
Trona 0 0
END
Examples 369
 Examples 370

48 Zn-S-C-H2O

Zn-S-C-H2O

0 O2(g) > 0.21 atm

Zn
-20
log f O2(g)

Zn2+ Zn5(OH)8Cl2 ZnCO3.H2O

-40

-60
Sphalerite

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\ZnS\ZnS_Zn1.ps

This is similar to the previous example except that it is for zn not Ni. As before, the ‘ht1s.inc’
file was used so that ‘(s)’ has been appended to the mineral names, which in this case
included Zn5(OH)8Cl2.
 Examples 371

SPECIATION
jobTitle “Zn-C-H&lt;sub&gt;2&lt;/sub&gt;O”
calculationType ht1
calculationMethod 1
mainSpecies Zn
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 200

PLOT
plotTitle “Zn-S-C-H&lt;sub&gt;2&lt;/sub&gt;O”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextZnS.dat”

CHEMISTRY

include ‘ht1s.inc’

PHASES
Hydrozincite
Zn5(OH)6(CO3)2 + 10H+ = 5Zn+2 + 2CO2 + 8H2O
log_k 45.0 #9.0
-delta_H -256.5 kJ #Preis & Gamsjager 2001

SOLUTION 1
Temp 20
pH 1.8 # start at pH less than pHmin for Fix_H+
units mol/kgw
Zn 1e-1 # total Zn
S(6) 1e-1 # also redox sensitive
Na 1e-1
Cl 1e-1 charge
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3 1.0

Sphalerite 0 0 # minerals that could ppt

Wurtzite 0 0
ZnS(a) 0 0
# to maintain some Na at all times
Halite -10 1 dis
Sulfur 0 0
ZnO(a) 0 0
Zincite(c) 0 0
Zn(OH)2-e 0 0
Zn(OH)2-g 0 0
Zn(OH)2-b 0 0
Zn(OH)2-c 0 0
Zn(OH)2-a 0 0
ZnCl2 0 0
Zn2(OH)3Cl 0 0
ZnCO3:H2O 0 0
Smithsonite 0 0
Nahcolite 0 0
ZnMetal 0 0
Natron 0 0
Goslarite 0 0
Thermonatrite 0 0
Bianchite 0 0
ZnSO4:H2O 0 0
 Examples 372

Thenardite 0 0
Mirabilite 0 0
Zn5(OH)8Cl2 0 0
Zincosite 0 0
Zn2(OH)2SO4 0 0
Trona 0 0
Zn4(OH)6SO4 0 0
Zn3O(SO4)2 0 0
END
Examples 373
 Examples 374

49 Cd-S-C-H2O

Cd-S-C-H2O at 20oC

0 O2(g) > 0.21 atm

Cd
-20

CdCl+
log f O2(g)

Otavite

-40

-60
Greenockite

CH4(g) > 1 atm

-80
2 4 6 8 10
pH

C:\PhreePlot\demo\CdS\CdS_Cd1.ps

In this example, simplify was set to a high value (10) in order to eliminate the ‘steppiness’ of
the low-angled Greenockite-Otavite boundary.
 Examples 375

SPECIATION
jobTitle “Cd in the presence of sulphur”
calculationType ht1
calculationMethod 1
mainSpecies Cd
xmin 2.0 # logH range
xmax 10.0
ymin -80.0 # O2(g) range
ymax 0.0
resolution 100
# straightens out the low-angled boundary
simplify 10

PLOT
plotTitle “Cd-S-C-H&lt;sub&gt;2&lt;/sub&gt;O at \
20&lt;sup&gt;o&lt;/sup&gt;C”
xtitle pH
ytitle “log &lt;i&gt;f \
&lt;/i&gt;O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextCdS.dat”

CHEMISTRY

include ht1.inc # standard ‘hunt and track’ file

SOLUTION 1
Temp 20
pH 1.8
units mol/kgw
Cd 1e-1 # total Cd
S(6) 1e-1
Na 1e-1 # background electrolyte
Cl 1e-1
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Greenockite 0 0
CdCl2:2.5H2O 0 0
CdCl2:H2O 0 0
CdCl2 0 0
Sulfur 0 0
CdOHCl 0 0
Cd(OH)2 0 0
Monteponite 0 0
Cd(OH)2(a) 0 0
CdMetal 0 0
Cd(gamma) 0 0
Otavite 0 0
Nahcolite 0 0
Natron 0 0
Thermonatrite 0 0
CdSO4:2.7H2O 0 0
CdSO4:H2O 0 0
Thenardite 0 0
Mirabilite 0 0
CdSO4 0 0
Trona 0 0
Cd3(OH)4SO4 0 0
Cd4(OH)6SO4 0 0
Cd3(OH)2(SO4)2 0 0
 Examples 376

50 Pb-S-C-P-H2O

Pb-S-C-P-H2O
(two simulations)

0 O2(g) > 0.21 atm

Pb
-20
log f O2(g)

PbCl+ Matlockite
Cerussite

-40
Paralaurionite

-60
Hydrocerussite
Galena
Pb4Cl2(OH)6
Pb
-80
2 4 6 8 10
pH

C:\PhreePlot\demo\Pb\Pb_Pb1.ps

This is quite a ‘challenging’ diagram to generate. It has with competing mineral phases and
some close, low-angled boundaries.
The colour of the info text and the field labels have been set to blue with info and labelColor,
respectively.
 Examples 377

SPECIATION
jobTitle “Lead speciation”
Database llnl.dat # large database
calculationType ht1 # hunt and track approach
calculationMethod 1
mainSpecies “Pb”
xmin 2.0
xmax 10.0
ymin -80.0
ymax 0.0
resolution 500 # tracks on a 500 x 500 grid

PLOT
plotTitle \
“Pb-S-C-P-H&lt;sub&gt;2&lt;/sub&gt;O&lt;br&gt;(two simulations)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
labelColor blue # colour of the field labels
info nd blue # colour of the info and filename
extraText “extratextPb.dat”

CHEMISTRY

include ‘ht1.inc’

# first simulation - initial solution calculation only

SOLUTION 1
temp 25
pH 1.8
units mol/kgw
Pb 5e-4
S 2e-4
F 5e-4
P 1e-5
Na 1e-1
Cl 1e-1 charge
END

# second simulation - equilibrate

USE solution 1 # saves recalculation

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3 1.0

# these minerals were obtained by first running with resolution = 1 & PRINT -true
Pb(H2PO4)2 0 0
# this special case produces a list of all the possible mineral species
Pb4O(PO4)2 0 0
Pyromorphite-OH 0 0
Pb3(PO4)2 0 0
PbHPO4 0 0
Galena 0 0
#Ice 0 0
Matlockite 0 0
PbFCl 0 0
#Halite 0 0
Cotunnite 0 0
Paralaurionite 0 0
S 0 0
Pb 0 0
PbF2 0 0
C 0 0
Litharge 0 0
Massicot 0 0
 Examples 378

Nahcolite 0 0
Cerussite 0 0
Anglesite 0 0
Phosgenite 0 0
Pb2Cl2CO3 0 0
Mirabilite 0 0
Pb4Cl2(OH)6 0 0
Thenardite 0 0
Natron 0 0
Na2CO3:7H2O 0 0
Thermonatrite 0 0
Na2CO3 0 0
Lanarkite 0 0
PbCO3.PbO 0 0
Na 0 0
Plattnerite 0 0
Pyromorphite 0 0
Pb3SO6 0 0
Na2O 0 0
Pb4SO7 0 0
Na3H(SO4)2 0 0
Hydrocerussite 0 0
Minium 0 0
Burkeite 0 0

END
Examples 379
 Examples 380

51 Sb-S

Sb-S-O2-CO2-H2O
(demonstrates increased weighting of Fix_H+)

O2(g) > 0.21 atm

-5 Sb2O5 18oC

-25
Sb2O4
log f O2(g)

-45

Sb(OH)3
-65

Stibnite HSb2S4-
Sb
-85
5 6 7 8 9 10
pH

C:\PhreePlot\demo\SbS\SbS_Sb1.ps

This is also an awkward example to specify properly example because Sb(OH)3 is present as
both a solution species and a mineral species in the llnl.dat database. It is necessary to ensure
that the species names are actually different not just for plotting but also so that the tracking is
able to differentiate between them. As before, this is achieved by using the ht1s.inc include
file which appends ‘(s)’ to all mineral species names. In this case, the differentiation is not
just useful for making the plot more legible but is also important for actually generating the
proper boundaries.
The resolution has been set at 400 which produces the plot without problems. However,
PhreePlot fails to converge at some lower resolutions such as 100 because of problems in the
lower left-hand corner. There is a narrow sliver of Sb(s) which is uncomfortably close to the
lower axis boundary. PhreePlot therefore automatically increases the resolution until it con-
verges. The ‘steppiness’ of the low-angled boundaries at low resolutions can be reduced or
eliminated by increasing the resolution or the simplification factor using simplify.
 Examples 381

SPECIATION
jobTitle “Sb-O2-H2O”
Database llnl.dat # has Sb data
calculationType ht1
calculationMethod 1
mainSpecies “Sb”
xmin 5.0
xmax 10.0
ymin -85.0
ymax 0.0
# need an even higher resolution to get smooth low-angled boundaries
resolution 400

PLOT
plotTitle \
“Sb-S-O&lt;sub&gt;2&lt;/sub&gt;-CO&lt;sub&gt;2&lt;/sub&gt;-H&lt;sub&gt;2&lt;/sub \
&gt;O&lt;br&gt;(demonstrates increased weighting of Fix_H+)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; O&lt;sub&gt;2&lt;/sub&gt;(g)”
extraText “extratextSbS.dat”

CHEMISTRY

# first simulation

# adds “...(s)” for mineral phases to avoid confusion with aq species

include ‘ht1s.inc’

PHASES

Fix_H+
H+ = H+
log_k 0.0

SOLUTION 1 # Kerfoot, GWB 15 Dec 2005

Temp 18
pH 3.00
units mol/kgw
Sb 3e-7 # total Sb
S(6) 4.4e-4
Na 0.0027
K 0.00020
Mn 1e-4
Ca 9.93e-4
Fe(2) 1e-4
Cl 5e-5
END

# second simulation
USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.523 1.0

Pyrite 0 0
Stibnite 0 0
Sb 0 0
Sb(OH)3 0 0
S 0 0
Fe(OH)2 0 0
Mn(OH)2(am) 0 0
Sb2O3 0 0
Fe(OH)3 0 0
Sb2O4 0 0
Sb4O6(cubic) 0 0
Rhodochrosite 0 0
Siderite 0 0
 Examples 382

Calcite 0 0
Sb4O6(orthorhombic) 0 0
Sb2O5 0 0
END
Examples 383
 Examples 384

52 Se-S

2 2 2
(demonstrates increased
Selenium weightingand
protonation of Fix_H+)
redox
(no adsorption)
O2(g) > 0.21 atm
-5 0 Sb2O25(g) > 0.21 atm 18oC

SeO42-

-25
Se
-20
Sb2O4
log f O2(g)

H2SeO3
HSeO3-
log f O2(g)

SeO32-
-45
-40

Sb(OH)3
-65 Se(s)
-60
Stibnite HSb2S4-
Sb
-85 SeT = 10-3M CH4(g) > 1 atm
5 6 7 8 9 10
-80
2 4 pH 6 8 10
pH
C:\PhreePlot\demo\SbS\SbS_Sb1.ps

C:\PhreePlot\demo\Se\Se_Se1.ps

This plot was produced with the wateq4f.dat database. The low-angled boundaries for Se(s)
was rather ‘steppy’ and so simplify was set to 3. Selenium metal is stable under a wide range of
reducing conditions.
 Examples 385

SPECIATION
jobTitle “Plutonium redox and speciation”
Database wateq4f.dat # contains Se species
calculationType ht1
calculationMethod 1
mainSpecies “Se”
xmin 2.0 # pH 2 to 10
xmax 10.0
ymin -80.0 # redox
ymax 0.0
# some low-angled boundaries could benefit from higher resolution or more smoothing
resolution 200

PLOT
plotTitle “Selenium protonation and \
redox&lt;br&gt;(no adsorption)”
xtitle pH
ytitle “log &lt;i&gt;f&lt;/i&gt; \
O&lt;sub&gt;2&lt;/sub&gt;(g)”
labelSize 2.0
extraText “extratextSe.dat”

CHEMISTRY

# first simulation - initial solution calculation

include ‘ht1.inc’ # each adsorbed species is counted separately

SOLUTION 1
temp 25
pH 1.8 # start out at pH&lt;xmin
units mol/kgw
Se 1e-3 # total Se
Na 1e-1
Cl 1e-1
S 1e-3
END

# second simulation - equilibrate

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
O2(g) &lt;y_axis&gt; 0.1
CO2(g) -3.5 1.0

Se(s) 0 0 # possible Se minerals

Mirabilite 0 0
Thenardite 0 0
Sulfur 0 0
SeO2 0 0
END
 Examples 386

53 Clay mineral stability diagram

Clay mineral stability diagram

(using mainSpecies = minerals)

6
K-feldspar

K-mica
log (K+/H+)

Gibbsite
0 Kaolinite
Ca-Montmorillonite

-2
-5 -4 -3 -2 -1
log H4SiO4

C:\PhreePlot\demo\minstab\minstab_minerals1.ps

PhreePlot is not recommended for drawing the type of mineral stability diagrams often used
in mineral geochemistry as the large range of activities often involved can lead to problems of
convergence. However, in principle, such diagrams can be calculated and this example is one
such calculated using the ‘ht1’ procedure. It plots the most abundant mineral at any particular
point. The logic for determining the boundaries is in the include file ‘minstab1.inc’.
The main species has been set to ‘mineral’ as it is counting all minerals, not just minerals of a
particular element. The x- and y-axes are driven by ‘fixing’ the H4SiO4 activity and the K+/H+
activity ratio, respectively, using fictive phases defined in the PHASES keyword block.
The diagram shows the predominant mineral species (in terms of moles). Pure phases fix the
activity or activity product of their constituent species. The indicated mineral is often the only
mineral present (except on the phase boundaries). This is reflected by the NA code that appears
on the screen for the sub-dominant species. If no mineral is stable, the field is labelled ‘No
minerals present’. This can be demonstrated in this example by changing the units of con-
centration from mol/kgw to umol/kgw.
It can be difficult to fix the activity ratios over a wide range of values using the present
approach and numerical errors can mean that the boundaries are rather ragged (see bottom
right-hand corner). In such cases, the ‘grid’ approach may be a better option. An alternative is
to plot the mineral with the largest theoretical supersaturation (see the minstab2.ppi demo).
 Examples 387

# an example of a classical mineral stability diagram - diagram only includes \

minerals (not aqueous etc species)

SPECIATION
jobTitle “Clay mineral stability diagram”
Database “phreeqc.dat”
# use this approach for finding field boundaries of most abundant minerals
calculationType ht1
calculationMethod 1
# NB “minerals” is a special case that invokes this type of plot
mainSpecies “minerals”
xmin -5.0
xmax -1.0
ymin -2.0
ymax 8.0
resolution 200
PLOT
plotTitle “Clay mineral stability \
diagram&lt;br&gt;(using mainSpecies = minerals)”
xtitle “log \
H&lt;sub&gt;4&lt;/sub&gt;SiO&lt;sub&gt;4&lt;/sub&gt;”
ytitle “log (K&lt;sup&lt;+&gt;/sup&gt;/H)”
extraText “extratextminstab.dat”

CHEMISTRY

# first simulation - initial solution calculation

include ‘minstab1.inc’ # special file for generating mineral stability diagrams

PHASES
Fix_Si # used for driving the x-axis variable
H4SiO4 = H4SiO4
log_k 0.0

Fix_H/K # used for driving the y-axis variable

KOH = K+ + H2O -H+
log_k 0.0

PRINT
reset FALSE
SOLUTION 1
pH 4
units mol/kgw
K 0 # added by reaction
Na 1e-2
Cl 1e-2
Al 1e-2
Si 0 #added by reaction
Ca 1e-0
END

# second (final) simulation - iterates on this simulation when driving the x- and \
y-axes

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_Si &lt;x_axis&gt; H4SiO4 10 # fix H4SiO4 activity
Fix_H/K &lt;y_axis&gt; KOH 10 # fix H/K activity ratio

Kaolinite 0 0 # list of minerals considered

K-feldspar 0 0
K-mica 0 0
Gibbsite 0 0
# SiO2(a) 0 0 # can’t add \
this cos Si activity fixed by Fix_Si
Ca-Montmorillonite 0 0
END
Examples 388
 Examples 389

Custom plots

Custom plots refer to plots created directly from USER_PUNCH code. PHREEQC provides a
very versatile mechanism for writing output to the selected output ‘file’ using BASIC code
within USER_PUNCH keyword data blocks. This output is accumulated in the ‘out’ file which is
then used for plotting.
The following examples give a guide as to how to create custom plots.
 Examples 390

54 Gibbsite solubility vs pH

Al solubility vs pH
(plotting named species)

0 SIGibbs
log concn (mol/kgw)

-2
Gibbsite
-4 AlT
AlF2+
Al3+ Al(OH)4-

-6 Al3+
AlF2+
Al(OH)4-
-8 SIGibbs
AlT
Gibbsite
-10
2 4 6 8 10 12
pH

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

A custom plot showing the concentration of Al complexes as a function of pH. The species
plotted have been explicitly defined in the input file. The saturation index for gibbsite has also
been plotted.
This example demonstrates simple looping using the x axis variable. Xmin and xmax control
the range of values taken by the <x_axis> tag. Resolution determines the number of sub-divi-
sions within the x-axis and so directly controls the number of points calculated for each curve.
Here the resolution is 200 which is more than enough to get smooth curves.
Species names and plot labels have been defined by the headings given in the USER_PUNCH key-
word data block.. This writes the headings to the selected output file which are then copied to
the ‘out’ file which is then used for plotting. Note that text enhancement tags such as sub-
script can be used in the headings and passed through to the plot.
The curves plotted have been defined with the lines keyword and have auto colour selection.
The order of plotting and the order in which the labels are printed in the legend is determined
 Examples 391

by the order PUNCHed in the selected output file. The legend has been moved from its default
position to the right of the plot into the plot area using the <legend> tag in the extraText file.
 Examples 392

SPECIATION
calculationType custom
calculationMethod 1
xmin 2.0
xmax 12.0
# determines the number of ‘points’ on the curves (i.e. PHREEQC runs)
resolution 101

PLOT
# &lt;br&gt; causes a line break
plotTitle “Al solubility vs pH&lt;br&gt;(plotting \
named \
species)”
xtitle pH
ytitle “log concn (mol/kgw)”
pymin -10.0 # force the y-axis range
pymax 2.0
lineWidth 0.4 # in the units currently in force
# x-axis variable -’pH’ must match the name of one of the punched columns below
customXcolumn pH
# y-axis variables in legend order
lines Al+3 AlF+2 Al(OH)4- \
SI&lt;sub&gt;Gibbs&lt;/sub&gt; \
\
Al&lt;sub&gt;T&lt;/sub&gt; Gibbsite
extraText “extratextAlvsph.dat”
# turns off the little red label ‘anchors’
trackSymbolSize 0

CHEMISTRY

SELECTED_OUTPUT
reset false
high_precision true
PHASES
Fix_H+
H+ = H+
log_K 0.0
SOLUTION 1 Total Al
units mol/kgw
Al 1e-3
F 1e-3
S(6) 1e-3
Na 1e-1
Cl 1e-1
USER_PUNCH
# this is where ‘pH’ and all the y-axis variables are defined
headings pH Al+3 AlF+2 Al(OH)4- SI&lt;sub&gt;Gibbs&lt;/sub&gt; \
Al&lt;sub&gt;T&lt;/sub&gt; Gibbsite
-start
10 totel = SYS(“Al”,n,n$,t$,c)
20 punch -la(“H+”), lm(“Al+3”), lm(“AlF+2”), lm(“Al(OH)4-”), SI(“Gibbsite”), \
log10(tot(“Al”)), log10(equi(“Gibbsite”))
-end
END

USE solution 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
Gibbsite 0 0 # these are the possible minerals considered
# Al(OH)3(a) 0 0
Basaluminite 0 0
Boehmite 0 0
Jurbanite 0 0
END
Examples 393
 Examples 394

55 Acid titration of groundwater (using

‘REACTION’)

Acid titration of 50 mL of groundwater

(using REACTION keyword)

Gran
pH

6
pH

2
Closed system

0
0.0 0.5 1.0 1.5 2.0 2.5 3.0
ml 0.16M HCl

C:\PhreePlot\demo\titration\titration.ps

This example demonstrates how a single iteration of PHREEQC can generate a multiline
SELECTED_OUTPUT file. Each of the REACTION steps produces a line of output. RXN gives the
moles of reactant used at each step and this is converted to mmoles for plotting. resolution has
been set to 1 because only iteration is used.
The selectedOutputLines setting has been set to auto which signals that all lines in the
selected output are transferred to the ‘out’ file rather than just the last line.
The labels normally attached to each line have been suppressed by setting labelSize to 0. The
legend has been moved inside the plot with the <legend> tag in the extraText file.
It is much faster to use PHREEQC’s internal looping like this compared with PhreePlot’s
looping mechanisms. Having said that, calculation times are often so short that speed is not an
issue for simple calculations like this.
 Examples 395

SPECIATION
calculationType custom
calculationMethod 1
# get as many lines as there are -&gt; out file
selectedOutputLines auto

PLOT
plotTitle “Acid titration of 50 mL of \
groundwater&lt;br&gt;(using REACTION keyword)”
xtitle “ml 0.16M HCl”
ytitle pH
customXcolumn ml
pxmax 3
lines pH Gran # from selected output
points Gran # from selected output
labelSize 0 # suppress curve labels inside plot
lineColor blue
pointColor green
extraText extratexttitration.dat

CHEMISTRY

SELECTED_OUTPUT
-reset false

# Groundwater # the groundwater to titrate with HCl

SOLUTION 1
pH 7.05
units mg/L
# temp 10.5
water 0.050 kg
Na 6
K 0.6
Ca 124
Mg 1.6
Cl 11
Alkalinity 348 as HCO3
S(6) 3 as SO4
Si 5.8

REACTION 1 Add HCl to the soln

# 1 mL of 0.16M HCl # this takes into account the \
dilution since includes water
HCl 0.16e-3
H2O 55.5e-3
3 in 50 steps

USER_PUNCH
-headings ml pH water Gran
10 VT = TOT(“water”)*1000 # assumes density = 1
20 V = VT-50
30 pH = -la(“H+”)
40 Gran = VT*(10^-pH)*30
50 punch V, pH, VT, Gran

GAS_PHASE
-fixed_volume
-volume 0.01 # 10 mL gas + 50 mL solution
# equilibrate with solution 1 to begin with - this leads to some initial degassing
-equilibrate 1
CO2(g)

END
 Examples 396

56 Acid titration of groundwater (using

PhreePlot looping)

Acid titration of 50 mL of groundwater

(using MIX keyword)

Gran
pH

6
pH

2
Closed system

0
0.0 0.5 1.0 1.5 2.0 2.5 3.0
ml 0.16M HCl

C:\PhreePlot\demo\titration\titration2.ps

This is essentially the same example as the previous example but has been calculated using one
of PhreePlot’s own looping mechanisms. This involves using a 1 mol/kgw solution of HCl to
titrate the groundwater. The titration is achieved using the MIX keyword.
This approach includes the dilution brought about by the titration (the REACTION approach
essentially titrates with ‘solid’ HCl). In this case, the dilution is very small.
 Examples 397

SPECIATION
calculationType custom
calculationMethod 1
xmin 0.0
xmax 3.0E-03
resolution 50
numericTags &lt;titre&gt; = “&lt;x_axis&gt;”

PLOT
plotTitle “Acid titration of 50 mL of \
groundwater&lt;br&gt;(using MIX keyword)”
xtitle “ml 0.16M HCl”
ytitle pH
lineColor blue
customXcolumn ml
lines pH Gran
points Gran
pointColor green
labelSize 0
extraText “extratexttitration.dat”

CHEMISTRY

SELECTED_OUTPUT
-reset false

TITLE Acid titration of groundwater (assumes no CO2 loss)

SOLUTION 1 # Groundwater
pH 7.05
units mg/L
temp 10.5
water 0.050 kg
Na 6
K 0.6
Ca 124
Mg 1.6
Cl 11
Alkalinity 348 as HCO3
S(6) 3 as SO4
Si 5.8

SOLUTION 2
units mol/kgw
pH 1 charge # 0.16 mol/kgw HCl
Cl 0.16
END

MIX 1 Add 0.1M HCl to the soln # mix two solutions, the sample and the acid
1 1
2 &lt;titre&gt; # driven by x loop parameters, see above

USER_PUNCH
-headings ml pH VT Gran
1 pH = -la(“H+”)
10 V = &lt;titre&gt;*1000
11 VT = (0.05 + &lt;titre&gt;)*1000
20 Gran = VT*(10^-pH)*30
30 punch V, pH, VT, Gran

GAS_PHASE
-fixed_volume
-volume 0.01 # 10 mL gas + 50 mL solution
# equilibrate with solution 1 to begin with - this leads to some initial degassing
-equilibrate 1
CO2(g)

END
 Examples 398

57 Redox sequence

Development of redox zones

(using REACTION)

0.10 O2
NO3-
Mn2+
As(V
0.08 As(II
Concentration (mmol/L)

•
As(III) Fe2+
SO42
•
0.06 As(V) S2-
• CH4
S2- CH4
• •
NO3- SO42-
•
Mn2+
0.04 •

O
• 2

0.02

Fe2+•
0.00
0.0 0.1 0.2 0.3 0.4 0.5 0.6
Carbon added (mmol/L)

C:\PhreePlot\demo\redox\redox.ps

This example (from Appelo and Postma, 2005, Fig. 9.17) shows how a single iteration of
PHREEQC (using the REACTION keyword) can generate a series of points that can be assem-
bled to give the ‘redox ladder’ plot indicated. The REACTION keyword generates its own inter-
nal looping and so there is no need for PhreePlot loops.
The curves show the successive reduction of various solutes as the groundwater is titrated with
C (as in organic matter) in the presence of a small amount of goethite and pyrolusite.
The label names have been set explicitly by making them the names for the headings in the
selected output. These names get passed to the ‘out’ file which is then used for plotting. Note
that the default assumes that all labels are species names and so are interpreted with super-
scripts etc. accordingly. This behaviour can be suppressed by setting convertLabels to FALSE.
The order of species plotted and in the legend is determined from the order PUNCHed to the
selected output. FeS(ppt) is the only mineral that is allowed to form.
The script could be generalised by using tags to define the number of steps used, the mol of C
 Examples 399

added and the initial solution concentrations. For example, to define just the first two of these,
the following changes could be made:
(i) add to the PhreePlot section
numericTags <steps> = 100 \
<molCadded> = 0.572e-3
(ii) change line 10 in the USER_PUNCH data block
10 addedc=step_no*<molCadded>*1e3/<steps>
(iii) change the REACTION data block
REACTION 1
CH2O; <molCadded> in <steps> steps
INCREMENTAL_REACTIONS true
END
 Examples 400

# titrate with C (like glucose)

SPECIATION
jobTitle “Development of redox zones (A&P, Fig \
9.17)”
calculationType custom
calculationMethod 1
# just one iteration since REACTION has its own looping mechanism
resolution 1
# copy all lines in selected.out to out file
selectedOutputLines auto

PLOT
plotTitle “Development of redox \
zones&lt;br&gt;(using REACTION)”
xtitle “Carbon added (mmol/L)”
ytitle “Concentration (mmol/L)”
# heading from out file (derived from selected.out)
customXcolumn C
# headings from out file (derived from selected.out)
lines O2 NO3- Mn+2 As(V) As(III) Fe+2 SO4-2 S-2 \
CH4

CHEMISTRY

SELECTED_OUTPUT
-reset false
-high_precision true
USER_PUNCH
headings C O2 NO3- Mn+2 Fe+2 SO4-2 S-2 CH4 As(V) As(III)
-start
10 addedc=step_no*0.572/100
20 punch addedc, 1000*tot(“O(0)”)/2, 1000*tot(“N(5)”), 1000*tot(“Mn”), \
1000*tot(“Fe(2)”),\
1000*tot(“S(6)”), 1000*tot(“S(-2)”), 1000*tot(“C(-4)”), 1000*tot(“As(5)”), \
1000*tot(“As(3)”)
-end

SOLUTION 1
pH 7.1
Na 1.236
K 0.041
Mg 0.115
Ca 0.067
Cl 1.467
N(5) 0.058
S(6) 0.085
As(5) 0.075
Alkalinity 0.26
O(0) 0.124

EQUILIBRIUM_PHASES
Goethite 0 2.5e-3 # start with some
FeS(ppt) 0 0 # start with none
Pyrolusite 0 4e-5 # start with some

REACTION 1
CH2O; 0.572e-3 in 100 steps # internal looping by REACTION data block
INCREMENTAL_REACTIONS true
END
Examples 401
 Examples 402

58 Kd’s for trace metals as a function of pH

Kd’s of trace metals in neutralized AMD

4 KdU
KdZn
KdCd
Distribution coefficient, Kd

KdU
•

2 KdZn
•

1
KdCd
•

0
2 4 6 8 10
pH

C:\PhreePlot\demo\kd\kd.ps

This example (from Appelo and Postma, 2005, Fig. 11.19) also uses the REACTION keyword to
generate a series of curves showing the variation of solid/solution partition coefficient (Kd) as
a function of pH for U, Zn and Cd.
It uses the SURF() function to get the total number of moles of each element adsorbed to a
particular mineral surface (here Hfo) and TOT() to get the total number of moles of each ele-
ment remaining in solution. Cd and Zn are also bound by ion exchange reactions on kaoli-
nite. The total bound includes both adsorbed and exchanged species so these must be added
together to calculate the Kd.
The initial solution is a sample of acid mine drainage in equilibrium with a quartz-rich sedi-
ment. This is progressively neutralized with NaOH. The trace metals are bound to Hfo and
kaolinite and the Kd’s reflect how binding to these two surfaces changes with pH. Cd and Zn
are mostly bound to kaolinite at low pH and this is modelled as a simple pH-independent cat-
ion exchange reaction. At high pH, binding to ferrihydrite becomes important. U sorption is
out-competed by other trace metals on ferrihydrite at low pH. At high pH, various negatively
charged U species dominate in solution which works against their sorption at high pH.
 Examples 403

# plots the solid/solution partition coefft (Kd) for the sorption of metals by \
HFO as a function of pH

SPECIATION
jobTitle “Kd’s of trace metals in neutralized AMD \
(A&P, Fig 11.19)”
calculationType custom
calculationMethod 1 # 1 = calculate and plot
# just one iteration of x- and y-axis variables
resolution 1
# auto = results will be on the last line of the selected output
selectedOutputLines auto

PLOT
plotTitle “Kd’s of trace metals in neutralized AMD”
xtitle pH
ytitle “Distribution coefficient, Kd”
customXcolumn pH # from the out file
# from the out file - plot these three as lines
lines KdU KdZn KdCd
# additional text on/by plot
extraText “extratextkd.dat”

CHEMISTRY

SELECTED_OUTPUT
reset false
high_precision true
USER_PUNCH
headings pH KdU KdZn KdCd # these columns of data accumulate in the out file
-start
# don’t output any data for plotting for initial solution calculations
10 IF (STEP_NO = 0) THEN 70
20 PUNCH -la(“H+”)
30 KdU = SURF(“U”,”Hfo”)/TOT(“U”) # NB TOT(“U”) is total dissolved U
# solid phase = adsorbed + cation exchanged
40 KdZn = (SURF(“Zn”,”Hfo”) + mol(“ZnX2”))/TOT(“Zn”)
50 KdCd = (SURF(“Cd”,”Hfo”) + mol(“CdX2”))/TOT(“Cd”)
# this outputs the data to selected output and then the out file
60 PUNCH KdU,KdZn,KdCd
70 END
-end

SOLUTION 1 AMD
-temp 10
-units mmol/kgw
pH 2.3 # analysis from some Acid Mine Drainage
Na 23.8
K 0.1
Mg 2.0
Ca 11.6
C 1.7e-4
Cl 13
P 0.08
S(6) 52.8
Al 6.5
Cd 0.01
Fe(3) 10.7
Fe(2) 0.27
U(6) 0.18
Zn 1.5

SURFACE 1
Hfo_w 2e-3 600 0.89
Hfo_s 5e-5
-equil 1

EXCHANGE_SPECIES
H+ + X- = HX
log_k 1.0
 Examples 404

-gamma 9.0 0.0

EXCHANGE 1
X 50e-3
-equil 1

REACTION 1
NaOH 1
105e-3 in 100 steps # the number of steps controls the resolution of the plot
INCREMENTAL_REACTIONS

END
Examples 405
 Examples 406

59 Cd speciation vs pH

Cd-Cl-H2O speciation vs pH

100 Cd(OH)2
Cd(OH)3-
Cd(OH)42
Cd2+
80 CdCl+
CdNO3+
CdOH+
Cd(OH)2
•
% species

60 CdOHCl
•
Cd2+

40

CdOH+•
Cd(OH)3-
•
20
2-
CdOHCl Cd(OH)4 •
CdNO3+ •
•
•
CdCl+
0
6 7 8 9 10 11 12 13
pH

C:\PhreePlot\demo\Cdspeciation\Cdspeciation.ps

PHREEQC cannot automatically generate columns headings containing the species names.
This means that it is not possible to automatically write the correct header in the ‘out’ file
when writing species that are generated automatically, for example, by the SYS() function.
However, a custom plot needs to be able to pick up the correct label names from the header
line in order to be able to label the plot properly. Communicating the species names to the
plot file therefore becomes a problem. There are two ways round this: (i) put the label names
explicitly (manually) in the -headings line of a USER_PUNCH block, or (ii) write them as a sepa-
rate data column in the ‘out’ file, i.e. as name-value pairs.
The first approach is illustrated in this example. This requires that you know which species
will be output in the first place. The SYS() function in the Cdvsph.inc file makes it easy to
output all of the species involved automatically. These are output in descending amount order
(largest amounts first) and so this order will change with pH. The species therefore need to be
sorted. This is done with the sort.inc file. The species will then always be output in ascend-
ing alphabetic order (ignoring parentheses) and the -heading list should reflect this order. It is
normally necessary to run a problem like this twice: firstly to get the species involved, and sec-
 Examples 407

ondly to make the plot. This example also illustrates the use of nested include files. The mini-
mumYValueForPlotting keyword eliminates all curves which do not rise above 5%.
The next example illustrates the second approach which is normally easier to implement.
 Examples 408

SPECIATION
jobTitle “Cd speciation vs pH&lt;br&gt;(using \
explicit \
naming of species to plot)”
calculationType custom
calculationMethod 1
xmin -13.0
xmax -6.0
# determines the number of points at which speciation is calculated
resolution 100

PLOT
plotTitle “Cd-Cl-H&lt;sub&gt;2&lt;/sub&gt;O \
speciation vs pH”
xtitle pH
ytitle “% species”
pxmax 13
# explicit naming of species - order defined in user_punchCd.inc
lines Cd(OH)2 Cd(OH)3- Cd(OH)4-2 Cd+2 Cd2OH+3 \
CdCl+ CdCl2 CdCl3- CdNO3+ CdOH+ CdOHCl
lineColor “blue”
pointSize 5.0
# use first column as defined by include files - this is pH
customXcolumn 1
# this prevents minor species being plotted
minimumYValueForPlotting 5.0
extraText “extratextCdspeciation.dat”

CHEMISTRY
include ‘Cdvsph.inc’ # nested includes
Examples 409
 Examples 410

60 Zn-HFO: %sorption vs pH curves

%sorbed vs pH curves
(split into two PHREEQC simulations)

100
ZnT
1 10-6M
2 10-5M
80 3 10-4M
4 10-3M
5 10-2M

60
%sorbed

2
1 •
•

40
3
•

20
4
•
5
•
0
5.0 5.5 6.0 6.5 7.0 7.5 8.0
pH

C:\PhreePlot\demo\example8\pcsorption.ps

This example, based on Example 8 in the PHREEQC distribution, demonstrates the use of
the <x_axis> tag to loop over a range of pH and the loop variable to loop over a range of Zn
concentrations. The logLoopVar has been used to transform the loop variable to 10^z. The
plot shows the percentage of Zn adsorbed as a function of pH in 0.1M NaNO3.
The <x_axis> tag and the resolution determine the range and step size for the x-axis variable
(pH). The USER_PUNCH data block produces a block of selected output for each pH-Zn combi-
nation. With the default setting of selectedOutputLines, the last line of this block of output is
copied to the ‘out’ file for plotting. A blank line is written to the ‘out’ file for each new value
of the loop variable but not for each new value of the x-axis variable. The data are therefore
plotted as a series of curves with a new curve after each change of the loop variable.
The normal legend or key has been suppressed by setting legendTextSize to zero. A new legend
has been placed in the top-left corner using a line of the extraText file. The new ‘legend’ text
has been placed on a series of lines using the continuation character, \, to concatenate lines
and give the single text string required. Note that the maximum total length of the text string,
 Examples 411

including any text enhancement tags such as <sub>, is 200 characters. labels have been used to
number the curves.
 Examples 412

# %sorption vs pH for Zn on Hfo

# Modelled after ‘Example 8’ from the PHREEQC example set

SPECIATION
calculationType custom
calculationMethod 1
xmin 5.0 # x-axis (pH) range
xmax 8.0
# z-loop (log ZnT), one curve for each ZnT
loopMin -6.0
loopMax -2.0 # from -6 to -2 in steps of +1
loopInt 1.0
# 1 = value of loop variable is exponentiated (=10^&lt;loop&gt;) before use
loopLogVar 1
# number of calculations (PHREEQC simulations) for each curve
resolution 100

PLOT
plotTitle “%sorbed vs pH curves&lt;br&gt;(split into \
two PHREEQC simulations)”
xtitle pH
ytitle “%sorbed”
# this variable in the ‘out’ file is plotted as a line (%sorbed is a valid column
# header)
lines %sorbed
lineWidth 0.4
changeColor T
# used in order for label names on the plots
labels 1 2 3 4 5
labelSize 2.0
legendTextSize 0.0
customXcolumn pH
# adds customised legend text
extraText “extratextpcsorption.dat”

CHEMISTRY

# simulation 1 - initial surface calculation is run but no selected output is \

produced or read
TITLE Example 8.--Sorption of zinc on hydrous iron oxides.
SURFACE_SPECIES
Hfo_sOH + H+ = Hfo_sOH2+
log_k 7.18

Hfo_sOH = Hfo_sO- + H+
log_k -8.82

Hfo_sOH + Zn+2 = Hfo_sOZn+ + H+

log_k 0.66

Hfo_wOH + H+ = Hfo_wOH2+
log_k 7.18

Hfo_wOH = Hfo_wO- + H+
log_k -8.82

Hfo_wOH + Zn+2 = Hfo_wOZn+ + H+

log_k -2.32
SURFACE 1
Hfo_sOH 5e-6 600. 0.09
Hfo_wOH 2e-4

PHASES
Fix_H+
H+ = H+
log_k 0.0

# first simulation

USE solution none

 Examples 413

SELECTED_OUTPUT
-reset false
USER_PUNCH
-heading pH %sorbed sorbed # determines column headers in the ‘out’ file
10 sorbed = SURF(“Zn”,”Hfo”)
20 totZn = SYS(“Zn”)
30 pcsorbed = 100*sorbed/totZn
40 punch -la(“H+”), pcsorbed, sorbed
END

# simulation 2 - loops on this simulation to produce the output required for \

graphing

USE surface 1
SOLUTION 1
-units mol/kgw
pH 8.0
Zn &lt;loop&gt; # ZnT
Na 0.1
N(5) 0.1 charge
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10.0 # fixes the pH
-force_equality true
END
 Examples 414

61 Zn-HFO: Surface speciation

Speciation of zinc sorbed on HFO

-4 • Zn2+_1
Zn2+_2
Zn2+_2
Hfo_sOZn+_1
-5 Hfo_sOZn+_2 Hfo_sOZn+_2
•
Hfo_wOZn+_1
-6 Hfo_wOZn+_2
log conc (mol/kgw)

•
Hfo_wOZn+_2

-7 •
Zn2+_1

•
Hfo_sOZn+_1
-8
Hfo_wOZn+_1
•

-9

-10

-11
5 6 7 8
pH

C:\PhreePlot\demo\example8\speciation.ps

This example shows the surface speciation for Zn adsorbed to Hfo in the same system as that
of the previous example. Curves are produced for total Zn concentrations of 10-7M and 10-
4M. Adsorbed speciation is calculated by PUNCHing the log concentrations of the adsorbed spe-

cies directly. A similar plot could also be made using the ‘species plot’ procedure (see the
demo\example8 directory) with the logadsspeciesvsph.inc include file.
Since there are two loops for each species, the labelling appends an underscore and the loop
number to the species name to help to differentiate between the curves.
pxmajor has been set to one since the auto setting would produce major tick marks (and axis
labels) at every 0.5 pH unit.
The legend has been suppressed by setting the legend text size to 0 and the colour to ‘nd’ in
the <legend> line of the extraText file. It could also have omitted by setting the legendTextSize
to 0.
changeColor is by default false and useLineColorDictionary has been set to 0 (the default) so
that the default colour sequence is automatically used starting at red2, blue2 etc as given by
 Examples 415

their respective positions in the lineColor list in the input file. On the second loop, the colours
are kept the same but the density is increased to 4, e.g. red4, blue4, ... .
 Examples 416

SPECIATION
calculationType custom
calculationMethod 1
xmin 5.0
xmax 8.0
loopMin -7.0 # minimum value of &lt;loop&gt; tag
loopMax -4.0 # maximum value of &lt;loop&gt; tag
# increment of &lt;loop&gt; tag per iteration
loopInt 3.0
# 1 = antilog loop value, ie &lt;loop&gt; = 10^&lt;loop&gt;
loopLogVar 1
resolution 100

PLOT
plotTitle “Speciation of zinc sorbed on HFO”
xtitle pH
ytitle “log conc (mol/kgw)”
pxmajor 1.0
customXcolumn pH
# lines to plot from out file - headings defined below
lines Zn+2 Hfo_sOZn+ Hfo_wOZn+
lineWidth 0.6
# starting colours and colour densities
lineColor red2 blue2 green2
labelSize 1.8
trackSymbolSize 2.0

CHEMISTRY

# Similar to PHREEQC Example 8

TITLE Example 8.--Sorption of zinc on hydrous iron oxides.
# &lt;loop&gt; iterates on all simulations - this is the outer loop
SELECTED_OUTPUT
-reset false
-high_precision true
SURFACE_SPECIES
Hfo_sOH + H+ = Hfo_sOH2+
log_k 7.18

Hfo_sOH = Hfo_sO- + H+
log_k -8.82

Hfo_sOH + Zn+2 = Hfo_sOZn+ + H+

log_k 0.66

Hfo_wOH + H+ = Hfo_wOH2+
log_k 7.18

Hfo_wOH = Hfo_wO- + H+
log_k -8.82

Hfo_wOH + Zn+2 = Hfo_wOZn+ + H+

log_k -2.32
SURFACE 1
Hfo_sOH 5e-6 600. 0.09
Hfo_wOH 2e-4
PHASES
Fix_H+
H+ = H+
log_k 0.0
SOLUTION 1 # Initial setup simulation
-units mol/kgw
pH 8.0 # only for the initial solution calculation
Zn &lt;loop&gt;
Na 0.1 charge # background electrolyte
N(5) 0.1
USER_PUNCH
-heading pH Zn+2 Hfo_wOZn+ Hfo_sOZn+
10 punch -la(“H+”), lm(“Zn+2”), lm(“Hfo_wOZn+”), lm(“Hfo_sOZn+”)
END
 Examples 417

# &lt;x_axis&gt; iterations only execute the last iteration by default

USE solution 1
USE surface 1
EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH 10.0
END
 Examples 418

62 As-HFO: reduction in surface area

As desorption as the surface area decreases

5000
Initial conditions
1 g/kgw HFO equilibrated with 1 μg/kgw As

4000 Initial surface area 600 m2/g

0.01M NaNO3, pH 7
HFO aged under closed conditions
As (μg L-1)

3000

As
2000 •

1000
No phosphate

0
100 200 300 400 500 600
Surface area (m2 g-1)

C:\PhreePlot\demo\surfacearea\surfacearea.ps

This example shows how the dissolved As concentration could evolve as the surface area of
HFO declines (ageing). The example demonstrates the use of user-defined tags to pass infor-
mation from one simulation to the next. An alternative approach involves using the PUT() and
GET() BASIC functions

The total amount of As is defined by the first simulation and then the adsorbed As (and any
adsorbed P) is redistributed in the second simulation assuming closed conditions (apart from
H+). The dissolved As (and P) from the first simulation is discarded and the adsorbed As redis-
tributed as the surface area decreases. It is assumed that while the surface area of the HFO
decreases, the surface properties of the HFO remain unchanged (unlikely to be true in prac-
tice).
The various tag definitions in numericTags calculate the number of sites at any particular stage
based on the given initial surface characteristics. These values are substituted in the
PHREEQC code during each iteration.
The PhreePlot looping is only over the second (final) simulation.
 Examples 419

# calculates how the solution concn of As changes as the surface area of Hfo
# (but not the surface properties) is reduced in a closed system.
SPECIATION
JobTitle “Diagenesis”
calculationType custom
calculationMethod 1
xmin 10.0 # minimum surface area, see below
xmax 600.0 # maximum surface area
resolution 100

numericTags &lt;mass&gt; = 1 \
&lt;molecular_wt&gt; = 89 \
&lt;initial_site_density_per_mol&gt; = 0.2 \
\
&lt;initial_surface_area&gt; = 600 \
&lt;initial_site_density_per_g&gt; = \
&lt;initial_site_density_per_mol&gt;/&lt;molecular_wt&gt; \
&lt;initial_sites&gt; = \
&lt;initial_site_density_per_g&gt;*&lt;mass&gt; \
&lt;site_density_per_m2&gt; = \
&lt;initial_site_density_per_g&gt;/&lt;initial_surface_area&gt; \
&lt;surface_area&gt; = &lt;x_axis&gt; \
&lt;sites&gt; = \
&lt;surface_area&gt;*&lt;site_density_per_m2&gt;*&lt;mass&gt;
PLOT
plotTitle “As desorption as the surface area \
decreases”
xtitle “Surface area (m&lt;sup&gt;2&lt;/sup&gt; \
g&lt;sup&gt;-1&lt;/sup&gt;)”
ytitle “As (\mg L&lt;sup&gt;-1&lt;/sup&gt;)”
pymax 5000.0 # truncate the highest values
customxColumn surface_area
lines As
lineWidth 0.6
lineColor red
legendTextSize 0.0
extraText “extratextsurfacearea.dat”

CHEMISTRY

PRINT
# -reset false
PHASES
Fix_H+
H+ = H+
log_k 0.0

SELECTED_OUTPUT
-high_precision true
-reset false
USER_PUNCH
-headings totAs totP
-start
10 totAs=SYS(“As”,n,n$,t$,c)
20 totP=SYS(“P”,n,n$,t$,c)
30 punch totAs, totP
-end

# first simulation - set up initial conditions

SOLUTION 1
temp 25
pH 7.0
units mol/kgw
density 1
Na 1e-2
N(5) 1e-2
# Equilibrate Hfo with low As and P
As 1 ug/kgw
P 0 ug/kgw # P has an important effect
-water 1 kg
 Examples 420

EQUILIBRIUM_PHASES 1
Fix_H+ -7.0 NaOH 10
-force_equality true
O2(g) -0.67 10

SURFACE 1
Hfo_w &lt;initial_sites&gt; &lt;initial_surface_area&gt; &lt;mass&gt;
-equilibrate 1
END

# second simulation - now start reducing surface area always starting from the \
initial state
USER_PUNCH
-headings surface_area As
-start
10 As=tot(“As”)*74.9216*1e6
20 punch &lt;surface_area&gt; As
-end

SOLUTION 1
temp 25
pH 7.0
units mol/kgw
density 1
Na 1e-2
N(5) 1e-2
As &lt;totAs&gt; # tag name from selected output file headings above
P &lt;totP&gt; # mol/kgw
-water 1 # kg

EQUILIBRIUM_PHASES 1
Fix_H+ -7.0 NaOH 10 # keep a constant pH
O2(g) -0.67 10

SURFACE 1
Hfo_w &lt;sites&gt; &lt;surface_area&gt; &lt;mass&gt;
END
Examples 421
 Examples 422

63 CD-MUSIC: As(III) adsorption on

goethite

CD-MUSIC: As(III) remaining in solution

(after Stachowicz et al., 2006, Fig. 4)

-3 3 g/L, 0.55 mM AsT

5 g/L, 0.55 mM AsT
0.1M NaNO3 10 g/L, 0.55 mM AsT
As(III) in solution, log (mol/L)

3 g/L, 0.67 mM AsT

10 g/L, 0.67 mM AsT
-4

3 g/L, 0.67 mM AsT

•

3 g/L, 0.55 mM AsT

-5 •

5 g/L, 0.55 mM AsT

•

-6
10 g/L, 0.67 mM AsT
•

•
10 g/L, 0.55 mM AsT
-7
3 6 9 12
pH

C:\PhreePlot\demo\As-cd-music\As3-shvrfig4.ps

This example shows the calculated concentration of As(III) remaining in solution after
adsorption of As(III) on goethite (98 m2/g) as a function of pH. Calculations are based on the
CD-MUSIC model and parameters of Stachowicz et al. (2006) and reproduces their Figure 4.
As(III) loadings were varied by varying the solid/solution ratio and the initial As(III) concen-
tration.
Thermodynamic data for the aqueous As species are retrieved from the ecosat.inc include
file. The arsenic species in the default database have been removed from consideration by
defining all As(III) reactions in terms of a new element, [As3]. The CD-MUSIC model is
defined in the cdmusic.inc include file. Many parameter values are set with tags in the main
input file for convenience.
pxmin and pxmajor override the default x-axis scaling which would give an x-axis ranging
from 2 to 12 with labelling every 2 units. pxmin forces the x-axis to start at 3 while pxmajor
forces the axis labelling to be every 3 pH units. Similarly pymin and pymax force the y-axis
scaling to the desired range.
The label names are derived from the loop names which themselves are defined in column 1 of
the loopfile. changeColor has been set to TRUE to ensure that the different curves of the same
data column have different colours.
 Examples 423

SPECIATION
calculationType custom
calculationMethod 1
xmin 3.0
xmax 12.0
resolution 100
loopFile “loopfig4.dat”
numericTags &lt;G_uAs5K1CD&gt; = 26.62 \
&lt;G_uAs5m_z0&gt; = 0.30 \
&lt;G_uAs5m_z1&gt; = -1.30 \
&lt;G_uAs5K2CD&gt; = 29.29 \
&lt;G_uAs5b_z0&gt; = 0.47 \
&lt;G_uAs5b_z1&gt; = -1.47 \
&lt;G_uAs5K3CD&gt; = 32.69 \
&lt;G_uAs3K1CD&gt; = 4.91 \
&lt;G_uAs3K2CD&gt; = 7.26 \
&lt;G_uPK1CD&gt; = 20.8 \
&lt;G_uPK2CD&gt; = 29.2 \
&lt;G_uPK3CD&gt; = 35.4 \

&lt;mass&gt; = &lt;loop1&gt; \
&lt;AsT&gt; = &lt;loop2&gt;

PLOT
plotTitle “CD-MUSIC: As(III) remaining in \
solution&lt;br&gt;(after Stachowicz et al., 2006, \
Fig. 4)”
xtitle pH
ytitle “As(III) in solution, log (mol/L)”
pxmin 3
pxmajor 3
pymin -7
pymax -3
customxcolumn pH
lines [As3]
labelsize 1.5
extratext “extratextfig4.dat”

CHEMISTRY

SELECTED_OUTPUT
-reset false

SOLUTION 1
Temp 25
pH 2.9
units mol/kgw
# total As - [As3] is not As(3): it is not linked to any redox reactions
[As3] &lt;AsT&gt; mmol/kgw
Na 1e-1 # background electrolyte
[N5] 1e-1 # [N5] is not N(5) to avoid redox control

include ‘ecosat.inc’ # aqueous species database

include ‘cdmusic.inc’ # adsorbed species database

USER_PUNCH
-headings pH [As3]
10 PUNCH -la(“H+”), log10(tot(“[As3]”))

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

SURFACE 1
Goe_uniOHH0.5 3.45 98 &lt;mass&gt; # sites/nm2 m2/g g
-cap 0.85 0.75 # C1 C2 (in F/m2)
Goe_triOH0.5 2.7
-cd_music
-sites_units density

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
 Examples 424

-force_equality true
END
Examples 425
 Examples 426

64 CD-MUSIC: As(V) adsorption on

goethite

CD-MUSIC: As(V) remaining in solution (3 species)

(after Stachowicz et al., 2006, Fig. 6)

-3
0.5 mM As(V)
0.1M NaNO3
As(V) in solution, log (mol/L)

-4

3 g/L
•
-5

5 g/L
•

-6 10 g/L
•

-7
3 5 7 9 11
pH

C:\PhreePlot\demo\As-cd-music\As5-shvrfig6.ps

This is similar to the previous example except it is for the adsorption of As(V) rather than
As(III). The figure shows the calculated amount of As(V) remaining in solution after adsorp-
tion on goethite (98 m2/g) as a function of pH. The calculated curves were based on the CD-
MUSIC model and the parameters of Stachowicz et al. (2006). This figure replicates the cal-
culated curves of their Fig. 6.
 Examples 427

SPECIATION
calculationType custom
calculationMethod 1
xmin 3.0
xmax 12.0
resolution 100
# defines &lt;loop1&gt; and &lt;loop2&gt; tags for mass and AsT
loopfile “loopfig6.dat”
# these tags are used in cdmusic.inc
numericTags &lt;G_uAs5K1CD&gt; = 26.62 \
&lt;G_uAs5m_z0&gt; = 0.30 \
&lt;G_uAs5m_z1&gt; = -1.30 \
&lt;G_uAs5K2CD&gt; = 29.29 \
&lt;G_uAs5b_z0&gt; = 0.47 \
&lt;G_uAs5b_z1&gt; = -1.47 \
&lt;G_uAs5K3CD&gt; = 32.69 \
&lt;G_uAs3K1CD&gt; = 4.91 \
&lt;G_uAs3K2CD&gt; = 7.26 \
&lt;G_uPK1CD&gt; = 20.8 \
&lt;G_uPK2CD&gt; = 29.2 \
&lt;G_uPK3CD&gt; = 35.4 \

&lt;mass&gt; = &lt;loop1&gt; \
&lt;AsT&gt; = &lt;loop2&gt;

PLOT
plotTitle “CD-MUSIC: As(V) remaining in \
solution&lt;br&gt;(after Stachowicz et al., 2006, \
Fig. 6)”
xtitle pH
ytitle “As(V) in solution, log (mol/L)”
pxmin 3 # plot limits
pymin -7
pymax -3
# column name from selected output file: see below
customxcolumn pH
lines As5 # ibid
legendTextSize 0 # removes legend (key) from plot
# additional text for plot
extratext “extratextfig6.dat”

CHEMISTRY

SELECTED_OUTPUT
-reset false

SOLUTION 1
Temp 25
pH 2.9
units mol/kgw
[As5] &lt;AsT&gt; mmol/kgw
Na 1e-1
[N5] 1e-1

include ‘ecosat.inc’ # aqueous species database

include ‘cdmusic.inc’ # adsorbed species database

USER_PUNCH
-headings pH As5 # column names used above
10 PUNCH -la(“H+”), log10(tot(“[As5]”))

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

SURFACE 1
Goe_uniOHH0.5 3.45 98 &lt;mass&gt; # sites/nm2 m2/g g
-cap 0.85 0.75 # C1 C2 (in F/m2)
Goe_triOH0.5 2.7
-cd_music
-sites_units density
 Examples 428

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
END
Examples 429
 Examples 430

65 Kinetics of pyrite oxidation

Pyrite oxidation kinetics

(Appelo and Postma, 2005)

8I
PO2(g) or PCO2(g) (%)

6
O (g)
I
• 2

4
I
I J J
2 CO2(g)
•
J J
I J
J
J I I
I
0J
0 2 4 6 8 10 12 14
2
Time ( /10 hours)

C:\PhreePlot\demo\pyritekinetics\pyritekinetics.ps

This example shows the kinetics of the oxidation of pyrite from Appelo and Postma (2005), p
455-456, Fig. 9.28 (the calculated O2(g) curve here does not quite agree with A&P’s because
of small changes in the phreeqc.dat database used).
The resolution only has to be set to 1 since the KINETICS data block has an internal looping
mechanism (like REACTION) which produces a multi-lined selected output ‘file’. selectedOut-
putLines has therefore been set to auto so that all the lines in the selected output are picked
up.
The calculated points are plotted as a continuous curve using the lines keyword with two vari-
able (column) names, namely O2(g) and CO2(g). These names are defined in the USER_PUNCH
headings line and are automatically passed through to the ‘out’ file which is then used for the
plotting.
The data points are plotted using an extra file. legendTextSize has been set to 0 to eliminate
the legend. The Times-Roman font has been selected with the font keyword.
The x-axis scaling and title includes a scaling factor (x102) which indicates that the true scale
actually varies from 0–1400 hours.
 Examples 431

SPECIATION
jobTitle “Pyrite oxidation kinetics, A&P (2005) p \
455-6”
calculationType custom
calculationMethod 1
# only need to do one calculation as KINETICS block has its own looping
resolution 1
# multiline selected.out so copy all the lines produced into the out file
selectedOutputLines auto

PLOT
plotTitle “Pyrite oxidation \
kinetics&lt;br&gt;(Appelo and Postma, 2005)”
xtitle “Time (“ “ hours)”
ytitle \
“&lt;i&gt;P&lt;/i&gt;&lt;sub&gt;O2(g)&lt;/sub&gt; or \
&lt;i&gt;P&lt;/i&gt;&lt;sub&gt;CO2(g)&lt;/sub&gt; (%)”
pymax 9 # fix upper limit of y-axis
legendTextSize 0.0 # omit legend
customXcolumn Time # from out file
# modelled results - labels from USER_PUNCH block -&gt; out file
lines CO2(g) O2(g)
# plot experimental data points
extraSymbolsLines “pyritekineticsdata.dat”

CHEMISTRY

SELECTED_OUTPUT
-reset false
-high_precision true

USER_PUNCH
-headings Time CO2(g) O2(g) # defines column heading in out file
-start
10 PUNCH total_time/3600
20 PUNCH 100*10^si(“CO2(g)”), 100*10^si(“O2(g)”)
-end

RATES
Pyrite # the kinetic model
-start
1 A=15e3*m0
10 if SI(“Pyrite”)&gt;0 then goto 100
20 fH=mol(“H+”)
30 fFe2=(1+tot(“Fe(2)”)/1e-6)
40 if mol(“O2”)&lt;1e-6 then goto 80
# rate with oxygen
50 rO2=10^-8.19*mol(“O2”)*fH^-0.11
60 rO2_Fe3=6.3e-4*tot(“Fe(3)”)^0.92*fFe2^-0.43
70 goto 90
80 rem
# rate without oxygen
81 rFe3=1.9e-6*tot(“Fe(3)”)^0.28*fFe2^-0.52*fH^-0.3
90 rate=A*(m/m0)^0.67*(rO2+rO2_Fe3+rFe3)*(1-SR(“Pyrite”))
100 save rate*time # must include this
-end

SOLUTION_SPECIES
# force one way - dissolved N2(g) does not make nitric acid!
2NO3- + 12H+ + 10e- = N2 +6H2O; log_k 500

SOLUTION 1
-water 0.0069239 # kg
-temp 20
pH 7 charge; pe 14 O2(g) -1.0878
Ca 1 Calcite; C 1 CO2(g) -2.6021
Fe 1e-3 Goethite 2; N 1.3 N2(g) -0.0382

EQUILIBRIUM_PHASES
Goethite 2; Calcite 0; Gypsum 0 0
 Examples 432

GAS_PHASE 1
-fixed_pressure
-volume 0.02127; temp 20
CO2(g) 0.0025; O2(g) 0.0817; N2(g) 0.9157

KINETICS 1
Pyrite; -m0 1.32e-4; -step 0 5e5 5e5 5e5 5e5 5e5 5e5 5e5 5e5 5e5 5e5
INCREMENTAL_REACTIONS true

END
Examples 433
 Examples 434

66 Kinetics of quartz dissolution

Kinetics of quartz dissolution

(from Appelo ’Get-going’ sheet 11)

0.12

0.10

0.08
Si (mmol/kgw)

0.06

0.04
Rate equation:
0.02 dQtz/dt = -k * (1 - ΩQuartz)
k = 10-13.7 mol/m2/s (25 C)

0.00
0 1 2 3 4 5
Time (year)

C:\PhreePlot\demo\kineticsSi\kineticsSi.ps

This example demonstrates how a single iteration of the KINETICS data block generates a mul-
tiline selected output file which is read in with selectedOutputLines set to auto.
The label in the plot and the key to the right of the plot have been suppressed with labelSize
and legendTextSize both set to 0.
The extraText file also includes the use of various text enhancements – italics, subscripts,
superscripts and a Greek character.
 Examples 435

# plot of the dissolution of quartz vs time based on the PHREEQC kinetics model

SPECIATION
calculationType custom
calculationMethod 1
selectedOutputLines auto

PLOT
plotTitle “Kinetics of quartz \
dissolution&lt;br&gt;(from Appelo ‘Get-going’ sheet 11)”
xtitle “Time (year)”
ytitle “Si (mmol/kgw)”
customXColumn time # plot x = time
lines Si # plot y(line) = Si
linecolor blue
linewidth 0.6
labelSize 0 # suppresses label
legendTextSize 0 # suppresses key
numericTags &lt;log_k&gt; = -13.7
# additional text (including some Greek symbols)
extraText extratextkinetics.dat

CHEMISTRY
# Kinetics of quartz dissolution
# from Appelo ‘Get-going sheet #11’ (www.xs4all.nl/~appt)

RATES
#1 dQu/dt = -k * (1 - SR(Quartz). k = 10^-13.7 mol/m2/s (25 C)
#2 parm(1) = A (m2), parm(2) = V (dm3) recalculate to mol/dm3/s

Quartz # rate name

-start
10 moles = parm(1) / parm(2) * (m/m0)^0.67 * 10^&lt;log_k&gt; * (1 - SR(“Quartz”))
20 save moles * time # integrate. save and time must be in rate definition
-end # moles count positive when added to solution

KINETICS # Sediment: 100% qu, grain size 0.1 mm, por 0.3, rho_qu 2.65 kg/dm3
Quartz # rate name
-formula SiO2
-m0 102.7 # initial moles of quartz
-parms 22.7 0.162 # parameters for rate eqn. Here:
# Quartz surface area (m2/kg sediment), water filled porosity (dm3/kg sediment)
-step 1.5768e8 in 100 steps # 1.5768e8 seconds = 5 years
-tol 1e-8 # integration tolerance, default 1e-8 mol

INCREMENTAL_REACTIONS true # start integration from previous step

SOLUTION 1

SELECTED_OUTPUT
-reset FALSE

USER_PUNCH
# these are accumulated in the out file ready for plotting
-heading time Si SIQtz
-start
10 IF (step_no&gt;0) THEN punch total_time/3.1536e7, tot(“Si”)*1e3, SI(“Quartz”)
-end

END
 Examples 436

67 Symbols and lines

Symbols, dingbats and lines

0 1 2 3 4 5 6 7 8 9
# % ∗ + − . ? ⊥ _
10 11 12 13 14 15 16 17 18 19
⎯ | ′ ≤ ♣ ♦ ♥ ♠ ↔ ←
20 21 22 23 24 25 26 27 28 29
↑ → ↓ ∼ ©
30 31 32 33 34 35 36 37 38 39

 Ê    w v u     
40 41 42 43 44 45 46 47 50 51 52 53 54 55 56 57
i         
60 61 62 63 64 65 66 67 70 71 72 73 74 75 76 77


 
 
  !  "  # $ % & ' ( ) *
100 101 102 103 104 105 106 107 110 111 112 113 114 115 116 117
+ , - . / 0 1 2 3 4 5 6 7 8 9 :
120 121 122 123 124 125 126 127 130 131 132 133 134 135 136 137
; < = > ? @ A B C D E F G H I J
140 141 142 143 144 145 146 147 150 151 152 153 154 155 156 157
Ë K Ì L M N O Q R S T a b c d
160 161 162 163 164 165 166 167 170 171 172 173 174 175 176 177

200 201 202 203 204 205 206 207 210 211 212 213 214 215 216 217

220 221 222 223 224 225 226 227 230 231 232 233 234 235 236 237
e f g h j k l p o n m x y z {
240 241 242 243 244 245 246 247 250 251 252 253 254 255 256 257
| } ~  €  ‚ ƒ „ … † ‡ ˆ ‰ Š ‹
260 261 262 263 264 265 266 267 270 271 272 273 274 275 276 277
Œ  Ž   ‘ ’ “ ” • – — ˜ ™ š ›
300 301 302 303 304 305 306 307 310 311 312 313 314 315 316 317
œ  ž Ÿ   ¡ £ ¤ Ä ¥ À ¦ § ¨ © ª
320 321 322 323 324 325 326 327 330 331 332 333 334 335 336 337
« ¬ ­ ¢ ® ¯ ° ± ² ³ Á ´ Ç µ È ¶
340 341 342 343 344 345 346 347 350 351 352 353 354 355 356 357
É · ¸ Å ¹ Â Æ º Ã » ¼ ½ ¾ ¿
360 361 362 363 364 365 366 367 370 371 372 373 374 375 376 377

All symbols have a nominal height of 2 mm (without rims).

C:\PhreePlot\demo\symbols\symbols.ps

This example does no geochemistry but simply plots a grid of symbols with their codes. The
symbols are defined on an invisible grid in the extraSymbolsLines file called symbols.dat
while the code numbers printed below are defined in the extraText file called extratextsym-
bols.dat.

The surrounding box is drawn with four gray lines specified at the end of the extra file. axis-
NumberSize and axis have been set to 0 to suppress the plotting of the axis numbering and the
axis lines.
 Examples 437

SPECIATION
calculationType custom
calculationMethod 1

PLOT
units “mm”
plotTitle “Symbols, dingbats and lines”
xtitle “” # it should not look like an x-y plot
ytitle “”
# plot area large enough not clipped gray border
pxmin -2
pxmax 18
pxmajor 2
pymin -90
pymax 110
pymajor 20
tickSize 0
axisNumberSize 0
axisLineWidth 0
# contains the list of symbols and their positions etc
extraSymbolsLines “symbols.dat”
# demonstrates superscripts etc
extraText “extratextsymbols.dat”
 Examples 438

68 Varying symbols and lines in plots

2.0
•
SIAl(OH)3(a)*
0
concentration (mmol kgw-1)

1.5
• -2
SIfluorite*

Saturation index
1.0 SIcalcite*
•
AlT -4
•

Ca
0.5 •
• -6
Ca(HCO3)2
Alk
•
0.0 -8

-0.5 -10
5.0 5.5 6.0 6.5 7.0 7.5 8.0
pH

C:\PhreePlot\demo\symbols\plotsymbols.ps

This example demonstrates how different lines and sets of points of custom plots can have dif-
ferent attributes associated with them. Some acidic, Al-F-containing water is titrated with
Ca(HCO3)2. Eight variables are PUNCHed to the selected output. pH is used as the x-axis and
the other variables are plotted on the y- and 2y-axes according to the lists given in points, lines
and lines2y. Attributes are pulled off the associated lists (pointColor, pointType, pointSize
etc.) until exhausted in which case the list is automatically extended (colours) or recycled
(other attributes). There is a default sequence of 15 colours (red, blue, green, orange, cyan,
magenta, brown, sky, purple, gray, yellow, maroon, lawn, spring, black) for each type of list
(points and lines, y and 2y axes). These lists are rearranged according to the individual input
colour lists which effectively promote their members to the top of the respective sequence. If
there are more than one subsets of data, the colour density is cycled (not here).
The attributes chosen for a particular dataset depend on the position of that dataset in the
input list. For example, Alk is third in the points list so will pick up the third pointColor, third
pointType, third pointSize, and so on. Symbol types are defined either by number (see the
preceding Example) or name (see Appendix 3). The first six symbols can have a separate rim-
Color. The width of the rim is defined in terms of the fraction of the overall symbol width
(rimFactor). Dashed lines are signified by negative line widths and here are on the 2y axis (*).
 Examples 439

This is the basic method of assigning attributes. Colour selection can be modified from this by
using changeColor, pointsSameColor and restartColorSequence. The colours and other
attributes can also be set using the line colour dictionary and ensuring its use with lineColor-
Dictionary 1 or 2.
 Examples 440

# demonstrates the use of different symbols, colours and line types in a plot.
# For reference, the 15 auto color sequence is:
# red, blue, green, orange, cyan, magenta, brown, sky,
# purple, gray, yellow, maroon, lawn, spring, black
SPECIATION
calculationMethod 1
calculationType custom
xmin 5
xmax 8
resolution 20
PLOT
xtitle pH
ytitle “concentration (mmol kgw^-1)”
2ytitle “Saturation index”
customXcolumn pH # this is used as the x-axis
p2ymax 1
# these will be plotted as points
points Ca(HCO3)2 Al_T Alk Ca
# these will be plotted as lines
lines Ca(HCO3)2 Al_T Alk Ca
lines2y SI_calcite SI_fluorite SI<sub>Al(OH)3(a)</
sub>
pointType 1 2 6 # symbols to use in sequence for ‘points’, recycled
# colors to use in sequence for ‘points’
pointColor gray6 green2 red2 sky2
pointSize 3 # size of symbols, recycled
# explcit rim color for 2 points then auto (red4, blue4)
rimColor black green6 # recycled
rimFactor 0.08 # fractional rim width, recycled
lineColor black green6 red blue # colors to use in sequence for ‘lines’
# colors to use in sequence for ‘lines2y’ then auto sequence
lineColor2y purple brown6
# line width to use for ‘lines2y’, negative for dashed, recycled
lineWidth2y -0.4
changecolor f

CHEMISTRY
# titrate acidic Al-rich water with Ca(HCO3)2
PHASES
Fixed_H+
H+ = H+
log_k 0.
SOLUTION
-units mmol/kgw
pH 5
Al1
F2
Cl3 charge
SAVE solution 1
END

USE solution 1
EQUILIBRIUM_PHASES
Fixed_H+ -<x_axis> Ca(HCO3)2
Al(OH)3(a) 0 0
Fluorite 0 0
Calcite 0 0
CO2(g) -3.5
SELECTED_OUTPUT
-reset FALSE

USER_PUNCH
-headings Ca(HCO3)2 pH Al_T Alk Ca SI_calcite SI_fluo-
rite SI_Al(OH)3(a)
10 IF (STEP_NO = 1) THEN PUNCH (10-EQUI(“Fixed_H+”))/TOT(“water”)*1e3, -la(“H+”),
TOT(“Al”)*1e3, Alk*1e3, TOT(“Ca”)*1e3, SI(“Calcite”), SI(“Fluorite”),
SI(“Al(OH)3(a)”)
END
Examples 441
 Examples 442

69 Text

Text: demonstrating justification, orientation and character sets

subitalicsboldΓρεεκSingle Greek γρεεκ break

Left: sup sub sup
break
subitalicsboldΓρεεκSingle Greek γρεεκ break
Center: sup sub sup

Greek γρεεκ break

90: sup sub sub
break
subitalicsboldΓρεεκSingle Greek γρεεκ break
sup sup
Right: sub 123123
123123
break

k
45

123123

ea
:

123123
su

br
sup
p su

κ
italicsboldΓρεεκSingle

εε
b
su ub

γρ
s
p it

ke
al

re
ic

sub subitalicsboldΓρεεκSingle

G
sb

e
o

gl
ld

n
Γρ b
k Si

0: sup sup
sub subitalicsboldΓρεεκSingle Greek γρεεκ break
ea εκ εεbreak

Greek γρεεκ break sub subitalicsboldΓρεεκSingle

break
br ε
κS ak

180:
Γρ

break
sup sup
re
in

break
ld

gl
o

e
sb

G
ic

re
al

ek
Greek γρεεκ break
b it
su p
b su

γρ
εε
su

κ
p

sup
su

br
ea
5:
-4

abcde fghij klmno pqrst uwxyz

k

αβχδε φγηιϕ κλμνο πθρστ υωξψζ

sup

ABCDE FGHIJ KLMNO PQRST UWXYZ

270:

ΑΒΧΔΕ ΦΓΗΙϑ ΚΛΜΝΟ ΠΘΡΣΤ ϒΩΞΨΖ

C:\PhreePlot\demo\symbols\text.ps

This example also does no geochemistry but demonstrates some of the capabilities of justify-
ing and rotating text as well as enhancing it with subscripts and superscripts and Greek charac-
ters and text. These are all defined in the extraText file extratexttext.dat.
The light yellow background colour has been set with the backgroundColor setting. It only
occupies the ‘plot’ area.
 Examples 443

SPECIATION
calculationType custom
calculationMethod 1

PLOT
backgroundColor “yellow0”
plotTitle “<b>Text: demonstrating <i>justification</i>,
<i>orientation</i> and <i>character sets</i></b>”
xtitle “” # not supposed to look like an x-y plot
ytitle “”
xoffset 60
pxmin -2.0
pxmax 12.0
pxmajor 1.0
pymin -20.0
pymax 100.0
pymajor 10.0
tickSize 0.0
axisNumberSize 0.0
axisLineWidth 0.0
pointSize 0.0
# file containing special text
extraText “extratexttext.dat”
CHEMISTRY
 Examples 444

70 Simple PHREEQC looping

PhreePlot does not have to be used to produce plots. It also provides a simple way of looping
around a PHREEQC input file automtically substituting a different value during each itera-
tion. The input file in demo\PHREEQC_looping\Fespecies demonstrates this. It speciates a
trace Fe-containing solution that is adjusted to various pHs. It is split into two simulations so
that the initial solution calculations can be omitted from the PRINT output.
The pH is generated from xmin, xmax and resolution. There are always resolution iterations
of PhreePlot during looping of the x or y axes. Hence with xmin = -10, xmax = -4 and resolu-
tion = 3, the x-values of -10, -7 and -4 will be generated. These values are automatically asso-
ciated with the <x_axis> tag which is used in the penultimate line of code to ‘fix’ the pH.

# Simple looping on one variable, log (H+) activity

# Fe speciation at pH 4, 7, 10
SPECIATION
calculationType "custom"
xmin -10
xmax -4
resolution 3 # i.e. pH 10, 7, 4
debug 2 # writes phreeqcall.out file
selectedOutputLines 1 0 0 # no SELECTED_OUTPUT expected
CHEMISTRY
PRINT
-reset FALSE # don't output initial solution calculation
PHASES
Fix_H+
H+ = H+
log_k 0
SOLUTION 1
pH 2
units mol/kgw
Fe(3) 1e-6
Na 1e-2
Cl 1e-2
# no reaction so no need to SAVE solution 1
END

USE solution 1
PRINT
-equilibrium_phases true
-species TRUE
EQUILIBRIUM_PHASES
Fe(OH)3(a) 0 0
Fix_H+ <x_axis> NaOH
END
and the output from the three iterations of PHREEQC are accumulated in phreeqcall.out
which, when using the wateq4f.dat database looks like this:

================================== Simulation 1 ===================================

------------------------------------
Reading input data for simulation 1.
------------------------------------

PRINT
reset FALSE # don't output initial solution calculation
-------------------------------Phase assemblage--------------------------------

Moles in assemblage
Phase SI log IAP log KT Initial Final Delta

Fe(OH)3(a) -0.00 17.91 17.91 0.000e+000 7.572e-007 7.572e-007

Fix_H+ -10.00 -10.00 0.00
 Examples 445

NaOH is reactant 1.000e+001 9.989e+000-1.124e-002

----------------------------Distribution of species----------------------------

Log Log Log

Species Molality Activity Molality Activity Gamma

OH- 1.134e-004 1.001e-004 -3.945 -4.000 -0.054

H+ 1.113e-010 1.000e-010 -9.953 -10.000 -0.047
H2O 5.551e+001 9.995e-001 1.744 -0.000 0.000
Cl 9.998e-003
Cl- 9.998e-003 8.798e-003 -2.000 -2.056 -0.056
FeCl+ 4.580e-018 4.042e-018 -17.339 -17.393 -0.054
FeCl+2 3.414e-026 2.071e-026 -25.467 -25.684 -0.217
FeCl2+ 9.221e-028 8.138e-028 -27.035 -27.090 -0.054
FeCl3 7.134e-031 7.160e-031 -30.147 -30.145 0.002
Fe(2) 1.872e-015
FeOH+ 1.192e-015 1.052e-015 -14.924 -14.978 -0.054
Fe+2 5.487e-016 3.328e-016 -15.261 -15.478 -0.217
Fe(OH)2 8.916e-017 8.949e-017 -16.050 -16.048 0.002
Fe(OH)3- 3.765e-017 3.323e-017 -16.424 -16.478 -0.054
FeCl+ 4.580e-018 4.042e-018 -17.339 -17.393 -0.054
Fe(3) 2.427e-007
Fe(OH)4- 2.213e-007 1.953e-007 -6.655 -6.709 -0.054
Fe(OH)3 2.135e-008 2.143e-008 -7.671 -7.669 0.002
Fe(OH)2+ 1.886e-011 1.664e-011 -10.724 -10.779 -0.054
FeOH+2 8.290e-018 5.029e-018 -17.081 -17.299 -0.217
Fe+3 2.400e-025 7.793e-026 -24.620 -25.108 -0.488
FeCl+2 3.414e-026 2.071e-026 -25.467 -25.684 -0.217
FeCl2+ 9.221e-028 8.138e-028 -27.035 -27.090 -0.054
FeCl3 7.134e-031 7.160e-031 -30.147 -30.145 0.002
Fe2(OH)2+4 5.027e-033 6.807e-034 -32.299 -33.167 -0.868
Fe3(OH)4+5 0.000e+000 0.000e+000 -40.269 -41.626 -1.357
H(0) 2.347e-030
H2 1.173e-030 1.178e-030 -29.931 -29.929 0.002
Na 2.124e-002
Na+ 2.124e-002 1.877e-002 -1.673 -1.726 -0.054
O(0) 5.983e-033
O2 2.991e-033 3.002e-033 -32.524 -32.523 0.002

================================== Simulation 2 ===================================

-------------------------------Phase assemblage--------------------------------

Moles in assemblage
Phase SI log IAP log KT Initial Final Delta

Fe(OH)3(a) 0.00 17.91 17.91 0.000e+000 9.596e-007 9.596e-007

Fix_H+ -7.00 -7.00 0.00
NaOH is reactant 1.000e+001 9.989e+000-1.113e-002

----------------------------Distribution of species----------------------------

Log Log Log

Species Molality Activity Molality Activity Gamma

OH- 1.133e-007 1.001e-007 -6.946 -7.000 -0.054

H+ 1.113e-007 1.000e-007 -6.954 -7.000 -0.046
H2O 5.551e+001 9.995e-001 1.744 -0.000 0.000
Cl 9.998e-003
Cl- 9.998e-003 8.802e-003 -2.000 -2.055 -0.055
FeCl+ 1.181e-016 1.043e-016 -15.928 -15.982 -0.054
FeCl+2 3.410e-017 2.071e-017 -16.467 -16.684 -0.216
FeCl2+ 9.225e-019 8.144e-019 -18.035 -18.089 -0.054
FeCl3 7.143e-022 7.168e-022 -21.146 -21.145 0.002
Fe(2) 1.428e-014
Fe+2 1.413e-014 8.584e-015 -13.850 -14.066 -0.216
FeCl+ 1.181e-016 1.043e-016 -15.928 -15.982 -0.054
FeOH+ 3.073e-017 2.713e-017 -16.512 -16.567 -0.054
Fe(OH)2 2.300e-021 2.308e-021 -20.638 -20.637 0.002
Fe(OH)3- 9.708e-025 8.571e-025 -24.013 -24.067 -0.054
Fe(3) 4.043e-008
Fe(OH)3 2.135e-008 2.143e-008 -7.671 -7.669 0.002
Fe(OH)2+ 1.885e-008 1.664e-008 -7.725 -7.779 -0.054
Fe(OH)4- 2.212e-010 1.953e-010 -9.655 -9.709 -0.054
FeOH+2 8.278e-012 5.029e-012 -11.082 -11.299 -0.216
Fe+3 2.392e-016 7.793e-017 -15.621 -16.108 -0.487
FeCl+2 3.410e-017 2.071e-017 -16.467 -16.684 -0.216
FeCl2+ 9.225e-019 8.144e-019 -18.035 -18.089 -0.054
Fe2(OH)2+4 4.997e-021 6.806e-022 -20.301 -21.167 -0.866
FeCl3 7.143e-022 7.168e-022 -21.146 -21.145 0.002
Fe3(OH)4+5 5.332e-026 2.367e-027 -25.273 -26.626 -1.353
H(0) 1.561e-039
H2 7.807e-040 7.835e-040 -39.108 -39.106 0.002
Na 2.113e-002
Na+ 2.113e-002 1.868e-002 -1.675 -1.729 -0.053
O(0) 1.352e-014
O2 6.760e-015 6.784e-015 -14.170 -14.169 0.002
 Examples 446

================================== Simulation 3 ===================================

-------------------------------Phase assemblage--------------------------------

Moles in assemblage
Phase SI log IAP log KT Initial Final Delta

Fe(OH)3(a) -1.44 16.47 17.91 0.000e+000 0.000e+000

Fix_H+ -4.00 -4.00 0.00
NaOH is reactant 1.000e+001 9.989e+000-1.102e-002
----------------------------Distribution of species----------------------------

Log Log Log

Species Molality Activity Molality Activity Gamma

H+ 1.113e-004 1.000e-004 -3.954 -4.000 -0.046

OH- 1.133e-010 1.001e-010 -9.946 -10.000 -0.054
H2O 5.551e+001 9.995e-001 1.744 -0.000 0.000
Cl 9.998e-003
Cl- 9.998e-003 8.802e-003 -2.000 -2.055 -0.055
FeCl+2 1.243e-009 7.551e-010 -8.906 -9.122 -0.216
FeCl2+ 3.363e-011 2.969e-011 -10.473 -10.527 -0.054
FeCl+ 5.990e-013 5.288e-013 -12.223 -12.277 -0.054
FeCl3 2.604e-014 2.613e-014 -13.584 -13.583 0.002
Fe(2) 7.224e-011
Fe+2 7.164e-011 4.352e-011 -10.145 -10.361 -0.216
FeCl+ 5.990e-013 5.288e-013 -12.223 -12.277 -0.054
FeOH+ 1.558e-016 1.376e-016 -15.807 -15.861 -0.054
Fe(OH)2 1.166e-023 1.170e-023 -22.933 -22.932 0.002
Fe(OH)3- 4.922e-030 4.346e-030 -29.308 -29.362 -0.054
Fe(3) 9.997e-007
Fe(OH)2+ 6.872e-007 6.067e-007 -6.163 -6.217 -0.054
FeOH+2 3.017e-007 1.833e-007 -6.520 -6.737 -0.216
Fe+3 8.718e-009 2.841e-009 -8.060 -8.547 -0.487
FeCl+2 1.243e-009 7.551e-010 -8.906 -9.122 -0.216
Fe(OH)3 7.784e-010 7.812e-010 -9.109 -9.107 0.002
FeCl2+ 3.363e-011 2.969e-011 -10.473 -10.527 -0.054
Fe2(OH)2+4 6.640e-012 9.045e-013 -11.178 -12.044 -0.866
FeCl3 2.604e-014 2.613e-014 -13.584 -13.583 0.002
Fe(OH)4- 8.065e-015 7.120e-015 -14.093 -14.147 -0.054
Fe3(OH)4+5 2.583e-015 1.146e-016 -14.588 -15.941 -1.353
H(0) 0.000e+000
H2 0.000e+000 0.000e+000 -40.821 -40.819 0.002
Na 2.101e-002
Na+ 2.101e-002 1.858e-002 -1.677 -1.731 -0.053
O(0) 3.613e-011
O2 1.806e-011 1.813e-011 -10.743 -10.742 0.002

The output for pH 10, 7 and 4 shows that Fe(OH)3(a) is precipitated at pH 10 and 7 but not
at pH 4.
More flexible control of the <loop> variable can be had by reading in the values from a file
using the loopFile keyword. The FespeciesLoopFile.ppi example in the demo directory pro-
vides an example of this approach.
Examples 447
 Examples 448

71 PHREEQC mineral species

By default and for good reason, PHREEQC does not automatically precipitate all minerals for
which the saturation index exceeds zero. Nor is it possible easily to encourage it to do so. The
mineral species must be explicitly included in an EQUILIBRIUM_PHASES block. The actual min-
eral species that need to be considered will depend on the database being used (even the name
of the same mineral species can vary between databases).
The following input file from demo\PHREEQC_minerals\FeZnminerals demonstrates how a list
of all possible minerals can be created in the normal PHREEQC output file and used for past-
ing into the input file. The printphases.inc include file is used. This makes use of the
PHREEQC SYS() function for enquiring about the status of the system:

# runs a single iteration of PHREEQC to generate a list of all possible Fe and Zn

mineral phases
SPECIATION
calculationType "custom"
resolution 0 # 1 iteration only
debug 1 # writes phreeqc.out file
selectedOutputLines 0 # tells PhreePlot not to expect any
SELECTED_OUTPUT
CHEMISTRY
include 'printphases.inc'
SOLUTION 1
pH 1.95
units mol/kgw
Fe 0.01
Zn 1e-6
Na 1e-1
Cl 1e-1
END
and printphases.inc looks like this:
PRINT
-reset false
-user_print true
USER_PRINT
-start
10 totm = SYS("phases", nm, nm$, tm$, cm)
20 FOR i = 1 TO nm
30 k = INSTR(nm$(i),"(g)")
40 k = k+INSTR(nm$(i),"Fix")+INSTR(nm$(i),"FIX")+INSTR(nm$(i),"fix")
50 IF(k > 0) THEN 70
60 PRINT" ", CHR$(35)+PAD(nm$(i), 30), "0", "0"
70 NEXT i
-end

CHR$(35) is a convenient way of including the # symbol.

The output in phreeqc.out using the wateq4f.dat database looks like this:
------------------------------------
Reading input data for simulation 1.
------------------------------------

PRINT
reset false
-------------------User print-------------------------

#Fe(OH)2.7Cl.3 0 0
#Halite 0 0
#Goethite 0 0
#Hematite 0 0
#Fe(OH)3(a) 0 0
#Magnetite 0 0
 Examples 449

#Zincite(c) 0 0
#ZnO(a) 0 0
#Zn(OH)2-e 0 0
#Zn(OH)2-g 0 0
#Zn(OH)2-b 0 0
#Zn(OH)2-c 0 0
#Zn(OH)2-a 0 0
#ZnCl2 0 0
#Maghemite 0 0
#Zn2(OH)3Cl 0 0
#Fe3(OH)8 0 0
#ZnMetal 0 0
#Zn5(OH)8Cl2 0 0

The output for the minerals given above can be pasted into an input file and the required min-
erals un-commented. ‘0 0’ indicates that the mineral should precipitate when the saturation
index exceeds 0 (first 0) but will not dissolve since the initial abundance is 0 (second 0) in all
cases.
Therefore in order to find out all the possible mineral species in your system, edit the SOLU-
TION block of this file to include the components of interest, rename and run. Then look at
the phreeqc.out file.
 Examples 450

Species distribution plots

It is often useful to know the relative abundance of all the chemical species in a system. ‘spe-
cies’ plots are a special type of custom plot that produce plots of the distribution or abun-
dance of all the species for a particular element as a function of some master variable, often set
to pH.
There are two variants of this plot in PhreePlot, one produces a percentage distribution and
the other plots the log concentration. While these plots could be produced using the normal
custom plot approach, the species plot approach does not require any prior knowledge of the
names of the species present and is therefore usually easier to setup.
Examples 451
 Examples 452

72 Cd speciation vs pH (species plot)

100 Cd speciation Cd species

(using speciesvsph.inc) Cd2+
CdCl+
CdNO3+
80 Cd2+
CdOH +

Cd2+ Cd(OH)2 CdCl+

Cd(OH)
80 CdNO3+ 2
Cd(OH)
CdOH + 3-
% in species

Cd(OH)2
•
60 •
Cd(OH)242-
Cd(OH)
-
Cd2+ Cd(OH)
CdOHCl 3
Cd(OH)42-
60 CdOHCl
% in species

40 Cd(OH)3-
•
Cd(OH)3-
CdOH+•
40
20
+ 2-
CdOHCl Cd(OH)4 •
CdOH
CdNO3+ •
•
20 •
CdCl+
0
CdOHCl
6 7
CdNO3+ 8 9 10 11 12 13

0
CdCl+ pH
Cd(OH)42-
6 8 10 12
pH
C:\PhreePlot\demo\Cdspeciation(species1)\Cdspeciation(species1)_Cd.ps

This produces similar output to the previous example but uses the ‘species’ calculationType
to label the curves automatically. It uses the species-value paired output approach.
A plot automatically generates a % species versus pH plot. This is a special type of
species
custom plot in which PhreePlot expects the ‘out’ file to contain a succession of species name-
%distribution pairs. It ignores any headings. Rather it gets the species name from the preced-
ing column. It also expects the x-axis variable to be sent as the first pair of values. This is pH in
this example but by changing the include file, any variable can be used.
The speciesvsph.inc include file specifies the ‘out’ or plot file. Pure phases (assumed to be
mineral species) are appended with ‘(s)’ to distinguish them from aqueous species.
In order to generate the above type of plot, it is necessary to specify: (i) “species” as the plot
type; (ii) a main species, here ‘Cd’; (iii) an initial chemistry and any equilibrium phases, and
(iv) the x-axis variable and its range. It is also necessary to indicate with an <x_axis> tag how
the x-axis variable changes the chemistry (here pH) and point customXcolumn to the pH col-
umn.
If any of the following plot titles are blank, they are set as follows: (i) xtitle = name accompa-
nying the x-axis value (position defined by customXcolumn); (ii) ytitle = “% species”, and (iii)
plotTitle = “Distribution of <mainspecies> with <xtitle>” where the angle brackets indicate
 Examples 453

the substitutions to be made. To omit, set the appropriate colour to ‘nd’.

 Examples 454

SPECIATION
jobTitle “Speciation vs pH using ‘species’ plot \
type”
calculationType species
calculationMethod 1
mainSpecies Cd
xmin -13.0 # logH range
xmax -6.0
resolution 100

PLOT
plotTitle “Cd speciation&lt;br&gt;(using \
speciesvsph.inc)”
# x-axis value is the second column - the first column is ‘pH’ (see out file)
customXcolumn 2
pxmax 13 # default is 14
minimumYValueForPlotting 5.0 # eliminates minor species
legendTitle “Cd species”
extraText “extratextCdspeciation.dat”

CHEMISTRY

# contains the logic for outputting the expected x-axis, y-axis (%distr) pairs
# expected by ‘species’ plot type
include ‘speciesvsph.inc’

PHASES
Fix_H+
H+ = H+
log_k 0.0
SOLUTION 1
temp 25
pH 7
units mol/kgw
density 1
Cd 1e-4
Cl 2e-3
Na 0.1
N(5) 0.1 charge
END

USE solution 1
EQUILIBRIUM_PHASES
O2(g) -0.677 0.1
Fix_H+ &lt;x_axis&gt; NaOH 10
-force_equality true
END
Examples 455
 Examples 456

73 Cd speciation vs pH (log species plot)

log species concn

log species vs pH
concn vs pH
(using logspeciesvsph.inc)
(using logspeciesvsph.inc)

0 Cd2+
-5 +
CdCl+ CdNO3
CdOH+
Cd2+ Cd(OH)2
CdNO3+ • •
-5 • •
log concentration (mol/kgw)
log concentration (mol/kgw)

CdOHCl
CdCl+ CdOH+
•
-10 •
CdOHCl •
Cd(OH)2 Cd2OH3+ CdCl2
CdCl•3-
-10 CdCl 2
•
• CdCl3-
-15 Cd(OH)3-
Cd2OH 3+
Cd2+
• Cd2OH3+
-15 Cd(OH)42-
CdCl+
Cd2+CdCl
Cd(OH)3-
2
3+
Cd2OH
CdCl3-
-20 +
CdClCdNO3+
+
CdClCdOH
-20 2
Cd(OH)2
CdCl3-
Cd(OH)3-
CdNO3+
Cd(OH)42-
+
CdOHCdOHCl
-25 Cd(OH)2

-25 2-
Cd(OH)3-
Cd(OH)42-
Cd(OH)4
CdOHCl

-30 -306 8 9
6 7 8 10 10 11 12 12 13
pH pH

C:\Program Files\PhreePlot\0.01\demo\Cdspeciation(log)\Cdspeciation(logspecies).ps
C:\PhreePlot\demo\Cdspeciation(log)\Cdspeciation(logspecies)_Cd.ps

This is a variant of the previous example but plots the log of the species concentrations vs pH
rather than the %distribution. This change is made entirely within the include file which con-
trols the values sent to the ‘out’ file.. The include file has been changed to output log concen-
trations (see logspeciesvspH.inc) and ytitle has been given explicitly to override the default
‘% species’ title.
The size of the legend (key) text has been reduced using legendTextSize and its placement has
been set in the extraText file.
Examples 457
 Examples 458

74 U species plot (oxidizing)

U speciation vs pH (oxidizing conditions)

(using speciesvsph.inc)

100 UO22+
log P O2 = -0.7 atm (UO2)3(OH)5+
log P CO2 = -3.5 atm UO2CO3
UO2(CO3)22-
80 UO2(CO3)34-
UO2OH+
• UO2(OH)3-
% in species

UO2(CO3)34-
60
UO2(CO3)22-•

UO 2+
• 2
40 UO2OH+
•

20
UO2CO3 UO (OH)3-
• • 2
(UO2)3(OH)5•+

0
3 4 5 6 7 8 9 10
pH

C:\PhreePlot\demo\Uspeciation\Uspeciationox_U.ps

Another example of a ‘species’ plot. Oxidising conditions have been maintained by equilibrat-
ing with a high partial pressure of oxygen. This is set by the <pO2> tag. Similarly the CO2(g)
partial pressure is set with the <pCO2> tag.
The U speciation is dominated by U(VI) species under these conditions. Note the carbonate
species at high pH.
useLineColorDictionary has been set to 1 to force the colour dictionary (linecolor.dat) to
be read. This is where the colour of each of the lines is defined.
The minimumYValueForPlotting has been set to 5% so that minor species are not plotted.
The labelSize has been set to 1.5 mm. The label anchors shown as red dots by each of the
labels can be removed by setting trackSymbolColor to ‘nd’.
 Examples 459

SPECIATION
jobTitle “Speciation vs pH using ‘species’ plot \
type”
calculationType species
calculationMethod 1
mainSpecies “U”
xmin 3.0
xmax 10.0
resolution 100
numericTags &lt;pCO2&gt; = “-3.5” \
&lt;pO2&gt; = “-0.677” # atmospheric PO2
PLOT
plotTitle “U speciation vs pH (oxidizing \
conditions)&lt;br&gt;(using speciesvsph.inc)”
pxmin 3.0
pxmajor 1.0
labelSize 1.5
# only plot species with max(conc)&gt;5%
minimumYValueForPlotting 5.0
extraText “extratextUspeciation_ox.dat”

CHEMISTRY

include ‘speciesvsph.inc’ # PHREEQC code for outputting species-concn pairs

PHASES
Fix_H+
H+ = H+
log_k 0.0

SELECTED_OUTPUT
-reset false # omit all default output

SOLUTION 1
temp 25
pH 7
pe 4
units mol/kgw
U 1e-6 # total U
Cl 0.01 # background electrolyte
Na 0.01
END

USE solution 1 # second (final) simulation - loops on this one

EQUILIBRIUM_PHASES
O2(g) &lt;pO2&gt; 0.1
Fix_H+ -&lt;x_axis&gt; NaOH 1
-force_equality true
# Uraninite(c) 0 0 # omit for \
solution only
CO2(g) &lt;pCO2&gt; 1.0
END
 Examples 460

75 U species plot (reducing)

U speciation vs pH (reducing conditions)

(using speciesvspH.inc)

100 •
UO2+
log P O2 = -70 atm U(OH)4 UO22+
log P CO2 = -3.5 atm UO2(CO3)34-
U(OH)22+
80 U(OH)3+
U(OH)4
% in species

60 UO +
• 2

UO2(CO3)34-•

40

20
U(OH)3+
•

UO 2+ 2+
• 2 •U(OH)2
0
3 4 5 6 7 8 9 10
pH

C:\PhreePlot\demo\Uspeciation\Uspeciationred_U.ps

This is similar to the previous plot but <pO2> has been set to a low oxygen fugacity log PO2(g) =
-70. Most of the plotted species are U(IV) species but UO2(CO3)34- is a U(VI) species and
UO2+ is a U(V) species.
It would be necessary to go to an even lower <pO2> value (-75) to ensure that no U(VI) species
are plotted.
 Examples 461

SPECIATION
jobTitle “Speciation vs pH using ‘species’ plot \
type”
calculationType species
calculationMethod 1
mainSpecies “U”
xmin 3.0
xmax 10.0
resolution 100
numericTags &lt;pCO2&gt; = “-3.5” \
# quite strongly reducing
&lt;pO2&gt; = “-70”
PLOT
plotTitle “U speciation vs pH (reducing \
conditions)&lt;br&gt;(using speciesvspH.inc)”
pxmin 3.0
pxmajor 1.0
labelSize 1.5
# only plot species with max(conc)&gt;5%
minimumYValueForPlotting 5.0
extraText “extratextUspeciation_red.dat”

CHEMISTRY

include ‘speciesvspH.inc’ # PHREEQC code for outputting species-concn pairs

PHASES
Fix_H+
H+ = H+
log_k 0.0

SELECTED_OUTPUT
-reset false # omit all default output

SOLUTION 1
temp 25
pH 7
pe 4
units mol/kgw
U 1e-6 # total U
Cl 0.01 # background electrolyte
Na 0.01
END

USE solution 1 # second (final) simulation - loops on this one

EQUILIBRIUM_PHASES
O2(g) &lt;pO2&gt; 0.1
Fix_H+ -&lt;x_axis&gt; NaOH 1
-force_equality true
# Uraninite(c) 0 0 # omit for \
solution only
CO2(g) &lt;pCO2&gt; 1.0
END
 Examples 462

76 Carbon speciation vs pH

CCspeciation
speciationvs
vspH
pH
using
usingspeciesvsph.inc
speciesvsph.inc

100
100 CH
CH44
log C(4) = 1e-1
log TC(4) mol/kgw
T= 1e-1 mol/kgw CO
CO22
CO332-2-
CO
HCO33--
HCO
80
80 NaCO3--
NaCO 3
NaHCO
CO2 NaHCO33
HCO3-
% in species
% in species

60
60
•
HCO3-
•
CO32-

40
40 NaCO3-
•
CO2
• NaCO3-

20
20 CO32-

NaHCO
NaHCO
3• 3
CH4 CH4
00 •

22 44 6 6 8 8 10 10 12 12 14
pH
pH

C:\PhreePlot\demo\carbonspeciation\carbonspeciationvsph(species1)_C.ps
C:\Program Files\PhreePlot\0.01\demo\carbonspeciation\carbonspeciationvsph(species1).ps

This uses a ‘species’ plot to show the variation in carbon species with pH in an oxidising
environment. It uses the ‘speciesvspH.inc’ include file and so plots % in species vs pH.
The PHREEQC output is accumulated in ‘species name, species concentration’ pairs, one line
per pH. The order of the species output is based on decreasing C concentration (i.e. highest
concentration first) and so the order changes as the pH changes. Because it is a ‘species’ plot,
PhreePlot expects this type of paired output and sorts the data so that the column positions
for all species are fixed. This enables them to be plotted.
With the given include file and input file setup, the first column is defined as the x-axis varia-
ble and so the value of customXcolumn is ignored.
 Examples 463

SPECIATION
calculationType species # plot %C species vs pH
calculationMethod 1
mainSpecies C
xmin 2 # controls the range of pH plotted
xmax 13
# controls the number of points on each curve
resolution 100
PLOT
plotTitle “C speciation vs pH&lt;br&gt;using \
speciesvsph.inc”
extraText “extratextcarbonspeciation.dat”
# pxmax 13

CHEMISTRY

# this file exports the required x-axis(pH), y-axis (%) value pairs. Edit as
# required.
include ‘speciesvsph.inc’

PHASES
Fix_H+
H+ = H+
log_k 0.0
SOLUTION 1
temp 10 # carbonate speciation at least depends on temperature
pH 7
units mol/kgw
C(4) 1e-1 as HCO3 # total C
Na 0.1 charge # background electrolyte
Cl 0.1
END

USE solution 1
EQUILIBRIUM_PHASES
Fix_H+ -&lt;x_axis&gt; NaOH 10
-force_equality true
END
 Examples 464

77 CD-MUSIC: As(V) surface speciation

on goethite

CD-MUSIC: As(III) remaining in solution

(after Stachowicz et al., 2006, Fig. 4)

-3 3 g/L, 0.55 mM AsT

5 g/L, 0.55 mM AsT
0.1M NaNO3 10 g/L, 0.55 mM AsT
As(III) in solution, log (mol/L)

3 g/L, 0.67 mM AsT

10 g/L, 0.67 mM AsT
-4

3 g/L, 0.67 mM AsT

•

3 g/L, 0.55 mM AsT

-5 •

5 g/L, 0.55 mM AsT

•

-6
10 g/L, 0.67 mM AsT
•

•
10 g/L, 0.55 mM AsT
-7
3 6 9 12
pH

C:\PhreePlot\demo\As-cd-music\As3-shvrfig4.ps

This figure shows the surface speciation of As(V) adsorbed on goethite as a function of pH.
The calculated curves were based on the CD-MUSIC model and the parameters of Stachow-
icz et al. (2006). This figure replicates the calculated curves of their Fig. 7 for one of the three
surface loadings (1.70 μm/m2, 3 g/L) studied. The input file generates plots for the other two
surface loadings as separate files and the extraText file picks off the appropriate text based on
the plot number.
In the other plots, the contribution of several of the species is everywhere less than 10%.
These curves could be omitted by setting the minimumYValueForPlotting setting to 10.
 Examples 465

SPECIATION
# plot all As species f(pH) including adsorbed species
calculationType species
calculationMethod 1
# [As5] is different from As(5): see ecosat.inc database
mainSpecies “[As5]”
xmin 3.0
xmax 12.0
# controls the number of points at which speciation is calculated
resolution 100
# defines &lt;loop1&gt; and &lt;loop2&gt; which are used below
loopFile “loopfig7.dat”
# these tags are used in cdmusic.inc
numericTags &lt;G_uAs5K1CD&gt; = 26.62 \
&lt;G_uAs5m_z0&gt; = 0.30 \
&lt;G_uAs5m_z1&gt; = -1.30 \
&lt;G_uAs5K2CD&gt; = 29.29 \
&lt;G_uAs5b_z0&gt; = 0.47 \
&lt;G_uAs5b_z1&gt; = -1.47 \
&lt;G_uAs5K3CD&gt; = 32.69 \
&lt;G_uAs3K1CD&gt; = 4.91 \
&lt;G_uAs3K2CD&gt; = 7.26 \
&lt;G_uPK1CD&gt; = 20.8 \
&lt;G_uPK2CD&gt; = 29.2 \
&lt;G_uPK3CD&gt; = 35.4 \

&lt;AsT&gt; = &lt;loop1&gt; \
&lt;mass&gt; = &lt;loop2&gt;
PLOT
plotTitle “CD-MUSIC: As(V) surface \
speciation&lt;br&gt;(after Stachowicz et al., 2006, \
Fig. 7)”
xtitle pH
# 2nd column in selected output created by adsspeciesvsph.inc
customxcolumn 2
pxmin 3 # plot xmin
labelSize 1.5
# can be used to omit plotting of species that are always below this value
minimumyvalueforplotting 0
extratext “extratextfig7.dat”
# turn off legend to the right of the plot
legendTextSize 0

CHEMISTRY

# this controls exactly what is plotted (see the system directory for the file)
include ‘adsspeciesvsph.inc’
# must ‘punch’ x-axis, y-axis pairs

SELECTED_OUTPUT
-reset false

SOLUTION 1
Temp 25
pH 2.9
units mol/kgw
[As5] &lt;AsT&gt; mmol/kgw # total As concn
Na 1e-1 # background electrolyte
# this is different from N(5) - unlinks redox equilibrium for N species
[N5] 1e-1

include ‘ecosat.inc’
include ‘cdmusic.inc’

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

SURFACE 1
Goe_uniOHH0.5 3.45 98 &lt;mass&gt; # sites/nm2 m2/g g
-cap 0.85 0.75 # C1 C2 (in F/m2)
 Examples 466

Goe_triOH0.5 2.7
-cd_music
-sites_units density

EQUILIBRIUM_PHASES 1
Fix_H+ -&lt;x_axis&gt; NaOH
-force_equality true
END
Examples 467
 Examples 468

78 Test plot output formats

Fe-H
Fe-H22O O species
species vs
vs pH
pH
(using
(using logspeciesvsph.inc)
logspeciesvsph.inc)

0 3+
•
Fe(OH)4- Fe
2+
Fe2+
• Fe 3+
Fe3+
Fe
• Fe (OH)224+
Fe22(OH) 4+
-4 Fe (OH)24+
• 2
Fe(OH)3 5+
• FeOH2+ Fe
Fe33(OH)
(OH)445+
(mol/kgw)

• •
Fe(OH)3 Fe(OH)2+ FeCl 2+
FeCl2+
-10 •
FeCl2++
FeCl
Fe3+ FeCl32
log concentration

Fe2+ •
• FeCl32+
FeOH
FeCl3 •
• • FeCl2+ FeOH2+ +
Fe(OH)
-6 FeCl2-+
Fe(OH) FeCl2+ 2
log concentration

2+ •
4
•FeOH Fe(OH)32+
Fe(OH)
-
-20 Fe(OH)
Fe(OH)43
• • Fe(OH)4-
FeCl3 Fe2(OH)24+•
•
Fe3(OH)45+
FeCl2+
-8
-30

•
• 5+ Fe(OH)2+
Fe3(OH)4
Fe2+ •
-10
-40
22 44 66 88 10
10 12
12
pH
pH

C:\PhreePlot\demo\testplotformats\testplotformats_Fe.ps
C:\Program Files\PhreePlot\0.01\demo\testPlotFormats\testPlotFormats.ps

This example is primarily to demonstrate how plot files can be created in different formats: ps,
eps, epsi, jpg, pdf and ai. The conversions from the native ps format are all carried out by
Ghostscript and so can only be produced if Ghostscript is properly installed and the pdf-
Maker setting is pointing to a valid directory and file.
The example shows a species distribution plot for aqueous Fe species in the Fe-Cl-H2O system
as a function of pH.
The minimumYValueForPlotting has been set to -10 to eliminate minor species from the plot.
 Examples 469

SPECIATION
jobTitle “log speciation vs pH using ‘species’ plot type”
# plots concn/% of all species containing the main species
calculationType species
calculationMethod 1
mainSpecies Fe
xmin -12.0
xmax -2.0
resolution 100
minimumYValueForPlotting -10
pdf T
png T
ai T
epsi T
jpg T
PLOT
plotTitle “Fe-H&lt;sub&gt;2&lt;/sub&gt;O species vs pH&lt;br&gt;(using \
logspeciesvsph.inc)”

CHEMISTRY

# this controls exactly what is plotted (see the system directory for the file)
include ‘logspeciesvsph.inc’
# must ‘punch’ x-axis, y-axis pairs
PHASES
Fix_H+
H+ = H+
log_k 0.0
SOLUTION 1
temp 10
# pH for initial solution calculations only. Changed by &lt;x_axis&gt;
pH 7
units mol/kgw
Na 0.1 charge # background electrolyte
Cl 0.1
Fe(3) 1e-3 # total concn of element
END

USE solution 1
EQUILIBRIUM_PHASES
O2(g) -0.677 0.1
Fix_H+ &lt;x_axis&gt; NaOH 10 # controls logH from xmin to xmax
-force_equality true
END
 Examples 470

Fitting models to data

PhreePlot provides quite a versatile method for fitting chemical models to data (observa-
tions). This is sometimes called ‘optimization’ or ‘parameter identification’.
Other methods of optimizing PHREEQC models have been used, e.g. PEST, but the integra-
tion within PhreePlot is tight and the additional learning step is a relatively small one once
the basics of producing custom plots have been mastered.
Nevertheless successful optimization, whatever the software used, is always a bit of an art that
takes some time and experimentation to become proficient. The examples included here can
be used as a starting point to experiment with. The golden rule is to start out simple.
Examples 471
 Examples 472

79 Langmuir isotherm (1)

5
Zn sorbed (mmol Zn/mol Fe)

1 pH 5.5

0
0.0 0.1 0.2 0.3 0.4 0.5 0.6
Zn concn (mmol/L)

C:\PhreePlot\demo\fit\iso.ps

This example demonstrates the fitting of adsorption data to a Langmuir isotherm. Only one
point is calculated per speciation calculation. This approach therefore requires ndata x nitera-
tions PHREEQC runs. The onePass setting is set to FALSE in order to tell PhreePlot that it
will require more than pass through the PHREEQC code in order to calculate dependent var-
iable values for the complete set of data. The next example shows how to calculate all data
points in one PHREEQC run thus reducing the number of PHREEQC runs to niterations.
This latter approach speeds up the calculations at the expense of a more complex input file.
The input file must describe how to read in values for the dependent variable and all inde-
pendent variables from the fit data file. The columns can be specified by column number or
column name (from the header).
Fine tuning of the fitting parameters often helps convergence. The choice of fitFiniteDiffStep-
Size is often critical to get the fitting started. It is also important to decide how the residuals
are going to be weighted (the error model), here unit weighting has been used.
The plot can use any column from the ‘pts’ file. This includes special columns labelled
‘observed’, ‘calculated’, ‘residuals’ and ‘weightedResiduals’ as well as all the columns
from the fit data file and from the selected output.
 Examples 473

# simple example of fitting to a Langmuir isotherm using unit weighting

# basic fit with isotherm plot

SPECIATION
jobTitle “Test fitting: absolute errors (unit \
weighting)”
calculationType fit
calculationMethod 1
FIT
# contains a list of observations and independent variables
dataFile iso.dat
# does a separate PHREEQC simulation for each observation -
onepass FALSE
# slow but easy to set up
# name of column in fit data file containing the observations (dep variable)
dependentVariableColumnObs Znsorbed
# name of column in selected output file containing the calcd values of the dep
# variable
dependentVariableColumnCalc sorbZn
fitWeightingMethod 0 # 0 = unit weights
# initial step size for each adjustable parameter
fitFiniteDiffStepSize 1.0E-3
# column header in fit data file for which PHREEQC simulation(s) to use for each
# observation
mainLoopColumn sim
numberOfFitParameters 2
fitParameterNames log_k M1
# 0 = parameters on a linear scale, 1 = log10 parameters before fitting
fitLogParameters 0 0
fitAdjustableParameters 1 1 # 1 = adjustable
fitParameterValues 3.0 1.0 # initial values (starting point)

PLOT
plotTitle “Zn sorption on Hfo”
xtitle “Zn concn (mmol/L)”
ytitle “Zn sorbed (mmol Zn/mol Fe)”
# plot isotherm (x = Znconcn, y = sorbed)
# y = line from calculated values from out file with column heading = ‘calculated’
lines calculated
# y = points from observed values from out file with column heading = ‘observed’
points observed

lineWidth 0.4
lineColor red
labelSize 0.0 # no labels on plot
legendTextSize 0.0 # no legend (key)
pointSize 4.0
customXcolumn Znconcn # x = Znconcn column in out file
extraText “extratextiso.dat” # extra text on plot

CHEMISTRY

PHASES
Fix_H+
H+ = H+
log_k 0.0

SURFACE_MASTER_SPECIES
Surf Surf
SURFACE_SPECIES
Surf = Surf
log_k 0.0
Surf + Zn+2 = SurfZn+2 # Langmuir model
# this is where log_k (updated parameter value) is substituted
log_K &lt;log_k&gt;

SELECTED_OUTPUT
-high_precision true
-reset false
 Examples 474

PRINT
-reset false

USER_PUNCH
# fit Langmuir isotherm
# these are the column headings used for tag names: NB this is the output pH not
# the input pH
-headings sorbZn pH mmolZn step_no
10 sorbedZn=SURF(“Zn”,”Surf”)
# NB variable name (used internally) is distinct from column header
20 if sorbedZn&gt;0 THEN punch sorbedZn, -la(“H+”), tot(“Zn”)*1e3, step_no

SOLUTION 1
-pH &lt;pHobs&gt;
-units mmol/L
Na 1000 # 1 M NaNO3 background electrolyte
N(5) 1000
Zn &lt;Znconcn&gt; # &lt;Znconcn&gt; from iso.dat

SURFACE
# this is where the max number of sites (updated parameter) is substituted
Surf &lt;M1&gt;
-equil 1
-no_edl

EQUILIBRIUM_PHASES
Fix_H+ -&lt;pHobs&gt; NaOH # pHobs from the fit data file
-force_equality true
END
Examples 475
 Examples 476

80 Langmuir isotherm (n)

5
Zn sorbed (mmol Zn/mol Fe)

1 pH 5.5

0
0.0 0.1 0.2 0.3 0.4 0.5 0.6
Zn concn (mmol/L)

C:\PhreePlot\demo\fit\ison.ps

This is exactly the same as the previous example except that all 10 points are calculated in a
single pass of PHREEQC. This requires the onePass setting to be set TRUE. It also requires
some rearrangement of the way that the input data are presented. There are two critical differ-
ences compared with the ‘one point per pass’ approach:
(i) in the ‘one point per pass’ approach, the CHEMISTRY part of the input file has just
one PHREEQC simulation (one END at the end of the file) whereas in the ‘calculate all
points in one pass’ approach there is one simulation for each data point, i.e. multiple
END’s;

(ii) in the first approach, selectedOutputLines points to just the last line, e.g.
selectedOutputLines 1

whereas with the ‘calculate all points at once’ it points to many lines with the ‘auto’
selectedOutputLines auto

where ‘auto’ selects all the lines found in the selected output which should therefore
contain one line per point. Each line of output represents one simulation.
Note that the PHREEQC setup in the input file contains many simulations which are
near-repeats. This could become tedious to setup for large datasets and would probably
require some form of automatic generation. PhreePlot includes a simple input file pre-
 Examples 477

processor which can generate the necessary input file (see demo\fitpreproc-
esser\ppiso.ppi) from a simplified skeleton file.
 Examples 478

SPECIATION
jobTitle “Test fitting”
calculationType fit
calculationMethod 1

FIT
dataFile ison.dat # fit data file
# says that all dependent variable values output in one PHREEQC pass (see below)
onePass TRUE
# NB no half way house - either one calculation per pass or the whole lot
mainloop 2
# selectedOutputLines 0 1 1 1 1 1 1 1 1 1 1 # not \
necessary since pre-loop doesn’t write selected output
# observations from the fit data file
dependentVariableColumnObs Znsorbed
dependentVariableColumnCalc sorbZn # from selected output
fitFiniteDiffStepSize 1.0E-3 # initial step size
weightColumn wt # from the fit data file
# blockRangeColumn sim # from the \
fit data file - defaults ok
# mainLoopColumn main # from the \
fit data file - defaults ok
numberOfFitParameters 2
fitParameterNames log_k M1
fitLogParameters 0 0 # 0 = linear parameters
fitAdjustableParameters 1 1 # 1 = adjustable, 0 = fixed
fitParameterValues 3.0 1.0 # starting values

PLOT
plotTitle “Zn sorption on Hfo&lt;br&gt;(onePass = \
TRUE)”
xtitle “Zn concn (mmol/L)”
ytitle “Zn sorbed (mmol Zn/mol Fe)”
lines calculated # from the out file
points observed # from the out file
lineWidth 0.4
lineColor red
labelSize 0.0
legendTextSize 0.0
pointSize 4.0
customXcolumn Znconcn # from the out file
extraText extratextiso.dat

CHEMISTRY

#1
PHASES
Fix_H+
H+ = H+
log_k 0.0

SURFACE_MASTER_SPECIES
Surf Surf
SURFACE_SPECIES
Surf = Surf
log_k 0
END

#2
SURFACE_SPECIES
Surf + Zn+2 = SurfZn+2
# &lt;log_k&gt; is binding constant - substituted from the parameters defined above
log_K &lt;log_k&gt;

PRINT
-selected_output true
# -reset false
SELECTED_OUTPUT
-high_precision true
 Examples 479

-reset false
# -state true
# -m Zn+2 SurfZn+2

SOLUTION_SPREAD
-pH &lt;pHobs&gt;
# this is an easy way to put in data - paste in here from a spreadsheet etc
-units mmol/L
NumberNaN(5)ZnpH # strictly PHREEQC names, separated by tabs
1100010000.035.5 # this is the pH used
2100010000.0695.5 # data separated by tabs
3100010000.1185.5
4100010000.1665.5
5100010000.2175.5
6100010000.275.5
7100010000.3255.5
8100010000.3885.5
9100010000.4535.5
10100010000.5125.5

USER_PUNCH
# fit Langmuir isotherm
-headings sorbZn pH molZn step # this is the output pH
10 sorbedZn=SURF(“Zn”,”Surf”) # dependent variable calculated here
20 if sorbedZn&gt;0 THEN punch sorbedZn, -la(“H+”), tot(“Zn”)*1e3, step_no

END

#3
SURFACE
# &lt;M1&gt; is the number of sites - substituted from the parameters defined above
Surf &lt;M1&gt;
-no_edl
-equil 1 # this uses solution Number 1 above
END

#4
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 2 # this uses solution Number 2 above etc
END

#5
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 3
END

#6
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 4
END

#7
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 5
END

#8
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 6
END
 Examples 480

#9
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 7
END

#10
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 8
END

#11
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 9
END

#12
EQUILIBRIUM_PHASES
Fix_H+ -&lt;pHobs&gt; NaOH
SURFACE
Surf &lt;M1&gt;
-no_edl
-equil 10
END
Examples 481
 Examples 482

81 Langmuir isotherm (pre-processor)

Zn sorption on Hfo
(all in one pass of the input preprocessor)

5
Zn sorbed (mmol Zn/mol Fe)

0
0.0 0.1 0.2 0.3 0.4 0.5 0.6
Zn concn (mmol/L)

C:\PhreePlot\demo\fitpreprocessor\isopp.ps

This is similar to the \demo\iso\ison.ppi except that the near-repetitive blocks are generated
automatically by invoking the PhreePlot pre-processor (Section 13) to expand the various
blocks containing <repeatStartn> and <repeatEndn> tags where n is a positive integer.

# This demonstrates an efficient (fast) method of fitting data to a PHREEQC model.

# It uses the PhreePlot pre-processor which replicates blocks of PHREEQC code \
with minor changes.
# This enables the ‘one pass’ option to be used and avoids the copying normally \
necessary (cf ison.ppi).
# The expanded input file is writen to the log file.

SPECIATION
jobTitle “Test fitting”
calculationType “fit”
calculationMethod 1
 Examples 483

FIT
# fit data file - has observations
dataFile “isopp.dat”
# this produces a block of selected output with 10 lines of data (not 1)
onePass TRUE
mainLoop 1
dependentVariableColumnObs sorbed # column in isopp.dat
dependentVariableColumnCalc Znsorbed # column in selected output
# initial step size for parameter adjustment
fitFiniteDiffStepSize 1.0E-03
# column in fit data file with the weights
weightColumn wt
numberOfFitParameters 2
fitParameterNames “log_k” “M1”
fitLogParameters 0 0
fitAdjustableParameters 1 1 # 1= adjustable, 0 = fixed
fitParameterValues 3. 1. # initial values

PLOT
plotTitle “Zn sorption on Hfo&lt;br&gt;(all in one \
pass of the input preprocessor)”
xtitle “Zn concn (mmol/L)”
ytitle “Zn sorbed (mmol Zn/mol Fe)”
# plot this column from the out file as lines
lines calculated
points observed
lineWidth 0.4
lineColor “red”
labelSize 0.0
legendTextSize 0.0
pointSize 4.0
customXcolumn Znconcn

# debug 3 # to see input and selected output on screen

CHEMISTRY

PRINT
-reset false
SURFACE_MASTER_SPECIES
Surf Surf
SURFACE_SPECIES
Surf = Surf
log_k 0

Surf + Zn+2 = SurfZn+2

log_k &lt;log_k&gt; # from fitParameterNames

SELECTED_OUTPUT
-high_precision true
-reset false

USER_PUNCH
-headings Znsorbed pH molZn step
10 sorbedZn=SURF(“Zn”,”Surf”)
20 if (step_no = 0) THEN punch sorbedZn, -la(“H+”), tot(“Zn”)*1e3, step_no

SOLUTION_SPREAD
DescriptionZnpHNaN(5)
mmol/kgwmmol/kgwmmol/kgw
13.00E-025.510001000
26.90E-025.510001000
31.18E-015.510001000
41.66E-015.510001000
52.17E-015.510001000
62.70E-015.510001000
73.25E-015.510001000
83.88E-015.510001000
94.53E-015.510001000
105.12E-015.510001000
END
484 PhreePlot Guide

&lt;repeatStart1&gt; 1 10
SURFACE
Surf &lt;M1&gt; # from fitParameterNames
-no_edl
-equil &lt;repeatValue1&gt;
END
&lt;repeatEnd1&gt;
Examples 485
486 PhreePlot Guide

82 Ni sorption by goethite

Ni sorption by goethite (edl)

0.0005

observed
calculated
0.0004
soln Ni (mol/L)

0.0003

0.0002

0.0001

0.0000
4 5 6 7 8 9
pH

C:\PhreePlot\demo\fitNi\Niedl.ps

This example fits sorption data for Ni sorption by goethite from data by Sherman and Peacock
(unpublished). Ni sorption was measured as a function of pH at a constant solid solution ratio
of goethite and constant background electrolyte concentration (0.1M NaNO3). The depend-
ent variable was the final solution Ni concentration after sorption. The independent variable
was the final pH.
The data were fitted to the Dzombak and Morel (1990) diffuse double layer model as imple-
mented in PHREEQC (surface activities are defined in terms of mole fractions). The Ni was
assumed to bind to two types of bidentate surface sites as inferred from EXAFS data. The edl
SURFACE option was used. Two log K values were fitted.

The finiteDiffStepSize was set to 1e-2 which is a large enough shift in the log K’s to give a
small but significant change in the objective function while still giving reliable derivatives.
The fit is good but there is really not enough data to provide a convincing test of the model.
The line colour (blue) and points colour (red) are both determined by the line colour diction-
ary since useLineColorDictionary has been set to 1. This means ‘use the dictionary if present
and if the species are defined’, which they are.
 Examples 487

# fit some Ni sorption to goethite data

SPECIATION
calculationType fit
calculationMethod 1

FIT
# fit data file - fit the final Ni concn not the amount sorbed
dataFile “Nisolnfresh.dat”
# final Ni concn is in column 2 of fit data file
dependentVariableColumnObs 2
# NB this is often a good way of fitting sorption data where possible
# calcd final Ni concn in column 2 of selected output
dependentVariableColumnCalc 2
# size of initial adjustment of parameters when fitting
fitFiniteDiffStepSize 1.0E-02
fitConvergenceCriterion 1.0E-12
fitMaxStepSize 1.0
fitWeightingMethod 0 # 0 = unit weighting for all points
numberOfFitParameters 2
fitParameterNames “log_k1” “log_k2”
fitLogParameters 0 0 # 0 = linear parameters
fitAdjustableParameters 1 1 # 1 = adjustable
# initial values of log_k1 and log_k2
fitParameterValues 8. 0
PLOT
plotTitle “Ni sorption by goethite (edl)”
xoffset 60
xtitle pH
ytitle “soln Ni (mol/L)”
pxmin 4.0 # p or plot limits
pxmax 9.0
pymin 0
pymax 5.E-04
pydec 4 # number of decimal places
lineColor blue
lineWidth 0.4
# calculated column from out file
lines calculated
points observed # observed column from out file
legendTextSize 1.9 # key size
pointSize 3.0
labelSize 0 # suppress labelling
customXcolumn 6 # column 6 of out file
extraText “extratextfitNi.dat”

CHEMISTRY

TITLE Goethite surface 1pK model, Ni sorption 1 site.

PHASES
Fix_H+
H+ = H+
log_k 0.

SURFACE_MASTER_SPECIES
Fes_ Fes_OH-0.5
SURFACE_SPECIES
Fes_OH-0.5 = Fes_OH-0.5 # surface charging
log_k 0.0

Fes_OH-0.5 + H+ = Fes_OH2+0.5
log_k 8.50

2Fes_OH-0.5 + Ni+2 = (Fes_OH)2Ni+ # bidentate model

log_k &lt;log_k1&gt;

2Fes_OH-0.5 + Ni+2 + H2O = (Fes_OH)2NiOH + H+

log_k &lt;log_k2&gt;

SELECTED_OUTPUT
488 PhreePlot Guide

high_precision true
reset false
USER_PUNCH
headings pH Ni
-start
10 punch -la(“H+”), TOT(“Ni”) # pH and total dissolved Ni (calcd)
-end # fitting compares TOT(“Ni”) with obsd total, eg by ICP-AES

SURFACE 1
# -diffuse_layer
# -no_edl
Fes_OH-0.5 1.09e-3 32.7 3.33 # goethite parameters

SOLUTION 1
units mol/kgw
Ni 0.4258e-3 # NiT
Na 0.1 # background electrolyte
N(5) 0.1 charge

EQUILIBRIUM_PHASES
O2(g) -0.67 0.1
Fix_H+ -&lt;pHobs&gt; NaOH
-force_equality true
Ni(OH)2 0 0
END
Examples 489
490 PhreePlot Guide

83 As(V) sorption on hydrous ferric oxide

100 EAs1
•
EAs3 EAs2

EAs2 EAs3
•
80 EAs4
EAs5

EAs1 EAs6
•
60 EAs1
% bound

•
EAs4 EAs2
EAs3
•
EAs5 EAs4
40 EAs5
EAs6
•
EAs6
20

0
2 4 6 8 10 12
pH

C:\PhreePlot\demo\fithfoAs\fithfoAsv.ps

This example uses the As data used by Dzombak and Morel (1990) to fit the three surface log
K’s for As(V) sorption by HFO. A global fit has been used. The weighting factors have all
been set to one.
Line breaks in the input data file are used to defined line breaks in the plots – essentially six
different data sets. The line and point colours are read from the line colour dictionary.
Some of the fits are not very good - EAs4 (orange points, orange line), for example, shows
quite a large deviation between observations and fitted values.
Note that the in-plot labels are only plotted for the lines not the points. The lines and points
for each dataset could be given the same colour by editing the line colour dictionary and
replotting. convertLabels has been set to false to prevent the labels being interpreted as species
names and therefore subscripting the final number.
changeColor has been set to TRUE to ensure that the various curves, which are all subsets of
data from the same column, are given separate colours. This applies equally to both the points
and lines sets of data – hence they follow the same colour sequence.
 Examples 491

# Example of fitting some As sorption on Hfo data from Dzombak and Morel (1991)

SPECIATION
calculationType fit
calculationMethod 1
labels “EAs1” “EAs2” “EAs3” “EAs4” “EAs5” “EAs6” \
“EAs1” “EAs2” “EAs3” \
# used in turn for labelling points then curves in plot
“EAs4” “EAs5” “EAs6”
FIT
# file containing observations and independent variables
dataFile “1eAsv.dat”
dependentVariableColumnObs 6 # dep variable is in column 6
# this where the calcd values are foudn in selected output - see below
dependentVariableColumnCalc 4
# size of initial shift in parameter values looking for response
fitFiniteDiffStepSize 1.0E-02
# controls when convergence has been achieved
fitConvergenceCriterion 1.0E-03
fitMaxStepSize 1.0
fitWeightingMethod 2 # 2 = take weights from fit data file
weightColumn 7 # weights in column 7 in fit data file
# column 8 defines which PHREEQC simulation (see below) to use for each point
blockRangeColumn 8
numberOfFitParameters 3
fitParameterNames “log_K1” “log_K2” “log_K4”
# 0 = linear parameter values (ie don’t use log param)
fitLogParameters 0 0 0
fitAdjustableParameters 1 1 1 # 1 = adjustable (0 = fixed)
fitParameterValues 29.31 23.51 10.58 # initial values

PLOT
plotTitle “Refitting As(V) sorption data for \
Hfo&lt;br&gt;(1eAsv.dat)”
xtitle pH
ytitle “% bound”
# the ‘calculated’ column in the ‘out’ file is plotted as a line
lines calculated
# the ‘observed’ column in the ‘out’ file is plotted as points
points observed
# prevents the labels being interpreted as species
convertLabels F
# give subsets a sequence of difft colours
changeColor T
# 0 = do NOT use the line colour dictionary for colours
useLineColorDictionary 0
pointSize 3.0 # symbols will be 3 mm (nominal)
# x-axis variable is in column 8 of the ‘out’ file
customXcolumn 8
plotFactor 1.0 # can use this to scale whole plot
# additional text for plot
extraText “extratextfithfoAsv.dat”

CHEMISTRY

PHASES
Fix_H+
H+ = H+
log_k 0.
Fe(OH)3(a) 112
Fe(OH)3 + 3H+ = Fe+3 + 3H2O
log_k 4.891
-add_constant -10 # prevents Fe(OH)3(a) from dissolving

SURFACE_SPECIES
# Arsenate
Hfo_wOH + AsO4-3 + 3H+ = Hfo_wH2AsO4 + H2O
log_k &lt;log_K1&gt; # the first parameter is substituted here
492 PhreePlot Guide

Hfo_wOH + AsO4-3 + 2H+ = Hfo_wHAsO4- + H2O

log_k &lt;log_K2&gt;

Hfo_wOH + AsO4-3 = Hfo_wOHAsO4-3

log_k &lt;log_K4&gt;

SELECTED_OUTPUT
high_precision true
reset false

USER_PUNCH
# fourth column (%sorbed) is compared with observations
-headings pH Hfo AsT %sorbed
10 Hfo=equi(“Fe(OH)3(a)”)
20 totAs=SYS(“As”)
30 pcsorb=100*SURF(“As”,”Hfo”)/totAs
40 PUNCH -la(“H+”), Hfo, totAs, pcsorb
SURFACE 1
Hfo_sOH Fe(OH)3(a) equilibrium_phase 0.005 53300 # D&M Hfo parameters
Hfo_wOH Fe(OH)3(a) equilibrium_phase 0.2
SOLUTION
units mol/kgw
# &lt;I&gt;, &lt;FeT&gt; and &lt;AsT&gt; are from the fit data file
Na &lt;I&gt;
N(5) &lt;I&gt; charge
Fe &lt;FeT&gt;
As &lt;AsT&gt;
EQUILIBRIUM_PHASES
O2(g) -0.67 0.1
Fix_H+ -&lt;pH&gt; NaOH # &lt;pH&gt; from the fit data file
-force_equality true
Fe(OH)3(a) 0 0
END
 Examples 493

Contour plots

Contour plots provide a way of viewing the variation of some factor in two dimensions. The
contour plots generated by Phreeplot are simple, classical 2D views of the surface. The view-
ing angle of the generated surface is always looking down directly from above.
The user has control over many of the plotting parameters such as the choice of the contour
levels, and the size and colour of many of the plot attributes.
The challenge is to generate a set of data and choose a set of contour levels that produces a
good-looking plot while avoiding trying to trace numerical noise. This is largely controlled by
the choice of resolution used to generate the regular grid of values, and the choice of the con-
tour values. Plots based on geochemical data can produce areas with both extremely large and
extremely low gradients, both of which can be challenging to contour.
494 PhreePlot Guide

84 Contour two metals at three resolutions

Besides demonstrating the generation of contour plots, this example shows the use of tags in
the PhreePlot section of the main input file. These are used to produce contour plots for two
metals, Zn and Pb, at three resolutions, 10, 25 and 100. The data contoured are the percent-
age of metal adsorbed by HFO in the presence of a fixed amount of metal, Fe and background
electrolyte. The two variables, pH and O2(g) fugacity, change over a wide range leading to the
variable disolution/precipitation of HFO on which the Zn and Pb are adsorbed. This combi-
nation produces a total of six plots.
The calculationType keyword is set to ‘contour’. The <mt> tag defined in numericTags
defines the total concentration of metal in the system and the system-defined <mainspecies>
tag defines the metals of interest. This tag is generated from the mainspecies keyword list.
The PHREEQC calculations are relatively straightforward. A solution of either Zn or Pb plus
0.01 mol/kgw Fe and 0.1 mol/kgw NaCl background electrolyte is brought to a particular pH
and log f O2(g) using NaOH and O2(g), respectively, as defined by the the
EQUILIBRIUM_PHASES keyword data block. This uses the <x_axis> and <y_axis> tags. The
values of these are generated on a regular grid by the ‘contour’ routine using xmin, xmax,
ymin, ymax and resolution. The ‘hfo.inc’ include file is retrieved from the system directory
and adds the Hfo surface and the DLM adsorption model.
The USER_PUNCH block calculates the % adsorbed using TOT() for the total dissolved metal
concentration and SYS() for the total number of moles of the metal in the system. The total
dissolved concentration has to be multiplied by the total amount of water (in kg) in the system
to convert it to the number of moles of dissolved metal. The pH and percent adsorbed (%s) are
output to the selected output once per iteration.
The selected output results accumulate in the ‘out’ file based on the USER_PUNCH selected out-
put. It is this file that provides the z-data to contour. Note that the x- and y-data are not out-
put – they are defined implicitly by their position in the ‘out’ file, the calculation domain and
the grid resolution. The contourZvariable is defined as ‘%s’. The heading of the outfile is
searched for this string to determine the column position of the z-variable used in contouring.
The contour levels chosen are set to 1, 10, 20, 50, 80, 90 and 99% using the contours keyword.
A loopfile, loopmetalx.dat, defines a loop variable, res, which in turn defines a correspond-
ing <res> tag which successively takes on the values 10, 25 and 50. Note that a loop value
derived from a loopfile overrides any setting of the loop variable using loopMin etc.
Four PhreePlot loops are involved in the calculations, each based on a generated tag value.
These are (from the least rapidly changing outermost loop to the most rapidly changing inner-
most loop): <mainspecies>, <res>, <y_axis> and <x-axis>. The <res> tag is used in the
PhreePlot section of the input file and is updated once per loop iteration.
The plotTitle uses the <mainspecies> and <res> tags and these are substituted in the title just
before plotting. Similarly, the extraText file contains the <mt> and <mainspecies> tags and
these are substituted just before use.
Each mainspecies-res combination generates its own outfile so there are six such outfiles. The
multipageFile t setting means that each of the six plots is written to a single multi-page ps file,
one plot per page. The six plots are shown in Figure Ex84.1. Pb is adsorbed more strongly
than Zn resulting in a larger area with >99% adsorption. There is no adsorption at low pH or
low f O2(g) due to the instability of HFO under those conditions. As the resolution increases,
the clarity of the boundaries increase. The default placement of the labels is acceptable so there
is no need to move them.
 Examples 495

#$%
&'$'( #,'$%
&'$'(
&%
)*
+
 &%
)*
+



 


















 
!"! "

!"! "
 

 


 
 


 
 

 



  

 ,'



  

 

 
   

    


 

#$%
&'$'( #,'$%
&'$'(
&%
)*
+ &%
)*
+


 




















 
!"! "

!"! "

 

 


 

 


 
 

 



  

 ,'


  

 

blanhan    



   


 

#$%
&'$'( #,'$%
&'$'(
&%
)*
+
 &%
)*
+



 



















 
!"! "

!"! "

 

 


 

 


 
 

 



  

 ,'


  

 

 
   

    


 

c:\PhreePlot\demo\contour\contour_hfo_metalx.ppi

Figure Ex84.1. The percentage of Zn and Pb adsorbed by HFO as a function of pH and O2(g) fugacity using a set
of user-supplied contour levels. Calculated with resolutions of 10, 25 and 100.
496 PhreePlot Guide

# produces a contour plot for the Fe-H2O system with FeT = 0.01 mol/kgw
# and Fe(OH)3(a) as a possible mineral phase

SPECIATION

loopfile loopmetalx.dat
calculationType “contour”
calculationMethod 1
contourZvariable %s # see USER_PUNCH
mainspecies Zn Pb
xmin 2.0
xmax 12.0
ymin -90
ymax 0
resolution <res> # updated from loop file once per z-loop

numerictags <Fet> = 0.01 \

<mt>=10^<M>
PLOT
plotTitle “%<mainspecies> adsorbed by HFO<br>resolution = <res>”
xtitle pH
ytitle “log <i>f</i> O₂(g) (atm)”
contours 1 10 20 50 80 90 99
extraText extratextmetalx.dat
multipagefile f

CHEMISTRY

# one simulation

include hfo.inc # add standard Hfo DLM model

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

SELECTED_OUTPUT
-reset FALSE
-high_precision TRUE

USER_PUNCH
-headings pH %s
10 PUNCH -la(“H+”), 100*(1 - TOT(“<mainspecies>”)*TOT(“water”)/(SYS(“<mainspecies>”)))

SOLUTION 1
pH 1.8
units mol/kgw
Fe(3) <Fet>
<mainspecies> <mt>
Na 1e-1
Cl 1e-1

EQUILIBRIUM_PHASES 1
Fix_H+ -<x_axis> NaOH 10
-force_equality true
O2(g) <y_axis>
Fe(OH)3(a) 0 0
END
 The wateq4f.dat database 497

The wateq4f.dat database

log f O2-pH predominance diagrams were calculated using the ht1 method for each of the 32
components (excluding H, O and Humate) in the wateq4f.dat database.
Humate was not included since Fulvate was included and all of the entries for Humate match
those of Fulvate.
The total amount of each of the 32 components was set to 1e-2 mol/kgw.
Each of the possible 311 mineral species present in the database was allowed to precipitate if
its saturation index indicated such. In practice, only 54 minerals actually did so.
The calculation is not meant to be particularly significant in terms of environmental chemis-
try. However, it is a fairly demanding test for the speciation program (PHREEQC) since the
whole sequence of diagrams originally needed more than one week of continuous computing
to calculate (more recent runs are considerably faster due to improvements in processor speed
and in the PhreePlot and PHREEQC code).
These calculations also provide a unique insight into the essential character of the
wateq4f.dat database, something that is remarkably difficult to achieve by simply staring at a
table of numbers.
The following 32 components were considered: Ag, Al, As, B, Ba, Br, C, Ca, Cd, Cl,
Cs, Cu, F, Fe, Fulvate, I, K, Li, Mg, Mn, N, Na, Ni, P, Pb, Rb, S, Se, Si, Sr, U
and Zn.

The following 311 minerals were considered: Acanthite, Adularia, Ag2CO3, Ag2O,
Ag2SO4, Ag3PO4, AgF:4H2O, AgMetal, Al(OH)3(a), AlAsO4:2H2O, Albite, AlumK, Alu-
nite, Analcime, Anglesite, Anhydrite, Anilite, Annite, Anorthite, Antlerite,
Aragonite, Arsenolite, Artinite, As_native, As2O5(cr), As2S3(am), AsI3, Ata-
camite, Autunite, Azurite, Ba3(AsO4)2, BaF2, Barite, Basaluminite, BaSeO3, Bas-
setite, Beidellite, Bianchite, Birnessite, Bixbyite, BlaubleiI, BlaubleiII,
Boehmite, Brochantite, Bromyrite, Brucite, Bunsenite, B-UO2(OH)2, Ca3(AsO4)2:4w,
Calcite, CaSeO3, Cd(BO2)2, Cd(gamma), Cd(OH)2(a), Cd(OH)2, Cd3(OH)2(SO4)2,
Cd3(OH)4SO4, Cd3(PO4)2, Cd4(OH)6SO4, CdBr2:4H2O, CdCl2, CdCl2:2.5H2O, CdCl2:H2O,
CdF2, CdI2, CdMetal, CdOHCl, CdSiO3, CdSO4, CdSO4:2.7H2O, CdSO4:H2O, Celestite,
Cerargyrite, Cerrusite, Chalcanthite, Chalcedony, Chalcocite, Chalcopyrite,
Chlorite14A, Chlorite7A, Chrysotile, Claudetite, Clinoenstatite, Clpyromorphite,
Coffinite, Cotunnite, Covellite, Cristobalite, Cu(OH)2, Cu2(OH)3NO3, Cu2SO4,
Cu3(AsO4)2:6w, Cu3(PO4)2, Cu3(PO4)2:3H2O, CuBr, CuCO3, CuF, CuF2, CuF2:2H2O,
CuI, CuMetal, CuOCuSO4, CupricFerrite, Cuprite, CuprousFerrite, CuSO4, Diaspore,
Diopside, Dioptase, Djurleite, Dolomite(d), Dolomite, Epsomite, FCO3Apatite,
Fe(OH)2.7Cl.3, Fe(OH)3(a), Fe2(SeO3)3, Fe3(OH)8, FeS(ppt), FeSe2, Fluorapatite,
Fluorite, Forsterite, Galena, Gibbsite, Goethite, Goslarite, Greenalite, Green-
ockite, Greigite, Gummite, Gypsum, Halite, Halloysite, Hausmannite, H-Autunite,
Hematite, Hinsdalite, Huntite, Hxypyromorphite , Hydrocerrusite, Hydromagnesite,
Hydroxyapatite, Illite, Iodyrite, Jarosite(ss), JarositeH, Jarosite-K, Jarosite-
Na, Jurbanite, Kaolinite, K-Autunite, Kmica, Langite, Larnakite, Laumontite,
Laurionite, Leonhardite, Litharge, Mackinawite, Magadiite, Maghemite, Magnesite,
Magnetite, Malachite, Manganite, Massicot, Matlockite, Melanothallite, Melanter-
ite, Millerite, Minium, Mirabilite, Mn2(SO4)3, Mn3(AsO4)2:8H2O , Mn3(PO4)2,
MnCl2:4H2O, MnHPO4, MnS(Green), MnSO4, Monteponite, Montmorillonite-Aberdeen,
Montmorillonite-BelleFourche, Montmorillonite-Ca, Morenosite, Na4UO2(CO3)3, Na-
498 PhreePlot Guide

Autunite, Nahcolite, Nantokite, Natron, Nesquehonite, Ni(OH)2, Ni2SiO4,

Ni3(AsO4)2:8H2O, Ni3(PO4)2, Ni4(OH)6SO4, NiCO3, Ningyoite, Nsutite, Orpiment,
Otavite, Pb(BO2)2, Pb(OH)2, Pb2(OH)3Cl, Pb2O(OH)2, Pb2O3, Pb2OCO3, Pb2SiO4,
Pb3(AsO4)2, Pb3(PO4)2, Pb3O2CO3, Pb3O2SO4, Pb4(OH)6SO4, Pb4O3SO4, PbBr2, PbBrF,
PbF2, PbHPO4, PbI2, PbMetal, PbO:0.3H2O, PbSiO3, Phillipsite, Phlogopite, Phos-
genite, Plattnerite, Plumbogummite, Portlandite, Prehnite, Przhevalskite,
Pyrite, Pyrochroite, Pyrolusite, Pyrophyllite, Quartz, Realgar, Retgersite, Rho-
dochrosite(d), Rhodochrosite, Rutherfordine, Saleeite, Schoepite, Scorodite,
Se(s), SeO2, Sepiolite(d), Sepiolite, Siderite(d)(3), Siderite, Silicagel,
SiO2(a), Smithsonite, Sphalerite, Sr-Autunite, SrF2, Strengite, Strontianite,
Sulfur, Talc, Tenorite, Thenardite, Thermonatrite, Torbernite, Tremolite, Trona,
Tsumebite, U(HPO4)2:4H2O, U(OH)2SO4, U3O8(c), U4O9(c), UF4(c), UF4:2.5H2O,
UO2(a), UO2HPO4:4H2O, UO3(gamma), (UO2)3(PO4)2:4w, Uramphite, Uraninite(c),
Uranocircite, Uranophane, Vivianite, Wairakite, Willemite, Witherite, Wurtzite,
Zincite(c), Zincosite, Zn(BO2)2, Zn(NO3)2:6H2O, Zn(OH)2-a, Zn(OH)2-b, Zn(OH)2-c,
Zn(OH)2-e, Zn(OH)2-g, Zn2(OH)2SO4, Zn2(OH)3Cl, Zn3(AsO4)2:2.5w, Zn3(PO4)2:4w,
Zn3O(SO4)2, Zn4(OH)6SO4, Zn5(OH)8Cl2, ZnBr2:2H2O, ZnCl2, ZnCO3:H2O, ZnF2, ZnI2,
ZnMetal, ZnO(a), ZnS(a), ZnSiO3 and ZnSO4:H2O.

The usual ‘water limits’ of 0.21 atm O2(g) and 1 atm H2(g) were used. All calculations were
carried out for a temperature of 25oC.
In practice, given the conditions used, only 54 of the 311 possible minerals precipitated some-
where within the range of conditions imposed. Inclusion of the other 257 minerals therefore
has no impact on the predominance diagrams produced and in principle could be excluded.
This results in approximately a four-fold increase in calculation speed illustrating that the
number of pure phases considered can have a strong impact on the speed of PHREEQC cal-
culations.
In these examples, we found that on average, about half the time was spent hunting along the
domain boundaries and half was spent tracking along the internal boundaries. Of course this
varies considerably from diagram to diagram.
 The wateq4f.dat database 499

1 Ag

All elements

0 O2(g) > 0.21 atm

Ag
-20

Iodyrite
log f O2(g)

-40

-60
AgMetal

-80
2 4 6 8 10
pH
500 PhreePlot Guide

2 Al

All elements

0 O2(g) > 0.21 atm

Al
-20
Alunite
AlF2+
log f O2(g)

-40 AlF2+ Pyrophyllite Diaspore

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 501

3 As

All elements

0 O2(g) > 0.21 atm

As
-20 H2AsO4-
H3AsO4
log f O2(g)

Ba3(AsO4)2
-40

-60 H3AsO3

As_native
-80
2 4 6 8 10
pH
502 PhreePlot Guide

4 B

All elements

0 O2(g) > 0.21 atm

B
-20
log f O2(g)

-40 H3BO3 H2BO3-

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 503

5 Ba

All elements

0 O2(g) > 0.21 atm

Ba
-20
log f O2(g)

Ba3(AsO4)2
-40

-60 Barite

Ba2+

-80
2 4 6 8 10
pH
504 PhreePlot Guide

6 Br

All elements

0 O2(g) > 0.21 atm

Br
-20
log f O2(g)

-40 Br-

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 505

7 C

All elements

0 O2(g) > 0.21 atm

C
-20
UO2(CO3)34-
log f O2(g)

Otavite
CO2 NaCO3-
-40

-60
HCO3-
NiCO3
Rhodochrosite

CH4
-80
2 4 6 8 10
pH
506 PhreePlot Guide

8 Ca

All elements

0 O2(g) > 0.21 atm

Ca
-20
log f O2(g)

FCO3Apatite
-40 Ca2+

-60

Fluorite
-80
2 4 6 8 10
pH
 The wateq4f.dat database 507

9 Cd

All elements

0 O2(g) > 0.21 atm

Cd
-20
Cd2+
log f O2(g)

Otavite

-40
CdFulvate

-60

Greenockite

-80
2 4 6 8 10
pH
508 PhreePlot Guide

10 Cl

All elements

0 O2(g) > 0.21 atm

Cl
-20
log f O2(g)

-40 Cl-

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 509

11 Cs

All elements

0 O2(g) > 0.21 atm

Cs
-20
log f O2(g)

-40 Cs+

-60

-80
2 4 6 8 10
pH
510 PhreePlot Guide

12 Cu

All elements

0 O2(g) > 0.21 atm

Cu
Tenorite

CuFulvate
-20
log f O2(g)

-40
CuprousFerrite

-60
Djurleite

Chalcocite

CuMetal
-80
2 4 6 8 10
pH
 The wateq4f.dat database 511

13 F

All elements

0 O2(g) > 0.21 atm

F
-20
log f O2(g)

AlF2+ F-
-40 AlF2+ AlF3 Fluorite

-60

-80
2 4 6 8 10
pH
512 PhreePlot Guide

14 Fe

All elements

0 O2(g) > 0.21 atm

Fe
Hematite

-20
log f O2(g)

-40
CuprousFerrite

-60

Fe2+
Magnetite
-80
2 4 6 8 10
pH
 The wateq4f.dat database 513

15 Fulvate

All elements

0 O2(g) > 0.21 atm

Fulvate
CuFulvate
-20
log f O2(g)

CdFulvate
-40
Fulvate2-

-60 HFulvate-

-80
2 4 6 8 10
pH
514 PhreePlot Guide

16 I

All elements

0 O2(g) > 0.21 atm

I
-20

Iodyrite
log f O2(g)

-40

-60
I-

-80
2 4 6 8 10
pH
 The wateq4f.dat database 515

17 K

All elements

0 O2(g) > 0.21 atm

K
-20
log f O2(g)

-40 K+

-60

-80
2 4 6 8 10
pH
516 PhreePlot Guide

18 Li

All elements

0 O2(g) > 0.21 atm

Li
-20
log f O2(g)

-40 Li+

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 517

19 Mg

All elements

0 O2(g) > 0.21 atm

Mg
-20
log f O2(g)

Magnesite
-40 Mg2+

-60

Chlorite14A
-80
2 4 6 8 10
pH
518 PhreePlot Guide

20 Mn

All elements

0 O2(g) > 0.21 atm

Pyrolusite
Mn
-20 Bixbyite
log f O2(g)

Mn3(AsO4)2.8H2O
-40 MnHPO4

Mn2+
Rhodochrosite

-60

MnHPO4
-80
2 4 6 8 10
pH
 The wateq4f.dat database 519

21 N

All elements

0 O2(g) > 0.21 atm

NO3-
N
-20
log f O2(g)

N2
-40

-60

NH4+
NH3
-80
2 4 6 8 10
pH
520 PhreePlot Guide

22 Na

All elements

0 O2(g) > 0.21 atm

Na
-20
log f O2(g)

-40 Na+

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 521

23 Ni

All elements

0 O2(g) > 0.21 atm

Ni
-20
log f O2(g)

Ni(CO3)22-
-40 Ni2+ Ni(OH)2

-60

-80
2 4 6 8 10
pH
522 PhreePlot Guide

24 P

All elements

0 O2(g) > 0.21 atm

P
-20
log f O2(g)

FCO3Apatite
-40 Clpyromorphite Clpyromorphite

-60

MnHPO4
-80
2 4 6 8 10
pH
 The wateq4f.dat database 523

25 Pb

All elements

0 O2(g) > 0.21 atm

Pb
-20
log f O2(g)

-40 Clpyromorphite

-60

Pb(OH)2
PbMetal
-80
2 4 6 8 10
pH
524 PhreePlot Guide

26 Rb

All elements

0 O2(g) > 0.21 atm

Rb
-20
log f O2(g)

-40 Rb+

-60

-80
2 4 6 8 10
pH
 The wateq4f.dat database 525

27 S

All elements

0 O2(g) > 0.21 atm

S
-20

Celestite
log f O2(g)

SO42-

-40

-60 Barite

Chalcocite Greenockite

-80
2 4 6 8 10
pH
526 PhreePlot Guide

28 Se

All elements

0 O2(g) > 0.21 atm

SeO42-
Se
-20
H2SeO3
HSeO3-
log f O2(g)

SeO32-

-40

-60 Se(s)

-80
2 4 6 8 10
pH
 The wateq4f.dat database 527

29 Si

All elements

0 O2(g) > 0.21 atm

Si
-20
log f O2(g)

-40 Quartz ZnSiO3

Pyrophyllite

-60

Chlorite14A
-80
2 4 6 8 10
pH
528 PhreePlot Guide

30 Sr

All elements

0 O2(g) > 0.21 atm

Sr
-20

Celestite
log f O2(g)

Strontianite
-40

-60 Sr2+

-80
2 4 6 8 10
pH
 The wateq4f.dat database 529

31 U

All elements

0 O2(g) > 0.21 atm

U
-20 Schoepite
Na-Autunite
UO22+ UO2(CO3)34-
log f O2(g)

-40 U3O8(c)

U4O9(c)

-60
Uraninite(c)

-80
2 4 6 8 10
pH
530 PhreePlot Guide

32 Zn

All elements

0 O2(g) > 0.21 atm

Zn
-20
log f O2(g)

-40 Zn2+ ZnSiO3

-60

Zincite(c)
-80
2 4 6 8 10
pH
 563

References

Agans, D.J. 2002. Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Soft-
ware and Hardware Problems. AMACOM, New York.
Appelo, C.A.J. and Postma, D. 2005. Geochemistry, groundwater and pollution. 2nd edition.
A.A. Balkema, Leiden.
Bethke, C. M. 2005. The Geochemist’s Workbench. Rockware, Inc.
Bourke, P. 1987. CONREC: A Contouring Subroutine. http://paulbourke.net/papers/conrec/.
Charlton, S.R. and Parkhurst, D. L. 2011. Modules based on the geochemical model
PHREEQC for use in scripting and programming languages. Computers & Geosciences 37,
1653-1663. doi:10.1016/j.cageo.2011.02.005.
CoHort Software, 2004. CoPlot. Monterey, California.
Dzombak, D.A. and Morel, F.M.M. 1990. Surface Complexation Modeling: Hydrous Ferric
Oxide. John Wiley, New York.
Kinniburgh, D.G. and Cooper, D.M. 2004. Predominance and mineral stability diagrams revis-
ited. Environmental Science and Technology, 38, 3641–3648.
Kohler, K.E. 2005. PSPLOT: PostScript for Technical Drawings. A free Fortran-callable PostScript
Plotting Library. Nova Southeastern University Oceanographic Center, Dania Beach, FL, USA.
Luo, J., Weber F-A., Cirpka, O.A., Wu, W-M., Nyman, J.L., Carley, J., Jardine, P.M., Criddle,
C.S. and Kitanidis, P.K. 2007. Journal Contaminant Hydrol. 92, 129–148.
Parkhurst, D.L. and Appelo, C.A.J. 1999. User's guide to PHREEQC (version 2)--A computer
program for speciation, batch-reaction, one-dimensional transport, and inverse geochemical
calculations: U.S. Geological Survey Water-Resources Investigations Report 99-4259, 312 p.
Post, V. 2011. PHREEQC for Windows. http://pfw.antipodes.nl/index.html.
Powell, M.J.D. 1965. A method for minimizing a sum of squares of non-linear functions without
calculating derivatives. The Computer Journal 7, 303–307. Also see VA05 in the HSL Archive,
ftp://ftp.numerical.rl.ac.uk/pub/hsl_catalogs/archive/catalog.pdf.
Powell, M.J.D. 2007. Developments of NEWUOA for minimization without derivatives.
DAMTP 2007/NA05. http://www.damtp.cam.ac.uk/user/na/NA_papers/NA2007_05.pdf.
Powell, M.J.D. 2009. The BOBYQA algorithm for bound constrained optimization without
derivatives. DAMTP 2009/NA06. http://www.damtp.cam.ac.uk/user/na/NA_papers/
NA2009_06.pdf.
R Development Core Team 2007. R: A language and environment for statistical computing. R
Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0, URL http://
www.R-project.org.
Stachowicz, M., Hiemstra T., W. H. van Riemsdijk. 2006. Surface speciation of As(III) and As(V)
in relation to charge distribution. J. Colloid Interface Sci. 302, 62–75.
Wheeler, D.A. Review of Debugging by David J. Agans. http://www.dwheeler.com/essays/debug-
ging-agans.html
Acknowledgements

PhreePlot inherits most of the hard work from others. PHREEQC does all of the geochemical calculations and
is the work of David Parkhurst, Tony Appelo and Scott Charlton. Scott Charlton and David Parkhurst prepared
the PHREEQC module that is embedded in PhreePlot. PHREEQC has become ever more powerful over the
years and is a model of stability and reliability. It also comes with its own excellent documentation and data-
bases. The PHREEQC format is now a standard format for thermodynamic databases.
The Postscript plotting library embedded in PhreePlot is from the late Kevin Kohler. This library enables
PhreePlot to produce high quality, fully scalable plots. Ghostscript and GSView provide the perfect compan-
ions for rendering these files. Ghostscript provides a range of format conversions (pdf, png etc.) and can be
configured to run directly from within PhreePlot.
The three fitting routines are all by Mike Powell. The non-linear least squares routine (‘nlls’) has proved an
invaluable and reliable assistant over many years, and the two newer routines are expected to be equally reliable.
The contouring routine is from Paul Bourke. After quite a lot of testing, we found that this rather simple and
elegant algorithm proved the most reliable for contouring geochemical data. It has been slightly modified here
to enable the contour regions to be filled with colour.
Geochemical modelling is nothing without the databases that go with it and so we would like to thank all of
those who have helped to painstakingly prepare these for use in PHREEQC and elsewhere.
A number of smaller contributions have also been included. These are listed below with details of the sources
and Conditions of Use:

Development of PhreePlot was begun while dgk was a full-time member of the British Geological Survey
(Wallingford) and dmc was a member of the Centre of Ecology and Hydrology (Wallingford), both NERC
Research Centres. We are grateful to these two institutions for their support.
 565

Function/software Owner/source/Conditions of Use

PHREEQC David Parkhurst, Scott Charlton (USGS), Tony Appelo, wwwbrr.cr.usgs.gov/projects/

GWC_coupled/phreeqc/index.html. Free source code, libraries and binaries; license file.
Fitting Harwell Subroutine Library (HSL Archive), VA05 routine by M J D Powell, http://
www.cse.scitech.ac.uk/nag/hsl/howto.shtml. Free source code after registering; can freely
distribute binaries derived from this but not the source itself; license file.
Postscript plotting Kevin Kohler (deceased), PSPLOT subroutine plotting library. Originally free source
code after registering but no longer available.
Simulated annealing William L Goffe (1996) subroutine simann.f, www.bepress.com/snde/vol1/iss3/
algorithm1/. Free source code.
Douglas-Peuker line P R Wade (1984), Department of Computer Science, University of Hull. Also see Why-
simplification att, J D and Wade P R (1988) "The Douglas-Peucker Line Simplification Algorithm",
Society of University Cartographers Bulletin 22 (1), 17 - 25. Free source code. http://
www2.dcs.hull.ac.uk/CISRG/publications/DPs/DP4/DP4.html.
Function parser Roland Schmehl, University of Karlsruhe, Germany. Open source code. http://source-
forge.net/projects/fparser/.
Hash function Rich Townsend, groups.google.com/group/comp.lang.fortran/browse_frm/thread/
456a07645b77f678. Free source code.
Contouring Paul Bourke, CONREC, http://paulbourke.net/papers/conrec/. Free source code.

The following are used but not embedded in PhreePlot:

Windows installer Inno Setup, Copyright © 1997-2011 Jordan Russell. All rights reserved.
http://www.jrsoftware.org/isinfo.php. Open source code (Delphi) and binaries; license
file. Free to use but copyrighted.
Ghostscript Peter Deutsch, Ralph Levien and the Ghostscript team, www.cs.wisc.edu/~ghost/. Open-
source code and binary distributed under GPL conditions.
GSview Russell Lang, www.cs.wisc.edu/~ghost/gsview/. Free binary with a small, optional registra-
tion fee to eliminate a nag screen.
566 PhreePlot Guide

Appendix 1. Glossary of terms

Table A1. A glossary of terms used in this Guide

Term Meaning
a text file containing batch commands that is executed by the command line
batch file
interpreter (e.g. cmd.exe)
all statements in the main input file following the line containing the word
Chemistry section
CHEMISTRY. This is made up of slightly modified PHREEQC code
custom plot a type of xy-plot that is fully defined by the user
a variable that is set and retrieved through the operating system and can be used
by programs such as PhreePlot to configure the way in which they run.
environment vari-
PhreePlot uses environment variables to define where the PhreePlot system
able
directory is located and for defining the Paths to certain executable files such as
the PhreePlot executable and Ghostscript executable
a data file in tabular format that provides data (observations, independent varia-
(fit) data file
bles) used in fit and simulate calculations
Long-standing open source software for interpreting Postscript files under a
Ghostscript
number of operating systems and in many popular graphic file formats
a way of calculating predominance and stability diagrams that simply calculates
grid approach
the speciation on a square grid of points
software that provides a pleasant user interface for running Ghostscript under
GSview
Windows
hunt and track a way of calculating predominance and stability diagrams that works by finding
approach and then tracking the field boundaries from the domain boundaries inwards
a file containing text that will be inserted into the Chemistry section at the point
include file
given by the include ‘filename’ statement
input file a file containing PhreePlot keywords and settings
the result of pressing the ‘Esc’ key during calculations. This enables the calcula-
interrupt
tions to be paused, stopped or a keyword setting to be changed
job a block of one or more runs
a file that is normally generated by a PhreePlot run containing details of the run.
log file
The level of detail is controlled by the debug keyword
a data file in tabular format in which a row of data is read from the file for every
loop file iteration of the z-loop. Tags based on the column headings are generated from
the line of data and may be used in the Chemistry section.
the principal file containing PhreePlot keywords and settings. It will also contain
main input file the Chemistry section, if present. It normally has the extension .ppi and is used
to launch a job
main loop simula- all simulations numbered mainLoop or greater. Used for iterating with the least
tions overheads and with constant updating of the <x_axis> and <y_axis> tags
a character string representing a main species variable that is controlled by the
main species main species loop. Often used for a list of elements but can be used for a list of
any character strings
the outermost alphanumeric loop controlled by the <mainspecies> tag and list of
mainspecies loop
mainspecies
the selected selected output file. It is the default file used by custom calculations
outfile or ‘out’ file
to make a plot
an input file that contains PhreePlot keywords that is read immediately after the
override file
main input file and will override any settings in force at that point
the PhreePlot environment variable (PHREEPLOT) is required to tell your
PhreePlot envi- computer where to find the PhreePlot system directory. It is set during installa-
ronment variable tion, through the Control Panel or with a program such as setx.exe. It should
end in a backslash
PhreePlot execut-
the file that contains the executable code for PhreePlot, normally called pp.exe
able
 567

Table A1. A glossary of terms used in this Guide (contd)

Term Meaning
The directory containing many of the files needed by PhreePlot to run. It is nor-
PhreePlot system mally called something like ...\PhreePlot\x.xx\system\ where x.xx is the
directory PhreePlot version number; it is normally stored in the PHREEPLOT environ-
ment variable
a popular geochemical speciation program (pH-redox equilibrium calculations
PHREEQC
in C) from the USGS that does all the geochemical calculations in PhreePlot
a page description language noted for its ability to produce scalable text and vec-
tor graphics of high quality. Postscript is the code that PhreePlot uses to define
its plots. It can be rendered with the Ghostscript/GSview software combination
Postscript
and is readily converted to other formats. pdf is a popular descendant of Post-
script and was also developed by Adobe. Postscript files normally have the exten-
sion .ps
a file that contains a one-line entry for each PhreePlot run. It is automatically
pp.log file
generated and is located in the PhreePlot system directory
an input file that contains user-defined default settings for all the PhreePlot key-
pp.set file
words. This is the first input file to be read and overwrites the program defaults
pre-loop simula- All simulations preceding the main loop simulation(s). Used for initialization
tions calculations. Not repeated during execution of the x- and y-axis loops
a diagram, normally in two-dimensions, that shows the dominant chemical spe-
predominance cies for a particular ‘component’ over the domain of interest. The ‘predominant’
diagram species is defined in PhreePlot as the most abundant species in terms of moles of
component, irrespective of whether it is a solution, mineral or adsorbed species
a block of one or more simulations that are executed in a single call to
run
PHREEQC
tabular output generated by PHREEQC following some calculations. The out-
selected output put can be controlled using keywords such as SELECTED_OUTPUT and
USER_PUNCH
a ‘file’ created by PHREEQC that is used to communicate between PHREEQC
and PhreePlot. The actual name of the file is defined by the -file identifier in the
selected output
SELECTED_OUTPUT keyword data block of PHREEQC. The default name
file
is selected.out but it can be an unnamed virtual file in PhreePlot when there is
minimal debugging taking place
a block of one or more PHREEQC keywords ending with an END or the end-of-
simulation
file
simulation
the sequence number of a simulation counted from the top
number
similar to a predominance diagram except that a mineral species, if present,
stability diagram
always take precedence over any solution species
a character string (here 30 characters or less) that is enclosed by angle brackets,
e.g. <x_axis>. Tags are used as placeholders in the Chemistry section and in cer-
tain PhreePlot keyword settings such as the plot title. They can be defined in a
tag
number of ways and can refer to either numeric or character variables. Tags are
substituted by their current values before code is submitted either to PHREEQC
for processing or to the in-built plotting routines for writing the plot file
x-axis loop the third innermost loop controlled by the <x_axis> tag
the fourth innermost (and most rapidly changing) loop controlled by the
y-axis loop
<y_axis> tag
z-loop the second innermost loop controlled by the <loop> tag
568 PhreePlot Guide

Appendix 2. Thermodynamic databases

The following tables show which elements are found in the various PHREEQC-format ther-
modynamic databases distributed with PhreePlot. The included elements are shown in red.
Additional elements may be added by editing the databases or including the necessary code in
an input file.
These database files can be found in the PhreePlot ‘system’ directory.
The ‘Summary of inorganic species’ for each database has been generated with the
count_database_species demo.

Table A2a. Elements available in the phreeqc.dat (USGS) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† These files are included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

Summary of inorganic species (elements) included

number of primary master species = 25
number of secondary master species = 18
number of minerals = 57
number of gases = 8
number of aqueous species = 184
 569

Table A2b. Elements available in the Amm.dat database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

This database is similar to the original phreeqc.dat except that Amm.dat also includes Amm as a
master species and so breaks the assumed redox equilibrium between ammonium (N(-3)) and
other N species. Unlike the latest (2.17) version of phreeqc.dat, it also excludes diffusion coef-
ficients for some aqueous species.

Summary of inorganic species (elements) included

Summary of inorganic species (elements)
number of primary master species = 25
number of secondary master species = 17
number of minerals = 56
number of gases = 6
number of aqueous species = 180
570 PhreePlot Guide

Table A2c. Elements available in the wateq4f.dat (USGS) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

Summary of inorganic species (elements) included

number of primary master species = 33
number of secondary master species = 29
number of minerals = 311
number of gases = 8
number of aqueous species = 346
 571

Table A2d. Elements available in the llnl.dat (Lawrence Livermore National Laboratory) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

Summary of inorganic species (elements) included

number of primary master species = 81
number of secondary master species = 137
number of minerals = 1120
number of gases = 91
number of aqueous species = 1186
572 PhreePlot Guide

Table A2e. Elements available in the minteq.dat (USEPA) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

This database includes cyanide, DOM and some 30 organic ligands including EDTA, citrate
and acetate.

Summary of inorganic species (elements) included

number of primary master species = 38
number of secondary master species = 41
number of minerals = 478
number of gases = 14
number of aqueous species = 484
 573

Table A2f. Elements available in the minteq.v4.dat (USEPA) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

This database includes cyanide, cyanate and some 31 organic ligands including EDTA, citrate
and acetate.

Summary of inorganic species (elements) included

number of primary master species = 40
number of secondary master species = 45
number of minerals = 541
number of gases = 15
number of aqueous species = 609
574 PhreePlot Guide

Table A2g. Elements available in the pitzer.dat (USGS) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

This database includes Pitzer coefficients and is designed to be used with the Pitzer model.

Summary of inorganic species (elements) included

number of primary master species = 16
number of secondary master species = 4
number of minerals = 45
number of gases = 2
number of aqueous species = 26
 575

Table A2h. Elements available in the NAPSI_290502(260802).DAT (Nagra-PSI) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† See http://les.web.psi.ch/TDBbook/index.htm for a description of the associated publication and here for down-
loading the data. Also see Duro L., Grivé M., Cera E., Domènech C., Bruno J. Update of a thermodynamic data-
base for radionuclides to assist solubility limits calculation for performance assessment.Technical Report TR-06-
17 (2006), Svensk Kärnbränslehantering AB (Swedish Nuclear Fuel and Waste Management Co.).

Summary of inorganic species (elements) included

number of primary master species = 39
number of secondary master species = 37
number of minerals = 91
number of gases = 6
number of aqueous species = 391
576 PhreePlot Guide

Table A2i. Elements available in the sit.dat (ANDRA) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/. It is based on the ThermoChimie v.7.b database, developed by Amphos 21, BRGM
and HydrAsa for ANDRA, the French National Radioactive Waste Management Agency.

This database has been especially prepared for dealing with problems in radioactive waste
management. It includes a table of SIT epsilon parameters for use with the Specific Interac-
tion Theory (SIT) activity coefficient model of Grenthe et al. (1997).

Summary of inorganic species (elements)

number of primary master species = 54
number of secondary master species = 55
number of minerals = 775
number of gases = 10
number of aqueous species = 1013
 577

Table A2j. Elements available in the 050000c0.tdb (NEA) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† See http://migrationdb.jaea.go.jp/english.html for the download home page and links to the privacy policy and
copyright, and here for downloading this data. A variety of other related PHREEQC-format databases are availa-
ble from the home page.

Summary of inorganic species (elements) included

number of primary master species = 54
number of secondary master species = 4
number of minerals = 404
number of gases = 148
number of aqueous species = 387
578 PhreePlot Guide

Table A2k. Elements available in the 011213c2.tdb (JAEA) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† See http://migrationdb.jaea.go.jp/english.html for the home page and links to the privacy policy and copyright,
and here for downloading this data. A variety of other databases are available from the home page.

This database also includes definitions for the organic ligands: oxalate, citrate and EDTA.

Summary of inorganic species (elements) included

number of primary master species = 48
number of secondary master species = 39
number of minerals = 368
number of gases = 72
number of aqueous species = 497
 579

Table A2l. Elements available in the iso.dat (USGS) database.†

Group 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Period

1 1 2
H He
2 3 4 5 6 7 8 9 10
Li Be B C N O F Ne
3 11 12 13 14 15 16 17 18
Na Mg Al Si P S Cl Ar
4 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
K Ca Sc Ti V Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
5 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
Rb Sr Y Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I Xe
6 55 56 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
*
Cs Ba Hf Ta W Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
7 87 88
**
Fr Ra

* Lanthanoids 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
La Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
** Actinoids 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
Ac Th Pa U Np Pu Am Cm Bk Cf Es Fm Md No Lr

† This file is included with the standard PHREEQC distribution. See http://wwwbrr.cr.usgs.gov/projects/
GWC_coupled/phreeqc/.

This database includes isotopic fractionation factors and is designed to be used for stable iso-
tope (H, O, C) calculations. The two minerals included are calcite and gypsum.

Summary of inorganic species (elements) included

number of primary master species = 10
number of secondary master species = 12
number of minerals = 2
number of gases = 7
number of aqueous species = 38
580 PhreePlot Guide

Appendix 3. Symbol numbers and names

The following symbols are available for use in PhreePlot. Symbols can be specified either by
their symbol code or by their name (case independent). Enclose the name in quotes if it con-
tains a space. See Figure 7.4 for a display of all of the symbols.

Table A3. .Table showing the symbols available for plotting arranged by symbol code and name.

font symbol code symbol name

1 FILLED CIRCLE
2 FILLED SQUARE
3 FILLED TRIANGLE
4 FILLED UPSIDE DOWN TRIANGLE
5 FILLED DIAMOND
native
6 FILLED OCTAGON
7 OPEN CIRCLE
8 PLUS
9 MULTIPLY
10 STAR
11 NUMBER SIGN
12 PERCENT SIGN
13 ASTERISK
14 PLUS
15 MINUS
16 PERIOD
17 QUESTION MARK
18 PERPENDICULAR
19 UNDERSCORE
20 OVERSCORE
21 BAR
22 MINUTE
Symbol font
23 LESSEQUAL
24 CLUB
25 DIAMOND
26 HEART
27 SPADE
28 ARROWLEFTRIGHT
29 ARROWLEFT
30 ARROWUP
31 ARROWRIGHT
32 ARROWDOWN
33 SIMILAR
34 COPYRIGHTSANS
 581

font symbol code symbol name

41 UPPER BLADE SCISSORS
42 BLACK SCISSORS
43 LOWER BLADE SCISSORS
44 WHITE SCISSORS'
45 BLACK TELEPHONE
46 TELEPHONE LOCATION SIGN
47 TAPE DRIVE
50 AIRPLANE
51 ENVELOPE
52 BLACK POINTING RIGHT INDEX
53 WHITE POINTING RIGHT INDEX
54 VICTORY HAND
55 WRITING HAND
56 LOWER RIGHT PENCIL
57 PENCIL
60 UPPER RIGHT PENCIL
61 WHITE NIB
70 HEAVY BALLOT X
71 OUTLINED GREEK CROSS
72 HEAVY GREEK CROSS
73 OPEN CENTRE CROSS
74 HEAVY OPEN CENTRE CROSS
75 LATIN CROSS
76 SHADOWED WHITE LATIN CROSS
77 OUTLINED LATIN CROSS
100 MALTESE CROSS
101 STAR OF DAVID
102 FOUR TEARDROP-SPOKED ASTERISK
103 FOUR BALLOON-SPOKED ASTERISK
104 HEAVY FOUR BALLOON-SPOKED ASTERISK
105 FOUR CLUB-SPOKED ASTERISK
110 BLACK FOUR POINTED STAR
111 STRESS OUTLINED WHITE STAR
112 CIRCLED WHITE STAR
113 OPEN CENTRE BLACK STAR
114 BLACK CENTRE WHITE STAR
115 OUTLINED BLACK STAR
116 HEAVY OUTLINED BLACK STAR
117 PINWHEEL STAR
120 SHADOWED WHITE STAR
121 HEAVY ASTERISK
122 OPEN CENTRE ASTERISK
Zapf Dingbat 123 EIGHT SPOKED ASTERISK
font 124 EIGHT POINTED BLACK STAR
125 EIGHT POINTED PINWHEEL STAR
126 SIX POINTED BLACK STAR
127 EIGHT POINTED RECTILINEAR BLACK STAR
130 HEAVY EIGHT POINTED RECTILINEAR BLACK STAR
131 TWELVE POINTED BLACK STAR
132 SIXTEEN POINTED ASTERISK
133 TEARDROP-SPOKED ASTERISK
134 OPEN CENTRE TEARDROP-SPOKED ASTERISK
135 HEAVY TEARDROP-SPOKED ASTERISK
136 SIX PETALLED BLACK AND WHITE FLORETTE
137 BLACK FLORETTE
140 WHITE FLORETTE
141 EIGHT PETALLED OUTLINED BLACK FLORETTE
142 CIRCLED OPEN CENTRE EIGHT POINTED STAR
143 HEAVY TEARDROP-SPOKED PINWHEEL ASTERISK
144 SNOWFLAKE
145 TIGHT TRIFOLIATE SNOWFLAKE
146 HEAVY CHEVRON SNOWFLAKE
147 SPARKLE
582 PhreePlot Guide

font symbol code symbol name

150 HEAVY SPARKLE
151 BALLOON-SPOKED ASTERISK
152 EIGHT TEARDROP-SPOKED PROPELLER ASTERISK
153 HEAVY EIGHT TEARDROP-SPOKED PROPELLER ASTERISK
154 BLACK CIRCLE
155 SHADOWED WHITE CIRCLE
156 BLACK SQUARE
157 LOWER RIGHT DROP-SHADOWED WHITE SQUARE
160 UPPER RIGHT DROP-SHADOWED WHITE SQUARE
161 LOWER RIGHT SHADOWED WHITE SQUARE
162 UPPER RIGHT SHADOWED WHITE SQUARE
163 BLACK UP-POINTING TRIANGLE
164 BLACK DOWN-POINTING TRIANGLE
165 BLACK DIAMOND
166 BLACK DIAMOND MINUS WHITE X
167 RIGHT BLACK SEMICIRCLE
170 LIGHT VERTICAL BAR
171 MEDIUM VERTICAL BAR
172 HEAVY VERTICAL BAR
173 HEAVY SINGLE TURNED COMMA QUOTATION MARK ORNAMENT
174 HEAVY SINGLE COMMA QUOTATION MARK ORNAMENT
175 HEAVY DOUBLE TURNED COMMA QUOTATION MARK ORNAMENT
176 HEAVY DOUBLE COMMA QUOTATION MARK ORNAMENT
241 CURVED STEM PARAGRAPH SIGN ORNAMENT
242 HEAVY EXCLAMATION MARK ORNAMENT
243 HEAVY HEART EXCLAMATION MARK ORNAMENT
244 HEAVY BLACK HEART
245 ROTATED HEAVY BLACK HEART BULLET
246 FLORAL HEART
247 ROTATED FLORAL HEART BULLET
250 BLACK CLUB SUIT
Zapf Dingbat
251 BLACK DIAMOND SUIT
font
252 BLACK HEART SUIT
253 BLACK SPADE SUIT
254 DINGBAT CIRCLED DIGIT ONE
255 DINGBAT CIRCLED DIGIT TWO
256 DINGBAT CIRCLED DIGIT THREE
257 DINGBAT CIRCLED DIGIT FOUR
260 DINGBAT CIRCLED DIGIT FIVE
261 DINGBAT CIRCLED DIGIT SIX
262 DINGBAT CIRCLED DIGIT SEVEN
263 DINGBAT CIRCLED DIGIT EIGHT
264 DINGBAT CIRCLED DIGIT NINE
265 DINGBAT CIRCLED NUMBER TEN
266 DINGBAT NEGATIVE CIRCLED DIGIT ONE
267 DINGBAT NEGATIVE CIRCLED DIGIT TWO
270 DINGBAT NEGATIVE CIRCLED DIGIT THREE
271 DINGBAT NEGATIVE CIRCLED DIGIT FOUR
272 DINGBAT NEGATIVE CIRCLED DIGIT FIVE
273 DINGBAT NEGATIVE CIRCLED DIGIT SIX
274 DINGBAT NEGATIVE CIRCLED DIGIT SEVEN
275 DINGBAT NEGATIVE CIRCLED DIGIT EIGHT
276 DINGBAT NEGATIVE CIRCLED DIGIT NINE
277 DINGBAT NEGATIVE CIRCLED NUMBER TEN
300 DINGBAT CIRCLED SANS-SERIF DIGIT ONE
301 DINGBAT CIRCLED SANS-SERIF DIGIT TWO
302 DINGBAT CIRCLED SANS-SERIF DIGIT THREE
303 DINGBAT CIRCLED SANS-SERIF DIGIT FOUR
304 DINGBAT CIRCLED SANS-SERIF DIGIT FIVE
305 DINGBAT CIRCLED SANS-SERIF DIGIT SIX
306 DINGBAT CIRCLED SANS-SERIF DIGIT SEVEN
307 DINGBAT CIRCLED SANS-SERIF DIGIT EIGHT
310 DINGBAT CIRCLED SANS-SERIF DIGIT NINE
 583

font symbol code symbol name

311 DINGBAT CIRCLED SANS-SERIF NUMBER TEN
312 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT ONE
313 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT TWO
314 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT THREE
315 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT FOUR
316 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT FIVE
317 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT SIX
320 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT SEVEN
321 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT EIGHT
322 DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT NINE
323 DINGBAT NEGATIVE CIRCLED SANS-SERIF NUMBER TEN
324 HEAVY WIDE-HEADED RIGHTWARDS ARROW
330 HEAVY SOUTH EAST ARROW
331 HEAVY RIGHTWARDS ARROW
332 HEAVY NORTH EAST ARROW
333 DRAFTING POINT RIGHTWARDS ARROW
334 HEAVY ROUND-TIPPED RIGHTWARDS ARROW
335 TRIANGLE-HEADED RIGHTWARDS ARROW
336 HEAVY TRIANGLE-HEADED RIGHTWARDS ARROW
337 DASHED TRIANGLE-HEADED RIGHTWARDS ARROW
340 HEAVY DASHED TRIANGLE-HEADED RIGHTWARDS ARROW
341 BLACK RIGHTWARDS ARROW
342 THREE-D TOP-LIGHTED RIGHTWARDS ARROWHEAD
343 THREE-D BOTTOM-LIGHTED RIGHTWARDS ARROWHEAD
Zapf Dingbat 344 BLACK RIGHTWARDS ARROWHEAD
font 345 HEAVY BLACK CURVED DOWNWARDS AND RIGHTWARDS ARROW
346 HEAVY BLACK CURVED UPWARDS AND RIGHTWARDS ARROW
347 SQUAT BLACK RIGHTWARDS ARROW
350 HEAVY CONCAVE-POINTED BLACK RIGHTWARDS ARROW
351 RIGHT-SHADED WHITE RIGHTWARDS ARROW
352 LEFT-SHADED WHITE RIGHTWARDS ARROW
353 BACK-TILTED SHADOWED WHITE RIGHTWARDS ARROW
354 FRONT-TILTED SHADOWED WHITE RIGHTWARDS ARROW
355 HEAVY LOWER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW
356 HEAVY UPPER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW
357 NOTCHED LOWER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW
361 NOTCHED UPPER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW
362 CIRCLED HEAVY WHITE RIGHTWARDS ARROW
363 WHITE-FEATHERED RIGHTWARDS ARROW
364 BLACK-FEATHERED SOUTH EAST ARROW
365 BLACK-FEATHERED RIGHTWARDS ARROW
366 BLACK-FEATHERED NORTH EAST ARROW
367 HEAVY BLACK-FEATHERED SOUTH EAST ARROW
370 HEAVY BLACK-FEATHERED RIGHTWARDS ARROW
371 HEAVY BLACK-FEATHERED NORTH EAST ARROW
372 TEARDROP-BARBED RIGHTWARDS ARROW
373 HEAVY TEARDROP-SHANKED RIGHTWARDS ARROW
374 WEDGE-TAILED RIGHTWARDS ARROW
375 HEAVY WEDGE-TAILED RIGHTWARDS ARROW
376 OPEN-OUTLINED RIGHTWARDS ARROW
584 PhreePlot Guide