i

!"#$

&

.

%'

%'

-/

-/

#+%&,

%&

%

%&

%

%&

'%

'%

'%

'%

'%&

'%&

'%&

%

%

%(

%(

%)'

%)'

%&&

%&&

%&&

&

&

&

'

#*

#

#+

-,

-/

-/&

-/

%0

&

'

)

(

#*

#

%

&%

%&

),

&

PhreePlot

Creating graphical output with Phreeqc

David G Kinniburghhttp://www.phreeplot.org

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

June 2011

Last updated April 19, 2018

http://www.phreeplot.org

ii PhreePlot Guide

iii

Table of contents

1 INTRODUCTION ............................................................................................. 11.1 What does PhreePlot do?............................................................................ 11.2 What you need to know before using PhreePlot ......................................... 21.3 Navigating this document .......................................................................... 2

2 INSTALLATION................................................................................................ 52.1 Installing PhreePlot .................................................................................... 5

2.1.1 Windows .............................................................................................. 52.1.2 Windows Vista and Windows 7 ........................................................... 62.1.3 Linux .................................................................................................... 62.1.4 Mac OS X machines ............................................................................. 6

2.2 Checking for updates ................................................................................. 62.3 Changing the console appearance............................................................... 62.4 Installing GPL Ghostscript and GSview..................................................... 72.5 Setting the file paths, environment variables and permissions..................... 8

2.5.1 Ghostscript ........................................................................................... 8 Installing Ghostscript 9.16 and later.................................................... 8

2.5.2 Differences between different versions of Ghostscript ........................... 82.5.3 Launching PhreePlot from Windows Explorer or similar ...................... 82.5.4 Specifying the input file name on the command line ............................ 82.5.5 Specifying input and output filenames in PhreePlot input files ............. 82.5.6 Setting the PhreePlot environment variable .......................................... 92.5.7 Search path for files .............................................................................. 92.5.8 Ensuring that the correct databases are found ....................................... 9

2.6 Other useful software ............................................................................... 102.7 Trouble-shooting ..................................................................................... 10

File conversions ................................................................................. 10 Problem and bug reporting................................................................ 11

3 GETTING STARTED....................................................................................... 133.1 The command line interface and batch processing ................................... 133.2 Running the demo examples .................................................................... 133.3 The pp.log file........................................................................................ 143.4 Examining the results of the run............................................................... 153.5 Making a working directory ..................................................................... 153.6 Getting familiar with the options ............................................................. 163.7 Using batch files to run a set of runs......................................................... 16

4 PHREEQC BASICS .......................................................................................... 174.1 Online Phreeqc documentation................................................................ 174.2 How Phreeqc interacts with PhreePlot ..................................................... 174.3 Thermodynamic databases ....................................................................... 18

iv PhreePlot Guide

4.4 Types of output produced by Phreeqc ..................................................... 184.5 The SELECTED_OUTPUT and the USER_PUNCH data blocks ............................... 19

4.5.1 The SELECTED_OUTPUT filename and forcing the file to be written ......... 204.5.2 Scope of Phreeqc keywords ................................................................ 204.5.3 What is sent to the SELECTED_OUTPUT file? ............................................ 21

4.6 Setting up the SELECTED_OUTPUT file for input to PhreePlot ....................... 224.6.1 Possibilities for looping of Phreeqc input files .................................... 22

Predominance plots .......................................................................... 23 Data-led calculations......................................................................... 24 Custom plots .................................................................................... 25 Knowing which minerals might form using the given database ......... 27

4.6.2 Setting up a loop file .......................................................................... 274.7 Running Phreeqc without any plotting .................................................... 284.8 Include files ............................................................................................. 29

4.8.1 Use of include files ........................................................................... 294.8.2 Supplied include files ......................................................................... 29

4.9 Using Phreeqcs _RAW and _MODIFY keywords .................................. 29

5 PHREEPLOT INPUT AND OUTPUT FILES ........................................................ 315.1 Input/output files .................................................................................... 31

5.1.1 Use .................................................................................................... 315.1.2 Difference in execution of input files between PhreePlot and Phreeqc 31

5.2 Input files ................................................................................................ 325.2.1 Different types of input file ................................................................ 325.2.2 Structure of the main input files ......................................................... 335.2.3 Exceptions to the latest keyword definition overrides earlier ones rule ...

345.2.4 The colour dictionaries and other files ............................................... 345.2.5 Format of all input files ...................................................................... 34

Physical and logical lines ................................................................... 34 Specifying keyword-value pairs and keyword-lists ............................. 35 Format of keywords and their associated values................................. 35

