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 May 4, 2020

ii PhreePlot Guide
 iii

Table of contents

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

2 INSTALLATION ................................................................................................ 5
2.1 Installing PhreePlot.................................................................................... 5
2.1.1 Windows .............................................................................................. 5
2.1.2 Mac OS X machines ............................................................................. 7
2.2 Checking for updates ................................................................................. 7
2.3 Changing the console appearance............................................................... 7
2.4 Installing Ghostscript and GSview ............................................................. 8
2.4.1 Launching PhreePlot from Windows Explorer or similar ...................... 8
2.4.2 Specifying the input file name on the command line ............................ 8
2.4.3 Specifying input and output filenames in PhreePlot input files ............. 8
2.4.4 Setting the PhreePlot environment variable .......................................... 9
2.4.5 Adding the path to PhreePlot to the Windows PATH setting .............. 9
2.4.6 Search path for files .............................................................................. 9
2.4.7 Ensuring that the correct databases are found ....................................... 9
2.5 Other useful software ................................................................................. 9
2.6 Trouble-shooting ..................................................................................... 10
File conversions ................................................................................. 10
Problem and bug reporting................................................................ 10

3 GETTING STARTED ....................................................................................... 11

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

4 PHREEQC BASICS .......................................................................................... 15

4.1 Online Phreeqc documentation................................................................ 15
4.2 How Phreeqc interacts with PhreePlot ..................................................... 15
4.3 Thermodynamic databases ....................................................................... 16
4.4 Types of output produced by Phreeqc...................................................... 16
4.5 The SELECTED_OUTPUT and the USER_PUNCH data blocks................................ 17
4.5.1 The SELECTED_OUTPUT filename and forcing the file to be written ......... 18
iv PhreePlot Guide

4.5.2 Scope of Phreeqc keywords ................................................................ 18

4.5.3 What is sent to the SELECTED_OUTPUT file? ............................................ 19
4.6 Setting up the SELECTED_OUTPUT file for input to PhreePlot ....................... 20
4.6.1 Possibilities for looping of Phreeqc input files .................................... 20
Predominance plots .......................................................................... 21
Data-led calculations......................................................................... 22
Custom plots .................................................................................... 23
Knowing which minerals might form using the given database ......... 25
4.6.2 Setting up a loop file .......................................................................... 25
4.7 Running Phreeqc without any plotting .................................................... 26
4.8 Include files ............................................................................................. 27
4.8.1 Use of ‘include’ files ........................................................................... 27
4.8.2 Supplied include files ......................................................................... 27
4.9 Using Phreeqc’s _RAW and _MODIFY keywords .................................. 27

5 PHREEPLOT INPUT AND OUTPUT FILES ........................................................ 29

5.1 Input/output files .................................................................................... 29
5.1.1 Use .................................................................................................... 29
5.1.2 Difference in execution of input files between PhreePlot and Phreeqc 29
5.2 Input files ................................................................................................ 30
5.2.1 Different types of input file ................................................................ 30
5.2.2 Structure of the main input files ......................................................... 31
5.2.3 The input file pre-processor ............................................................... 32
5.2.4 Exceptions to the ‘latest keyword definition overrides earlier ones’ rule ...
32
5.2.5 The colour dictionaries and other files ............................................... 32
5.2.6 Format of all input files ...................................................................... 32
Physical and logical lines ................................................................... 32
Specifying keyword-value pairs and keyword-lists ............................. 33
Format of keywords and their associated values................................. 34
5.2.7 Data separators and parsing input files ............................................... 34
5.2.8 Case sensitivity of input ..................................................................... 35
5.2.9 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 ................................ 37
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 ................................................................. 41
5.4 Output files ............................................................................................. 42
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) ................................................................................ 46
Predominance plot calculations (ht1 only) ........................................ 46
 v

Other calculations ............................................................................. 46