5.2.6 Data separators and parsing input files ............................................... 365.2.7 Case sensitivity of input ..................................................................... 375.2.8 Reporting of errors in input files ........................................................ 37

5.3 Tags......................................................................................................... 375.3.1 What are tags used for? ...................................................................... 375.3.2 Rules for choosing tag names ............................................................. 385.3.3 Tag expressions .................................................................................. 385.3.4 Numeric tag expressions and available functions ................................ 385.3.5 Tags for character variables ................................................................ 395.3.6 System tags ........................................................................................ 395.3.7 User-defined tags ............................................................................... 405.3.8 The scope of tags, their initial values and their order of evaluation ..... 415.3.9 Examples of the use of tags ................................................................. 42

5.4 Output files ............................................................................................. 435.4.1 Output files produced ........................................................................ 445.4.2 The logical switches ........................................................................... 455.4.3 log file (log) ..................................................................................... 465.4.4 out file (out) ..................................................................................... 465.4.5 track file (trk) .................................................................................. 47

v

5.4.6 points file (pts) ................................................................................. 47 Predominance plot calculations (ht1 only)......................................... 47 Other calculations ............................................................................. 47

5.4.7 vectors file (vec) ................................................................................ 485.4.8 polygon file (pol) .............................................................................. 485.4.9 labels file (labelFile) .......................................................................... 495.4.10 Other output files ............................................................................... 50

5.5 Inserting plot files into Microsoft Word, Powerpoint and other software . 505.6 Speed of computations and plotting......................................................... 51

6 RUNNING PHREEPLOT ................................................................................. 536.1 Conventions for data input ...................................................................... 53

6.1.1 Types of variables ............................................................................... 536.1.2 Phreeqc notation for chemical formulae ............................................. 53

6.2 PhreePlot Looping ................................................................................... 546.2.1 Loop variables and their use ................................................................ 546.2.2 Looping over a list of character variables ............................................. 556.2.3 An example of the use of various looping mechanisms ........................ 55

Using the tag....................................................................... 55 Using the tag ......................................................................... 57 Using a loop file ................................................................................ 57 Using the simulate calculationMethod............................................. 57 Looping over two variables ................................................................ 58

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

Introduction...................................................................................... 59 Basic structure of a multi-simulation Phreeqc input file..................... 60

6.2.5 Dynamic switching between Phreeqc models (code) ........................... 626.2.6 Defining the expected output in the selected output file ..................... 626.2.7 Timing execution ............................................................................... 62

6.3 Possible types of calculations and plots ..................................................... 636.4 Preparing the SELECTED OUTPUT file................................................ 63

6.4.1 Normal behaviour .............................................................................. 636.4.2 The use of the headings identifier ..................................................... 64

Controlling the plotting of individual columns.................................. 65 Use of labels in a custom plot and the minimum text size.................. 66

6.5 Debugging ............................................................................................... 666.5.1 Types of problem ............................................................................... 666.5.2 Checking the return status of a Phreeqc run ........................................ 676.5.3 General approach to debugging .......................................................... 676.5.4 Using the debug keyword .................................................................... 686.5.5 The most common reason for a failure to converge ............................. 696.5.6 Changing Phreeqcs convergence parameters ...................................... 71

6.6 Interrupting execution and changing keyword values ............................... 716.7 Running the standard Phreeqc examples .................................................. 72

6.7.1 Going round for just one iteration ...................................................... 72

7 PLOTTING BASICS......................................................................................... 737.1 Introduction............................................................................................. 737.2 Types of plot ............................................................................................ 737.3 Summary of basic plotting........................................................................ 73

vi PhreePlot Guide

7.3.1 Introduction ...................................................................................... 737.3.2 Setting up the plotting area ................................................................ 737.3.3 Setting up the axes scales, tick marks and grid lines ............................ 747.3.4 Axis numbering and annotation ......................................................... 757.3.5 Adding fills, lines and points .............................................................. 75

7.4 Controlling the style of lines and points (symbols) in Custom plots......... 767.4.1 The default style for lines and points (symbols) .................................. 767.4.2 Lines .................................................................................................. 77

Line styles ......................................................................................... 77 Automatic colouring ......................................................................... 78

7.4.3 Points (symbols) ................................................................................ 787.4.4 Order of plotting of lines and points (symbols) .................................. 79

7.5 Labelling plots ......................................................................................... 797.5.1 Label names and label position ........................................................... 797.5.2 Overriding calculated label positions and angles ................................. 807.5.3 Legend ............................................................................................... 80

7.6 Inputting text strings ............................................................................... 817.6.1 Available fonts and character sizes ...................................................... 817.6.2 Available characters ............................................................................ 827.6.3 Text enhancements (bold, italic, subscript, superscript) and Greek charac-

ters 827.6.4 Accented and other foreign characters - the Latin-1 encoding .......... 847.6.5 Non-printing characters ..................................................................... 857.6.6 Justification ........................................................................................ 857.6.7 Angle ................................................................................................. 85

7.7 Special PhreePlot variables or tags............................................................ 857.7.1 Available tags ..................................................................................... 85

7.8 Axis scaling .............................................................................................. 857.8.1 Auto or user-defined axis scaling ........................................................ 857.8.2 Secondary y axis (the 2y axis) ............................................................. 86

7.9 Controlling the properties of text, symbols, polygon fills and lines .......... 867.9.1 Principles ........................................................................................... 867.9.2 The colour palette .............................................................................. 887.9.3 Automatic or explicit ......................................................................... 887.9.4 The colour dictionaries ...................................................................... 89

Fill colours ........................................................................................ 89 Line colours and auto line colouring ................................................. 89 Point colours..................................................................................... 91 Filled symbols with a different rim colour ......................................... 91

7.9.5 Directories for the colour dictionaries ................................................ 927.10 Labelling.................................................................................................. 92

7.10.1 Predominance plots ........................................................................... 927.10.2 Contour plots .................................................................................... 927.10.3 Custom plots ..................................................................................... 92

7.11 Replotting without recalculating.............................................................. 937.11.1 The replot option ............................................................................. 937.11.2 The reprocess and replot option for predominance plots .................. 94

7.12 Adding extra lines, symbols and text ........................................................ 947.12.1 Lines and symbols .............................................................................. 957.12.2 Text ................................................................................................... 95

............................................................................................. 97

vii

or ............................................................................ 98 ............................................................................................ 98 ................................................................................... 98

7.12.3 Formatting numbers in plots varying the number of significant figures displayed 98

7.12.4 Other changes to a plot ...................................................................... 99

8 PREDOMINANCE PLOTS .............................................................................. 1018.1 setting up a file to calculate a predominance diagram ............................. 101

8.1.1 The grid and ht1 approaches ........................................................ 101 Grid approach ................................................................................. 101 Hunt and track approach............................................................... 102

8.1.2 Using the ht1.inc code to return the dominant species .................... 1048.1.3 Optimising the calculation efficiency ................................................ 1058.1.4 Predominance vs mineral stability diagrams ...................................... 1058.1.5 Using ht1minerals.inc to determine the minerals present ............... 105

8.2 The grid approach................................................................................ 1068.3 The Hunt and track approach .............................................................. 107

8.3.1 Strategy ............................................................................................ 1078.3.2 Details of the hunt and track algorithm .......................................... 107

Applying the concepts of hunting and tracking at the practical level 107 Definitions of 'predominance' and mineral stability ........................ 109

8.3.3 Failure of the hunt and track approach ........................................... 1108.4 Feasible domains and the preparation of Eh (pe) -pH diagrams.............. 110

8.4.1 General principles ............................................................................. 1108.4.2 Domain tags - avoiding speciation calculations ................................. 1118.4.3 Speciation failure when there is not enough reactant present ............ 112

8.5 Choice of the resolution of the plot........................................................ 1128.6 Monitoring the progress of a hunt and track run .................................. 1138.7 Plotting and Replotting.......................................................................... 1148.8 Modifying the appearance of predominance plots .................................. 1148.9 Adding lines and points to a predominance plot..................................... 1158.10 Controlling the labelling of plots and the plotting of fields..................... 1158.11 Why do I not see methane gas when using llnl.dat?.............................. 1178.12 Failure to complete a predominance diagram ......................................... 117

9 CONTOUR PLOTS........................................................................................ 1199.1 What are contour plots? ......................................................................... 1199.2 Implementation ..................................................................................... 119

9.2.1 Generating the contour data ............................................................. 1199.2.2 Choosing the contour levels .............................................................. 1209.2.3 Types of contour plot ....................................................................... 1209.2.4 Changing the appearance of the contour lines. ................................. 1219.2.5 Colouring the plot ............................................................................ 1219.2.6 Labels and Legend ............................................................................ 1229.2.7 Flow of data ..................................................................................... 1229.2.8 What if Phreeqc fails? ....................................................................... 122

9.3 A simple example ................................................................................... 1239.4 Some details of the data processing......................................................... 125

9.4.1 Algorithm ......................................................................................... 1259.4.2 Problematic cases .............................................................................. 126

viii PhreePlot Guide

9.5 Modifying the appearance of the plot .................................................... 1279.6 Refining a plot replotting without recalculating.................................. 129