5.4.7 ‘vectors’ file (vec) ................................................................................ 46
5.4.8 ‘polygon’ file (pol) .............................................................................. 47
5.4.9 ‘labels’ file (labelFile) .......................................................................... 47
5.4.10 Other output files ............................................................................... 48
5.5 Inserting plot files into Microsoft Word, Powerpoint and other software . 49
5.6 Speed of computations and plotting ......................................................... 50

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 Looping over a list of character variables ............................................. 53
6.2.3 An example of the use of various looping mechanisms ........................ 53
Using the <x_axis> tag....................................................................... 53
Using the <loop> tag ......................................................................... 55
Using a loop file ................................................................................ 55
Using the ‘simulate’ calculationMethod............................................. 55
Looping over two variables ................................................................ 56
6.2.4 Looping in multi-simulation input files - pre-loop simulations and the
main loop 57
Introduction...................................................................................... 57
Basic structure of a multi-simulation Phreeqc input file..................... 58
6.2.5 Dynamic switching between Phreeqc models (code) ........................... 60
6.2.6 Defining the expected output in the selected output file ..................... 60
6.2.7 Timing execution ............................................................................... 60
6.2.8 Speeding-up calculations .................................................................... 61
6.3 Possible types of calculations and plots..................................................... 61
6.4 Preparing the SELECTED OUTPUT file................................................ 62
6.4.1 Normal behaviour .............................................................................. 62
6.4.2 The use of the ‘headings’ identifier ..................................................... 62
Controlling the plotting of individual columns.................................. 64
Use of labels in a custom plot and the minimum text size.................. 64
6.5 Debugging ............................................................................................... 65
6.5.1 Types of problem ............................................................................... 65
6.5.2 Checking the return status of a Phreeqc run ........................................ 66
6.5.3 General approach to debugging .......................................................... 66
6.5.4 Using the debug keyword .................................................................... 67
6.5.5 The most common reason for a failure to converge ............................. 67
6.5.6 Changing Phreeqc’s convergence parameters ...................................... 70
6.6 Interrupting execution and changing keyword values ............................... 70
6.7 Running the standard Phreeqc examples .................................................. 71
6.7.1 Going round for just one iteration ...................................................... 71
6.8 Return status and exit codes ..................................................................... 71

7 PLOTTING BASICS ......................................................................................... 73

7.1 Introduction............................................................................................. 73
7.2 Types of plot ............................................................................................ 73
7.3 Summary of basic plotting........................................................................ 73
vi PhreePlot Guide

7.3.1 Introduction ...................................................................................... 73

7.3.2 Setting up the plotting area ................................................................ 73
7.3.3 Setting up the axes scales, tick marks and grid lines ............................ 74
7.3.4 Axis numbering and annotation ......................................................... 75
7.3.5 Adding fills, lines and points .............................................................. 75
7.4 Controlling the style of lines and points (symbols) in Custom plots......... 76
7.4.1 The default style and colour for lines and points (symbols) ................ 76
7.4.2 Lines .................................................................................................. 77
Line styles ......................................................................................... 77
Automatic colouring of lines and points............................................ 78
7.4.3 Points (symbols) ................................................................................ 78
7.4.4 Order of plotting of lines and points (symbols) .................................. 79
7.5 Labelling plots ......................................................................................... 79
7.5.1 Label names and label position ........................................................... 79
7.5.2 Overriding calculated label positions and angles ................................. 80
7.5.3 Legend ............................................................................................... 81
7.6 Inputting text strings ............................................................................... 81
7.6.1 Available fonts and character sizes ...................................................... 81
7.6.2 Available characters and inserting ‘special’ characters ......................... 82
7.6.3 Text enhancements (bold, italic, subscript, superscript) and Greek charac-
ters 82
7.6.4 Accented and other ‘foreign’ characters - the Latin-1 encoding .......... 84
7.6.5 Non-printing characters ..................................................................... 85
7.6.6 Justification ........................................................................................ 85
7.6.7 Angle ................................................................................................. 85
7.6.8 Tags in text strings ............................................................................. 85
7.7 Special PhreePlot variables or tags............................................................ 85
7.7.1 Available tags ..................................................................................... 85
7.7.2 System pH, system pe and system temperature .................................. 86
7.8 Axis scaling .............................................................................................. 86
7.8.1 Auto or user-defined axis scaling ........................................................ 86
7.8.2 Secondary y axis (the 2y axis) ............................................................. 87
7.9 Controlling the properties of text, symbols, polygon fills and lines .......... 87
7.9.1 Principles ........................................................................................... 87
7.9.2 The colour palette .............................................................................. 88
7.9.3 Automatic or explicit ......................................................................... 89
7.9.4 The colour dictionaries ...................................................................... 89
Fill colours ........................................................................................ 89
Line colours and auto line colouring ................................................. 90
Point colours..................................................................................... 91
Filled symbols with a different rim colour ......................................... 91
7.9.5 Directories for the colour dictionaries ................................................ 92
7.10 Labelling.................................................................................................. 92
7.10.1 Predominance plots ........................................................................... 93
7.10.2 Contour plots .................................................................................... 93
7.10.3 Custom plots ..................................................................................... 93
7.11 Replotting without recalculating.............................................................. 94
7.11.1 The ‘replot’ option ............................................................................. 94
7.11.2 The ‘reprocess and replot’ option for predominance plots .................. 95
7.12 Adding extra lines, symbols and text ........................................................ 95
7.12.1 Lines and symbols .............................................................................. 95
 vii