9.6.1 Where to start? ................................................................................. 1299.6.2 Smoothing the z-data ....................................................................... 130

9.7 Overlapping or misplaced label.............................................................. 1309.8 What happens if Phreeqc fails during contouring calculations? .............. 130

10 CUSTOM PLOTS .......................................................................................... 13110.1 Overview ............................................................................................... 13110.2 Preparation of the input file................................................................... 131

10.2.1 Introduction .................................................................................... 13110.2.2 Controlling the scope of custom plots .............................................. 132

10.3 Simple looping ...................................................................................... 13210.4 Calculating speciation on a 2-D grid ..................................................... 13310.5 Modifying the appearance of custom plots............................................. 133

10.5.1 Overview ......................................................................................... 13310.5.2 Customising the plot ....................................................................... 134

11 SPECIES PLOTS ............................................................................................ 13711.1 What is special about a species plot?..................................................... 13711.2 Modifying the appearance of species plots.............................................. 13911.3 Adding other variables to a species plot.................................................. 140

12 FITTING AND SIMULATIONS........................................................................ 14112.1 Introduction .......................................................................................... 14112.2 Fitting is special ..................................................................................... 14212.3 Approach to fitting ................................................................................ 14212.4 Practical Setup....................................................................................... 143

12.4.1 Approach ......................................................................................... 14312.4.2 Flow of data and information during fitting ..................................... 14512.4.3 The parameters ................................................................................ 14612.4.4 Variables .......................................................................................... 14712.4.5 Passing the fitted values from Phreeqc to PhreePlot: preparing the input

file 148 One pass to generate a single data value .......................................... 148 One pass to generate all data values................................................. 148 Global optimization - switching models.......................................... 149

12.4.6 Data file ........................................................................................... 15012.5 The optimization routines ..................................................................... 152

12.5.1 Choice of fit algorithm ..................................................................... 15212.5.2 Scaling of parameters ....................................................................... 15212.5.3 Constrained optimization ................................................................ 15212.5.4 Control parameters .......................................................................... 152

Finite difference step size (nlls only).............................................. 154 Convergence criterion ..................................................................... 154 Step size .......................................................................................... 154 Maximum iterations ....................................................................... 154 Weighting method.......................................................................... 154

12.6 Preparing an input file ........................................................................... 15512.6.1 Simple example ................................................................................ 15512.6.2 Automatic updating of parameter values in an input file .................. 156

ix

12.7 Forcing relations between parameter values ............................................ 15612.8 Output files............................................................................................ 15612.9 Response in the event of a failure of Phreeqc to converge ....................... 15712.10 Plotting the results of the fitting............................................................. 157

12.10.1Plots of observed and calculated results ............................................ 15712.10.2Contour plot of the residual sum of squares ..................................... 157

12.11 Simulations ............................................................................................ 15912.12 Root finding solving equations, adding constraints.............................. 159

13 THE INPUT FILE PRE-PROCESSOR................................................................ 16313.1 Use of the pre-processor ......................................................................... 163

14 KEYWORDS ................................................................................................. 16514.1 Summary of available keywords.............................................................. 16514.2 Conventions........................................................................................... 16814.3 Keyword description .............................................................................. 169

ai..................................................................................................................169all.................................................................................................................169axisLineColor...............................................................................................170axisLineWidth .............................................................................................170axisNumberColor ........................................................................................170axisNumberSize ...........................................................................................171axisTitleColor ..............................................................................................171axisTitleSize .................................................................................................171backgroundColor.........................................................................................171beep .............................................................................................................172blockRangeColumn .....................................................................................172calculationMethod .......................................................................................173calculationType ...........................................................................................174changeColor ................................................................................................174characterTags ...............................................................................................175checkForUpdate...........................................................................................176colorModel ..................................................................................................176contourDashesPerInch.................................................................................177contourFillColor ..........................................................................................177contourLabelColor.......................................................................................178contourLabelFigs .........................................................................................178contourLabelFont ........................................................................................178contourLabelSize..........................................................................................179contourLineColor ........................................................................................179contourLineType .........................................................................................179contourLineWidth.......................................................................................180contourOptions ...........................................................................................180contours.......................................................................................................181contourShiftLabel ........................................................................................182contourZvariable..........................................................................................184convertLabels ...............................................................................................184customLoopManyPlots ................................................................................185customXcolumn...........................................................................................185dashesPerInch, dashesPerInch2y ..................................................................186database .......................................................................................................186

x PhreePlot Guide

databaseVersion........................................................................................... 187dataFile ....................................................................................................... 187dataSeparators ............................................................................................. 188dateDatabase ............................................................................................... 190debug .......................................................................................................... 190dependentVariableColumnObs ................................................................... 191dependentVariableColumnCalc................................................................... 192domain........................................................................................................ 192dominant .................................................................................................... 193eps............................................................................................................... 193epsi.............................................................................................................. 194extradat ....................................................................................................... 195extraSymbolsLines ....................................................................................... 196extraText ..................................................................................................... 197fillColorDictionary...................................................................................... 199FIT.............................................................................................................. 200fitAdjustableParameters ............................................................................... 200fitConvergenceCriterion.............................................................................. 200fitFiniteDiffStepSize.................................................................................... 201fitLogParameters ......................................................................................... 201fitLowerParameterValues............................................................................. 201fitMaxIterations........................................................................................... 202fitMethod.................................................................................................... 202fitnpt ........................................................................................................... 203fitParameterNames...................................................................................... 203fitParameterValues ...................................................................................... 204fitStepSize ................................................................................................... 204fitUpperParameterValues ............................................................................ 205fitWeightingMethod ................................................................................... 205font ............................................................................................................. 206gridColor..................................................................................................... 208gridDashesPerInch ...................................................................................... 208gridLines ..................................................................................................... 209gridLineType............................................................................................... 209info ............................................................................................................. 210initialValue.................................................................................................. 210jobTitle ....................................................................................................... 211jpg............................................................................................................... 211labelColor.................................................................................................... 212labelEffort ................................................................................................... 212labelFile....................................................................................................... 213labels ........................................................................................................... 213labelSize ...................................................................................................... 214legendBox.................................................................................................... 214legendTitle .................................................................................................. 215legendTextSize ............................................................................................ 215lineColor, lineColor2y................................................................................. 216lineColorDictionary .................................................................................... 216lines, lines2y ................................................................................................ 217lineType, lineType2y................................................................................... 217lineWidth, lineWidth2y .............................................................................. 218

xi

log................................................................................................................218logDepVariable ............................................................................................219logVariableIn ...............................................................................................219loopFile........................................................................................................220loopIndexStartNumber ................................................................................222loopInt.........................................................................................................222loopLogVar..................................................................................................223loopMax ......................................................................................................223loopMin.......................................................................................................223mainLoop ....................................................................................................224mainLoopColumn .......................................................................................225mainspecies ..................................................................................................225minimumAreaForLabeling...........................................................................226minimumYValueForPlotting .......................................................................226missingValue................................................................................................227multipageFile ...............................................................................................227nameSpeciationProgram ..............................................................................228numberOfFitParameters ..............................................................................228numericTags ................................................................................................228omitAccumulate...........................................................................................229onePass ........................................................................................................230out ...............................................................................................................231overlay .........................................................................................................231pageOrientation...........................................................................................233paperSize......................................................................................................233pdf ...............................................................................................................234pdfMaker .....................................................................................................235IPhreePlotVersion........................................................................................235Phreeqc.0.out...............................................................................................236PLOT ..........................................................................................................236plotFactor ....................................................................................................236plotFrequency..............................................................................................237plotOrder.....................................................................................................237plotTitle.......................................................................................................237plotTitleColor..............................................................................................238plotTitleSize ................................................................................................238png ..............................................................................................................238pointColor, pointColor2y............................................................................239points, points2y ...........................................................................................239pointsSameColor .........................................................................................240pointSize, pointSize2y..................................................................................240pointType, pointType2y..............................................................................241pol ...............................................................................................................241post..............................................................................................................242postSize........................................................................................................243ppa...............................................................................................................243pplog ...........................................................................................................243printScreenFrequency ..................................................................................244ps .................................................................................................................244pts................................................................................................................245pxdec ...........................................................................................................245

xii PhreePlot Guide

pxmajor ....................................................................................................... 245pxmax ......................................................................................................... 245pxmin.......................................................................................................... 246pxminor ...................................................................................................... 246pydec, p2ydec.............................................................................................. 246pymajor, p2ymajor ...................................................................................... 247pymax, p2ymax ........................................................................................... 247pymin, p2ymin............................................................................................ 247pyminor, p2yminor ..................................................................................... 248resolution .................................................................................................... 248restartColorSequence................................................................................... 249rimColor ..................................................................................................... 250rimFactor .................................................................................................... 250screen .......................................................................................................... 251selectedOutputFile ...................................................................................... 251selectedOutputLines.................................................................................... 251simplify ....................................................................................................... 253skip ............................................................................................................. 253SPECIATION ............................................................................................ 254speciationProgram....................................................................................... 254speciationProgramVersion........................................................................... 254startTemperature ......................................................................................... 254stopOnFail .................................................................................................. 255tickColor ..................................................................................................... 255tickSize........................................................................................................ 256trackSymbolColor ....................................................................................... 257trackSymbolSize .......................................................................................... 257trk ............................................................................................................... 258units ............................................................................................................ 259unrecognisedKeywordIsFatal ....................................................................... 259updateFitParameters.................................................................................... 259useLabelsFile ............................................................................................... 260useLineColorDictionary .............................................................................. 260vec............................................................................................................... 261weightColumn ............................................................................................ 261writeAllInputFiles........................................................................................ 261writePlaceholder .......................................................................................... 262xaxisLength ................................................................................................. 262xmax ........................................................................................................... 262xmin............................................................................................................ 263xoffset.......................................................................................................... 263xtitle ............................................................................................................ 263yaxisLength ................................................................................................. 264ymax ........................................................................................................... 264ymin............................................................................................................ 264yoffset.......................................................................................................... 264yscale........................................................................................................... 265ytitle, 2ytitle ................................................................................................ 266