7.12.2 Text .................................................................................................... 96

<input> ............................................................................................. 98
<loop> or <loop...>............................................................................ 98
<legend>............................................................................................ 99
<mainspecies> ................................................................................... 99
7.12.3 Formatting numbers in plots – varying the number of significant figures
displayed 99
7.12.4 Making fancy plots ........................................................................... 100

8 PREDOMINANCE PLOTS .............................................................................. 101

8.1 setting up a file to calculate a predominance diagram ............................. 101
8.1.1 The ‘grid’ and ‘ht1’ approaches ........................................................ 102
Grid approach ................................................................................. 102
‘Hunt and track’ approach............................................................... 102
8.1.2 Using the ht1.inc code to return the dominant species .................... 104
8.1.3 Problems with the ‘hunt and track’ approach – ‘unclosed polygons’ . 105
8.1.4 Optimising the calculation efficiency ................................................ 106
8.1.5 Predominance vs mineral stability diagrams ...................................... 106
8.1.6 Using ht1minerals.inc to determine the minerals present ............... 106
8.2 The ‘grid’ approach ................................................................................ 107
8.3 The ‘Hunt and track’ approach .............................................................. 107
8.3.1 Strategy ............................................................................................ 107
8.3.2 Details of the ‘hunt and track’ algorithm .......................................... 108
Applying the concepts of hunting and tracking at the practical level 108
Definitions of 'predominance' and mineral stability ........................ 110
8.3.3 Failure of the ‘hunt and track’ approach ........................................... 110
8.4 Feasible domains and the preparation of Eh (pe) -pH diagrams.............. 111
8.4.1 General principles ............................................................................. 111
8.4.2 Domain tags - avoiding speciation calculations ................................. 112
8.4.3 Speciation failure when there is not enough reactant present ............ 113
8.5 Choice of the resolution of the plot........................................................ 113
8.6 Monitoring the progress of a ‘hunt and track’ run.................................. 114
8.7 Plotting and Replotting.......................................................................... 115
8.8 Modifying the appearance of predominance plots .................................. 115
8.9 Adding lines and points to a predominance plot..................................... 117
8.10 Controlling the labelling of plots and the plotting of fields..................... 117
8.11 Why do I not see methane gas when using llnl.dat?.............................. 118
8.12 Failure to complete a predominance diagram ......................................... 118

9 CONTOUR PLOTS........................................................................................ 121

9.1 What are contour plots? ......................................................................... 121
9.2 Implementation ..................................................................................... 121
9.2.1 Generating the contour data ............................................................. 121
9.2.2 Choosing the contour levels .............................................................. 122
9.2.3 Types of contour plot ....................................................................... 122
9.2.4 Changing the appearance of the contour lines. ................................. 123
9.2.5 Colouring the plot ............................................................................ 123
9.2.6 Labels and Legend ............................................................................ 124
9.2.7 Flow of data ..................................................................................... 124
9.2.8 What if Phreeqc fails? ....................................................................... 124
9.3 A simple example ................................................................................... 125
viii PhreePlot Guide

9.4 Some details of the data processing ........................................................ 128

9.4.1 Algorithm ........................................................................................ 128
9.4.2 Problematic cases ............................................................................. 128
9.5 Modifying the appearance of the plot .................................................... 129
9.6 Refining a plot – replotting without recalculating.................................. 131
9.6.1 Where to start? ................................................................................. 131
9.6.2 Smoothing the z-data ....................................................................... 132
9.7 Overlapping or misplaced label.............................................................. 132
9.8 What happens if Phreeqc fails during contouring calculations? .............. 132

10 CUSTOM PLOTS .......................................................................................... 133

10.1 Overview ............................................................................................... 133
10.2 Preparation of the input file................................................................... 133
10.2.1 Introduction .................................................................................... 133
10.2.2 Controlling the scope of custom plots .............................................. 134
10.3 Simple looping ...................................................................................... 134
10.4 Calculating speciation on a 2-D grid ..................................................... 135
10.5 Modifying the appearance of custom plots............................................. 135
10.5.1 Overview ......................................................................................... 135
10.5.2 Customising the plot ....................................................................... 136

11 SPECIES PLOTS ............................................................................................ 139

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

12 FITTING AND SIMULATIONS ........................................................................ 143

12.1 Introduction .......................................................................................... 143
12.2 Fitting is special ..................................................................................... 144
12.3 Approach to fitting ................................................................................ 144
12.4 Practical Setup....................................................................................... 145
12.4.1 Approach ......................................................................................... 145
12.4.2 Flow of data and information during fitting ..................................... 147
12.4.3 The parameters ................................................................................ 148
12.4.4 Variables .......................................................................................... 149
12.4.5 Passing the fitted values from Phreeqc to PhreePlot: preparing the input
file 150
One pass to generate a single data value .......................................... 150
One pass to generate all data values................................................. 151
Skipping unwanted Phreeqc selected output ................................... 151
Global optimization - switching models.......................................... 151
12.4.6 Data file ........................................................................................... 153
12.5 The optimization routines ..................................................................... 154
12.5.1 Choice of fit algorithm ..................................................................... 154
12.5.2 Scaling of parameters ....................................................................... 155
12.5.3 Constrained optimization ................................................................ 155
12.5.4 Control parameters .......................................................................... 155
Finite difference step size (‘nlls’ only).............................................. 155
Convergence criterion ..................................................................... 156
Step size .......................................................................................... 157
Maximum iterations ....................................................................... 157
 ix

Weighting method .......................................................................... 157

12.6 Preparing an input file............................................................................ 157
12.6.1 Simple example ................................................................................ 157
12.6.2 Automatic updating of parameter values in an input file ................... 158
12.7 Interrupting or stopping the fitting ........................................................ 158
12.8 Forcing relations between parameter values ............................................ 158
12.9 Multi-objective fitting ............................................................................ 159
12.10 Output files............................................................................................ 159
12.11 Response in the event of a failure of Phreeqc to converge ....................... 160
12.12 Plotting the results of the fitting............................................................. 160
12.12.1Plots of observed and calculated results ............................................ 160
12.12.2Contour plot of the residual sum of squares ..................................... 160
12.13 Simulations ............................................................................................ 162
12.14 Root finding – solving equations, adding constraints.............................. 162

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

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

14 KEYWORDS ................................................................................................. 169

14.1 Summary of available keywords.............................................................. 169
14.2 Conventions........................................................................................... 172
14.3 Keyword description .............................................................................. 173
all.................................................................................................................173
axisLineColor...............................................................................................173
axisLineWidth .............................................................................................174
axisNumberColor ........................................................................................174
axisNumberSize ...........................................................................................174
axisTitleColor ..............................................................................................174
axisTitleSize .................................................................................................175
backgroundColor.........................................................................................175
beep .............................................................................................................175
blockRangeColumn .....................................................................................176
calculationMethod .......................................................................................177
calculationType ...........................................................................................178
changeColor ................................................................................................178
characterTags ...............................................................................................179
checkForUpdate...........................................................................................180
colorModel ..................................................................................................180
contourDashesPerInch.................................................................................181
contourFillColor..........................................................................................181
contourLabelColor.......................................................................................182
contourLabelFigs .........................................................................................182
contourLabelFont ........................................................................................182
contourLabelSize..........................................................................................183
contourLineColor ........................................................................................183
contourLineType .........................................................................................183
contourLineWidth.......................................................................................184
contourOptions ...........................................................................................184
contours.......................................................................................................185
contourShiftLabel ........................................................................................186
contourZvariable..........................................................................................188
x PhreePlot Guide

convertLabels .............................................................................................. 189

customLoopManyPlots................................................................................ 190
customXcolumn .......................................................................................... 190
dashesPerInch, dashesPerInch2y.................................................................. 191
database....................................................................................................... 191
databaseVersion........................................................................................... 191
dataFile ....................................................................................................... 192
dataSeparators ............................................................................................. 193
dateDatabase ............................................................................................... 195
debug .......................................................................................................... 195
dependentVariableColumnObs ................................................................... 196
dependentVariableColumnCalc................................................................... 197
domain........................................................................................................ 197
dominant .................................................................................................... 198
eps............................................................................................................... 198
epsi.............................................................................................................. 199
extradat ....................................................................................................... 200
extraSymbolsLines....................................................................................... 201
extraText ..................................................................................................... 203
fillColorDictionary...................................................................................... 203
FIT.............................................................................................................. 204
fitAdjustableParameters ............................................................................... 204
fitConvergenceCriterion.............................................................................. 204
fitFiniteDiffStepSize.................................................................................... 205
fitLogParameters ......................................................................................... 205
fitLowerParameterValues............................................................................. 206
fitMaxIterations........................................................................................... 206
fitMethod.................................................................................................... 206
fitnpt ........................................................................................................... 207
fitParameterNames...................................................................................... 208
fitParameterValues ...................................................................................... 208
fitStepSize ................................................................................................... 208
fitUpperParameterValues ............................................................................ 209
fitWeightingMethod ................................................................................... 209
font ............................................................................................................. 210
gridColor..................................................................................................... 212
gridDashesPerInch ...................................................................................... 213
gridLines ..................................................................................................... 213
gridLineType............................................................................................... 213
info ............................................................................................................. 214
initialValue.................................................................................................. 215
jobTitle ....................................................................................................... 215
jpg............................................................................................................... 215
labelColor.................................................................................................... 216
labelEffort ................................................................................................... 216
labelFile....................................................................................................... 217
labels ........................................................................................................... 217
labelSize ...................................................................................................... 218
legendBox.................................................................................................... 219
legendTextColor ......................................................................................... 220
legendTextSize ............................................................................................ 220
 xi