15 EXAMPLES ................................................................................................... 267Predominance plots (grid approach)..................................................................................268

xiii

1 Fe-H2O (grid approach) ....................................................................................... 2702 Cu-S-C (island found with grid) ....................................................................... 274

Predominance plots (ht1 approach) .................................................................................. 2773 Fe-H2O (Hunt and track approach) ................................................................... 2784 Fe-H2O: close-up (predominance criterion) ......................................................... 2805 Fe-H2O: close-up (stability criterion) ................................................................... 2826 Fe-H2O (pe scale)................................................................................................. 2847 Fe-H2O (Eh scale) ................................................................................................ 2868 As-O2(g)-H2O...................................................................................................... 2889 As-O2(g)-H2O (sub-dominant) ............................................................................ 29010 Fe-As-C-S............................................................................................................. 29211 Fe-As .................................................................................................................... 29612 Fe-As-Hfo (ht1.inc) .............................................................................................. 29813 Fe-As-Hfo (ht1c.inc) ............................................................................................ 30014 Fe-S-As (without sorption) ................................................................................... 30215 Fe-S-As (low Fe, without surface speciation)......................................................... 30616 Fe-S-As (goethite, CD-MUSIC) ........................................................................... 31017 Fe-As-S (high Fe).................................................................................................. 31418 Fe-CO2-SO4-H2O with sample points ................................................................. 31819 Fe-Ni-S ................................................................................................................ 32220 Fe-Zn-C-H2O (HFO).......................................................................................... 32621 Fe-Zn-C-H2O (HFO).......................................................................................... 33022 Ca-Fe-Na-X-HFO (adsorption and ion exchange)................................................ 33423 Acid mine drainage............................................................................................... 33824 AMD (carbon) ..................................................................................................... 34225 Ca-Mg-Zn-CO3.................................................................................................................................................. 34626 U-CO3...................................................................................................................................................................... 35027 Ca-Mg-CO3 at high T.......................................................................................... 35228 P-Ca-Mg-CO3(aq)................................................................................................ 35429 P-Ca-Mg-CO3 (with solids) .................................................................................. 35630 Mn-CO2-H2O (no minerals)................................................................................ 36031 Mn-H2O (with minerals) ..................................................................................... 36232 Mn-CO2-H2O ..................................................................................................... 36433 Pu-F-H2O ............................................................................................................ 36634 U-C-H2O (wateq4f.dat) ....................................................................................... 36835 U-C-H2O (NAPSI) .............................................................................................. 37036 U-C-H2O (llnl.dat) .............................................................................................. 37237 U-Fe-C-H2O........................................................................................................ 37638 U-Fe-C (risk colours)............................................................................................ 38039 U-H2O (redox state) ............................................................................................ 38440 U-F-P (U) ............................................................................................................ 38641 U-F-P (F) ............................................................................................................. 39042 U-F-P (P) ............................................................................................................. 39243 Cu-S-C (island not found with ht1).................................................................. 39444 Cu-S-C (simplification factor = 1) ........................................................................ 39645 Cu-S-C (simplification factor = 3) ........................................................................ 40046 Cu-EDTA-H2O ................................................................................................... 40447 Ca-F-P-C-H2O .................................................................................................... 40648 Ni-S-C-H2O ........................................................................................................ 40849 Zn-S-C-H2O........................................................................................................ 41250 Cd-S-C-H2O........................................................................................................ 41651 Pb-S-C-P-H2O..................................................................................................... 41852 Sb-S...................................................................................................................... 42253 Se-S ...................................................................................................................... 42654 Clay mineral stability diagram .............................................................................. 428

xiv PhreePlot Guide