legendTitle...................................................................................................220
lineColor, lineColor2y .................................................................................221
lineColorDictionary.....................................................................................221
lines, lines2y ................................................................................................222
lineType, lineType2y ...................................................................................222
lineWidth, lineWidth2y...............................................................................223
log................................................................................................................223
logDepVariable ............................................................................................223
logVariableIn ...............................................................................................224
loopFile........................................................................................................225
loopIndexStartNumber ................................................................................227
loopInt.........................................................................................................227
loopLogVar..................................................................................................227
loopMax ......................................................................................................228
loopMin.......................................................................................................228
mainLoop ....................................................................................................228
mainLoopColumn .......................................................................................230
mainspecies..................................................................................................230
minimumAreaForLabeling...........................................................................231
minimumYValueForPlotting .......................................................................231
missingValue................................................................................................232
multipageFile ...............................................................................................232
nameSpeciationProgram ..............................................................................233
nudge...........................................................................................................233
nudgeFile.....................................................................................................235
numberOfFitParameters ..............................................................................236
numericTags ................................................................................................236
omitAccumulate...........................................................................................237
onePass ........................................................................................................237
out ...............................................................................................................238
overlay .........................................................................................................239
pageOrientation...........................................................................................241
paperSize......................................................................................................241
pdf ...............................................................................................................242
pdfMaker.....................................................................................................243
IPhreePlotVersion........................................................................................244
Phreeqc.0.out...............................................................................................244
PLOT ..........................................................................................................244
plotFactor ....................................................................................................244
plotFrequency ..............................................................................................245
plotOrder.....................................................................................................245
plotTitle.......................................................................................................245
plotTitleColor..............................................................................................246
plotTitleSize ................................................................................................246
png ..............................................................................................................246
pointColor, pointColor2y............................................................................247
points, points2y ...........................................................................................248
pointsSameColor .........................................................................................248
pointSize, pointSize2y..................................................................................248
pointType, pointType2y..............................................................................249
pol ...............................................................................................................249
xii PhreePlot Guide

post ............................................................................................................. 250

postSize ....................................................................................................... 251
ppa .............................................................................................................. 251
pplog........................................................................................................... 252
printScreenFrequency.................................................................................. 252
ps ................................................................................................................ 252
pts ............................................................................................................... 253
pxdec........................................................................................................... 253
pxmajor....................................................................................................... 253
pxmax ......................................................................................................... 254
pxmin.......................................................................................................... 254
pxminor ...................................................................................................... 254
pydec, p2ydec.............................................................................................. 255
pymajor, p2ymajor ...................................................................................... 255
pymax, p2ymax ........................................................................................... 255
pymin, p2ymin............................................................................................ 256
pyminor, p2yminor ..................................................................................... 256
resolution .................................................................................................... 256
restartColorSequence................................................................................... 258
rimColor ..................................................................................................... 258
rimFactor .................................................................................................... 258
screen .......................................................................................................... 259
selectedOutputFile ...................................................................................... 259
selectedOutputLines.................................................................................... 260
simplify ....................................................................................................... 261
skip ............................................................................................................. 262
SPECIATION ............................................................................................ 262
speciationProgram....................................................................................... 262
speciationProgramVersion ........................................................................... 263
startTemperature......................................................................................... 263
stopOnFail .................................................................................................. 263
symbolsLines ............................................................................................... 264
text.............................................................................................................. 265
tickColor ..................................................................................................... 267
tickSize........................................................................................................ 267
trackSymbolColor ....................................................................................... 269
trackSymbolSize .......................................................................................... 269
trk ............................................................................................................... 270
units ............................................................................................................ 270
unrecognisedKeywordIsFatal ....................................................................... 271
updateFitParameters.................................................................................... 271
useLabelsFile ............................................................................................... 271
useLineColorDictionary .............................................................................. 272
vec............................................................................................................... 272
weightColumn ............................................................................................ 273
writeAllInputFiles........................................................................................ 273
writePlaceholder .......................................................................................... 273
xaxisLength ................................................................................................. 274
xmax ........................................................................................................... 274
xmin............................................................................................................ 274
xoffset.......................................................................................................... 274
 xiii

xtitle ............................................................................................................275
yaxisLength..................................................................................................275
ymax ............................................................................................................276
ymin ............................................................................................................276
yoffset ..........................................................................................................276
yscale ...........................................................................................................276
ytitle, 2ytitle.................................................................................................277

15 EXAMPLES ................................................................................................... 279

Predominance plots (grid approach).................................................................................. 280
1 Fe-H2O (grid approach) ....................................................................................... 282
2 Cu-S-C (‘island’ found with ‘grid’) ....................................................................... 286
Predominance plots (ht1 approach) .................................................................................. 289
3 Fe-H2O (‘Hunt and track’ approach) ................................................................... 290
4 Fe-H2O: close-up (predominance criterion) ......................................................... 292
5 Fe-H2O: close-up (stability criterion) ................................................................... 294
6 Fe-H2O (pe scale)................................................................................................. 296
7 Fe-H2O (Eh scale) ................................................................................................ 298
8 As-O2(g)-H2O...................................................................................................... 300
9 As-O2(g)-H2O (sub-dominant) ............................................................................ 302
10 Fe-As-C-S............................................................................................................. 304
11 Fe-As .................................................................................................................... 308
12 Fe-As-Hfo (ht1.inc) .............................................................................................. 310
13 Fe-As-Hfo (ht1c.inc) ............................................................................................ 312
14 Fe-S-As (without sorption) ................................................................................... 314
15 Fe-S-As (low Fe, without surface speciation)......................................................... 318
16 Fe-S-As (goethite, CD-MUSIC) ........................................................................... 322
17 Fe-As-S (high Fe).................................................................................................. 326
18 Fe-CO2-SO4-H2O with sample points ................................................................. 330
19 Fe-Ni-S ................................................................................................................ 334
20 Fe-Zn-C-H2O (HFO) .......................................................................................... 338
21 Fe-Zn-C-H2O (HFO) .......................................................................................... 342
22 Ca-Fe-Na-X-HFO (adsorption and ion exchange)................................................ 346
23 Acid mine drainage............................................................................................... 350
24 AMD (carbon) ..................................................................................................... 354
25 Ca-Mg-Zn-CO3.................................................................................................................................................. 358
26 U-CO3...................................................................................................................................................................... 362
27 Ca-Mg-CO3 at high T.......................................................................................... 364
28 P-Ca-Mg-CO3(aq)................................................................................................ 366
29 P-Ca-Mg-CO3 (with solids).................................................................................. 368
30 Mn-CO2-H2O (no minerals)................................................................................ 372
31 Mn-H2O (with minerals) ..................................................................................... 374
32 Mn-CO2-H2O ..................................................................................................... 376
33 Pu-F-H2O ............................................................................................................ 378
34 U-C-H2O (wateq4f.dat) ....................................................................................... 380
35 U-C-H2O (NAPSI) .............................................................................................. 382
36 U-C-H2O (llnl.dat) .............................................................................................. 384
37 U-Fe-C-H2O........................................................................................................ 388
38 U-Fe-C (risk colours)............................................................................................ 392
39 U-H2O (redox state) ............................................................................................ 396
40 U-F-P (U) ............................................................................................................ 398
41 U-F-P (F) ............................................................................................................. 402
42 U-F-P (P) ............................................................................................................. 404
43 Cu-S-C (‘island’ not found with ‘ht1’).................................................................. 406
xiv PhreePlot Guide

44 Cu-S-C (simplification factor = 1) ........................................................................ 408