Custom plots.....................................................................................................................43155 Gibbsite solubility vs pH....................................................................................... 43256 Acid titration of groundwater (using REACTION) ............................................ 43657 Acid titration of groundwater (using PhreePlot looping) ....................................... 43858 Redox sequence..................................................................................................... 44059 Kds for trace metals as a function of pH............................................................... 44460 Cd speciation vs pH.............................................................................................. 44861 Zn-HFO: %sorption vs pH curves........................................................................ 45262 Zn-HFO: Surface speciation ................................................................................. 45663 As-HFO: reduction in surface area........................................................................ 46064 CD-MUSIC: As(III) adsorption on goethite ......................................................... 46465 CD-MUSIC: As(V) adsorption on goethite .......................................................... 46866 Kinetics of pyrite oxidation ................................................................................... 47267 Kinetics of quartz dissolution ................................................................................ 47668 Symbols and lines ................................................................................................. 47869 Varying symbols and lines in plots ........................................................................ 48070 Text ...................................................................................................................... 48471 Simple Phreeqc looping ........................................................................................ 48672 Phreeqc mineral species......................................................................................... 490

Species plots ......................................................................................................................49273 Cd speciation vs pH (species plot)......................................................................... 49474 Cd speciation vs pH (log species plot)................................................................... 49875 U species plot (oxidizing) ...................................................................................... 50076 U species plot (reducing)....................................................................................... 50277 Carbon speciation vs pH....................................................................................... 50478 CD-MUSIC: As(V) surface speciation on goethite................................................ 50679 Test plot output formats ....................................................................................... 510

Fitting models to data .......................................................................................................51280 Langmuir isotherm (1).......................................................................................... 51481 Langmuir isotherm (n).......................................................................................... 51882 Langmuir isotherm (pre-processor) ....................................................................... 52483 Ni sorption by goethite ......................................................................................... 52884 As(V) sorption on hydrous ferric oxide ................................................................. 532

Contour plots.................................................................................................................... 53585 Contour two metals at three resolutions................................................................ 536

16 THE WATEQ4F.DAT DATABASE.................................................................... 539References .........................................................................................................................573Acknowledgements............................................................................................................575Appendix 1. Glossary of terms...........................................................................................577Appendix 2. Thermodynamic databases ............................................................................579Appendix 3. Symbol numbers and names.......................................................................... 592Appendix 4. The Standard and Latin-1 character sets........................................................ 596

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 Phree-Plot 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) incoporated some simple chart-ing and this has been extended and is now fully incorporated in the latest Windows version of Phreeqc (Version 3). Phreeqc is also now available as a modular version as iPhreeqc (Charl-ton 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 available 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 calcu-lations made. These programming languages also usually have access to libraries of other use-ful 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 maintianing the basic structure of Phreeqcinput 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 Ghostscriptis 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 Geochemists 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 included in the PhreePlot dis-tribution and so does not need to be separately installed.

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 (Mller 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 Phree-Plot. 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-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 Phree-

1.Thanks to Hans Meeussen for pointing this out.

Introduction 3

Plot 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 filename for the Windows installer should have the format, setup-pp-win-yymmdd-zzzz.exewhere 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 PhreePlotactually 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 installation. 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.The following files and directories will be created:

\system\demo\doc

where\system The PhreePlot system directory.

pp.set User-defined initial settings and preferencesoverride.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 andassociated files), one or more ppi files persubdirectory (see the Examples Section)

\docPhreePlot.pdfThis user guidechanges.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 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

http://www.phreeplot.org

6 PhreePlot Guide

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

2.1.2 Mac OS X machines

PhreePlot has been reported to work on Apple Macs 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 you would like to be emailed about updates, send a message to sub-scribe@phreeplot.org with the word 'subscribe' in the Subject line. To unsubscribe, put the word 'unsubscribe' in the Subject line (not case sensitive).

If the keyword, checkForUpdate is set to TRUE, then PhreePlot will automatically check the server to see if a more recent version is available. This uses the wget program. 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 set-ting it to 0 will mean that the server will be checked every time PhreePlot is executed.

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.

2.4 INSTALLING GHOSTSCRIPT AND GSVIEW

PhreePlot now comes wth Ghostscript installed but it is possible to install it yourself in the normal way. If you want to use your installed version, you must point the pdfMaker setting to the appropriate path (see pdfMaker). It is also useful to install a native ps viewer such as

http://sourceforge.net/project/showfiles.php?group_id=1897&package_id=108733http://www.phreeplot.org

Installation 7

GSview or GSView (confusing!).GSview 5.0 is available from Ghostgum Software Pty Ltd at http://pages.cs.wisc.edu/~ghost/gsview/. After downloading, run GSview and under Options|Advanced Configure|Ghost-script DLL enter %PHREEPLOT_PATH%\gsdllc.dll where is either 32 or 64 depend-ing on which version of PhreePlot you have installed. This should point to the folder that contains your pp.exe executable.GSView 6.0, is a separate viewer produced and maintained by Artifex Software Inc, the pro-viders of GPL Ghostscript. GSView 6.0 is available from https://artifex.com/developers-ghostscript-gsview/. It is free to use for non-commercial users. After downloading and install-ing, 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. The distribution contains its own ver-sion of the gsdll.dll file.Despite their similar names, the two viewers are distinct with different development and license conditons. They also have somewhat different interfaces, options and capabilities, e.g. GSview 5.0 view can be configured in different units (mm, inch etc) and has a crosshair to accurately determine x-y coordinates in an image. It also automatically updates the image when a file has been changed without the need to manually reload. GSView 6.0 version does not have these facilities but, for example, will convert ps files to svg format.If installed correctly, typing pp -v

from a console should show some information about the current version of PhreePlot includ-ing its release date, whether the 32- or 64-bit versions is running and whether Ghostscript is installed, and if so, its source and version.Running the demo\test\test.ppi file will indicate whether your Ghostscript setup has been successful. If successful, this should produce ps, pdf, png, eps, epsi and jpg plot files.

2.4.1 Launching PhreePlot from Windows Explorer or similar

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

2.4.2 Specifying the input file name on the command line

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

2.4.3 Specifying input and output filenames in PhreePlot input files

Various file paths can be specified in PhreePlot input files but somewhat stricter requirements than above apply when specifying these file paths. File paths should not contain a + sign even though this is legal in Windows. PhreePlot uses a system shell command to copy various files and your system may interpret an unquoted + sign as the beginning of another file to copy.File paths can in principle contain any characters that are compatible with normal operating system rules (Windows disallows / ? < > \ : * | "). In order to avoid having to escape

http://pages.cs.wisc.edu/~ghost/gsview/http://pages.cs.wisc.edu/~ghost/gsview/http://pages.cs.wisc.edu/~ghost/gsview/https://artifex.com/developers-ghostscript-gsview/https://artifex.com/developers-ghostscript-gsview/

8 PhreePlot Guide

characters, it is wise to also ignore parentheses, brackets and the ampersand. Other characters including the + sign, comma,semi-colon, percent sign and space are best avoided. In other words, keep it simple for an easy life!File paths are not case sensitive in Windows so any mixture of cases will do. However, what-ever is entered is preserved in PhreePlot. PhreePlot itself tends to use lowercase filenames with the exception that chemical elements follow their normal notation.

2.4.4 Setting the PhreePlot environment variable

The environment variable, PHREEPLOT, must be set before PhreePlot will work. This should be set to the PhreePlot directory that you specify during installation, i.e. the root directory con-taining the system, demo and doc directories. In Windows, this could be your AppData direc-tory (default) or a location that you chose during installation such as C:\PhreePlot. Note that there is no trailing backslash.The environment variable, PHREEPLOT_PATH, is also set to the location of the PhreePlot exe-cutable, pp.exe, e.g. C:\Program Files\PhreePlot\.You can check that this has been done correctly by typing set PhreePlot in a console win-dow. This will return the two directories currently set.

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

2.4.5 Search path for files

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

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

2.5 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

http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/http://notepad-plus-plus.org/

Installation 9

large number of file types. The normal Phreeqc installations now come with a file to colour Phreeqc keywords in pqi and ppi files (http://note-pad-plus-plus.org/).

7-zip free file compression utility that is efficient and easy to use (http://www.7-zip.org/).

xplorer2 dual pane Windows Explorer that makes a great way for launching Phree-Plot files and for viewing the graphical and text files produced (plus many of the other things you have to do for file management) (http://zab-kat.com/index.htm).

Able Batch Converter batch conversion of Postscript files to other image formats including autocropping and resizing (http://www.graphicregion.com).

CoPlot Flexible and powerful scientific plotting package (http://www.cohort.com/coplot.html).

R Powerful and well-supported open-source working environment for data processing including flexible, high quality graphics (http://www.r-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 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.6 TROUBLE-SHOOTING

File conversions

File conversions from ps to other formats can be automatically carried out by Ghostscriptunder 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 GSviewway.Once installed correctly, the demo examples should run (see Section 3.2).

Problem and bug reporting

Contact David Kinniburgh (david@phreeplot.org).

http://www.7-zip.org/http://www.7-zip.org/http://www.7-zip.org/http://zabkat.com/index.htmhttp://zabkat.com/index.htmhttp://zabkat.com/index.htmhttp://www.gr