45 Cu-S-C (simplification factor = 3) ........................................................................ 412
46 Cu-EDTA-H2O ................................................................................................... 416
47 Ca-F-P-C-H2O..................................................................................................... 420
48 Ni-S-C-H2O......................................................................................................... 422
49 Zn-S-C-H2O ........................................................................................................ 426
50 Cd-S-C-H2O ........................................................................................................ 430
51 Pb-S-C-P-H2O ..................................................................................................... 434
52 Sb-S ...................................................................................................................... 438
53 Se-S ...................................................................................................................... 442
54 Clay mineral stability diagram............................................................................... 444
Custom plots..................................................................................................................... 447
55 Gibbsite solubility vs pH....................................................................................... 448
56 Acid titration of groundwater (using ‘REACTION’) ............................................ 452
57 Acid titration of groundwater (using PhreePlot looping) ....................................... 454
58 Redox sequence..................................................................................................... 458
59 Kd’s for trace metals as a function of pH............................................................... 462
60 Cd speciation vs pH.............................................................................................. 466
61 Zn-HFO: %sorption vs pH curves........................................................................ 470
62 Zn-HFO: Surface speciation ................................................................................. 474
63 As-HFO: reduction in surface area........................................................................ 478
64 CD-MUSIC: As(III) adsorption on goethite......................................................... 482
65 CD-MUSIC: As(V) adsorption on goethite .......................................................... 484
66 Kinetics of pyrite oxidation ................................................................................... 488
67 Kinetics of quartz dissolution ................................................................................ 492
68 Symbols and lines ................................................................................................. 496
69 Varying symbols and lines in plots ........................................................................ 498
70 Text ...................................................................................................................... 502
71 Simple Phreeqc looping ........................................................................................ 504
72 Phreeqc mineral species......................................................................................... 508
Species plots ...................................................................................................................... 510
73 Cd speciation vs pH (species plot)......................................................................... 512
74 Cd speciation vs pH (log species plot)................................................................... 514
75 U species plot (oxidizing) ...................................................................................... 516
76 U species plot (reducing)....................................................................................... 518
77 Carbon speciation vs pH....................................................................................... 520
78 CD-MUSIC: As(V) surface speciation on goethite................................................ 522
79 Test plot output formats ....................................................................................... 526
Fitting models to data ....................................................................................................... 528
80 Langmuir isotherm (1).......................................................................................... 530
81 Langmuir isotherm (n).......................................................................................... 534
82 Langmuir isotherm (pre-processor) ....................................................................... 540
83 Ni sorption by goethite ......................................................................................... 544
84 As(V) sorption on hydrous ferric oxide ................................................................. 548
Contour plots.................................................................................................................... 551
85 Contour two metals at three resolutions................................................................ 552
86 Contour Fe solubility as a function of Eh-pH ....................................................... 556

16 THE WATEQ4F.DAT DATABASE .................................................................... 559

References ......................................................................................................................... 593
Acknowledgements............................................................................................................ 595
Appendix 1. Glossary of terms........................................................................................... 597
Appendix 2. Thermodynamic databases ............................................................................ 599
Appendix 3. Symbol numbers and names.......................................................................... 612
 xv

Appendix 4. The Standard and Latin-1 character sets ....................................................... 616

xvi PhreePlot Guide
 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, 2013). Phreeqc is a popular and freely-available program 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. In short, it is an excellent geochemical calculator.
Phreeqc originally did not include any charting options or any mechanism for repeating
blocks of calculations with a DO ... ENDDO-type structure. It was these two missing features
that led to the development of PhreePlot.
An early fork of Phreeqc, Phreeqc for Windows (Post, 2011) incorporated some simple
charting and this has been extended and is now fully incorporated in the latest Windows ver-
sion of Phreeqc (Version 3). Phreeqc is also now available as a modular version as iPhreeqc
(Charlton and Parkhurst, 2011). This includes most of the functionality of the batch version
and means that Phreeqc can be incorporated into programs written in C++, Fortran as well as
in interpreted languages such as Python and R (there is a ‘phreeqc’ package). It is also availa-
ble as a Windows COM server and so can be linked to spreadsheets and databases. These
options allow fine-grained programming giving the developer a large degree of control over
the calculations made. These programming languages also usually have access to libraries of
other useful functions to facilitate programming.
So what does PhreePlot do? PhreePlot sits on top of Phreeqc and makes it relatively straight-
forward to do certain kinds of repetitive Phreeqc calculations, the type of calculations that are
often needed to make a plot. It does this while maintaining the basic structure of Phreeqc
input files. PhreePlot uses tags placed within the Phreeqc input files to identify places where
substitutions are to be made and has several mechanisms to control the values substituted and
the looping done. It also contains software for generating Postscript plot files. If Ghostscript
is installed then automatic conversion to pdf, png, jpg, ai, eps and epsi formats is possible.
With this basic functionality, PhreePlot can be used to generate predominance diagrams, con-
tour plots, and to fit observations to Phreeqc models.
One of the motivations for developing PhreePlot was to develop the ability to calculate pre-
dominance and mineral stability diagrams, often known as Eh-pH or pe-pH diagrams, based
on a full chemical speciation. This numerical approach is different from the ‘equation-based’
approach typically found in textbooks and employed in 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
using the same database.
The intellectual ‘penalty’ with this approach 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 analytical approach.
2 PhreePlot Guide

We have developed two ways of constructing predominance diagrams: the ‘grid’ approach sim-
ply calculates the speciation at all points on a grid and while the ‘hunt and track’ attempts to
track the boundaries between predominant fields. This approach usually requires considerably
fewer speciation calculations than the ‘grid’ approach to produce a diagram of equivalent qual-
ity but it makes the assumption that all fields are interconnected and can be reached in some
way by tracking along their boundaries. 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 also makes use of its looping capability to fit chemical models to data. This can be
used, for example, to derive log K values from experimental data.
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, GIMP, etc. As of February 2018, Ghostscript is optionally included in the
PhreePlot distribution and if selected to be installed, does not need to be separately installed.
Inkscape is currently probably the best free vector graphics editor capable of editing native
Postscript text.

1.2 WHAT PHREEPLOT DOES NOT DO

The iteration scheme available in PhreePlot is quite limited and follows a fixed format: once
through zero or more ‘initialization’ or pre-loop simulations and then a four-loop iteration
scheme (x, y, z and character). If something else is wanted, then this will have to be pro-
grammed specifically using the iPhreeqc module as mentioned above (Müller et al., 2011).
PhreePlot leaves getting the geochemistry right and the necessary output produced up to the
user. You will have to be reasonably proficient with Phreeqc before attempting to use
PhreePlot. We provide many demos to help get you started.
The plotting is hopefully of a high quality but the types of plots produced are rather limited. If
more sophisticated plots are wanted, then some other plotting program must be used. There
are many. Some of these such as R, Python, Matlab and Mathematica allow external pro-
grams to be run and so could still use PhreePlot to generate the data with all the communica-
tions being done via files.
The interface to PhreePlot is via a console or command prompt. There is no GUI. You will
need to use a text editor to edit the input files.

1.3 WHAT YOU NEED TO KNOW BEFORE USING PHREEPLOT

PhreePlot currently runs on the Windows operating system. It contains iPhreeqc, an embed-
ded version 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 main ‘selected output’ file (number 0). 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(s). If you are not, follow the docu-

1.Thanks to Hans Meeussen for pointing this out.

 Introduction 3

mentation 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(s), some knowledge of BASIC programming is useful. A careful study of the demo exam-
ples provided here should give an introduction to this and will provide example of the link to
PhreePlot.

1.4 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
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 can be downloaded from http://www.phreeplot.org. The file-
name for the Windows installer should have the format, setup-pp-xxxxx-yymmdd-zzzz.exe
where xxxxx is the target system (Win32 or x64), yymmdd is the date of the PhreePlot build and
zzzz is the Phreeqc build 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. 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 straightfor-
ward manner. The banner sent to the screen and log file will indicate the version of PhreePlot
actually being used.
The installer should be executed and PhreePlot installed to your preferred directory (called a
‘folder’ in Windows parlance). The default directory is a PhreePlot sub-directory in your
application data directory. This can be changed during the initial installation (but not when
PhreePlot is updated on top of an existing installation).

There are also options during installation to (i) Associate ppi files with PhreePlot; (ii) Install
Ghostscript, and (iii) Add path to the PATH variable. All three options are recommended but
can be skipped here and manually selected later if desired.
The installation will create a series 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.
6 PhreePlot Guide

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.set any 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.pdf This 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 recom-
 Installation 7

mended, then double clicking a ppi file in Windows Explorer or similar will automatically
execute it with PhreePlot. This is the easiest way to run PhreePlot as there is no GUI.
Spaces in input filenames should work but if in doubt, enclose the filename in quotes (or pref-
erably, avoid!). The search path for the input file follows the normal operating system conven-
tions although as with most PhreePlot searches, PhreePlot will also search the system
directory. In 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. 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.
Installing PhreePlot under Windows requires Administrator rights. You will be asked to
accept the installation.
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 Administrator privileges to run but will need
permission to ‘Read & execute’ (set under the Security tab of the file’s properties).

2.1.2 Mac OS X machines

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

2.2 CHECKING FOR UPDATES

The latest version will always be available for download from the PhreePlot website,
www.phreeplot.org. If the keyword, checkForUpdate is set to TRUE, then PhreePlot will auto-
matically check the server to see if a more recent version is available. This uses the wget pro-
gram. The second parameter for the checkForUpdate keyword sets the minimum time gap (in
days) between checking. Setting this to 1 means that the server will be checked once every day
whereas setting it to 0 will mean that the server will be checked every time PhreePlot is exe-
cuted.

2.3 CHANGING THE CONSOLE APPEARANCE

The default appearance of the console is white text on a black background. If you want to
change this, right click on an existing console and select Defaults. This gives the option of
changing the default window size and position, the text font and the foreground and back-
ground colours, e.g. to black text on a white background.
These settings should become the default for all new console windows. If only a temporary
change is required, use the console Properties dialogs instead.