The Geochemist’s Workbench®
Release 11
GWB
Reference
Manual
The Geochemist’s Workbench®
Release 11
GWB
Reference
Manual
Craig M. Bethke
Sharon Yeakel
Aqueous Solutions, LLC
Champaign, Illinois
Printed January 5, 2018
This document © Copyright 2018 by Aqueous Solutions LLC. All rights reserved. Earlier editionscopyright 2000–2017. This document may be reproduced freely to support any licensed use ofthe GWB software package.
Software copyright notice: Programs GSS, Rxn, Act2, Tact, SpecE8, Gtplot, TEdit, React, X1t,X2t, Xtplot, and ChemPlugin © Copyright 1983–2018 by Aqueous Solutions LLC. An unpublishedwork distributed via trade secrecy license. All rights reserved under the copyright laws.
The Geochemist’s Workbench®, ChemPlugin™, We put bugs in our software™, and TheGeochemist’s Spreadsheet™ are a registered trademark and trademarks of Aqueous SolutionsLLC; Microsoft®, MS®, Windows XP®, Windows Vista®, Windows 7® and Windows 8® areregistered trademarks of Microsoft Corporation; PostScript® is a registered trademark of AdobeSystems, Inc. Other products mentioned in this document are identified by the trademarks of theirrespective companies; the authors disclaim responsibility for specifying which marks are ownedby which companies. The software uses zlib © 19952005 JeanLoup Gailly and Mark Adler, andExpat © 19982006 Thai Open Source Center Ltd. and Clark Cooper.
The GWB software was originally developed by the students, staff, and faculty of theHydrogeology Program in the Department of Geology at the University of IllinoisUrbanaChampaign. The package is currently developed and maintained by Aqueous SolutionsLLC at the University of Illinois Research Park.
Address inquiries to
Aqueous Solutions LLC301 North Neil Street, Suite 400Champaign, IL 61820 USA
Warranty: The Aqueous Solutions LLC warrants only that it has the right to convey license to theGWB software. Aqueous Solutions makes no other warranties, express or implied, with respect tothe licensed software and/or associated written documentation. Aqueous Solutions disclaims anyexpress or implied warranties of merchantability, fitness for a particular purpose, andnoninfringement. Aqueous Solutions does not warrant, guarantee, or make any representationsregarding the use, or the results of the use, of the Licensed Software or documentation in termsof correctness, accuracy, reliability, currentness, or otherwise. Aqueous Solutions shall not beliable for any direct, indirect, consequential, or incidental damages (including damages for loss ofprofits, business interruption, loss of business information, and the like) arising out of any claimby Licensee or a third party regarding the use of or inability to use Licensed Software. The entirerisk as to the results and performance of Licensed Software is assumed by the Licensee. SeeLicense Agreement for complete details.
License Agreement: Use of the GWB is subject to the terms of the accompanying LicenseAgreement. Please refer to that Agreement for details.
Cover photo: Salinas de Janubio by Jorg Hackemann.
Contents
Chapter List
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Rxn Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Act2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4 Tact Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5 SpecE8 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6 React Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7 X1t Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
8 X2t Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Appendix: Thermo Datasets . . . . . . . . . . . . . . . . . . . . . . . . 287
Appendix: User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Appendix: Graphics Output . . . . . . . . . . . . . . . . . . . . . . . . . 303
Appendix: Scatter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Appendix: Report Command . . . . . . . . . . . . . . . . . . . . . . . . 317
Appendix: Control Scripts . . . . . . . . . . . . . . . . . . . . . . . . . 333
Appendix: Plugin Feature . . . . . . . . . . . . . . . . . . . . . . . . . 337
Appendix: Multiple Analyses . . . . . . . . . . . . . . . . . . . . . . . . 393
Appendix: Remote Control . . . . . . . . . . . . . . . . . . . . . . . . . 397
Appendix: Units Recognized . . . . . . . . . . . . . . . . . . . . . . . . 403
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
v
vi
Contents
1 Introduction 1
1.1 Command reference . . . . . . . 1
1.2 Appendices . . . . . . . . . . . . 2
2 Rxn Commands 5
2.1 activity . . . . . . . . . . . . . . 5
2.2 add . . . . . . . . . . . . . . . . 5
2.3 alter . . . . . . . . . . . . . . . . 6
2.4 block . . . . . . . . . . . . . . . 6
2.5 chdir . . . . . . . . . . . . . . . . 6
2.6 clear . . . . . . . . . . . . . . . . 7
2.7 clipboard . . . . . . . . . . . . . 7
2.8 couple . . . . . . . . . . . . . . . 7
2.9 data . . . . . . . . . . . . . . . . 7
2.10 decouple . . . . . . . . . . . . . 8
2.11 Eh . . . . . . . . . . . . . . . . . 8
2.12 explain . . . . . . . . . . . . . . 9
2.13 factor . . . . . . . . . . . . . . . 9
2.14 fugacity . . . . . . . . . . . . . . 9
2.15 go . . . . . . . . . . . . . . . . . 10
2.16 help . . . . . . . . . . . . . . . . 10
2.17 history . . . . . . . . . . . . . . . 10
2.18 ionic_strength . . . . . . . . . . 11
2.19 log . . . . . . . . . . . . . . . . . 11
2.20 long . . . . . . . . . . . . . . . . 11
2.21 molality . . . . . . . . . . . . . . 12
2.22 output . . . . . . . . . . . . . . . 12
2.23 pause . . . . . . . . . . . . . . . 12
2.24 pe . . . . . . . . . . . . . . . . . 12
2.25 pH . . . . . . . . . . . . . . . . . 13
2.26 polymorphs . . . . . . . . . . . . 13
2.27 pwd . . . . . . . . . . . . . . . . 14
2.28 quit . . . . . . . . . . . . . . . . 14
2.29 ratio . . . . . . . . . . . . . . . . 14
2.30 react . . . . . . . . . . . . . . . . 15
2.31 read . . . . . . . . . . . . . . . . 15
2.32 remove . . . . . . . . . . . . . . 16
2.33 report . . . . . . . . . . . . . . . 16
2.34 reset . . . . . . . . . . . . . . . . 16
2.35 resume . . . . . . . . . . . . . . 17
2.36 reverse . . . . . . . . . . . . . . 17
2.37 save . . . . . . . . . . . . . . . . 17
2.38 script . . . . . . . . . . . . . . . 17
2.39 short . . . . . . . . . . . . . . . 18
2.40 show . . . . . . . . . . . . . . . 18
2.41 sorbed_mass . . . . . . . . . . . 19
2.42 stoich_IS . . . . . . . . . . . . . 19
2.43 suffix . . . . . . . . . . . . . . . 20
2.44 surface_capacitance . . . . . . . 20
2.45 surface_charge . . . . . . . . . . 21
2.46 surface_data . . . . . . . . . . . 21
2.47 surface_potential . . . . . . . . . 22
2.48 swap . . . . . . . . . . . . . . . 22
2.49 system . . . . . . . . . . . . . . 23
2.50 temperature . . . . . . . . . . . 23
2.51 unalter . . . . . . . . . . . . . . 24
2.52 unswap . . . . . . . . . . . . . . 24
2.53 usgovt . . . . . . . . . . . . . . . 25
3 Act2 Commands 27
3.1 activity . . . . . . . . . . . . . . 27
3.2 add . . . . . . . . . . . . . . . . 27
3.3 alter . . . . . . . . . . . . . . . . 28
3.4 background . . . . . . . . . . . . 28
3.5 banner . . . . . . . . . . . . . . 28
3.6 chdir . . . . . . . . . . . . . . . . 29
3.7 clear . . . . . . . . . . . . . . . . 29
3.8 clipboard . . . . . . . . . . . . . 29
vii
Contents
3.9 color_by_sample . . . . . . . . . 29
3.10 couple . . . . . . . . . . . . . . . 30
3.11 custom . . . . . . . . . . . . . . 30
3.12 data . . . . . . . . . . . . . . . . 30
3.13 decouple . . . . . . . . . . . . . 31
3.14 diagram . . . . . . . . . . . . . . 31
3.15 Eh . . . . . . . . . . . . . . . . . 32
3.16 explain . . . . . . . . . . . . . . 32
3.17 extrapolate . . . . . . . . . . . . 32
3.18 font . . . . . . . . . . . . . . . . 33
3.19 fugacity . . . . . . . . . . . . . . 33
3.20 gases . . . . . . . . . . . . . . . 33
3.21 go . . . . . . . . . . . . . . . . . 34
3.22 grep . . . . . . . . . . . . . . . . 34
3.23 gridlines . . . . . . . . . . . . . . 34
3.24 help . . . . . . . . . . . . . . . . 35
3.25 history . . . . . . . . . . . . . . . 35
3.26 labels . . . . . . . . . . . . . . . 35
3.27 legend . . . . . . . . . . . . . . . 35
3.28 line . . . . . . . . . . . . . . . . 36
3.29 log . . . . . . . . . . . . . . . . . 36
3.30 minerals . . . . . . . . . . . . . . 37
3.31 mosaic_bounds . . . . . . . . . 37
3.32 mosaic_labels . . . . . . . . . . 37
3.33 paper . . . . . . . . . . . . . . . 38
3.34 pause . . . . . . . . . . . . . . . 39
3.35 pe . . . . . . . . . . . . . . . . . 39
3.36 pH . . . . . . . . . . . . . . . . . 39
3.37 polymorphs . . . . . . . . . . . . 40
3.38 pressure . . . . . . . . . . . . . 40
3.39 print . . . . . . . . . . . . . . . . 40
3.40 pwd . . . . . . . . . . . . . . . . 41
3.41 quit . . . . . . . . . . . . . . . . 41
3.42 ratio . . . . . . . . . . . . . . . . 41
3.43 read . . . . . . . . . . . . . . . . 41
3.44 remove . . . . . . . . . . . . . . 42
3.45 reset . . . . . . . . . . . . . . . . 42
3.46 resume . . . . . . . . . . . . . . 42
3.47 save . . . . . . . . . . . . . . . . 43
3.48 scatter . . . . . . . . . . . . . . . 43
3.49 script . . . . . . . . . . . . . . . 43
3.50 show . . . . . . . . . . . . . . . 44
3.51 speciate . . . . . . . . . . . . . . 45
3.52 suffix . . . . . . . . . . . . . . . 45
3.53 suppress . . . . . . . . . . . . . 46
3.54 swap . . . . . . . . . . . . . . . 46
3.55 system . . . . . . . . . . . . . . 47
3.56 temperature . . . . . . . . . . . 47
3.57 title . . . . . . . . . . . . . . . . 47
3.58 trace . . . . . . . . . . . . . . . . 48
3.59 unalter . . . . . . . . . . . . . . 48
3.60 unspeciate . . . . . . . . . . . . 49
3.61 unsuppress . . . . . . . . . . . . 49
3.62 unswap . . . . . . . . . . . . . . 50
3.63 usgovt . . . . . . . . . . . . . . . 50
3.64 water_limits . . . . . . . . . . . . 50
3.65 xaxis . . . . . . . . . . . . . . . 51
3.66 yaxis . . . . . . . . . . . . . . . 51
4 Tact Commands 53
4.1 activity . . . . . . . . . . . . . . 53
4.2 add . . . . . . . . . . . . . . . . 53
4.3 alter . . . . . . . . . . . . . . . . 54
4.4 background . . . . . . . . . . . . 54
4.5 banner . . . . . . . . . . . . . . 54
4.6 chdir . . . . . . . . . . . . . . . . 55
4.7 clear . . . . . . . . . . . . . . . . 55
4.8 clipboard . . . . . . . . . . . . . 55
4.9 color_by_sample . . . . . . . . . 55
4.10 couple . . . . . . . . . . . . . . . 56
4.11 custom . . . . . . . . . . . . . . 56
4.12 data . . . . . . . . . . . . . . . . 56
4.13 decouple . . . . . . . . . . . . . 57
4.14 diagram . . . . . . . . . . . . . . 57
4.15 Eh . . . . . . . . . . . . . . . . . 58
4.16 explain . . . . . . . . . . . . . . 58
4.17 extrapolate . . . . . . . . . . . . 58
4.18 font . . . . . . . . . . . . . . . . 59
4.19 fugacity . . . . . . . . . . . . . . 59
4.20 gases . . . . . . . . . . . . . . . 59
4.21 go . . . . . . . . . . . . . . . . . 60
4.22 grep . . . . . . . . . . . . . . . . 60
4.23 gridlines . . . . . . . . . . . . . . 60
4.24 help . . . . . . . . . . . . . . . . 61
4.25 history . . . . . . . . . . . . . . . 61
4.26 labels . . . . . . . . . . . . . . . 61
4.27 legend . . . . . . . . . . . . . . . 61
4.28 line . . . . . . . . . . . . . . . . 62
4.29 log . . . . . . . . . . . . . . . . . 62
viii
Contents
4.30 minerals . . . . . . . . . . . . . . 63
4.31 mosaic_bounds . . . . . . . . . 63
4.32 mosaic_labels . . . . . . . . . . 63
4.33 paper . . . . . . . . . . . . . . . 64
4.34 pause . . . . . . . . . . . . . . . 64
4.35 pe . . . . . . . . . . . . . . . . . 64
4.36 pH . . . . . . . . . . . . . . . . . 65
4.37 polymorphs . . . . . . . . . . . . 65
4.38 pressure . . . . . . . . . . . . . 65
4.39 print . . . . . . . . . . . . . . . . 66
4.40 pwd . . . . . . . . . . . . . . . . 66
4.41 quit . . . . . . . . . . . . . . . . 66
4.42 ratio . . . . . . . . . . . . . . . . 67
4.43 read . . . . . . . . . . . . . . . . 67
4.44 remove . . . . . . . . . . . . . . 67
4.45 reset . . . . . . . . . . . . . . . . 68
4.46 resume . . . . . . . . . . . . . . 68
4.47 save . . . . . . . . . . . . . . . . 68
4.48 scatter . . . . . . . . . . . . . . . 68
4.49 script . . . . . . . . . . . . . . . 69
4.50 show . . . . . . . . . . . . . . . 69
4.51 speciate . . . . . . . . . . . . . . 70
4.52 suffix . . . . . . . . . . . . . . . 70
4.53 suppress . . . . . . . . . . . . . 71
4.54 swap . . . . . . . . . . . . . . . 71
4.55 system . . . . . . . . . . . . . . 72
4.56 title . . . . . . . . . . . . . . . . 72
4.57 trace . . . . . . . . . . . . . . . . 73
4.58 unalter . . . . . . . . . . . . . . 73
4.59 unspeciate . . . . . . . . . . . . 73
4.60 unsuppress . . . . . . . . . . . . 74
4.61 unswap . . . . . . . . . . . . . . 74
4.62 usgovt . . . . . . . . . . . . . . . 75
4.63 water_limits . . . . . . . . . . . . 75
4.64 xaxis . . . . . . . . . . . . . . . 75
4.65 yaxis . . . . . . . . . . . . . . . 76
5 SpecE8 Commands 77
5.1 <unit> . . . . . . . . . . . . . . . 77
5.2 activity . . . . . . . . . . . . . . 78
5.3 add . . . . . . . . . . . . . . . . 79
5.4 alkalinity . . . . . . . . . . . . . 79
5.5 alter . . . . . . . . . . . . . . . . 79
5.6 balance . . . . . . . . . . . . . . 80
5.7 chdir . . . . . . . . . . . . . . . . 80
5.8 clear . . . . . . . . . . . . . . . . 80
5.9 clipboard . . . . . . . . . . . . . 80
5.10 conductivity . . . . . . . . . . . . 81
5.11 couple . . . . . . . . . . . . . . . 81
5.12 data . . . . . . . . . . . . . . . . 81
5.13 debyehuckel . . . . . . . . . . . 82
5.14 decouple . . . . . . . . . . . . . 82
5.15 density . . . . . . . . . . . . . . 82
5.16 dual_porosity . . . . . . . . . . . 83
5.17 Eh . . . . . . . . . . . . . . . . . 84
5.18 epsilon . . . . . . . . . . . . . . 84
5.19 exchange_capacity . . . . . . . 84
5.20 explain . . . . . . . . . . . . . . 85
5.21 extrapolate . . . . . . . . . . . . 85
5.22 fugacity . . . . . . . . . . . . . . 86
5.23 go . . . . . . . . . . . . . . . . . 86
5.24 grep . . . . . . . . . . . . . . . . 86
5.25 gtplot . . . . . . . . . . . . . . . 87
5.26 hmw . . . . . . . . . . . . . . . 87
5.27 help . . . . . . . . . . . . . . . . 87
5.28 history . . . . . . . . . . . . . . . 87
5.29 inert . . . . . . . . . . . . . . . . 88
5.30 itmax . . . . . . . . . . . . . . . 88
5.31 Kd . . . . . . . . . . . . . . . . . 88
5.32 log . . . . . . . . . . . . . . . . . 89
5.33 mobility . . . . . . . . . . . . . . 89
5.34 pause . . . . . . . . . . . . . . . 90
5.35 pe . . . . . . . . . . . . . . . . . 90
5.36 permeability . . . . . . . . . . . 90
5.37 pH . . . . . . . . . . . . . . . . . 91
5.38 phrqpitz . . . . . . . . . . . . . . 92
5.39 pitz_dgamma . . . . . . . . . . . 92
5.40 pitz_precon . . . . . . . . . . . . 92
5.41 pitz_relax . . . . . . . . . . . . . 93
5.42 pitzer . . . . . . . . . . . . . . . 93
5.43 plot . . . . . . . . . . . . . . . . 93
5.44 polymorphs . . . . . . . . . . . . 94
5.45 porosity . . . . . . . . . . . . . . 94
5.46 print . . . . . . . . . . . . . . . . 94
5.47 pwd . . . . . . . . . . . . . . . . 95
5.48 quit . . . . . . . . . . . . . . . . 95
5.49 ratio . . . . . . . . . . . . . . . . 96
5.50 read . . . . . . . . . . . . . . . . 96
5.51 remove . . . . . . . . . . . . . . 96
ix
Contents
5.52 report . . . . . . . . . . . . . . . 97
5.53 reset . . . . . . . . . . . . . . . . 97
5.54 resume . . . . . . . . . . . . . . 97
5.55 save . . . . . . . . . . . . . . . . 98
5.56 script . . . . . . . . . . . . . . . 98
5.57 show . . . . . . . . . . . . . . . 98
5.58 simax . . . . . . . . . . . . . . . 99
5.59 sorbate . . . . . . . . . . . . . . 99
5.60 suffix . . . . . . . . . . . . . . . 100
5.61 suppress . . . . . . . . . . . . . 100
5.62 surface_capacitance . . . . . . . 100
5.63 surface_data . . . . . . . . . . . 101
5.64 surface_potential . . . . . . . . . 102
5.65 swap . . . . . . . . . . . . . . . 102
5.66 system . . . . . . . . . . . . . . 103
5.67 TDS . . . . . . . . . . . . . . . . 103
5.68 temperature . . . . . . . . . . . 103
5.69 timax . . . . . . . . . . . . . . . 104
5.70 title . . . . . . . . . . . . . . . . 104
5.71 unalter . . . . . . . . . . . . . . 104
5.72 unsuppress . . . . . . . . . . . . 105
5.73 unswap . . . . . . . . . . . . . . 105
5.74 usgovt . . . . . . . . . . . . . . . 106
5.75 volume . . . . . . . . . . . . . . 106
6 React Commands 109
6.1 <unit> . . . . . . . . . . . . . . . 109
6.2 activity . . . . . . . . . . . . . . 111
6.3 add . . . . . . . . . . . . . . . . 111
6.4 alkalinity . . . . . . . . . . . . . 111
6.5 alter . . . . . . . . . . . . . . . . 111
6.6 balance . . . . . . . . . . . . . . 112
6.7 carbon . . . . . . . . . . . . . . 112
6.8 chdir . . . . . . . . . . . . . . . . 113
6.9 clear . . . . . . . . . . . . . . . . 113
6.10 clipboard . . . . . . . . . . . . . 113
6.11 conductivity . . . . . . . . . . . . 113
6.12 couple . . . . . . . . . . . . . . . 114
6.13 cpr . . . . . . . . . . . . . . . . . 114
6.14 cpu_max . . . . . . . . . . . . . 115
6.15 cpw . . . . . . . . . . . . . . . . 115
6.16 data . . . . . . . . . . . . . . . . 115
6.17 debyehuckel . . . . . . . . . . . 116
6.18 decouple . . . . . . . . . . . . . 116
6.19 delQ . . . . . . . . . . . . . . . . 116
6.20 delxi . . . . . . . . . . . . . . . . 117
6.21 density . . . . . . . . . . . . . . 117
6.22 dual_porosity . . . . . . . . . . . 118
6.23 dump . . . . . . . . . . . . . . . 119
6.24 dx_init . . . . . . . . . . . . . . . 120
6.25 dxplot . . . . . . . . . . . . . . . 120
6.26 dxprint . . . . . . . . . . . . . . . 120
6.27 Eh . . . . . . . . . . . . . . . . . 121
6.28 enddump . . . . . . . . . . . . . 121
6.29 epsilon . . . . . . . . . . . . . . 121
6.30 exchange_capacity . . . . . . . 121
6.31 explain . . . . . . . . . . . . . . 122
6.32 explain_step . . . . . . . . . . . 122
6.33 extrapolate . . . . . . . . . . . . 123
6.34 fix . . . . . . . . . . . . . . . . . 123
6.35 flash . . . . . . . . . . . . . . . . 124
6.36 flowthrough . . . . . . . . . . . 124
6.37 flush . . . . . . . . . . . . . . . . 124
6.38 fugacity . . . . . . . . . . . . . . 125
6.39 go . . . . . . . . . . . . . . . . . 125
6.40 grep . . . . . . . . . . . . . . . . 125
6.41 gtplot . . . . . . . . . . . . . . . 126
6.42 hmw . . . . . . . . . . . . . . . 126
6.43 heat_source . . . . . . . . . . . 126
6.44 help . . . . . . . . . . . . . . . . 127
6.45 history . . . . . . . . . . . . . . . 127
6.46 hydrogen . . . . . . . . . . . . . 127
6.47 inert . . . . . . . . . . . . . . . . 128
6.48 isotope . . . . . . . . . . . . . . 128
6.49 itmax . . . . . . . . . . . . . . . 128
6.50 itmax0 . . . . . . . . . . . . . . . 129
6.51 Kd . . . . . . . . . . . . . . . . . 129
6.52 kinetic . . . . . . . . . . . . . . . 129
6.53 log . . . . . . . . . . . . . . . . . 134
6.54 mobility . . . . . . . . . . . . . . 134
6.55 noprecip . . . . . . . . . . . . . 135
6.56 nswap . . . . . . . . . . . . . . . 135
6.57 nswap0 . . . . . . . . . . . . . . 135
6.58 oxygen . . . . . . . . . . . . . . 136
6.59 pause . . . . . . . . . . . . . . . 136
6.60 pe . . . . . . . . . . . . . . . . . 136
6.61 permeability . . . . . . . . . . . 137
6.62 pH . . . . . . . . . . . . . . . . . 138
6.63 phrqpitz . . . . . . . . . . . . . . 138
x
Contents
6.64 pickup . . . . . . . . . . . . . . . 138
6.65 pitz_dgamma . . . . . . . . . . . 139
6.66 pitz_precon . . . . . . . . . . . . 139
6.67 pitz_relax . . . . . . . . . . . . . 140
6.68 pitzer . . . . . . . . . . . . . . . 140
6.69 plot . . . . . . . . . . . . . . . . 140
6.70 pluses . . . . . . . . . . . . . . . 141
6.71 polymorphs . . . . . . . . . . . . 141
6.72 porosity . . . . . . . . . . . . . . 141
6.73 precip . . . . . . . . . . . . . . . 142
6.74 print . . . . . . . . . . . . . . . . 142
6.75 pwd . . . . . . . . . . . . . . . . 143
6.76 quit . . . . . . . . . . . . . . . . 143
6.77 ratio . . . . . . . . . . . . . . . . 143
6.78 react . . . . . . . . . . . . . . . . 144
6.79 reactants . . . . . . . . . . . . . 145
6.80 read . . . . . . . . . . . . . . . . 145
6.81 remove . . . . . . . . . . . . . . 146
6.82 report . . . . . . . . . . . . . . . 146
6.83 reset . . . . . . . . . . . . . . . . 146
6.84 resume . . . . . . . . . . . . . . 147
6.85 save . . . . . . . . . . . . . . . . 147
6.86 script . . . . . . . . . . . . . . . 147
6.87 segregate . . . . . . . . . . . . . 148
6.88 show . . . . . . . . . . . . . . . 149
6.89 simax . . . . . . . . . . . . . . . 149
6.90 slide . . . . . . . . . . . . . . . . 150
6.91 sorbate . . . . . . . . . . . . . . 150
6.92 start_date . . . . . . . . . . . . . 151
6.93 start_time . . . . . . . . . . . . . 151
6.94 step_increase . . . . . . . . . . 151
6.95 step_max . . . . . . . . . . . . . 152
6.96 suffix . . . . . . . . . . . . . . . 152
6.97 sulfur . . . . . . . . . . . . . . . 152
6.98 suppress . . . . . . . . . . . . . 153
6.99 surface_capacitance . . . . . . . 153
6.100 surface_data . . . . . . . . . . . 154
6.101 surface_potential . . . . . . . . . 154
6.102 swap . . . . . . . . . . . . . . . 155
6.103 system . . . . . . . . . . . . . . 155
6.104 TDS . . . . . . . . . . . . . . . . 156
6.105 temperature . . . . . . . . . . . 156
6.106 theta . . . . . . . . . . . . . . . . 157
6.107 timax . . . . . . . . . . . . . . . 157
6.108 time . . . . . . . . . . . . . . . . 157
6.109 title . . . . . . . . . . . . . . . . 158
6.110 unalter . . . . . . . . . . . . . . 158
6.111 unsegregate . . . . . . . . . . . 158
6.112 unsuppress . . . . . . . . . . . . 159
6.113 unswap . . . . . . . . . . . . . . 159
6.114 usgovt . . . . . . . . . . . . . . . 159
6.115 volume . . . . . . . . . . . . . . 160
7 X1t Commands 163
7.1 <unit> . . . . . . . . . . . . . . . 163
7.2 activity . . . . . . . . . . . . . . 165
7.3 add . . . . . . . . . . . . . . . . 165
7.4 alkalinity . . . . . . . . . . . . . 165
7.5 alter . . . . . . . . . . . . . . . . 166
7.6 audit . . . . . . . . . . . . . . . . 166
7.7 balance . . . . . . . . . . . . . . 166
7.8 chdir . . . . . . . . . . . . . . . . 167
7.9 clear . . . . . . . . . . . . . . . . 167
7.10 clipboard . . . . . . . . . . . . . 167
7.11 conductivity . . . . . . . . . . . . 167
7.12 couple . . . . . . . . . . . . . . . 168
7.13 Courant . . . . . . . . . . . . . . 168
7.14 cpr . . . . . . . . . . . . . . . . . 169
7.15 cpu_max . . . . . . . . . . . . . 169
7.16 cpw . . . . . . . . . . . . . . . . 169
7.17 data . . . . . . . . . . . . . . . . 170
7.18 debyehuckel . . . . . . . . . . . 170
7.19 decouple . . . . . . . . . . . . . 170
7.20 delQ . . . . . . . . . . . . . . . . 171
7.21 deltar . . . . . . . . . . . . . . . 171
7.22 deltax . . . . . . . . . . . . . . . 171
7.23 delxi . . . . . . . . . . . . . . . . 172
7.24 density . . . . . . . . . . . . . . 172
7.25 diffusion_coef . . . . . . . . . . 173
7.26 discharge . . . . . . . . . . . . . 173
7.27 dispersivity . . . . . . . . . . . . 174
7.28 dual_porosity . . . . . . . . . . . 174
7.29 dx_init . . . . . . . . . . . . . . . 176
7.30 dxplot . . . . . . . . . . . . . . . 176
7.31 dxprint . . . . . . . . . . . . . . . 177
7.32 Eh . . . . . . . . . . . . . . . . . 178
7.33 epsilon . . . . . . . . . . . . . . 178
7.34 exchange_capacity . . . . . . . 178
7.35 explain . . . . . . . . . . . . . . 179
xi
Contents
7.36 explain_step . . . . . . . . . . . 179
7.37 extrapolate . . . . . . . . . . . . 179
7.38 fix . . . . . . . . . . . . . . . . . 180
7.39 fugacity . . . . . . . . . . . . . . 180
7.40 go . . . . . . . . . . . . . . . . . 181
7.41 grep . . . . . . . . . . . . . . . . 181
7.42 hmw . . . . . . . . . . . . . . . 182
7.43 head_drop . . . . . . . . . . . . 182
7.44 heat_source . . . . . . . . . . . 183
7.45 height . . . . . . . . . . . . . . . 183
7.46 help . . . . . . . . . . . . . . . . 184
7.47 history . . . . . . . . . . . . . . . 184
7.48 inert . . . . . . . . . . . . . . . . 184
7.49 interval . . . . . . . . . . . . . . 185
7.50 itmax . . . . . . . . . . . . . . . 185
7.51 Kd . . . . . . . . . . . . . . . . . 186
7.52 kinetic . . . . . . . . . . . . . . . 186
7.53 left . . . . . . . . . . . . . . . . . 191
7.54 length . . . . . . . . . . . . . . . 192
7.55 log . . . . . . . . . . . . . . . . . 192
7.56 mobility . . . . . . . . . . . . . . 192
7.57 noprecip . . . . . . . . . . . . . 193
7.58 nswap . . . . . . . . . . . . . . . 194
7.59 Nx . . . . . . . . . . . . . . . . . 194
7.60 pause . . . . . . . . . . . . . . . 194
7.61 pe . . . . . . . . . . . . . . . . . 194
7.62 permeability . . . . . . . . . . . 195
7.63 pH . . . . . . . . . . . . . . . . . 196
7.64 phrqpitz . . . . . . . . . . . . . . 196
7.65 pitz_dgamma . . . . . . . . . . . 196
7.66 pitz_precon . . . . . . . . . . . . 197
7.67 pitz_relax . . . . . . . . . . . . . 197
7.68 pitzer . . . . . . . . . . . . . . . 197
7.69 plot . . . . . . . . . . . . . . . . 198
7.70 pluses . . . . . . . . . . . . . . . 198
7.71 polymorphs . . . . . . . . . . . . 198
7.72 porosity . . . . . . . . . . . . . . 199
7.73 precip . . . . . . . . . . . . . . . 199
7.74 print . . . . . . . . . . . . . . . . 200
7.75 pwd . . . . . . . . . . . . . . . . 200
7.76 quit . . . . . . . . . . . . . . . . 201
7.77 radial . . . . . . . . . . . . . . . 201
7.78 ratio . . . . . . . . . . . . . . . . 201
7.79 react . . . . . . . . . . . . . . . . 202
7.80 read . . . . . . . . . . . . . . . . 203
7.81 remove . . . . . . . . . . . . . . 203
7.82 report . . . . . . . . . . . . . . . 204
7.83 reset . . . . . . . . . . . . . . . . 204
7.84 resume . . . . . . . . . . . . . . 205
7.85 right . . . . . . . . . . . . . . . . 205
7.86 save . . . . . . . . . . . . . . . . 206
7.87 scope . . . . . . . . . . . . . . . 206
7.88 script . . . . . . . . . . . . . . . 207
7.89 show . . . . . . . . . . . . . . . 208
7.90 simax . . . . . . . . . . . . . . . 208
7.91 slide . . . . . . . . . . . . . . . . 209
7.92 sorbate . . . . . . . . . . . . . . 209
7.93 spherical . . . . . . . . . . . . . 210
7.94 start_date . . . . . . . . . . . . . 210
7.95 start_time . . . . . . . . . . . . . 210
7.96 step_increase . . . . . . . . . . 211
7.97 step_max . . . . . . . . . . . . . 211
7.98 suffix . . . . . . . . . . . . . . . 211
7.99 suppress . . . . . . . . . . . . . 212
7.100 surface_capacitance . . . . . . . 212
7.101 surface_data . . . . . . . . . . . 213
7.102 surface_potential . . . . . . . . . 213
7.103 swap . . . . . . . . . . . . . . . 214
7.104 system . . . . . . . . . . . . . . 214
7.105 TDS . . . . . . . . . . . . . . . . 215
7.106 temperature . . . . . . . . . . . 215
7.107 thermal_cond . . . . . . . . . . . 216
7.108 theta . . . . . . . . . . . . . . . . 216
7.109 threads . . . . . . . . . . . . . . 217
7.110 timax . . . . . . . . . . . . . . . 217
7.111 time . . . . . . . . . . . . . . . . 217
7.112 title . . . . . . . . . . . . . . . . 218
7.113 unalter . . . . . . . . . . . . . . 218
7.114 unsuppress . . . . . . . . . . . . 218
7.115 unswap . . . . . . . . . . . . . . 219
7.116 usgovt . . . . . . . . . . . . . . . 219
7.117 width . . . . . . . . . . . . . . . 219
7.118 xtplot . . . . . . . . . . . . . . . 220
7.119 Xstable . . . . . . . . . . . . . . 220
8 X2t Commands 221
8.1 <unit> . . . . . . . . . . . . . . . 221
8.2 activity . . . . . . . . . . . . . . 223
8.3 add . . . . . . . . . . . . . . . . 223
xii
Contents
8.4 alkalinity . . . . . . . . . . . . . 223
8.5 alter . . . . . . . . . . . . . . . . 224
8.6 audit . . . . . . . . . . . . . . . . 224
8.7 balance . . . . . . . . . . . . . . 224
8.8 bottom . . . . . . . . . . . . . . 225
8.9 chdir . . . . . . . . . . . . . . . . 226
8.10 clear . . . . . . . . . . . . . . . . 226
8.11 clipboard . . . . . . . . . . . . . 226
8.12 conductivity . . . . . . . . . . . . 226
8.13 couple . . . . . . . . . . . . . . . 227
8.14 Courant . . . . . . . . . . . . . . 227
8.15 cpr . . . . . . . . . . . . . . . . . 228
8.16 cpu_max . . . . . . . . . . . . . 228
8.17 cpw . . . . . . . . . . . . . . . . 228
8.18 data . . . . . . . . . . . . . . . . 229
8.19 debyehuckel . . . . . . . . . . . 229
8.20 decouple . . . . . . . . . . . . . 229
8.21 delQ . . . . . . . . . . . . . . . . 230
8.22 deltar . . . . . . . . . . . . . . . 230
8.23 deltax . . . . . . . . . . . . . . . 230
8.24 deltay . . . . . . . . . . . . . . . 231
8.25 delxi . . . . . . . . . . . . . . . . 232
8.26 density . . . . . . . . . . . . . . 232
8.27 diffusion_coef . . . . . . . . . . 233
8.28 discharge . . . . . . . . . . . . . 233
8.29 dispersivity . . . . . . . . . . . . 235
8.30 dual_porosity . . . . . . . . . . . 235
8.31 dx_init . . . . . . . . . . . . . . . 237
8.32 dxplot . . . . . . . . . . . . . . . 237
8.33 dxprint . . . . . . . . . . . . . . . 238
8.34 Eh . . . . . . . . . . . . . . . . . 238
8.35 epsilon . . . . . . . . . . . . . . 239
8.36 exchange_capacity . . . . . . . 239
8.37 explain . . . . . . . . . . . . . . 240
8.38 explain_step . . . . . . . . . . . 240
8.39 extrapolate . . . . . . . . . . . . 240
8.40 fix . . . . . . . . . . . . . . . . . 241
8.41 fugacity . . . . . . . . . . . . . . 241
8.42 go . . . . . . . . . . . . . . . . . 241
8.43 grep . . . . . . . . . . . . . . . . 242
8.44 hmw . . . . . . . . . . . . . . . 242
8.45 head_drop . . . . . . . . . . . . 243
8.46 heat_source . . . . . . . . . . . 244
8.47 height . . . . . . . . . . . . . . . 244
8.48 help . . . . . . . . . . . . . . . . 245
8.49 history . . . . . . . . . . . . . . . 245
8.50 inert . . . . . . . . . . . . . . . . 245
8.51 interval . . . . . . . . . . . . . . 246
8.52 itmax . . . . . . . . . . . . . . . 246
8.53 Kd . . . . . . . . . . . . . . . . . 247
8.54 kinetic . . . . . . . . . . . . . . . 247
8.55 left . . . . . . . . . . . . . . . . . 252
8.56 length . . . . . . . . . . . . . . . 253
8.57 log . . . . . . . . . . . . . . . . . 253
8.58 mobility . . . . . . . . . . . . . . 253
8.59 modflow . . . . . . . . . . . . . . 255
8.60 noprecip . . . . . . . . . . . . . 256
8.61 nswap . . . . . . . . . . . . . . . 256
8.62 Nx . . . . . . . . . . . . . . . . . 256
8.63 Ny . . . . . . . . . . . . . . . . . 256
8.64 offdiag . . . . . . . . . . . . . . 257
8.65 pause . . . . . . . . . . . . . . . 257
8.66 pe . . . . . . . . . . . . . . . . . 257
8.67 permeability . . . . . . . . . . . 257
8.68 pH . . . . . . . . . . . . . . . . . 258
8.69 phrqpitz . . . . . . . . . . . . . . 259
8.70 pitz_dgamma . . . . . . . . . . . 259
8.71 pitz_precon . . . . . . . . . . . . 259
8.72 pitz_relax . . . . . . . . . . . . . 260
8.73 pitzer . . . . . . . . . . . . . . . 260
8.74 plot . . . . . . . . . . . . . . . . 260
8.75 pluses . . . . . . . . . . . . . . . 261
8.76 polymorphs . . . . . . . . . . . . 261
8.77 porosity . . . . . . . . . . . . . . 261
8.78 precip . . . . . . . . . . . . . . . 262
8.79 print . . . . . . . . . . . . . . . . 262
8.80 pwd . . . . . . . . . . . . . . . . 263
8.81 quit . . . . . . . . . . . . . . . . 263
8.82 radial . . . . . . . . . . . . . . . 263
8.83 ratio . . . . . . . . . . . . . . . . 264
8.84 react . . . . . . . . . . . . . . . . 264
8.85 read . . . . . . . . . . . . . . . . 266
8.86 remove . . . . . . . . . . . . . . 266
8.87 report . . . . . . . . . . . . . . . 267
8.88 reset . . . . . . . . . . . . . . . . 267
8.89 resume . . . . . . . . . . . . . . 268
8.90 right . . . . . . . . . . . . . . . . 268
8.91 save . . . . . . . . . . . . . . . . 269
xiii
Contents
8.92 scope . . . . . . . . . . . . . . . 270
8.93 script . . . . . . . . . . . . . . . 271
8.94 show . . . . . . . . . . . . . . . 271
8.95 simax . . . . . . . . . . . . . . . 272
8.96 slide . . . . . . . . . . . . . . . . 272
8.97 sorbate . . . . . . . . . . . . . . 273
8.98 start_date . . . . . . . . . . . . . 273
8.99 start_time . . . . . . . . . . . . . 273
8.100 step_increase . . . . . . . . . . 274
8.101 step_max . . . . . . . . . . . . . 274
8.102 suffix . . . . . . . . . . . . . . . 274
8.103 suppress . . . . . . . . . . . . . 275
8.104 surface_capacitance . . . . . . . 275
8.105 surface_data . . . . . . . . . . . 276
8.106 surface_potential . . . . . . . . . 276
8.107 swap . . . . . . . . . . . . . . . 277
8.108 system . . . . . . . . . . . . . . 277
8.109 TDS . . . . . . . . . . . . . . . . 278
8.110 temperature . . . . . . . . . . . 278
8.111 thermal_cond . . . . . . . . . . . 279
8.112 theta . . . . . . . . . . . . . . . . 279
8.113 threads . . . . . . . . . . . . . . 280
8.114 timax . . . . . . . . . . . . . . . 280
8.115 time . . . . . . . . . . . . . . . . 280
8.116 title . . . . . . . . . . . . . . . . 281
8.117 top . . . . . . . . . . . . . . . . . 281
8.118 unalter . . . . . . . . . . . . . . 282
8.119 unsuppress . . . . . . . . . . . . 282
8.120 unswap . . . . . . . . . . . . . . 283
8.121 usgovt . . . . . . . . . . . . . . . 283
8.122 well . . . . . . . . . . . . . . . . 283
8.123 width . . . . . . . . . . . . . . . 285
8.124 xtplot . . . . . . . . . . . . . . . 285
8.125 Xstable . . . . . . . . . . . . . . 286
Appendix: Thermo Datasets 287
A.1 Dataset format . . . . . . . . . . 287
A.1.1 Header lines . . . . . . . 288
A.1.2 Data tables . . . . . . . . 288
A.1.3 Elements . . . . . . . . . 289
A.1.4 Basis species . . . . . . 290
A.1.5 Redox couples . . . . . . 290
A.1.6 Aqueous species . . . . 292
A.1.7 Free electron . . . . . . 293
A.1.8 Minerals . . . . . . . . . 293
A.1.9 Gases . . . . . . . . . . 293
A.1.10 Oxide components . . . 294
A.1.11 Virial coefficients . . . . 294
A.1.12 Legacy formats . . . . . 295
A.1.12.1 Tables . . . . . 295
A.1.12.2 Redox couples 295
A.1.12.3 Free electron . 295
Appendix: User Interface 297
B.1 Spelling completion . . . . . . . 297
B.2 History substitution . . . . . . . 298
B.3 Special characters . . . . . . . . 299
B.4 Calculator . . . . . . . . . . . . . 299
B.5 Startup files . . . . . . . . . . . 300
B.6 Help pages . . . . . . . . . . . . 300
B.7 System commands . . . . . . . 300
B.8 Text size in the windows . . . . 301
B.9 Keyboard shortcuts . . . . . . . 301
Appendix: Graphics Output 303
C.1 Clipboard . . . . . . . . . . . . . 303
C.2 Saving images . . . . . . . . . . 304
C.3 Font for data markers . . . . . . 306
Appendix: Scatter Data 307
D.1 Act2 and Tact . . . . . . . . . . 308
D.2 Gtplot . . . . . . . . . . . . . . . 309
D.3 Xtplot . . . . . . . . . . . . . . . 313
Appendix: Report Command 317
Appendix: Control Scripts 333
F.1 Control statements . . . . . . . 334
F.2 Interacting with the application . 334
F.3 Example control script . . . . . 335
F.4 Tcl license agreement . . . . . . 336
Appendix: Plugin Feature 337
I.1 C++ . . . . . . . . . . . . . . . . 338
I.1.1 Initializing the GWB ap
plication . . . . . . . . . 338
I.1.2 Configuring and execut
ing calculations . . . . . 339
I.1.3 Retrieving the results . . 340
I.1.4 C++ programs . . . . . . 341
I.1.5 Compiling and linking . . 344
xiv
Contents
I.2 Fortran . . . . . . . . . . . . . . 347
I.2.1 Initializing the GWB ap
plication . . . . . . . . . 348
I.2.2 Configuring and execut
ing calculations . . . . . 349
I.2.3 Retrieving the results . . 349
I.2.4 Fortran programs . . . . 351
I.2.5 Compiling . . . . . . . . 354
I.3 Java . . . . . . . . . . . . . . . . 357
I.3.1 Initializing the GWB ap
plication . . . . . . . . . 357
I.3.2 Configuring and execut
ing calculations . . . . . 359
I.3.3 Retrieving the results . . 359
I.3.4 Java programs . . . . . . 360
I.3.5 Java command line . . . 364
I.4 Perl . . . . . . . . . . . . . . . . 365
I.4.1 Initializing the GWB ap
plication . . . . . . . . . 366
I.4.2 Configuring and execut
ing calculations . . . . . 367
I.4.3 Retrieving the results . . 367
I.4.4 Perl programs . . . . . . 368
I.4.5 Perl command line . . . 371
I.5 Python . . . . . . . . . . . . . . 372
I.5.1 Initializing the GWB ap
plication . . . . . . . . . 372
I.5.2 Configuring and execut
ing calculations . . . . . 374
I.5.3 Retrieving the results . . 374
I.5.4 Python programs . . . . 375
I.5.5 Python command line . 377
I.6 MATLAB . . . . . . . . . . . . . 379
I.6.1 GWBplugin MATLAB
wrapper class overview . 379
I.6.2 Initializing the GWB ap
plication . . . . . . . . . 380
I.6.3 Configuring and execut
ing calculations . . . . . 381
I.6.4 Retrieving the results . . 381
I.6.5 Cleaning up . . . . . . . 382
I.6.6 MATLAB code examples
using the plugin feature 383
I.6.7 MATLAB command line 385
I.7 Other . . . . . . . . . . . . . . . 386
I.7.1 GWBplugin.dll function
prototypes . . . . . . . . 386
I.7.2 Initializing the GWB ap
plication . . . . . . . . . 387
I.7.3 Configuring and execut
ing calculations . . . . . 388
I.7.4 Retrieving the results . . 389
Appendix: Multiple Analyses 393
G.1 Calculation procedure . . . . . . 393
G.2 Example calculation . . . . . . . 394
Appendix: Remote Control 397
H.1 C++ program, unnamed pipes . 398
H.2 C++ program, named pipes . . 400
H.3 Tcl script, unnamed pipes . . . 401
H.4 Perl script, unnamed pipes . . . 402
Appendix: Units Recognized 403
Index 411
xv
xvi
Introduction
This GWB Reference Manual contains specifics of the formats of the various GWBcommands. It also contains information about the format of thermodynamic datasets,the user interface on the Command pane, manipulating graphics output, the reportcommand, control scripts, and running the GWB applications within your own applicationusing the plugin feature.
This manual is intended as a supplement to the GWB manuals: GWB Essentials
Guide, GWB Reaction Modeling Guide, and the GWB Reactive Transport Modeling
Guide.
1.1 Command reference
The initial chapters of the manual contain details of the formats of the various commandsavailable in Rxn, Act2, Tact, SpecE8, React, X1t, and X2t. Each command listedmay be typed directly into the Command pane, using the syntax shown. Alternatively,almost all of the commands have GUI equivalents, and these are also shown.
Two or more commands may appear separated by semicolons on the same line ofinput, and you may continue one line onto another with a backslash (\). Commentsmay appear anywhere in the input; they begin with a pound sign (#) followed by ablank and extend to the end of the line. Equal signs appear in the commands forclarity and may be included or omitted as desired.
You need enter only enough characters to uniquely identify a command. You can,furthermore, use the spelling completion feature: touch “[tab]” or “[esc]” to have theprogram cycle through the possible completions, or Ctrl+D to list possible completions.
Within the command reference sections, the entry <value> signifies that you shouldenter a numerical value. You can enter values as numbers (e.g., 4.15, 3.8e6),exponentials (10ˆ6), fractions (1/2), or percentages (25%).
For programs X1t and X2t, some keywords may be set to an entry identified as<field_variable>. These are keywords representing properties of the medium or thesimulation initial conditions that can be set to vary over the domain. In other words,these are values that can be heterogeneous.
You can enter several things in a command in place of <field_variable>:
A value, in any of the forms described above.
1
GWB Reference Manual
A question mark (?), to unset the variable.
A mean ˙ a standard deviation, in which case values are assigned to nodalblocks randomly, within a Gaussian distribution.
The name of a dataset containing a table of values, one for each nodal block inthe simulation.
An expression used to calculate values at individual nodal blocks.
A basic script used to calculate values.
A compiled function in a dll, or dynamic load library.
For more information about setting field variables, see the Heterogeneity appendix inthe GWB Reactive Transport Modeling Guide.
1.2 Appendices
In addition to the command reference sections described above, this manual containsa number of appendices providing details about specific features of the GWB softwarepackage. These appendices are:
Thermo Datasets — Information about the formatting and content of thethermodynamic databases the GWB programs can read. This information is usefulif you need to modify the database, or create your own.
User Interface — The features of the user interface for the Command pane,including spelling completion, history substitution, and the builtin calculator.
Graphics Output — How you can manipulate the graphical output from Act2,Tact, Gtplot, and Xtplot.
Scatter Data — The legacy method of adding scatter data to a diagram byimporting a specially formatted table from a text file. The preferred method is touse a GSS spreadsheet as described in the GWB Essentials Guide.
Report Command — Format and use of the “report” command, which returns theresults of calculations. This command provides a means of transmitting resultsto control scripts and to programs running a GWB application as a plugin or byremote control.
Control Scripts — How to set up within GWB input file scripts containing loops,branches, if checks, and so on.
Plugin Feature — Details how to use the capabilities of the GWB applicationsthrough the functions of a DLL.
Multiple Analyses — Examples of how to process a number of chemical analysesfrom a spreadsheet and save the results to the spreadsheet.
2
Introduction
Remote Control — Details the deprecated legacy method of how you can runthe GWB applications as slave processes from other programs and softwareenvironments. This method has been replaced by the Plugin Feature.
Units Recognized — A complete table of the unit names to be used in thecommands.
3
4
Rxn Commands
2.1 activity
activity <species> = <value | ?>
Basis ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies, the water activity, or the activity of a surface complex from an ion exchangemodel. Examples:
activity Na+ = 0.3a H2O = 0.9log a H+ = -5
Use “?” to unset an activity value:
activity U++++ = ?
Seealsothe“pH”, “Eh”, “pe”, “molality”, “fugacity”, “sorbed_mass”,and“ratio”commands.
2.2 add
add <basis species>
Basis ! add
Use the “add” command to cause a basis species to be included in the calculation.Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “ratio”, “pH”, “pe”, and “Eh” commands.
5
GWB Reference Manual
2.3 alter
alter <species | mineral | gas> <log K’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list log K ’s that have been altered; the “unalter” command reversesthe process.
2.4 block
block <append>
Run ! Block ! Overwrite or Append
Use the “block” command to create blocks of text for aqueous species, minerals, andgases, in the form of entries in the thermo dataset. When you issue the command,Rxn copies the current reaction and associated log K ’s to the clipboard, so you canpaste the block directly into a thermo dataset. With the “append” argument, the blockis written at the end of any previous blocks on the clipboard, from previous invocationsof the “block” command. The command is convenient for updating and manipulatingthe contents of a thermo dataset, such as if you were to add redox coupling reactions.
2.5 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (also: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
6
Rxn Commands
changes to the user’s home directory, if one is defined by the operating system.
2.6 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
2.7 clipboard
clipboard
Edit ! Copy
The “clipboard” command causes the contents of the Results pane to be copied tothe clipboard, from where it can be pasted into various types of documents.
2.8 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
2.9 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
7
GWB Reference Manual
data "..\my_thermo.tdat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
2.10 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
2.11 Eh
Eh = <value in volts | ?>
Basis ! Eh
Use the “Eh” command to set Eh for the calculation. Example:
Eh = 1/2
sets the system’s oxidation state to correspond to an Eh of 0.5 volts. Use “?” to unsetan Eh value:
Eh = ?
See also the “activity”, “pH”, “pe”, “fugacity”, and “ratio” commands.
8
Rxn Commands
2.12 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula, mole volume, and density) about species, minerals,and gases in the dataset. Example:
explain Analcime
2.13 factor
factor = <reaction multiplier | ? | ->factor <explicit> <reaction multiplier | ? | ->
Basis ! factor reaction by reverse
Use the “factor” command to multiply reaction coefficients by a numeric value. Withoutthe “explicit” qualifier, the current factor is multiplied by the value. Negative valuesreverse the reaction. Examples:
factor 5/2factor -1.5factor -factor ?factor explicit 1.7
The third example reverses the current reaction, and the fourth resets the multiplierto 1. The last example explicitly sets the factor to the value, rather than multiplyingthe current factor by the value. See also the “reverse” command.
2.14 fugacity
fugacity <gas> = <value | ?>
Basis ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) forthe calculation. Examples:
9
GWB Reference Manual
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
Use “?” to unset a fugacity value:
fugacity CH4(g) = ?
See also the “activity”, “pH”, “Eh”, “pe”, and “ratio” commands.
2.15 go
go
Run ! Go
Results ! Run
Use the “go” command to initiate an Rxn calculation based on the current chemicalsystem.
2.16 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
2.17 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
10
Rxn Commands
2.18 ionic_strength
ionic_strength = <value | ?>
Basis ! ionic strength true molal
Use the “ionic_strength” command (also: “I”, “IS”) to set, in molal units, the solution ionicstrength. Use the “?” argument to unset this value. Setting the ionic strength when Rxn
is invoked in “long” mode has two effects. First, if a temperature has been set, it causesthe program to use the extended DebyeHückel equations to calculate the activitycoefficients of any aqueous species in the equilibrium equation. The program alsouses the calculated activity coefficients to simplify the equilibrium equation, if possible.Second, if you have set temperature to 25°C and set a value for surface charge or surfacepotential, Rxn will evaluate the Boltzman factor for surface complexation reactionsand use this factor to simplify the equilibrium equation. See also the “stoich_IS”,“temperature”, “surface_data”, “surface_charge”, and “surface_potential” commands.
2.19 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
log fugacity O2(g) = -65log activity U++++ = -10react Cu+ log activity = -8
2.20 long
long
Results !
Use the “long” command to get a more detailed output than that produced by default(see the “short” command).
11
GWB Reference Manual
2.21 molality
molality <surface complex> = <value | ?>
Basis ! molality
Use the “molality” command (abbrev.: “m”) to set for a surface complex from a twolayeror Langmuir model the mole number of the complex present per kilogram of solventwater. Example:
molality >(w)FeOH = 10^-2
An argument of “?” unsets the value. Use the “activity” command to constrainaqueous species, as well as surface complexes from an ion exchange model, andthe “sorbed_mass” command for surface complexes from a Kd or Freundlich sorptionmodel. See also the “pH”, “Eh”, “pe”, “activity”, “fugacity”, “ratio”, “sorbed_mass”, and“surface_data” commands.
2.22 output
output <append>
Run ! Output ! Overwrite or Append
Use the “output” command to make a run and write the results to a dataset in theworking directory, instead of to the text window (as would be the case for the “go”command). The output appears in file “Rxn_output.txt”. The “append” option causesthe results to be written at the end of the dataset.
2.23 pause
pause
Use the “pause” command to cause Rxn to pause temporarily during input. Thiscommand is useful if you are debugging input scripts.
2.24 pe
pe = <value | ?>
Basis ! pe
12
Rxn Commands
Use the “pe” command to set pe for the calculation. Example:
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron.Use “?” to unset a pe value:
pe = ?
See also the “activity”, “Eh”, “pH”, “fugacity”, and “ratio” commands.
2.25 pH
pH = <value | ?>
Basis ! pH
Use the “pH” command to set pH for the calculation. Example:
pH = 5
is equivalent to
log activity H+ = -5
Use “?” to unset a pH value:
pH = ?
See also the “activity”, “Eh”, “pe”, “fugacity”, and “ratio” commands.
2.26 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
13
GWB Reference Manual
polymorphs Albite
2.27 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
2.28 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
2.29 ratio
ratio <act./fug. ratio> = <value | ?>
Basis ! ratio
Use the “ratio” command to set activity or fugacity ratios for the calculation. Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
Use “?” to unset a ratio value:
ratio Ca++/H+^2 = ?
See also the “activity”, “pH”, “Eh”, “pe”, and “fugacity” commands.
14
Rxn Commands
2.30 react
react <main species> activity = <value | ?>
Basis !
Use the “react” command (also: “reaction for”) to set the species to appear on theleft side of the reaction, and optionally the species’ activity. Examples:
react Pyritereact CH4(g) log fugacity = -1reaction for H3PO4 activity = 1e-4
Note that the species in question must have been first swapped into the basis (seethe “swap” command) if not included in the original basis.
2.31 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Cu_solubility
Control returns to the user after the script has been read, unless the script containsa “quit” command.
You can also use the “read” command in place of the “data” or “surface_data”command to read a thermo or surface reaction dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
15
GWB Reference Manual
2.32 remove
remove <basis species>
Basis ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries fromconsideration in the calculation. Examples:
remove Na+remove Quartz Calcite
Components can be reentered into the basis using the “swap”, “add”, “activity”,“fugacity”, or “ratio” commands.
2.33 report
report <option>report set_digits <value>
Once the program has completed a calculation, you can use the “report” commandto return aspects of the calculation results. You can use this command from theCommand pane to query the program interactively. More significantly, the “report”command provides a means of communicating calculation results to control scriptsand external programs running GWB programs by remote control.
For arguments available, see the Report Command appendix to this GWB Reference
Manual. For details about control scripts and the plugin feature, see theControl Scripts and Plugin Feature appendices. Use the “set_digits” argument toset the number of significant digits in the values reported.
2.34 reset
reset
File ! Reset Configuration
Use the “reset” command to begin defining the geochemical system again with aclean slate. Your current settings will be lost, and all command options returned tothe default state. The command, however, does not alter the setting for the thermodataset.
16
Rxn Commands
2.35 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exitedthe program. The program configuration is stored in a file “rxn_resume.rxn” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
2.36 reverse
reverse
Basis ! reverse
Use the “reverse” command to reverse the sense of the reaction, so that species onthe left appear on the right and vice versa. The command is the same as “factor 1”or “factor ”.
2.37 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in termsof Rxn commands. The dataset can be used as an input script for a later Rxn run.Examples:
savesave kspar.rxn
If you don’t specify a dataset name, Rxn will ask for one.
2.38 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not only
17
GWB Reference Manual
Rxn commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.rxn
within a control script.
2.39 short
short
Results !
Use the “short” command to produce output in a concise format that consists of thebalanced reaction and, if the temperature is set, the log K.
2.40 show
show <option>show <species | minerals | surfaces> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display information about the current system or database.Examples:
show show directory show showshow altered show elements show speciesshow basis show gases show surfacesshow commands show minerals show systemshow couples show oxides
The command “show show” gives show command options. When you type “showspecies”, “show minerals”, or “show surfaces”, the program will prompt you for a matchstring. You may enter either a basis species, a literal string, or nothing. If you supplya basis species, the program will list only species or minerals containing that basisspecies. If you enter a string, the program shows species or minerals whose namescontain that string. Otherwise, the program lists all species or minerals in the thermodatabase. A long form of the “show species” and “show minerals” commands lets youset the basis species or match string directly:
18
Rxn Commands
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
2.41 sorbed_mass
sorbed_mass <surface complex> = <value | ?>
Basis ! mol/dry g
Use the “sorbed_mass” command (abbrev.: “SM”) to set the mass, expressed in molesper gram of solid phase, of a surface complex from a Kd or Freundlich sorption model.Example:
sorbed_mass >Pb++ = 0.002
An argument of “?” unsets the value. Use the “activity” command to constrain aqueousspecies and surface complexes from an ion exchange model, and the “molality”command to set concentrations of surface complexes from a twolayer or Langmuirmodel. See also the “pH”, “Eh”, “pe”, “activity”, “molality”, “fugacity”, “ratio”, and“surface_data” commands.
2.42 stoich_IS
stoich_IS = <value | ?>
Basis ! stoichiometric molal
Use the “stoich_IS” command (also: “SI”, “SIS”) to set, in molal units, the stoichiometricionic strength. Use the “?” argument to unset this value. Setting the ionic strengthwhen a temperature has been specified and Rxn is invoked in “long” mode causes theprogram to calculate the activity of water, if water appears in the reaction considered,and to use this value to simplify the equation. See also the “ionic_strength” command.
19
GWB Reference Manual
2.43 suffix
suffix <string>
Run ! Suffix. . .
Use the “suffix” command to alter the names of the output datasets (“Rxn_output.txt”)by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “Rxn_output_run2.txt”.
2.44 surface_capacitance
surface_capacitance = <value | ?>surface_capacitance on <type> = <value | ?>
File! Open! Sorbing Surfaces. . . ! constant capacitance F/m2
Use this command (abbrev.: “surf_capacitance”) to set, in units of F/m2, the capacitanceof a sorbing surface. When you set this value (or if a capacitance has been set in thesurface reaction dataset), Rxn in long mode will calculate the relationship betweensurface charge and surface potential for the surface in question using the constantcapacitance model, rather than the full twolayer model.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_capacitance on HFO = 2
The “type” associated with each surface is listed at the top of each dataset ofsurface reactions. The “type” of the hydrous ferric oxide surface represented by thedataset “FeOH.sdat”, for example, is “HFO”. You can use the “show” command todisplay the “type” of each active surface. See also the “ionic_strength”, “temperature”,“surface_charge”, and “surface_potential” commands.
20
Rxn Commands
2.45 surface_charge
surface_charge = <value | ?>surface_charge on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant charge uC/cm2
Use this command (abbrev.: “surf_charge”) to set, in units of �C/cm2, the chargedensity of a sorbing surface. When you set this value (or a value for surface potential),a value for ionic strength, and temperature to 25°C, Rxn in long mode will calculate avalue for the Boltzman factor and use it to simplify the equilibrium equation.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_charge on HFO = 0
The “type” associated with each surface is listed at the top of each dataset ofsurface reactions. The “type” of the hydrous ferric oxide surface represented by thedataset “FeOH.sdat”, for example, is “HFO”. You can use the “show” command todisplay the “type” of each active surface. See also the “ionic_strength”, “temperature”,“surface_capacitance”, “surface_data”, and “surface_potential” commands.
2.46 surface_data
surface_data <sorption dataset>surface_data remove <sorption dataset | surface type>surface_data OFF
File ! Open ! Sorbing Surfaces. . . ! add
File ! Open ! Sorbing Surfaces. . . ! select surface(s) ! delete
Use the “surface_data” command (abbrev.: “surf_data”) to specify an input datasetof surface sorption reactions to be considered in the calculation. The dataset nameshould be enclosed in quotes if it contains any unusual characters. Use the “remove”argument to eliminate a surface dataset, specified by name or surface type (e.g.,“HFO”), from consideration. The argument “OFF” disables consideration of all surfacecomplexes.
You can specify more than one sorbing surface in a model by repeating the“surface_data” command for different datasets (a dataset of surface reactions forsorption onto hydrous ferric oxide, as well as example datasets for the ion exchange,Kd , Freundlich, and Langmuir models are distributed with the software). To remove adataset of surface reactions from consideration, you use commands such as
21
GWB Reference Manual
surface_data remove FeOH.sdatsurface_data remove HFOsurface_data OFF
The latter command removes all of the surface datasets that have been loaded.
2.47 surface_potential
surface_potential = <value | ?>surface_potential on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant potential mV
Use this command (abbrev.: “surf_potential”) to set, in units of mV, the electricalpotential for a sorbing surface. When you set this value and a temperature (or valuesfor surface charge and ionic strength, and temperature to 25°C), Rxn in long mode willcalculate a value for the Boltzman factor and use it to simplify the equilibrium equation.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_potential on HFO = -10
The “type” associated with each surface is listed at the top of each dataset ofsurface reactions. The “type” of the hydrous ferric oxide surface represented by thedataset “FeOH.sdat”, for example, is “HFO”. You can use the “show” command todisplay the “type” of each active surface. See also the “ionic_strength”, “temperature”,“surface_charge”, and “surface_data” commands.
2.48 swap
swap <new basis> <for> <basis species>
Basis !
Use the “swap” command to change the set of basis entries. All reactions are written interms of an initial list of basis species. The basis can be altered over the course of thecalculation to reflect the species, minerals, and gases to be included in the reaction.To include an aqueous species, mineral, gas, or activity ratio in the calculation, swapit into the basis in place of a basis species from the original list, as carried in thedatabase. Examples:
22
Rxn Commands
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
2.49 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving Rxn. Example:
system "copy Rxn_output.txt Rxn_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the Rxn command with a “$”:
$copy Rxn_output.txt Rxn_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
2.50 temperature
temperature = <value | ?> <unit>
Basis ! temperature C
Use the “temperature” command (also: “T”) to set temperature in °C, °F, or K. Examples:
23
GWB Reference Manual
temperature 25 Ctemperature 300 FT = 298 K
Temperature can range from 0°C to 300°C; centigrade is the default scale. Use “?” tounset the temperature:
T = ?
2.51 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
2.52 unswap
unswap <species | ALL>
Basis ! !
Use the “unswap” command to reverse a basis swap. Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the previous command
swap Quartz for SiO2(aq)
24
Rxn Commands
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
2.53 usgovt
usgovt
Help ! About Rxn. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
25
26
Act2 Commands
3.1 activity
activity <species> = <value>
Basis ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies or water over the diagram. Examples:
activity Na+ = 0.3activity main = 10^-5a H2O = 0.9log a H+ = -5
The label “main” refers to the species being diagrammed. See also the “pH”, “Eh”,“pe”, “fugacity”, and “ratio” commands.
3.2 add
add <basis species>
Basis ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “ratio”, “pH”, “pe”, and “Eh” commands.
27
GWB Reference Manual
3.3 alter
alter <species | mineral | gas> <log K’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
3.4 background
background <color name>
Plot ! Plot Area. . .
Use the “background” command to set the background color of the plot. Example:
background "sky blue"
Type “show lines” for current color settings; “show colors” for color choices. Enclosemultiword colors in quotes.
3.5 banner
banner <off>
Plot ! View. . .Plot ! Title. . .
The “banner” command controls whether Act2 will plot a banner along the side ofthe diagram summarizing the calculation constraints. The optional argument “off”deselects the option. Type “show options” to display the current option setting.
28
Act2 Commands
3.6 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (also: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
3.7 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
3.8 clipboard
clipboardclipboard bitmap
Edit ! CopyEdit ! Copy As ! Bitmap
The “clipboard” command causes the contents of the Plot pane to be copied to theclipboard, from where it can be pasted into various types of documents. The “bitmap”keyword causes the plot to be copied as a bitmap, rather than a vector graphic.
3.9 color_by_sample
color_by_sample <off>
Plot ! Scatter Data. . .
29
GWB Reference Manual
The “color_by_sample” command causes Act2 to show each scatter data samplelabel in the color of its related marker. The optional argument “off” causes all of thesample labels to be shown in the color set in Plot !Scatter Data. . . .
3.10 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
3.11 custom
custom <color number> <name> <red green blue>
Color ! Define Custom Colors
The “custom” command allows you to change the name and/or RGB values of theeleven custom colors. Specify the custom color number (1 11), the name in quotes,and the RGB values (0 255). Examples:
custom 2 "Med Blue" 128 128 255custom 2 "Med Blue"custom 2 128 128 255
3.12 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
data "..\my_thermo.tdat"
30
Act2 Commands
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
3.13 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
3.14 diagram
diagram <main species> <on axis> <vs axis> <activity = value>
Basis !
Use the “diagram” command (also: “plot”) to set the species to be diagrammed, itsactivity, and the diagram axes. Examples:
31
GWB Reference Manual
diagram Fe++ on Eh vs pH activity = 1e-4diagram U++++ log activity = -10diagram on pe vs H+^-1diagram x= Cl- y= H+^2/Ca++
The keywords “x” and “y” may be substituted for “on” and “vs”. The species to bediagrammed, as well as the species appearing on the axes, must have been swappedinto the basis if they do not appear in the original basis.
3.15 Eh
Eh = <value in volts>
Basis ! Eh
Use the “Eh” command to set Eh over the diagram. Example:
Eh = 1/2
sets the system’s oxidation state to correspond to an Eh of 0.5 volts. See also the“activity”, “Eh”, “pe”, “fugacity”, and “ratio” commands.
3.16 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula, mole volume, and density) about species, minerals,and gases in the dataset. Example:
explain Analcime
3.17 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . . or Plot ! Diagram. . .
32
Act2 Commands
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of dataprovided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation. When the “extrapolate”option is invoked, the program will estimate log K ’s as functions of temperature bymaking a polynomial fit to the data provided. Use this option with considerable care.
3.18 font
font <font name>
Use the “font” command to select the font to be used to label the diagram. Example:
font "courier new"
You may select any font name available in the Choose Font. . . dialog. Enclose multipleword names in quotes. To change the font for individual aspects of the diagram,rightclick on the aspect and choose Font !.
3.19 fugacity
fugacity <gas> = <value>
Basis ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) overthe diagram. Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
See also the “activity”, “pH”, “Eh”, “pe”, and “ratio” commands.
3.20 gases
gases <off>
Plot ! View. . .Plot ! Diagram. . .
33
GWB Reference Manual
The “gases” command controls whether Act2 will consider gaseous species when itcalculates the full diagram. By default, the program includes any gases that containthe species being diagrammed and that can be made up from the basis entries; itassigns each a fugacity equal to the total pressure. Use this command with the “off”argument to cause gases to be excluded from the calculation. See also the “pressure”command.
3.21 go
go
Run ! Go
Plot
Use the “go” command to initiate calculation of a diagram based on the currentchemical system.
3.22 grep
grep <string>
File ! View ! .\Act2_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “Act2_output.txt” containing the string “Albite”.
3.23 gridlines
gridlines <off>
Plot ! View. . .Plot ! Axes and Ticks. . .
The “gridlines” command controls whether Act2 will draw gridlines on the diagram.The optional argument “off” deselects the option.
34
Act2 Commands
3.24 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
3.25 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
3.26 labels
labels <off>
Plot ! View. . .Plot ! Diagram. . .
The “labels” command controls whether Act2 will label the diagram with the names ofpredominant aqueous species and stable minerals and gases. Other types of letteringon the plot, such as axis labels, may be eliminated by using the “line” command toomit the aspect. Act2, by default, includes species labels on the diagram. The optionalargument “off” deselects the option. Type “show options” to display the current optionsetting.
3.27 legend
legend <off>legend x <value | ?> y <value | ?>
Plot ! View. . .Plot ! Scatter Data. . .
35
GWB Reference Manual
Use the “legend” command to control whether a legend related to scatter data isshown. The legend is only available when scatter data is currently loaded. Keyword“off” hides the legend. Keywords “x” and “y” set the position of the legend. Examples:
legendlegend offlegend x 2 y 7
3.28 line
line <aspect> <pen thickness> <color> <size = character size><font = <noitalic | italic>> <font = <nobold | bold>><noomit | include | omit>
Plot ! View. . .Plot ! Diagram. . .Plot ! Axes and Ticks. . .Plot ! Plot Area. . .Plot ! Title. . .Plot ! Scatter Data. . .Plot ! Trace. . .
Use the “line” command to change the boldness and color of lines used to constructthe diagram, set the point size for lettering, set bold and/or italic lettering, or omit anaspect of the lettering. Examples:
line axes fine cyanline axis_labels size = 18line axis_labels font = boldline axis_labels omit
Set the lettering size in points (values � 1) or inches (values < 1). Type “show lines”for aspects that can be changed and their current settings, “show pens” and “showcolors” for available pens and colors.
3.29 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
36
Act2 Commands
log fugacity O2(g) = -65log activity U++++ = -10diagram Cu+ log activity = -8
3.30 minerals
minerals <off>
Plot ! View. . .Plot ! Diagram. . .
The “minerals” command controls whether Act2 will consider mineral species whenit calculates the full diagram. By default, the program includes each mineral thatcontains the species being diagrammed and that can be made up from the basisentries. Use this command with the “off” argument to cause minerals to be excludedfrom the calculation.
3.31 mosaic_bounds
mosaic_bounds <off>
Plot ! View. . .Plot ! Diagram. . .
When calculating a mosaic diagram (see the “speciate” command), Act2 normallydraws the boundaries among subdiagrams using a finely dashed line. The “mosaic_bounds” command controls whether these lines are drawn. Act2, by default,draws the mosaic boundaries. The optional argument “off” deselects the option. Type“show options” to display the current option setting.
3.32 mosaic_labels
mosaic_labels <off>
Plot ! View. . .Plot ! Diagram. . .
The “mosaic_labels” command controls whether Act2 labels the subdiagrams in amosaic diagram (see the “speciate” command). The program, by default, does notlabel these fields. The command “mosaic_labels” causes the labels to be drawn;the optional argument “off” deselects the option. Type “show options” to display thecurrent option setting.
37
GWB Reference Manual
3.33 paper
paper height = <value | ?> width = <value | ?> \factor = <value | ?> \orientation = <portrait | landscape | ?> \units = <in | cm | ?> scale = <on | off | ?>
paper reset
File ! Page Setup. . .
The “paper” command controls printing from Act2, including the paper size and diagramorientation. Keywords “height” and “width” specify paper dimensions, “factor” is anoptional scaling factor applied to the plot upon printing, “orientation” controls whetherthe plot prints as portrait or landscape, “units” tells whether the page dimensions arein inches or centimeters, and “scale” controls whether the plot is scaled automaticallyto the size of the printed page. Keywords “selection” and “paper” are for internal useby the program.
Type
show paper
to see the current settings, and
paper reset
to restore settings to their default values.
38
Act2 Commands
3.34 pause
pause
Use the “pause” command to cause Act2 to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
3.35 pe
pe = <value>
Basis ! pe
Use the “pe” command to set pe over the diagram. Example:
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, and “ratio”commands.
3.36 pH
pH = <value>
Basis ! pH
Use the “pH” command to set pH over the diagram. Example:
pH = 5
is equivalent to
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, and “ratio” commands.
39
GWB Reference Manual
3.37 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
3.38 pressure
pressure = <value> <unit>
Basis ! pressure ! bars
Use the “pressure” command (also: “P”) to set total pressure. Pressure affects theposition of water stability limits and the fugacities assigned to gaseous species, butnot mineral or species stability. Examples:
pressure 20 atmpressure 1.01 barP 0.1 MPa
Default is 1 atm below 100°C, vapor pressure of water above this temperature; defaultunits are bars.
3.39 print
print <off | on>
Plot ! Diagram. . .
The command “print” (also: “printout”) with the argument “off” causes Act2 to bypasswriting calculation results to the “Act2_output.txt” dataset. By default, the programwrites to this dataset. The command “print on” (or just “print”) reenables the output.
40
Act2 Commands
3.40 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
3.41 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
3.42 ratio
ratio <act./fug. ratio> = <value>
Basis ! ratio
Use the “ratio” command to set activity or fugacity ratios over the diagram. Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, and “fugacity” commands.
3.43 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Cu_solubility
41
GWB Reference Manual
Control returns to the user after the script has been read, unless the script containsa “quit” command.
You can also use the “read” command in place of the “data” command to read athermo dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
3.44 remove
remove <basis species>
Basis ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries fromconsideration in the calculation. Example:
remove Na+remove Quartz Calcite
Components can be reentered into the basis using the “swap”, “add”, “activity”,“fugacity”, or “ratio” commands.
3.45 reset
reset
File ! Reset Configuration
Use the “reset” command to begin defining the system again with a clean slate. Yourcurrent settings will be lost, and all options will be returned to the default state. Thecommand, however, does not alter the setting for the thermo dataset.
3.46 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exited theprogram. The program configuration is stored in the file “act2_resume.ac2” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
42
Act2 Commands
3.47 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in Act2
format commands. The dataset can be used as an Act2 input script. Examples:
savesave kspar.ac2
If you don’t specify a dataset name, Act2 will ask for one.
3.48 scatter
scatter <dataset>
File ! Open ! Scatter Data. . .
Use the “scatter” command to project data points onto the diagram. Data points areread from the specified dataset; “scatter off” turns off the option. The preferred wayto add scatter data is to import it from a GSS spreadsheet (“.gss” file, see the UsingGSS and Using Act2 chapters of the GWB Essentials Guide). The old method ofimporting a specially formatted table from a text file still works, however (see theScatter Data appendix to this guide).
3.49 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not onlyAct2 commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.ac2
within a control script.
43
GWB Reference Manual
3.50 show
show <option>show <species | minerals> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show elements show pensshow altered show gases show speciesshow basis show lines show suppressedshow colors show minerals show symbolsshow commands show options show systemshow couples show oxides show showshow directory show paper
The command “show show” gives a list of show command options. When you type“show species” or “show minerals”, the program will prompt you for a match string.You may enter either a basis species, a literal string, or nothing. If you supply a basisspecies, the program will list only species or minerals containing that basis species. Ifyou enter a string, the program shows species or minerals whose names contain thatstring. Otherwise, the program lists all species or minerals in the thermo database.A long form of the “show species” and “show minerals” commands lets you set thebasis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
44
Act2 Commands
3.51 speciate
speciate <basis species> <over> <X | Y | X-Y>
Basis !
Use the “speciate” command to cause a basis species of the chemical system toreact with the axis species to form complex ions and minerals. Example: SO4
�� canspeciate on an EhpH diagram to form HSO4
�, H2S(aq), HS�, and native sulfur. Theprogram will calculate subdiagrams within each area of predominance resulting fromthe speciation and assemble the subdiagrams into a complete diagram. Examples:
speciate SO4--speciate HCO3- over Xspeciate NO3- over X-Y
Each basis species can speciate over both axes, the default if the speciate commandis given, or over only the x or the y axis. The “unspeciate” command reverses theprocess.
3.52 suffix
suffix <string>
Run ! Suffix. . .
Use the “suffix” command to alter the names of the output datasets (“Act2_output.txt”)by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “Act2_output_run2.txt”.
45
GWB Reference Manual
3.53 suppress
suppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species, minerals,or gases from being considered in a calculation. Example:
suppress H3SiO4- Quartz "Maximum Microcline"
prevents the three entries listed from being loaded from the database. Typing “suppressALL” suppresses all of the minerals in the thermodynamic database. The “unsuppress”command reverses the process. To suppress all but a few minerals, you could type
suppress ALLunsuppress Quartz Muscovite Kaolinite
3.54 swap
swap <new basis> <for> <basis species>
Basis !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that can be altered over the course of the calculationto reflect the chemical constraints to be imposed. An aqueous species, mineral, gas,or activity ratio can be swapped into the basis in place of one of the original basisspecies listed in the database. Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
46
Act2 Commands
3.55 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving Act2. Example:
system "copy Act2_output.txt Act2_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the Act2 command with a “$”:
$copy Act2_output.txt Act2_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
3.56 temperature
temperature = <value> <unit>
Basis ! temperature C
Use the “temperature” command (also: “T”) to set temperature in °C, °F, or K. Examples:
temperature 25 Ctemperature 300 FT = 298 K
Temperature can range from 0°C to 300°C. Setting the temperature automaticallysets pressure to the liquid vapor curve, or 1 atm below 100°C; 25°C is the defaulttemperature; centigrade is the default scale.
3.57 title
title <character string | empty>title x <value | ?> y <value | ?>
Plot ! View. . .Plot ! Title. . .
47
GWB Reference Manual
Use the “title” command to set a title to be written above the plot. Keyword “empty”eliminates the title. Keywords “x” and “y” set the position of the title. Examples:
title "Al solubility vs pH"title x 2 y 7
Enclose multiword titles in quotes.
3.58 trace
trace <dataset>
File ! Open ! Reaction Trace. . .File ! Update TracePlot ! Trace. . .
Use the “trace” command to project the results of a React run onto the diagram. TheReact results are read from a “React_plot.gtp” dataset in the working directory or froma specified dataset. Examples:
tracetrace ..\React_plot_run1.gtptrace off
The third command turns off the projection option.
3.59 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
48
Act2 Commands
3.60 unspeciate
unspeciate <basis species>
Basis !
Use the “unspeciate” command to reverse the effects of the “speciate” command.Example:
unspeciate SO4--
3.61 unsuppress
unsuppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies, minerals, or gases that have previously been suppressed. Examples:
unsuppress Quartz Albite "Albite low"unsuppress ALL
The argument “ALL” clears any species, minerals, or gases that have been suppressed.
49
GWB Reference Manual
3.62 unswap
unswap <species | ALL>
Basis ! !
Use the “unswap” command to reverse a basis swap. Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
3.63 usgovt
usgovt
Help ! About Act2. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
3.64 water_limits
water_limits <off>
Plot ! View. . .Plot ! Diagram. . .
Water, depending on its oxidation state, can decompose to form oxygen or hydrogengas. The “water_limits” command controls whether Act2 will determine the stabilitylimits of water at the current pressure (see the “pressure” command) and constrainthe diagram to within these limits. If this option is not selected, the program draws adiagram to fill the axis range, regardless of whether water is stable over the diagram.Act2, by default, honors the stability limits of water in chemical systems where water
50
Act2 Commands
can decompose. The optional argument “off” deselects the option. Type “show options”to display the current option setting.
3.65 xaxis
x-axis <from value> <to value> <increment value><length value> <margin value>
Plot ! Axis Range. . .Plot ! Plot Area. . .
Basis ! from to increment
Use the “xaxis” command (abbrev.: “x”) to set the range, tick increment, length andmargin for the horizontal axis. Examples:
x-axis from -6 to 0 increment .5x 0 14 2x length 6 margin 2
Axis ranges are set on a log scale, and the axis length and margin are set in inches.The keywords “from”, “to”, and “increment” may be omitted, and any keyword may beabbreviated to two letters.
3.66 yaxis
y-axis <from value> <to value> <increment value><length value> <margin value>
Plot ! Axis Range. . .Plot ! Plot Area. . .
Basis ! from to increment
Use the “yaxis” command (abbrev.: “y”) to set the range, tick increment, length andmargin for the vertical axis. Examples:
y-axis from -6 to 0 increment .5y 0 14 2y length 6 margin 2
51
52
Tact Commands
4.1 activity
activity <species> = <value>
Basis ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies or water over the diagram. Examples:
activity Na+ = 0.3activity main = 10^-5a H2O = 0.9log a H+ = -5
The label “main” refers to the species being diagrammed. See also the “pH”, “Eh”,“pe”, “fugacity”, and “ratio” commands.
4.2 add
add <basis species>
Basis ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “ratio”, “pH”, “pe”, and “Eh” commands.
53
GWB Reference Manual
4.3 alter
alter <species | mineral | gas> <log K’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
4.4 background
background <color name>
Plot ! Plot Area. . .
Use the “background” command to set the background color of the plot. Example:
background "sky blue"
Type “show lines” for current color settings; “show colors” for color choices. Enclosemultiword colors in quotes.
4.5 banner
banner <off>
Plot ! View. . .Plot ! Title. . .
The “banner” command controls whether Tact will plot a banner along the side ofthe diagram summarizing the calculation constraints. The optional argument “off”deselects the option. Type “show options” to display the current option setting.
54
Tact Commands
4.6 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (also: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
4.7 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
4.8 clipboard
clipboardclipboard bitmap
Edit ! CopyEdit ! Copy As ! Bitmap
The “clipboard” command causes the contents of the Plot pane to be copied to theclipboard, from where it can be pasted into various types of documents. The “bitmap”keyword causes the plot to be copied as a bitmap, rather than a vector graphic.
4.9 color_by_sample
color_by_sample <off>
Plot ! Scatter Data. . .
55
GWB Reference Manual
The “color_by_sample” command causes Tact to show each scatter data sample labelin the color of its related marker. The optional argument “off” causes all of the samplelabels to be shown in the color set in Plot !Scatter Data. . . .
4.10 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
4.11 custom
custom <color number> <name> <red green blue>
Color ! Define Custom Colors
The “custom” command allows you to change the name and/or RGB values of theeleven custom colors. Specify the custom color number (1 11), the name in quotes,and the RGB values (0 255). Examples:
custom 2 "Med Blue" 128 128 255custom 2 "Med Blue"custom 2 128 128 255
4.12 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
data "..\my_thermo.tdat"
56
Tact Commands
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
4.13 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
4.14 diagram
diagram <main species> <vs axis> <activity = value>
Basis !
Use the “diagram” command (also: “plot”) to set the species to be diagrammed, itsactivity, and the diagram axis. Examples:
57
GWB Reference Manual
diagram Fe++ vs pH activity = 1e-4diagram U++++ log activity = -10diagram x= Cl-
The keyword “x”may be substituted for “vs”. The species to be diagrammed, as wellas the species appearing on the axis, must have been swapped into the basis if theydo not appear in the original basis.
4.15 Eh
Eh = <value in volts>
Basis ! Eh
Use the “Eh” command to set Eh over the diagram. Example:
Eh = 1/2
sets the system’s oxidation state to correspond to an Eh of 0.5 volts. See also the“activity”, “pH”, “pe”, “fugacity”, and “ratio” commands.
4.16 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula, mole volume, and density) about species, minerals,and gases in the dataset. Example:
explain Analcime
4.17 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . . or Plot ! Diagram. . .
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of data
58
Tact Commands
provided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation. When the “extrapolate”option is invoked, the program will estimate log K ’s as functions of temperature bymaking a polynomial fit to the data provided. Use this option with considerable care.
4.18 font
font <font name>
Use the “font” command to select the font to be used to label the diagram. Example:
font "courier new"
You may select any font name available in the Choose Font. . . dialog. Enclose multipleword names in quotes. To change the font for individual aspects of the diagram,rightclick on the aspect and choose Font !.
4.19 fugacity
fugacity <gas> = <value>
Basis ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) overthe diagram. Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
See also the “activity”, “pH”, “Eh”, “pe”, and “ratio” commands.
4.20 gases
gases <off>
Plot ! View. . .Plot ! Diagram. . .
The “gases” command controls whether Tact will consider gaseous species when itcalculates the full diagram. By default, the program includes any gases that containthe species being diagrammed and that can be made up from the basis entries; it
59
GWB Reference Manual
assigns each a fugacity equal to the total pressure. Use this command with the “off”argument to cause gases to be excluded from the calculation. See also the “pressure”command.
4.21 go
go
Run ! Go
Plot
Use the “go” command to initiate calculation of a diagram based on the currentchemical system.
4.22 grep
grep <string>
File ! View ! .\Tact_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “Tact_output.txt” containing the string “Albite”.
4.23 gridlines
gridlines <off>
Plot ! View. . .Plot ! Axes and Ticks. . .
The “gridlines” command controls whether Tact will draw gridlines on the diagram.The optional argument “off” deselects the option.
60
Tact Commands
4.24 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
4.25 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
4.26 labels
labels <off>
Plot ! View. . .Plot ! Diagram. . .
The “labels” command controls whether Tact will label the diagram with the names ofpredominant aqueous species and stable minerals and gases. Other types of letteringon the plot, such as axis labels, may be eliminated by using the “line” command toomit the aspect. Tact, by default, includes species labels on the diagram. The optionalargument “off” deselects the option. Type “show options” to display the current optionsetting.
4.27 legend
legend <off>legend x <value | ?> y <value | ?>
Plot ! View. . .Plot ! Scatter Data. . .
61
GWB Reference Manual
Use the “legend” command to control whether a legend related to scatter data isshown. The legend is only available when scatter data is currently loaded. Keyword“off” hides the legend. Keywords “x” and “y” set the position of the legend. Examples:
legendlegend offlegend x 2 y 7
4.28 line
line <aspect> <pen thickness> <color> <size = character size><font = <noitalic|italic>> <font = <nobold|bold>><noomit|include|omit>
Plot ! View. . .Plot ! Diagram. . .Plot ! Axes and Ticks. . .Plot ! Plot Area. . .Plot ! Title. . .Plot ! Scatter Data. . .Plot ! Trace. . .
Use the “line” command to change the boldness and color of lines used to constructthe diagram, set the point size for lettering, set bold and/or italic lettering, or omit anaspect of the lettering. Examples:
line axes fine cyanline axis_labels size = 18line axis_labels font = boldline axis_labels omit
Set the lettering size in points (values � 1) or inches (values < 1). Type “show lines”for aspects that can be changed and their current settings, “show pens” and “showcolors” for available pens and colors.
4.29 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
62
Tact Commands
log fugacity O2(g) = -65log activity U++++ = -10diagram Cu+ log activity = -8
4.30 minerals
minerals <off>
Plot ! View. . .Plot ! Diagram. . .
The “minerals” command controls whether Tact will consider mineral species whenit calculates the full diagram. By default, the program includes each mineral thatcontains the species being diagrammed and that can be made up from the basisentries. Use this command with the “off” argument to cause minerals to be excludedfrom the calculation.
4.31 mosaic_bounds
mosaic_bounds <off>
Plot ! View. . .Plot ! Diagram. . .
When calculating a mosaic diagram (see the “speciate” command), Tact normallydraws the boundaries among subdiagrams using a finely dashed line. The “mosaic_bounds” command controls whether these lines are drawn. Tact, by default,draws the mosaic boundaries. The optional argument “off” deselects the option. Type“show options” to display the current option setting.
4.32 mosaic_labels
mosaic_labels <off>
Plot ! View. . .Plot ! Diagram. . .
The “mosaic_labels” command controls whether Tact labels the subdiagrams in amosaic diagram (see the “speciate” command). The program, by default, does notlabel these fields. The command “mosaic_labels” causes the labels to be drawn;the optional argument “off” deselects the option. Type “show options” to display thecurrent option setting.
63
GWB Reference Manual
4.33 paper
paper height = <value | ?> width = <value | ?> \factor = <value | ?> \orientation = <portrait | landscape | ?> \units = <in | cm | ?> scale = <on | off | ?>
paper reset
File ! Page Setup. . .
The “paper” command controls printing from Tact, including the paper size and diagramorientation. Keywords “height” and “width” specify paper dimensions, “factor” is anoptional scaling factor applied to the plot upon printing, “orientation” controls whetherthe plot prints as portrait or landscape, “units” tells whether the page dimensions arein inches or centimeters, and “scale” controls whether the plot is scaled automaticallyto the size of the printed page. Keywords “selection” and “paper” are for internal useby the program.
Type
show paper
to see the current settings, and
paper reset
to restore settings to their default values.
4.34 pause
pause
Use the “pause” command to cause Tact to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
4.35 pe
pe = <value>
Basis ! pe
Use the “pe” command to set pe over the diagram. Example:
pe = 10
64
Tact Commands
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, and “ratio”commands.
4.36 pH
pH = <value>
Basis ! pH
Use the “pH” command to set pH over the diagram. Example:
pH = 5
is equivalent to
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, and “ratio” commands.
4.37 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
4.38 pressure
pressure = <value | vapor> <unit>
Basis ! pressure ! bars
65
GWB Reference Manual
Use the “pressure” command (also: “P”) to set total pressure. Pressure affects theposition of water stability limits and the fugacities assigned to gaseous species, butnot mineral or species stability. Examples:
pressure 20 atmpressure 1.01 barP 0.1 Mpapressure vapor
By default, the program assumes 1 atm pressure where temperature is below 100°C,and the vapor pressure of water at higher temperatures; default units are bars.
4.39 print
print <off | on>
Plot ! Diagram. . .
The command “print” (also: “printout”) with the argument “off” causes Tact to bypasswriting calculation results to the “Tact_output.txt” dataset. By default, the programwrites to this dataset. The command “print on” (or just “print”) reenables the output.
4.40 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
4.41 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
66
Tact Commands
4.42 ratio
ratio <act./fug. ratio> = <value>
Basis ! ratio
Use the “ratio” command to set activity or fugacity ratios over the diagram. Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, and “fugacity” commands.
4.43 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Cu_solubility
Control returns to the user after the script has been read, unless the script containsa “quit” command.
You can also use the “read” command in place of the “data” command to read athermo dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
4.44 remove
remove <basis species>
Basis ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries fromconsideration in the calculation. Example:
remove Na+remove Quartz Calcite
67
GWB Reference Manual
Components can be reentered into the basis using the “swap”, “add”, “activity”,“fugacity”, or “ratio” commands.
4.45 reset
reset
File ! Reset Configuration
Use the “reset” command to begin defining the chemical system again with a cleanslate. Your current settings will be lost, and all options will be returned to the defaultstate. The command, however, does not alter the setting for the thermo dataset.
4.46 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exitedthe program. The program configuration is stored in the file “tact_resume.tac” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
4.47 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in Tact
format commands. The dataset can be used as an Tact input script. Examples:
savesave kspar.tac
If you don’t specify a dataset name, Tact will ask for one.
4.48 scatter
scatter <dataset>
File ! Open ! Scatter Data. . .
68
Tact Commands
Use the “scatter” command to project data points onto the diagram. Data points areread from the specified dataset; “scatter off” turns off the option. The preferred wayto add scatter data is to import it from a GSS spreadsheet (“.gss” file, see the Using
GSS and Using Act2 chapters of the GWB Essentials Guide). The old method ofimporting a specially formatted table from a text file still works, however (see theScatter Data appendix to this guide).
4.49 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not onlyTact commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.tac
within a control script.
4.50 show
show <option>show <species | minerals> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show elements show pensshow altered show gases show speciesshow basis show lines show suppressedshow colors show minerals show symbolsshow commands show options show systemshow couples show oxides show showshow directory show paper
The command “show show” gives a list of show command options. When you type“show species” or “show minerals”, the program will prompt you for a match string.
69
GWB Reference Manual
You may enter either a basis species, a literal string, or nothing. If you supply a basisspecies, the program will list only species or minerals containing that basis species. Ifyou enter a string, the program shows species or minerals whose names contain thatstring. Otherwise, the program lists all species or minerals in the thermo database.A long form of the “show species” and “show minerals” commands lets you set thebasis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
4.51 speciate
speciate <basis species>
Basis !
Use the “speciate” command to cause a basis species of the chemical system toreact with the xaxis species to form complex ions and minerals. Example: SO4
��
can speciate over a pH axis to form HSO4�; H2S(aq) can form HS� and S��. The
program will calculate subdiagrams within each area of predominance resulting fromthe speciation and assemble the subdiagrams into a complete diagram. Examples:
speciate HCO3-speciate SO4--speciate NO3-
The “unspeciate” command reverses the process.
4.52 suffix
suffix <string>
Run ! Suffix. . .
70
Tact Commands
Use the “suffix” command to alter the names of the output datasets (“Tact_output.txt”)by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “Tact_output_run2.txt”.
4.53 suppress
suppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species, minerals,or gases from being considered in a calculation. Example:
suppress H3SiO4- Quartz "Maximum Microcline"
prevents the three entries listed from being loaded from the database. Typing “suppressALL” suppresses all of the minerals in the thermodynamic database. The “unsuppress”command reverses the process. To suppress all but a few minerals, you could type
suppress ALLunsuppress Quartz Muscovite Kaolinite
4.54 swap
swap <new basis> <for> <basis species>
Basis !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that can be altered over the course of the calculationto reflect the chemical constraints to be imposed. An aqueous species, mineral, gas,or activity ratio can be swapped into the basis in place of one of the original basisspecies listed in the database. Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
71
GWB Reference Manual
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
4.55 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving Tact. Example:
system "copy Tact_output.txt Tact_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the Tact command with a “$”:
$copy Tact_output.txt Tact_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
4.56 title
title <character string | empty>title x <value | ?> y <value | ?>
Plot ! View. . .Plot ! Title. . .
Use the “title” command to set a title to be written above the plot. Keyword “empty”eliminates the title. Keywords “x” and “y” set the position of the title. Examples:
title "Al solubility vs pH"title x 2 y 7
Enclose multiword titles in quotes.
72
Tact Commands
4.57 trace
trace <dataset>
File ! Open ! Reaction Trace. . .File ! Update TracePlot ! Trace. . .
Use the “trace” command to project the results of a React run onto the diagram. TheReact results are read from a “React_plot.gtp” dataset in the working directory or froma specified dataset. Examples:
tracetrace ..\React_plot_run1.gtptrace off
The third command turns off the projection option.
4.58 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
4.59 unspeciate
unspeciate <basis species>
Basis !
73
GWB Reference Manual
Use the “unspeciate” command to reverse the effects of the “speciate” command.Example:
unspeciate SO4--
4.60 unsuppress
unsuppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies, minerals, or gases that have previously been suppressed. Examples:
unsuppress Quartz Albite "Albite low"unsuppress ALL
The argument “ALL” clears any species, minerals, or gases that have been suppressed.
4.61 unswap
unswap <species | ALL>
Basis ! !
Use the “unswap” command to reverse a basis swap. Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
74
Tact Commands
4.62 usgovt
usgovt
Help ! About Tact. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
4.63 water_limits
water_limits <off>
Plot ! View. . .Plot ! Diagram. . .
Water, depending on its oxidation state, can decompose to form oxygen or hydrogengas. The “water_limits” command controls whether Tact will determine the stabilitylimits of water at the current pressure (see the “pressure” command) and constrainthe diagram to within these limits. If this option is not selected, the program draws adiagram to fill the axis range, regardless of whether water is stable over the diagram.Tact, by default, honors the stability limits of water in chemical systems where water candecompose. The optional argument “off” deselects the option. Type “show options”to display the current option setting.
4.64 xaxis
x-axis <from value> <to value> <increment value><length value> <margin value>
Plot ! Axis Range. . .Plot ! Plot Area. . .
Basis ! from to increment
Use the “xaxis” command (abbrev.: “x”) to set the range, tick increment, length andmargin for the horizontal axis. Examples:
x-axis from -6 to 0 increment .5x 0 14 2x length 6 margin 2
Axis ranges are set on a log scale. The axis length and margin are set in inches.The keywords “from”, “to”, and “increment” may be omitted, and any keyword may beabbreviated to two letters.
75
GWB Reference Manual
4.65 yaxis
y-axis <from value> <to value> <increment value><length value> <margin value>
Plot ! Axis Range. . .Plot ! Plot Area. . .
Basis ! from to increment
Use the “yaxis” command (abbrev.: “y”) to set the range, tick increment, length andmargin for the vertical (temperature) axis. Examples:
y-axis from 0 to 200 increment 25y 100 200 10y length 6 margin 2
76
SpecE8 Commands
5.1 <unit>
<value> <free> <unit> <as element symbol> <basis entry>
Basis ! free kg
To constrain the initial system, enter a command containing only the above entries.Entries may appear in any order. The qualifier “free” specifies that the constraintapplies to the free rather than to the bulk basis entry. SpecE8 recognizes the followingunits for constraining the initial system:
By mass or volume:mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 l
By concentration:mol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
By carbonate alkalinity (applied to bicarbonate component):eq_acid meq_acid ueq_acid neq_acideq_acid/kg meq_acid/kg ueq_acid/kg neq_acid/kgeq_acid/l meq_acid/l ueq_acid/l neq_acid/lg/kg_as_CaCO3 mg/kg_as_CaCO3 ug/kg_as_CaCO3 ng/kg_as_CaCO3wt%_as_CaCO3g/l_as_CaCO3 mg/l_as_CaCO3 ug/l_as_CaCO3 ng/l_as_CaCO3
Per volume of the system:mol/cm3 mmol/cm3 umol/cm3 nmol/cm3kg/cm3 g/cm3 mg/cm3 ug/cm3ng/cm3
77
GWB Reference Manual
mol/m3 mmol/m3 umol/m3 nmol/m3kg/m3 g/m3 mg/m3 ug/m3ng/m3volume% "vol. fract."
By activity:activity fugacity ratiopH V pe
Activity and fugacity may be abbreviated to “a” or “f”. Keyword “total” reverses a settingof “free”.
Use the “as” keyword to constrain mass in terms of elemental equivalents. Forexample, the command
CH3COO- = 10 umol/kg as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
20 mg/kg SO4-- as S
would specify 59.9 mg/kg of sulfate, since the ion’s mole weight is about 3 times thatof sulfur itself.
Examples:
55 mg/kg HCO3-Na+ = 1 molal1 ug/kg U++++100 free cm3 DolomitepH = 8Eh = .550 Vlog f O2(g) = -60HCO3- = 30 mg/kg as C
5.2 activity
activity <species> = <value>
Basis ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies or water in the initial system. Examples:
activity Na+ = 0.3log a H+ = -5
78
SpecE8 Commands
See also the “pH”, “Eh”, “pe”, “ratio”, “fugacity”, “fix”, and “slide” commands.
5.3 add
add <basis species>
Basis ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “pH”, “pe”, and “Eh” commands.
5.4 alkalinity
alkalinity = <value> <unit>
Basis ! HCO3- mg/kg_as_CaCO3
Use the “alkalinity” command to constrain the total concentration of HCO�
3 to reflectthe solution’s carbonate alkalinity. You can specify one of the units listed in theUnits Recognized appendix; “mg/kg_as_CaCO3” is the default. To use this option,the solution pH must be set explicitly.
5.5 alter
alter <species | mineral | gas> <log K ’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
79
GWB Reference Manual
5.6 balance
balance <on> <basis entry>balance <off>
Basis ! unit ! Balance species
Use the “balance” command to specify the basis entry to be used for electrical chargebalancing. The basis entry must be a charged aqueous species. By default, SpecE8
balances on Cl�.The command “balance off” disables React’s charge balancing feature. In this case,
the user is responsible for prescribing chargebalanced input constraints.
5.7 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (abbrev.: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
5.8 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
5.9 clipboard
clipboard
Edit ! Copy
80
SpecE8 Commands
The “clipboard” command causes the contents of the Results pane to be copied tothe clipboard, from where it can be pasted into various types of documents.
5.10 conductivity
conductivity <conductivity dataset>
File ! Open ! Conductivity Data. . .
Use the “conductivity” command to change the input file of coefficients used to calculateelectrical conductivity. Example:
conductivity "..\my_conductivity.dat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.Beginning with GWB11, the applications compute electrical conductivity using eitherof two different approaches, the USGS and APHA methods; the USGS method is thedefault. The required coefficients are defined in the files “conductivityUSGS.dat” and“conductivityAPHA.dat”, respectively, which are installed in the same directory as thethermo datasets (commonly “\Program Files\GWB\Gtdata”).
5.11 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
5.12 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
81
GWB Reference Manual
data "..\my_thermo.tdat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
5.13 debyehuckel
debye-huckel
File ! Open ! Thermo Data. . . ! thermo.tdat
The “debyehuckel” command (abbrev.: “dh”) sets the program to calculate species’activity coefficients using the extended DebyeHückel equations. Executing thiscommand automatically sets the input dataset of thermodynamic data to “thermo.tdat”.
5.14 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
5.15 density
density = <value | ?>density = <TDS | chlorinity>
Basis ! advanced ! density g/cm3 TDS chlorinity
82
SpecE8 Commands
You can use the “density” command to set in g/cm3 the fluid density the programuses to convert compositional constraints to molality, the concentration unit it carriesinternally. If you set the initial NaC composition in mg/l, for example, the programneeds to know the density of the initial fluid to determine NaC molality.
The program by default converts units using a density value it calculates automatically,as discussed below. This value is sufficient for most purposes, and hence it is generallynot necessary to set fluid density explicitly. You might, however, want to set the densityif you are working at high temperature, but your analysis is expressed per liter ofsolution at room temperature.
You can also use the “density” command to tell the program how to calculate thedefault density it uses to convert units, and the fluid density it reports in the simulationresults. The program normally figures density as that of an NaCl solution with thesame TDS as the fluid in question, at the temperature of interest. With the command“density = chlorinity” you can tell the program to instead use the density of an NaClsolution of equivalent chlorinity.
To restore automatic calculation, type the command with no argument or with anargument of “?”. To see the current setting of this variable, type “show variables”.
5.16 dual_porosity
dual_porosity = <on | off> <blocks | spheres | fractures><geometry = blocks | spheres | fractures | ?>> |<volfrac = value | ?>><<half-width | radius> = <value | ?><unit>>
Config ! Dual Porosity. . .
Use the “dual_porosity” command (abbrev: “dual”) to configure stagnant zones inthe simulation, using the dual porosity feature. Enable and disable the feature withthe “on” and “off” keywords. Disabling the feature does not affect other settings, soreenabling the feature returns the model to its most recent configuration.
With the “geometry” keyword, you configure the stagnant zone into blocks, spheres,or a fractured domain, the latter being slabs separated by fractures arrayed along thex direction. Alternatively, you can set the three configurations directly with keywords“blocks”, “spheres”, and “fractures”. Keyword “volfrac” sets the fraction of the nodalblock’s bulk volume occupied by the stagnant zone.
The “halfwidth” (or “radius”, for spherical geometries) keyword sets the zone’scharacteristic dimension, in units of distance (see the Units Recognized appendix;default is cm). You may also set any of the keywords recognized by React, X1t, andX2t, but these have no effect in SpecE8, since that program does not model reactionprocesses.
As an example, the command
dual_porosity geometry = spheres, radius = 50 cm, volfrac = 75%
83
GWB Reference Manual
configures the stagnant zone into spheres of halfmeter radius that occupythreequarters of the domain.
5.17 Eh
Eh = <value> <unit>
Basis ! Eh
Use the “Eh” command to set Eh in the initial system. Example:
Eh = 200 mV
sets the system’s oxidation state to correspond to an Eh of 0.2 volt. See also the“activity”, “pH”, “pe”, “fugacity”, “fix”, and “slide” commands.
5.18 epsilon
epsilon = <value | ?>
Config ! Iteration. . .
Use the “epsilon” command to set the convergence criterion (dimensionless) foriterating to a solution of the equations representing the distribution of chemical mass.By default, this variable is set to 5�10�11 . To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
5.19 exchange_capacity
exchange_capacity = <value | ?> <units>exchange_capacity on <type> = <value | ?> <units>
File ! Open ! Sorbing Surfaces. . . ! exchange capacity eq
Use the “exchange_capacity” command (abbrev.: “ex_capacity” or “exch_capacity”) toset the exchange capacitiy (i.e., the CEC) of the system when modeling ion exchangereactions or sorption according to Langmuir isotherms. For ion exchange reactions,you set units of electrical equivalents (“eq”, “meq”, and so on) or equivalents per gramof dry sediment (“eq/g”, “meq/g”, . . . ). For Langmuir reactions, you similarly set a valuein mole units: “mol”, “mmol”, “mol/g”, “mmol/g”. If you set units per gram of sediment,the program multiplies the value entered by the mass of rock in the system (includingequilibrium and kinetic minerals as well as inert volume) to get the system’s capacity.
84
SpecE8 Commands
If you read in a surface that sorbs by ion exchange or Langmuir isotherms, youmust set a value for its exchange capacity. If you have set more than one sorbingsurface (using the “surface_data” command), you identify the surface in question byits “type”. For example
exchange_capacity on IonEx = .0008 eq/g
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the surface represented by the sample dataset “IonEx.sdat”,for example, is “IonEx”. You can use the “show” command to display the “type” ofeach active surface. See also the “surface_data” and “inert” commands.
5.20 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula and mole volume) about species, minerals, and gasesin the dataset. Example:
explain Analcime
5.21 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . .
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of dataprovided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation.
When the “extrapolate” option is invoked, the program will estimate log K ’s asfunctions of temperature by making a polynomial fit to the data provided. Use thisoption with considerable care.
85
GWB Reference Manual
5.22 fugacity
fugacity <gas> = <value>
Basis ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) inthe initial system. Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
See also the “activity”, “ratio”, “pH”, “Eh”, “pe”, “fix”, and “slide” commands.
5.23 go
go
Run ! Go
Results ! Run
Use the “go” command to initiate calculation of a model based on the currentconfiguration.
5.24 grep
grep <string>
File ! View ! .\SpecE8_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “SpecE8_output.txt” (or the current output dataset, asmodified by the “suffix” command) containing the string “Albite”.
86
SpecE8 Commands
5.25 gtplot
gtplot <gtplot options>
Run ! Gtplot
The “gtplot” command launches program Gtplot from the SpecE8 command line,invoking input from the current graphics interface dataset (by default, “SpecE8_plot.gtp”;see the “suffix” command). For example,
gtplot piper
starts Gtplot with a Piper diagram as the initial plot.
5.26 hmw
h-m-w
File ! Open ! Thermo Data. . . ! thermo_hmw.tdat
Use the “hmw” command (abbrev.: “hmw”) to set the program to calculate species’activitycoefficientsbyusingtheHarvieMøllerWeareequations.Executingthiscommandautomatically sets the input dataset of thermodynamic data to “thermo_hmw.tdat”.Note that dataset “thermo_hmw.tdat” supports calculations at 25°C only.
5.27 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
5.28 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands, and then choosing Execute, or with a
87
GWB Reference Manual
history substitution command, as explained in the User Interface appendix to thisguide.
5.29 inert
inert = <value | ?> <units>
Medium ! inert volume cm3
Use the “inert” command to set the volume of nonreacting space in the system. Youmay set a value in units of volume, including cm3, m3, and l, as well as volume%and “vol. fract.”. The default setting is zero and the default unit is cm3.
Assuming you have not set a value for the initial fluid fraction in the system using the“porosity” command, the program figures the porosity over the course of the calculationas a derived variable. Specifically, it divides the fluid volume by the sum of the fluidvolume, mineral volume, and inert volume, and reports this value as a result.
When you have set a value for initial porosity with the “porosity” command, on theother hand, the program works in the contrary sense. In this case, it calculates theinert volume as that required to form a system of the specified initial porosity; theprogram now ignores any entry you may have set using the “inert” command.
To restore the default state, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show”.
5.30 itmax
itmax = <value | ?>
Config ! Iteration. . .
Use the “itmax” command to set the maximum number of iterations that may be takenin an attempt to converge to a solution for the equations representing the distributionof chemical mass. By default, this variable is set to 999. To restore the default value,type the command with no argument or with an argument of “?”. To see the currentsetting of this variable, type “show variables”.
5.31 Kd
Kd <off>
Config ! Iteration. . .
The “Kd” command controls whether the program calculates Kd distribution coefficientsfor sorbing components, in units of liters per kg sediment mass. This calculation
88
SpecE8 Commands
requires that the mineral mass in the system (as specified for individual mineralsand/or in terms of inert volume) be set correctly.
5.32 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
log fugacity O2(g) = -65log activity U++++ = -10
5.33 mobility
mobility = <surface_type> <value>
File ! Open ! Sorbing Surfaces. . . ! mobility
Use the “mobility” command to set up a complexing surface in your model as amobile colloid. A mobile colloid is composed of the mineral (or minerals) associatedwith a complexing surface, as well as the ion complexes present on that surface.Only datasets with model type “twolayer” as set in the dataset header are surfacecomplexation models, and hence only those datasets can be used to form a mobilecolloid.
Since SpecE8 is a static model, the program reports the composition of mobilecolloids in the system, but does not move them. To model transport of the colloidalfraction, you would typically use program X1t or X2t to trace a reactive transportsimulation.
Mobility refers to the fraction of the surface in question that can move in the modelby advection and dispersion. A surface with a mobility of one moves freely, whereasa mobility of zero sets the surface to be stationary. Intermediate values arise, forexample, when some of the surface is attached to the medium, or when colloid motionis impeded by electrostatic interactions. By default in the software the mobility of anysurface is zero.
To set a mobile colloid, begin by reading in a surface complexation dataset using the“surface_data” command. Then, use the “mobility” command, referencing the surface’slabel, to set the colloid’s mobility. The label is given at the head of the surface dataset,on a line beginning “Surface type”. The label in dataset “FeOH.sdat”, for example, is“HFO”. If you omit the label, the program will assume you are referring to the surfacecomplexation dataset most recently read.
89
GWB Reference Manual
You can define the mobility as a field variable, which means you can have theprogram calculate mobility using an equation, script, or compiled function you provide.The program evaluates mobility at each block just once, at the start of the run.
Example:
surface_data FeOH.sdatmobility HFO = 100%
where “HFO” is the label for the surface defined by dataset “FeOH.sdat”.Restore the default behavior of immobility by entering a command such as
mobility HFO ?
5.34 pause
pause
Use the “pause” command to cause SpecE8 to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
5.35 pe
pe = <value>
Basis ! pe
Use the “pe” command to set oxidation state in the initial system in terms of pe.Example:
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, “fix”, and “slide”commands.
5.36 permeability
permeability <intercept = value | ?> <unit> \<porosity = value | ?> \
90
SpecE8 Commands
<mineral = value | ?>
Medium ! A (porosity)
B (intercept) darcy
add
You use the “permeability” command to set the correlation by which the programcalculates sediment permeability. SpecE8 calculates this value as a reported variableconsistent with X1t and X2t, but does not use it in its calculations.
The correlation gives log permeability in any of the units listed in the Units Recognized
appendix (darcys by default) as a linear function of the porosity (expressed as avolume fraction) of a nodal block and, optionally, the volume fractions of one or moreminerals.
Examples:
permeability intercept = -11 cm2 porosity = 15permeability Kaolinite = -8
The latter command adds a term for the mineral Kaolinite to the existing correlation.To remove a term from the correlation, set a value of “?”. The entry
permeability Kaolinite = ?
for example, removes the correlation entry for that mineral.The default correlation is
logk D �5C15�
where k is permeability in darcys and � is porosity (expressed as a fraction).
5.37 pH
pH = <value>
Basis ! pH
Use the “pH” command to set pH in the initial system. Example:
pH = 5
is equivalent to
91
GWB Reference Manual
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
5.38 phrqpitz
phrqpitz
File ! Open ! Thermo Data. . . ! thermo_phrqpitz.tdat
Use the “phrqpitz” command to set the program to calculate species’ activitycoefficients using the HarvieMøllerWeare equations, as implemented in the USGSprogram PHRQPITZ. Executing this command automatically sets the input dataset ofthermodynamic data to “thermo_phrqpitz.tdat”. Note that dataset “thermo_phrqpitz.tdat”is primarily intended to support calculations at or near 25°C.
5.39 pitz_dgamma
pitz_dgamma = <value | ?>
Config ! Iteration. . .
Use the “pitz_dgamma” command to control the relative change in an activity coefficient’svalue the program allows during each NewtonRaphson iteration, when a virial activitymodel (“the Pitzer equations”) has been invoked. By default, the program allows a10% change, which corresponds to a value of 0.1.
5.40 pitz_precon
pitz_precon = <value | ?>
Config ! Iteration. . .
Use the “pitz_precon” command to control the maximum number of passes the programtakes through the preconditioning loop before beginning a NewtonRaphson iteration,when a virial activity model (“the Pitzer equations”) has been invoked. By default, theprogram makes up to 10 passes. In cases of difficult convergence, counterintuitively,it can sometimes be beneficial to decrease this value.
92
SpecE8 Commands
5.41 pitz_relax
pitz_relax = <value | ?>
Config ! Iteration. . .
The “pitz_relax” command controls underrelaxation when evaluating a virial activitymodel (“the Pitzer equations”). The program at each NewtonRaphson iteration assignsactivity coefficients as a weighted average of the newly calculated value and thecorresponding value at the previous iteration level. Setting pitz_relax to zero eliminatesunderrelaxation, so the newly calculated values are used directly; a value of one, incontrast, should be avoided because it would prevent the activity coefficients frombeing updated. By default, the program carries an underrelaxation factor of 0.5.
5.42 pitzer
pitzer
File ! Open ! Thermo Data. . . ! thermo_pitzer.tdat
Use the “pitzer” command to set the program to calculate species’ activity coefficientsusing the Pitzer equations. Executing this command automatically sets the input datasetof thermodynamic data to “thermo_pitzer.tdat”. Note that dataset “thermo_pitzer.tdat”is intended to support calculations at or near 25°C.
5.43 plot
plot <character | bit | on | off>
Config ! Output. . .
Use the “plot” command to set the format of the “SpecE8_plot.gtp” dataset. The datasetcan be written in ascii characters, which are humanreadable and can be transferredsafely among computer systems, or as a bitstream, which is faster to read and write,more compact, and more accurate. The command “plot off” causes SpecE8 to bypasswriting calculation results to the “SpecE8_plot.gtp” dataset, which is used to pass inputto Gtplot. By default, the program writes output to the dataset. The command “ploton” (or just “plot”) reenables the output. To see the current setting, type “show print”.
93
GWB Reference Manual
5.44 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
5.45 porosity
porosity = <value | ?>
Medium ! porosity
Use the “porosity” command to set (as a volume fraction) the initial porosity of thesystem. Porosity, the fraction of the system occupied by fluid, is the ratio of fluidvolume to the sum of fluid, mineral, and inert volume.
The examples
porosity = 0.30porosity = 30%
are equivalent.When you specify the porosity, the program will figure the difference between the
volume of a system of the given porosity and fluid volume, and the volume takenup initially in the system by minerals and fluid. The program assigns this differenceas inert, nonreactive volume (see the “inert” command). In this case, the programignores any settings that may have been made with the “inert” command.
When you do not specify an initial porosity with the “porosity” command, on theother hand, the program calculates it from volumes in the system of fluid, minerals,and inert space. To restore this default behavior, enter the command with an argumentof “?”.
5.46 print
print <option> = <long | short | none>print <off | on>print <numeric | alphabetic>
94
SpecE8 Commands
Config ! Output. . .
Use the “print” command (also: “printout”) to control the amount of detail to be writteninto the “SpecE8_output.txt” dataset. For example, the dataset can contain informationabout each aqueous species, information on only species with concentrations greaterthan 10�8 molal, or no species information.
Options, which may be abbreviated to three letters, and their default settings are:
species longsurfaces longsaturations longgases longbasis noneorig_basis longelements longreactions nonestagnant none
The “print” command can also be used to arrange entries in the output dataset eithernumerically or alphabetically:
print numericprint alphabetic
To see the current print settings, type “show print”. Finally, the command “print off”causes SpecE8 to bypass writing calculation results to the “SpecE8_output.txt” dataset.By default, the program writes to the dataset. The command “print on” (or just “print”)reenables the output.
5.47 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
5.48 quit
quit
File ! Quit
95
GWB Reference Manual
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
5.49 ratio
ratio <species ratio> = <value>
Basis ! ratio
Use the “ratio” command to constrain an activity ratio in the initial system. Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
5.50 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Seawater
Control returns to the user after the script has been read unless the script containsa “quit”command. You can also use the “read” command in place of the “data” or“surface_data” command to read a thermo or surface reaction dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
5.51 remove
remove <basis specie(s)>
Basis ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries fromconsideration in the calculation. Example:
96
SpecE8 Commands
remove Na+remove Quartz Calcite
Components can be reentered into the basis using the “swap”, “add”, “activity”, and“fugacity” commands.
5.52 report
report <option>report set_digits <value>
Once the program has completed a calculation, you can use the “report” commandto return aspects of the calculation results. You can use this command from theCommand pane to query the program interactively. More significantly, the “report”command provides a means of communicating calculation results to control scriptsand external programs running GWB programs by remote control.
For arguments available, see the Report Command appendix to this GWB Reference
Manual. For details about control scripts and the plugin feature, see theControl Scripts and Plugin Feature appendices. Use the “set_digits” argument to setthe number of significant digits in the values reported, and the “set_node” argumentto identify the node of interest.
5.53 reset
resetreset systemreset variables
File ! Reset Configuration
Use the “reset” command to begin defining the chemical system again with a cleanslate. Your current settings will be lost, all options will be returned to their defaultstates. The command, however, does not alter the setting for the thermo dataset.The “reset system” command resets only the initial system. Similarly, typing “resetvariables” sets each settable variable to its default value.
5.54 resume
resume
File ! Resume
97
GWB Reference Manual
Use the “resume” command to restore the configuration from when you last exited theprogram. The program configuration is stored in a file “spece8_resume.sp8” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
5.55 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in SpecE8
format commands. The dataset can be used as an SpecE8 input script. Examples:
savesave kspar.sp8
If you don’t specify a dataset name, SpecE8 will ask for one.
5.56 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain notonly SpecE8 commands, but control structures such as loops and ifelse branches.Control scripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as wellas several widely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.sp8
within a control script.
5.57 show
show <option>show <species | minerals | surfaces> <with | w/> <basis entry | string>
Config ! Show. . .
98
SpecE8 Commands
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show gases show showshow altered show initial show speciesshow basis show suppressed show commandsshow minerals show surfaces show couplesshow oxides show system show directory
The command “show show” gives a list of show command options. When you type“show species”, “show minerals”, or “show surfaces”, the program lists all speciesor minerals in the thermo database. A long form of the “show species” and “showminerals” commands lets you set the basis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
5.58 simax
simax = <value | ?>
Config ! Iteration. . .
The “simax” command sets in molal units the maximum value of the stoichiometricionic strength used in calculating water activity when the DebyeHückel model isemployed. By default, this variable is set to 3 molal. To restore the default value, typethe command with no argument or with an argument of “?”. To see the current settingof this variable, type “show variables”.
5.59 sorbate
sorbate <exclude | include>
Config ! Iteration. . .
Use the “sorbate” command to tell the program, when considering sorption ontosurfaces (see the “surface_data” command), whether to include or exclude sorbedspecies in figuring the composition of the initial system. By default, the program does
99
GWB Reference Manual
not include sorbed species in this calculation. If you set the CaCC concentration to 15mg/kg, for example, the initial system would contain that amount in the fluid and anadditional amount sorbed onto mineral surfaces. If you type the command “sorbateinclude”, however, that amount would apply to the sum of the CaCC sorbed and insolution.
5.60 suffix
suffix <string>
Config ! Output. . .
Use the “suffix” command to alter the names of the output datasets (“SpecE8_output.txt”,“SpecE8_plot.gtp”, “Table1.txt”..., and “Btab1.txt”...) by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “SpecE8_output_run2.txt”.
5.61 suppress
suppress <species, surface_species>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species orsurface species from being considered in a calculation. Example:
suppress H3SiO4- >(s)FeOPb+
prevents the entries listed from being loaded from the database. The “unsuppress”command reverses the process.
5.62 surface_capacitance
surface_capacitance = <value | ?>surface_capacitance on <type> = <value | ?>
File! Open! Sorbing Surfaces. . . ! constant capacitance F/m2
Use this command (abbrev.: “surf_capacitance”) to set, in units of F/m2, the capacitanceof a sorbing surface. When you set this value (or if a value for capacitance is set inthe header of the surface reaction dataset), SpecE8 will model surface complexation
100
SpecE8 Commands
for the surface in question using the constant capacitance model, rather than the fulltwolayer model.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_capacitance on HFO = 2
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_potential” commands.
5.63 surface_data
surface_data <sorption dataset>surface_data remove <sorption dataset | surface type>surface_data OFF
File ! Open ! Sorbing Surfaces. . . ! add
File ! Open ! Sorbing Surfaces. . . ! select surface(s) ! delete
Use the “surface_data” command (abbrev.: “surf_data”) to specify an input datasetof surface sorption reactions to be considered in the calculation. The dataset nameshould be enclosed in quotes if it contains any unusual characters. Use the “remove”argument to eliminate a surface dataset, specified by name or surface type (e.g.,“HFO”), from consideration. The argument “OFF” disables consideration of all surfacecomplexes.
You can specify more than one sorbing surface in a model by repeating the“surface_data” command for different datasets (a dataset of surface reactions forsorption onto hydrous ferric oxide, as well as example datasets for the ion exchange,Kd , Freundlich, and Langmuir models are distributed with the software). To remove adataset of surface reactions from consideration, you use commands such as
surface_data remove FeOH.sdatsurface_data remove HFOsurface_data OFF
The latter command removes all of the surface datasets that have been loaded.
101
GWB Reference Manual
5.64 surface_potential
surface_potential = <value | ?>surface_potential on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant potential mV
Use this command (abbrev.: “surf_potential”) to set, in units of mV, the electricalpotential for a sorbing surface. When you set this value (or if a value is set in thesurface reaction dataset), SpecE8 will model surface complexation for the surface inquestion using the constant potential, rather than full twolayer, method.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_potential on HFO = 0
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_data” commands.
5.65 swap
swap <new basis> <for> <basis species>
Basis !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that you can alter to constrain the composition ofthe initial system. An aqueous species, mineral, gas, or activity ratio can be swappedinto the basis in place of one of the original basis species listed in the database.Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflect
102
SpecE8 Commands
enabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
5.66 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving SpecE8. Example:
system "copy SpecE8_output.txt SpecE8_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the SpecE8 command with a “$”:
$copy SpecE8_output.txt SpecE8_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
5.67 TDS
TDS = <value | ?>
Basis ! advanced ! TDS mg/kg
Use the “TDS” command to set in mg/kg the total dissolved solids for the initial fluid,if you don’t want the program to calculate this value automatically. The program usesthe TDS when needed to convert input constraints into molal units.
To restore automatic calculation of the TDS, type the command with no argumentor with an argument of “?”. To see the variable’s current setting, type “show variables”.
5.68 temperature
temperature = <value> <unit>
Basis ! temperature C
103
GWB Reference Manual
Use the “temperature” command (also: “T”) to set the temperature of the system. TheUnits Recognized appendix lists possible units, which default to “C”. Examples:
temperature 300 CT = 473 K
Temperature values can range over the span of the thermo dataset, from 0°C to 300°Cfor “thermo.tdat”; 25°C is the default.
5.69 timax
timax = <value | ?>
Config ! Iteration. . .
The “timax” command sets in molal units the maximum value of ionic strength used incalculating species’ activity coefficients when the DebyeHückel model is employed.By default, this variable is set to 3 molal. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
5.70 title
title <character string>
Config ! Output. . .
Use the “title” command to set a title to be passed to the graphics program. Example:
title "Yucca Mountain Groundwater"
Be sure to put multiword titles in quotes.
5.71 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
104
SpecE8 Commands
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
5.72 unsuppress
unsuppress <species, minerals, gases, surface_species | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies or surface species that have previously been suppressed. Examples:
unsuppress H3SiO4- >(s)FeOPb+unsuppress ALL
The argument “ALL” clears any species, that have been suppressed.
5.73 unswap
unswap <species | ALL>
Basis ! !
Use the “unswap” command to reverse a basis swap. Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
105
GWB Reference Manual
5.74 usgovt
usgovt
Help ! About SpecE8. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
5.75 volume
volume = <value | ?> <unit>
Medium ! bulk volume cm3
Use the “volume” (also “bulk_volume”) command to cause the program to scale thesystem to a specific size. By default, the program does not scale the system. In thiscase, the bulk volume Vb
Vb D Vf CVmn CVin CVstag (5.1)
is computed as the sum of the fluid volume Vf , mineral volume Vmn, inert volumeVin, and the volume Vstagof the stagnant zone, if one has been specified using the“dual_porosity” command.
If Xstag is the stagnant fraction of the system, which is zero if a dual porosity modelhas not been invoked, the above equation can be rewritten
�
1�Xstag
�
Vb D Vf CVmn CVin (5.2)
When you use the “volume” command to set the bulk volume Vb, the program scalesthe fluid volume Vf and optionally the mineral and inert volumes, Vmn and Vin, so thesystem fills the specified space.
The command
volume = 2 m3
for example, causes the program to scale the fluid volume Vf and optionally the mineraland inert volumes, Vmn and Vin, so the system occupies 2 m3. Default behavior, inwhich no scaling is performed, can be restored at any time with the command
volume = ?
The unit you use to constrain the amount of each mineral in the system controlswhether or not the program adjusts that mineral’s volume. If you constrain Quartz
106
SpecE8 Commands
to “10 cm3”, for example, Quartz will occupy 10 cm3 after scaling. Setting Quartz inrelative units such “volume%” or “mmol/m3”, in contrast, causes the program to fixthe mineral’s volume relative to Vb.
Similarly if you set inert volume in an absolute unit, such as
inert = 50 cm3
the program will honor that constraint and hold Vin steady. The inert portion of thesystem in this example will occupy 50 cm3 after scaling. The command
inert = 10 volume%
however, causes the program to scale the inert volume to 10% of the system’s bulkvolume.
107
108
React Commands
6.1 <unit>
<value> <free> <unit> <as element symbol> <basis entry>
Basis ! free kg
To constrain the initial system, enter a command containing only the above entries.Entries may appear in any order. The qualifier “free” specifies that the constraintapplies to the free rather than to the bulk basis entry. React recognizes the followingunits for constraining the initial system:
By mass or volume:mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 l
By concentration:mol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
By carbonate alkalinity (applied to bicarbonate component):eq_acid meq_acid ueq_acid neq_acideq_acid/kg meq_acid/kg ueq_acid/kg neq_acid/kgeq_acid/l meq_acid/l ueq_acid/l neq_acid/lg/kg_as_CaCO3 mg/kg_as_CaCO3 ug/kg_as_CaCO3 ng/kg_as_CaCO3wt%_as_CaCO3g/l_as_CaCO3 mg/l_as_CaCO3 ug/l_as_CaCO3 ng/l_as_CaCO3
Per volume of the system:mol/cm3 mmol/cm3 umol/cm3 nmol/cm3kg/cm3 g/cm3 mg/cm3 ug/cm3ng/cm3
109
GWB Reference Manual
mol/m3 mmol/m3 umol/m3 nmol/m3kg/m3 g/m3 mg/m3 ug/m3ng/m3volume% "vol. fract."
By activity:activity fugacity ratiopH V pe
Activity and fugacity may be abbreviated to “a” or “f”. Keyword “total” reverses a settingof “free”.
Use the “as” keyword to constrain mass in terms of elemental equivalents. Forexample, the command
CH3COO- = 10 umol/kg as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
20 mg/kg SO4-- as S
would specify 59.9 mg/kg of sulfate, since the ion’s mole weight is about 3 times thatof sulfur itself.
Examples:
55 mg/kg HCO3-Na+ = 1 molal1 ug/kg U++++100 free cm3 DolomitepH = 8Eh = .550 Vlog f O2(g) = -60HCO3- = 30 mg/kg as C
You may in a similar fashion constrain the concentration of a kinetic aqueous orsurface complex. For example, the commands
kinetic AlF++AlF++ = 1 umol/kg
set the concentration of the kinetic complex AlFCC to 1 �mol kg�1.
110
React Commands
6.2 activity
activity <species> = <value>
Basis ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies or water in the initial system. Examples:
activity Na+ = 0.3log a H+ = -5
See also the “pH”, “Eh”, “pe”, “ratio”, “fugacity”, “fix”, and “slide” commands.
6.3 add
add <basis species>
Basis ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “pH”, “pe”, and “Eh” commands.
6.4 alkalinity
alkalinity = <value> <unit>
Basis ! HCO3- mg/kg_as_CaCO3
Use the “alkalinity” command to constrain the total concentration of HCO�
3 to reflectthe solution’s carbonate alkalinity. You can specify one of the units listed in theUnits Recognized appendix; “mg/kg_as_CaCO3” is the default. To use this option,the solution pH must be set explicitly.
6.5 alter
alter <species | mineral | gas> <log K ’s>
Config ! Alter Log Ks. . .
111
GWB Reference Manual
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
6.6 balance
balance <on> <basis entry>balance <off>
Basis ! unit ! Balance species
Use the “balance” command to specify the basis entry to be used for electrical chargebalancing. The basis entry must be a charged aqueous species. By default, React
balances on Cl�.The command “balance off” disables React’s charge balancing feature. In this case,
the user is responsible for prescribing chargebalanced input constraints.
6.7 carbon
carbon <fluid | reactant | segregated mineral> = <value>
Config ! Isotopes. . .
Use the “carbon” command to set the 13C isotopic composition of the initial fluid,reactant species (aqueous species, minerals, or gases) or segregated minerals. Thecomposition may be set on any scale (e.g., PDB), but you must be consistent throughoutthe calculation. Example:
carbon fluid = -10, Calcite = +4
The commands
carbon removecarbon off
clear all settings for carbon isotopes from the calculation.
112
React Commands
6.8 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (abbrev.: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
6.9 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
6.10 clipboard
clipboard
Edit ! Copy
The “clipboard” command causes the contents of the Results pane to be copied tothe clipboard, from where it can be pasted into various types of documents.
6.11 conductivity
conductivity <conductivity dataset>
File ! Open ! Conductivity Data. . .
Use the “conductivity” command to change the input file of coefficients used to calculateelectrical conductivity. Example:
113
GWB Reference Manual
conductivity "..\my_conductivity.dat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.Beginning with GWB11, the applications compute electrical conductivity using eitherof two different approaches, the USGS and APHA methods; the USGS method is thedefault. The required coefficients are defined in the files “conductivityUSGS.dat” and“conductivityAPHA.dat”, respectively, which are installed in the same directory as thethermo datasets (commonly “\Program Files\GWB\Gtdata”).
6.12 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
6.13 cpr
cpr = <value | ?> <unit>
Medium ! cpr (minerals) cal/g/C
Use the “cpr” command to set the heat capacity of the rock (mineral) framework. Youcan specify one of the units listed in the Units Recognized appendix; “cal/g°C” is thedefault. This value is used during polythermal simulations in calculating the effectsof advective heat transport. The “transient” keyword causes the model to evaluatethe field variable continuously over the course of the simulation, if it is set with anequation, script, or function.
By default, this variable is set to 0.2 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
114
React Commands
6.14 cpu_max
cpu_max = <value | ?>
Config ! Stepping. . .
Use the “cpu_max” command to limit the amount of computing time a simulationmay take. You set the maximum computing time in seconds, or use a “?” to restorethe default state, which is no prescribed limit. To see the current setting, type “showvariables”.
6.15 cpw
cpw = <value | ?> <unit>
Medium ! cpw (fluid) cal/g/C
Use the “cpw” command to set in cal/g°C the heat capacity of the fluid. You can specifyone of the units listed in the Units Recognized appendix; “cal/g°C” is the default. Thisvalue is used during polythermal simulations in calculating the effects of advectiveheat transport. The “transient” keyword causes the model to evaluate the field variablecontinuously over the course of the simulation, if it is set with an equation, script, orfunction.
By default, this variable is set to 1.0 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
6.16 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
data "..\my_thermo.tdat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
115
GWB Reference Manual
6.17 debyehuckel
debye-huckel
File ! Open ! Thermo Data. . . ! thermo.tdat
The “debyehuckel” command (abbrev.: “dh”) sets the program to calculate species’activity coefficients using the extended DebyeHückel equations. Executing thiscommand automatically sets the input dataset of thermodynamic data to “thermo.tdat”.
6.18 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
6.19 delQ
delQ = <value | ?>
Config ! Stepping. . .
Use the “delQ” command to control the lengths of time steps taken in a simulationaccounting for reaction kinetics. The program limits how much the ion activity productQ can change over a step, for each kinetic reaction considered. The setting for “delQ”is the projected change �Q=Q allowed in the relative value of the activity product.You can set a larger value to permit longer time steps, or a smaller value to improvestability. The default setting is 0.1. Type the command with no argument or with anargument of “?” to restore the default. To see the current setting, type “show variables”.
116
React Commands
6.20 delxi
delxi = <value | ?> <linear | log>
Config ! Stepping. . .
Use the “delxi” command to set the maximum length (in terms of reaction progress,which varies from zero to one over the course of the simulation) of the reaction step,and to specify reaction stepping on a linear or logarithmic scale.
The command
delxi = .1 linear
for example, causes the program, in the absence of other constraints on the reactionstep, to take steps through reaction progress of .1, .2, .3, . . . , 1.0. Alternatively, thecommands
dx_init = .001delxi = .5 log
produce a path with steps .001, .003, .01, .03, .1, .3, and 1.0 (see the “dx_init”command).
By default, this variable is set to 0.01 and “linear”. To restore the default settings,type the command with no argument or with an argument of “?”. To see the currentsettings, type “show variables”.
6.21 density
density = <value | ?>density = <TDS | chlorinity>
Basis ! advanced ! density g/cm3 TDS chlorinity
You can use the “density” command to set in g/cm3 the fluid density the programuses to convert compositional constraints to molality, the concentration unit it carriesinternally. If you set the initial NaC composition in mg/l, for example, the programneeds to know the density of the initial fluid to determine NaC molality.
The program by default converts units using a density value it calculates automatically,as discussed below. This value is sufficient for most purposes, and hence it is generallynot necessary to set fluid density explicitly. You might, however, want to set the densityif you are working at high temperature, but your analysis is expressed per liter ofsolution at room temperature.
You can also use the “density” command to tell the program how to calculate thedefault density it uses to convert units, and the fluid density it reports in the simulation
117
GWB Reference Manual
results. The program normally figures density as that of an NaCl solution with thesame TDS as the fluid in question, at the temperature of interest. With the command“density = chlorinity” you can tell the program to instead use the density of an NaClsolution of equivalent chlorinity.
To restore automatic calculation, type the command with no argument or with anargument of “?”. To see the current setting of this variable, type “show variables”.
6.22 dual_porosity
dual_porosity = <on | off> <blocks | spheres | fractures> \<geometry = <blocks | spheres | fractures | ?>> \<volfrac = <field_variable | ?>> \<Nsubnode = <value | ?>> \<<half-width | radius> = <field_variable | ?> <unit>> \<diff_length = <field_variable | ?> <unit>> \<porosity = <field_variable | ?>> \<retardation = <field_variable | ?>> <steady | transient> \<diff_coef = <field_variable | ?> <unit>> <steady | transient> \<thermal_con = <field_variable | ?> <unit>> <steady | transient> \<theta = <value | ?>> <reset | ?>
Config ! Dual Porosity. . .
Use the “dual_porosity” command (abbrev: “dual”) to configure stagnant zones inthe simulation, using the dual porosity feature. Enable and disable the feature withthe “on” and “off” keywords. Disabling the feature does not affect other settings, soreenabling the feature returns the model to its most recent configuration.
With the “geometry” keyword, you configure the stagnant zone into blocks, spheres,or a fractured domain, the latter being slabs separated by fractures arrayed along thex direction. Alternatively, you can set the three configurations directly with keywords“blocks”, “spheres”, and “fractures”. Keyword “volfrac” sets the fraction of the nodalblock’s bulk volume occupied by the stagnant zone.
The “Nsubnode” (or “nx”) keyword sets the number of nodes into which the stagnantzone within each node will be divided when solving for solute and temperaturedistributions. The “halfwidth” (or “radius”, for spherical geometries) keyword setsthe zone’s characteristic dimension, in units of distance (see the Units Recognized
appendix; default is cm), and keyword “diff_length” sets the distance (same units) fromthe contact with the freeflowing zone over which the model will account for solutediffusion and heat conduction. Use keywords “porosity”, “retardation”, “diff_coef”, and“thermal_con” to set values for the porosity, retardation factor, diffusion coefficient,and thermal conductivity of the stagnant zone. The default unit for the diffusioncoefficient is cm2/s, and thermal conductivity defaults to cal/cm/s/°C units; see theUnits Recognized appendix for a list of options.
By default, the stagnant zone is configured in blocks divided into 5 subnodes. Youmust specify a value for the volume fraction of the stagnant zone, as well as one for
118
React Commands
the halfwidth (or radius); the diffusion length defaults to the latter value. The programuses whatever values are set for the freeflowing zone in the node in question asdefault values for the porosity, diffusion coefficient, and thermal conductivity of thestagnant zone; the retardation factor defaults to a value of one.
The “theta” keyword sets time weighting (0 � � � 1) for the numerical solution ofdiffusive transport within the stagnant zone. A weight � D 0 assigns the explicit method,and larger values invoke an implicit solution. By default, the program chooses �
automatically, using the explicit method unless it would force too many more timesteps than would otherwise be necessary. In that case, the program uses the implicitmethod (� D 0:6), which requires more computing effort per time step, but can takelong steps without becoming numerically unstable.
You can append the “transient” keyword when setting several of the parameters:the diffusion coefficient, thermal conductivity, and retardation factor. If the variableis defined by an equation, script, or external function, it will then be reevaluatedcontinuously over the course of the run.
As an example, the command
dual_porosity geometry = spheres, radius = 50 cm, volfrac = 75%
configures the stagnant zone into spheres of halfmeter radius that occupy threequarters of the domain. The command
dual_porosity reset
enables the feature after restoring default settings for each keyword.
6.23 dump
dump <off>
Config ! Stepping. . .
Use the “dump” command to eliminate minerals present at the beginning of the reactionbefore the program begins to trace the path. Use
dumpdump off
119
GWB Reference Manual
6.24 dx_init
dx_init = <value | ?>
Config ! Stepping. . .
Use the “dx_init” command to set the length of the initial time step. You set this valuein terms of reaction progress, which varies from zero to one over the course of thesimulation. By default, the variable is ignored. To restore the default state, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
6.25 dxplot
dxplot = <value | ?>
Config ! Output. . .
Use the “dxplot” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “React_plot.gtp”dataset. A value of zero causes the program to write the results after each stepin reaction progress. This variable setting does not apply to reactions paths withlogarithmic reaction stepping (see the “delxi” command), in which case all points inreaction progress are written to the plot dataset.
By default, this variable is set to 0.005. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
6.26 dxprint
dxprint = <value | ?>
Config ! Output. . .
Use the “dxprint” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “React_output.txt”dataset. A value of zero causes the program to write the results after each step inreaction progress, which can produce large amounts of output This variable settingdoes not apply to reactions paths with logarithmic reaction stepping (see the “delxi”command), in which case all points in reaction progress are written to the plot dataset.
By default, this variable is set to 0.01. To restore the default value, type the commandwith no argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
120
React Commands
6.27 Eh
Eh = <value> <unit>
Basis ! Eh
Use the “Eh” command to set Eh in the initial system. Example:
Eh = 200 mV
sets the system’s oxidation state to correspond to an Eh of 0.2 volt. See also the“activity”, “pH”, “pe”, “fugacity”, “fix”, and “slide” commands.
6.28 enddump
end-dump <off>
Config ! Stepping. . .
Use the “enddump” command (also: “enddump”) to eliminate minerals present at theend of the reaction path after the path has been traced. Use
end-dumpend-dump off
This operation can also be accomplished using the command “pickup fluid”.
6.29 epsilon
epsilon = <value | ?>
Config ! Iteration. . .
Use the “epsilon” command to set the convergence criterion (dimensionless) foriterating to a solution of the equations representing the distribution of chemical mass.By default, this variable is set to 5�10�11 . To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
6.30 exchange_capacity
exchange_capacity = <value | ?> <units>exchange_capacity on <type> = <value | ?> <units>
121
GWB Reference Manual
File ! Open ! Sorbing Surfaces. . . ! exchange capacity eq
Use the “exchange_capacity” command (abbrev.: “ex_capacity” or “exch_capacity”) toset the exchange capacitiy (i.e., the CEC) of the system when modeling ion exchangereactions or sorption according to Langmuir isotherms. For ion exchange reactions,you set units of electrical equivalents (“eq”, “meq”, and so on) or equivalents per gramof dry sediment (“eq/g”, “meq/g”, . . . ). For Langmuir reactions, you similarly set a valuein mole units: “mol”, “mmol”, “mol/g”, “mmol/g”. If you set units per gram of sediment,the program multiplies the value entered by the mass of rock in the system (includingequilibrium and kinetic minerals as well as inert volume) to get the system’s capacity.
If you read in a surface that sorbs by ion exchange or Langmuir isotherms, youmust set a value for its exchange capacity. If you have set more than one sorbingsurface (using the “surface_data” command), you identify the surface in question byits “type”. For example
exchange_capacity on IonEx = .0008 eq/g
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the surface represented by the sample dataset “IonEx.sdat”,for example, is “IonEx”. You can use the “show” command to display the “type” ofeach active surface. See also the “surface_data” and “inert” commands.
6.31 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula and mole volume) about species, minerals, and gasesin the dataset. Example:
explain Analcime
6.32 explain_step
explain_step <off>
Config ! Stepping. . .
122
React Commands
The “explain_step” option causes the program to report on the Results pane the factorcontrolling the length of each time step, whenever the step size is limited by the needto maintain numerical stability.
6.33 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . .
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of dataprovided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation.
When the “extrapolate” option is invoked, the program will estimate log K ’s asfunctions of temperature by making a polynomial fit to the data provided. Use thisoption with considerable care.
6.34 fix
fix <unit> <species | gas>
Reactants ! add !
Use the “fix” command to hold the activity of a species, fugacity of a gas, or an activityratio constant over the course of a run. The <unit> can be “activity” or “fugacity” (“a”or “f” for short), “ratio”, “pH”, “pe”, or “Eh”, or it can be omitted. Examples:
fix pHfix a H+fix f O2(g)fix ratio Ca++/Na+^2
123
GWB Reference Manual
6.35 flash
flash <on | off | fluid | system>
Config ! Stepping. . .
Use the “flash” command to set a “flash” model in which the original fluid (or fluid andminerals, if keyword “system” is used) is removed over the course of the reaction path.Keywords “on” and “fluid” are synonymous. The command “flash” without an argumentis the same as “flash fluid”. Generally, the fluid is replaced by a reactant fluid. Use
flashflash systemflash off
6.36 flowthrough
flow-through <off>
Config ! Stepping. . .
Use the “flowthrough” command to turn on or off the flowthrough option by whichmineral precipitates are isolated from backreaction. Use
flow-throughflow-through off
6.37 flush
flush <off>
Config ! Stepping. . .
Use the “flush” command to turn on or off the flush option by which fluid reactantsdisplace existing fluid from the system over the course of the reaction path. Use
flushflush off
124
React Commands
6.38 fugacity
fugacity <gas> = <value>
Basis ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) inthe initial system. Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
See also the “activity”, “ratio”, “pH”, “Eh”, “pe”, “fix”, and “slide” commands.
6.39 go
go
Run ! Go
Results ! Run
Use the “go” command to initiate calculation of a model based on the currentconfiguration.
6.40 grep
grep <string>
File ! View ! .\React_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “React_output.txt” (or the current output dataset, asmodified by the “suffix” command) containing the string “Albite”.
125
GWB Reference Manual
6.41 gtplot
gtplot <gtplot options>
Run ! Gtplot
The “gtplot” command launches program Gtplot from the React command line, invokinginput from the current graphics interface dataset (by default, “React_plot.gtp”; see the“suffix” command). For example,
gtplot piper
starts Gtplot with a Piper diagram as the initial plot.
6.42 hmw
h-m-w
File ! Open ! Thermo Data. . . ! thermo_hmw.tdat
Use the “hmw” command (abbrev.: “hmw”) to set the program to calculate species’activitycoefficientsbyusingtheHarvieMøllerWeareequations.Executingthiscommandautomatically sets the input dataset of thermodynamic data to “thermo_hmw.tdat”.Note that dataset “thermo_hmw.tdat” supports calculations at 25°C only.
6.43 heat_source
heat_source = <field_variable | ?> <unit> <steady | transient> \<temp_min = <value | ?> <C>> <temp_max = <value | ?> <C>>
Medium ! internal heat source
temperature: minimum C maximum C
cal/cm3/s
Use the “heat_source” command (also: “heat_src”) to set the rate of internal heatproduction within the medium. You can specify one of the units listed in theUnits Recognized appendix; “cal/cm3/s” is the default. The “transient” keyword causesthe model to evaluate the field variable continuously over the course of the simulation,if it is set with an equation, script, or function. By default, the program does not accountfor internal heat production. The “?” argument resets the default value of zero.
The “temp_min” and “temp_max” keywords (also: “tempmax”, “tempmin”) set theallowable temperature range for the simulation. These values serve two purposes.
126
React Commands
First, the simulation will give an error message and stop if temperature at anypoint in the domain falls more than 5°C less than the minimum value, or exceeds themaximum value by more than this amount.
Second, unless the “extrap” option is set, the model will load for the simulation onlythose species for which log K values are available in the thermodynamic dataset overthe allowable temperature range. Values for the keywords default to the temperaturespan of the thermodynamic database, as set in the database header.
6.44 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
6.45 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands, and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
6.46 hydrogen
hydrogen <fluid | reactant | segregated mineral> = <value>
Config ! Isotopes. . .
Use the “hydrogen” command to set the 2H isotopic composition of the initial fluid,reactant species (aqueous species, minerals, or gases) or segregated minerals. Thecomposition may be set on any scale (e.g., SMOW), but you must be consistentthroughout the calculation. Example:
hydrogen fluid = -120, Muscovite = -40
The commands
127
GWB Reference Manual
hydrogen removehydrogen off
clear all settings for hydrogen isotopes from the calculation.
6.47 inert
inert = <field_variable | ?> <units>
Medium ! inert volume cm3
Use the “inert” command to set the volume of nonreacting space in the system. Youmay set a value in units of volume, including cm3, m3, and l, as well as volume%and “vol. fract.”. The default setting is zero and the default unit is cm3.
Assuming you have not set a value for the initial fluid fraction in the system using the“porosity” command, the program figures the porosity over the course of the calculationas a derived variable. Specifically, it divides the fluid volume by the sum of the fluidvolume, mineral volume, and inert volume, and reports this value as a result.
When you have set a value for initial porosity with the “porosity” command, on theother hand, the program works in the contrary sense. In this case, it calculates theinert volume as that required to form a system of the specified initial porosity; theprogram now ignores any entry you may have set using the “inert” command.
To restore the default state, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show”.
6.48 isotope
isotope <dataset>
File ! Open ! Isotope Data. . .
Use the “isotope” command (also: “idata”) to set the name of the database containingisotope fractionation factors for species, minerals, and gases. Example:
isotope Isotope.mydata
6.49 itmax
itmax = <value | ?>
Config ! Iteration. . .
128
React Commands
Use the “itmax” command to set the maximum number of iterations that may be takenin an attempt to converge to a solution for the equations representing the distributionof chemical mass. By default, this variable is set to 400. To restore the default value,type the command with no argument or with an argument of “?”. To see the currentsetting of this variable, type “show variables”.
6.50 itmax0
itmax0 = <value | ?>
Config ! Iteration. . .
Use the “itmax0” command to set the maximum number of iterations that may be takenin an attempt to converge to a solution for the equations representing the distributionof chemical mass in the initial chemical system. By default, this variable is set to 999.To restore the default value, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show variables”.
6.51 Kd
Kd <off>
Config ! Iteration. . .
The “Kd” command controls whether the program calculates Kd distribution coefficientsfor sorbing components, in units of liters per kg sediment mass. This calculationrequires that the mineral mass in the system (as specified for individual mineralsand/or in terms of inert volume) be set correctly.
6.52 kinetic
kinetic <species | mineral | gas> <variable> = <value>kinetic <species | mineral | gas> <variable> = <field_variable> \
<steady | transient>kinetic <species | mineral | gas> <apower | mpower(species)> = <value>kinetic <redox(label)> <variable> = <value>kinetic <redox(label)> <variable> = <field_variable> <steady | transient>kinetic <redox(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <variable> = <value>kinetic <microbe(label)> <variable> = <field_variable> <steady | transient>kinetic <microbe(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <apower | mpower(species)> = <value> \
<apowerA | mpowerA(species)> = <value> \<apowerD | mpowerD(species)> = <value>
129
GWB Reference Manual
Reactants ! add !
Use the “kinetic” command to set variables defining a kinetic rate law for (1) dissolutionor precipitation of any mineral in the initial system or reactant list, (2) the associationor dissociation of any aqueous or surface complex in the system modeled, (3) thetransfer of gases into or out of an external reservoir, (4) a redox reaction, includingthose promoted by catalysis or enzymes, or (5) a microbial metabolism.
In the first three cases, you identify the kinetic reaction by the name of the species,mineral, or gas involved. In the case of a redox reaction, you set a label that beginswith the characters “redox”, such as “redox1” or “redoxFe”. For a microbial reaction,set a label that starts with “microbe”, such as “microbeEcoli”.
The rate law you specify in a “kinetic” command, by default, applies to the dissolutionof a mineral, dissociation of a complex, dissolution of a gas, or forward progress of aredox or microbial reaction. The synonymous keywords “forward”, “dissolution”, and“dissociation” set this behavior. Including in a “kinetic” command the keyword “reverse”or its synonyms “precipitation”, “complexation”, “association”, or “exsolution” invokesthe opposite behavior. In this case, the rate law applies to the reverse reaction: mineralprecipitation, complex association, or gas exsolution.
You can append the “transient” keyword when setting the following field variables:rate constant, specific surface area, activation energy, preexponential factor, nucleusarea, and critical saturation index. If the variable is defined by an equation, script, orexternal function, it will then be reevaluated continuously over the course of the run.
See also the “react” and “remove reactant” commands.
The following paragraphs apply to all types of kinetic reactions. You set the rate constant either directly using the “rate_con” keyword, or by setting an activation energyand preexponential factor with keywords “act_en” and “preexp”. In the absence ofpromoting and inhibiting species (see next paragraph), you set the rate constant andpreexponential factor in (1) mol/cm2 sec for mineral and gas transfer reactions, (2)molal/sec or molal/cm2 sec (the latter when accounting for heterogeneous catalysis)for complexation and redox reactions, and (3) mol/mg sec for microbial reactions. Theactivation energy is specified in J/mol. Example:
kinetic "Albite low" rate_con = 1e-15
130
React Commands
You can set “rate_con”, “act_en”, and “preexp” as field variables (see the Heterogeneity
appendix to the GWB Reactive Transport Modeling Guide).You use the “apower” or “mpower” (also “apow” or “mpow”) keyword to specify
any promoting or inhibiting species in the kinetic rate law. Keyword “apower” setsthe exponent of a species activity, and “mpower” the exponent of a species molality.Promoting species have positive powers, and the powers of inhibiting species arenegative. For example, the command
kinetic "Albite low" apower(H+) = 1
sets HC as a promoting species, the activity of which is raised to a power of one. Youcan use aqueous species, gas species (represented by fugacity), surface complexes(molal concentration), and solvent water (activity) as promoting and inhibiting species.
The “order1” and “order2” keywords set nonlinear rate laws. Keyword “order1”represents the power of the Q=K term, and “order2” represents the power of the (1 Q=K/ term.
Use the “rate_law” keyword to set the form of the kinetic rate law for a specificmineral, redox reaction, or microbial metabolism. You may set the keyword equal to (1)a character string containing the rate law, (2) the name of a file containing a basiclikescript, or (3) the name of a function in a library. The name of a file containing a ratelaw script must end in “.bas”. To specify a function from a library, set the name of adynamic link library (DLL) separated from the function name by a colon (“:”), such as“rate_laws.dll:my_ratelaw”; the library file must end in “.dll”. To return to the program’sbuiltin rate law, enter “rate_law = off” or “rate_law = ?”.
The following paragraphs apply to dissolution and precipitation reactions. You set the
specific surface area of a kinetic mineral (in cm2/g) with the “surface” keyword. Forexample,
kinetic "Albite low" surface = 1000
The “crossaffinity” option lets you use the saturation state of one mineral to modelthe reaction rate of another, as is sometimes useful for example in studying glassdissolution. To do so, you use the “xaffin” option. For (a hypothetical) example, thecommand
kinetic Quartz xaffin = Cristobalite
causes the program to calculate the reaction rate of quartz according to the fluid’ssaturation state with respect to cristobalite. The command
kinetic Quartz xaffin = OFF
turns off the option.
131
GWB Reference Manual
Finally, you use the “nucleus” and “critSI” keywords to set the area available fornucleation (in cm2/cm3 fluid volume) and the critical saturation index above which themineral can nucleate. Each of these values, by default, is zero.
Keywords “surface”, “nucleus”, and “critSI” can be set as field variables (see theHeterogeneity appendix to the GWB Reactive Transport Modeling Guide).
The following paragraphs apply to reactions for aqueous and surface complexes.When you specify a kinetic reaction for the association of an aqueous complex orsurface complex, or its dissociation, you can set the complex’s initial concentrationdirectly. The concentration can be set heterogeneously, as a field variable. If you donot specify an initial concentration, or set an entry of “?”, the program takes thecomplex at the start of the simulation to be in equilibrium with the initial fluid.
You specify the initial concentration within a “kinetic” command or as a separatecommand line. For example, the commands
kinetic AlF++ rate_con = 3.3e-6, mpow(AlF++) = 1AlF++ = 1 umol/kg
are equivalent to
kinetic AlF++ 1 umol/kg rate_con = 3.3e-6, mpow(AlF++) = 1
Either case defines a kinetic reaction for decomposition of the AlFCC ion pair, settingit initially to a free concentration of 1 �mol kg�1.
The following paragraphs apply to gas transfer reactions. Use the “f_ext” keyword tospecify the fugacity of the gas in question in the external reservoir, and keyword“contact” to set, in cm2/kg of water, the contact area between fluid and externalreservoir. Example:
kinetic CO2(g) f_ext = 10^-3.5, contact = 10
Both values can be set as field variables, as described in the Heterogeneity appendixto the GWB Reactive Transport Modeling Guide.
If you do not set a value for the gas’ external fugacity, or set “f_ext = ?”, the programuses the fugacity in the initial fluid, at the start of the simulation, and the externalfugacity.
The following paragraphs apply to redox reactions. You set the form of the redoxreaction to be considered as a character string, using the “rxn” (or “reaction”) keyword.For example,
kinetic redox-1 rxn = "Fe++ + 1/4 O2(aq) + H+ -> Fe+++ + 1/2 H2O"
To specify that the reaction be promoted by a heterogeneous catalyst, set keyword“catalyst” to the name of the catalyzing mineral, or simply to “on”. In the former case,
132
React Commands
you use keyword “surface” to set the specific surface area of the catalytic mineral (incm2/g). If you have set “catalyst = on”, however, you use the “surface” keyword to settotal catalytic area, in cm2. Setting “catalyst = off” disables the catalysis feature.
To set an enzymatically promoted reaction, set keyword “me” to the name of theaqueous species serving as the enzyme, or simply to the value to be used as theenzyme’s molality. In the former case, the program tracks the enzyme molality mE
over the course of the simulation from the calculated distribution of species. If youhave set a numeric value for mE using the “mE” keyword, the program uses this valuedirectly. You may alternatively specify the enzyme species or its activity aE usingkeyword “aE”, in which case variables mE , mA, and mP in the rate law are replacedby the activities aE , aA, and aP .
For an enzymatic reaction, you further set the halfsaturation constants KA and KP
for the forward and reverse reactions in molal with the “KA” and “KP” keywords. Youmust set a value for KA, but may omit KP , in which case the mP /KP term in the ratelaw will be ignored. Setting “enzyme = off” disables the enzyme feature.
The following paragraphs apply to microbial reactions.Yousettheformofthemetabolicreaction using the “rxn” (or “reaction”) keyword, in the same manner as with redoxreactions. For example,
kinetic microbe-1 rxn = "CH4(aq) + 2 O2(aq) -> HCO3- + H+ + H2O"
Set the halfsaturation constants KD and KA for the electron donating and acceptingreactions with the “KD” and “KA” keywords. These values default to zero.
You set the powers of species in the numerator of the rate law with the “mpower”keyword, as with other types of kinetic reactions. Use keywords “mpowerD” and“mpowerA” (or “mpowD” and “mpowA”) to set the powers PD, etc., of species from theelectron accepting and donating reactions, respectively, within the product functionsin the rate law’s denominator. For example,
kinetic microbe-1 mpower(CH4(aq)) = 1, mpowerD(CH4(aq)) = 1
sets the power of the electrondonating species CH4(aq) to one in both the rate lawnumerator and denominator. Keywords “PKD” and “PKA” set the overall powers PKD
and PKA of the electron donating and accepting terms in the denominator of the ratelaw; by default, these are one.
You set the free energy �GATP of ATP hydrolysis (in kJ/mol) with the “ATP_energy”keyword, and the value of nATP with keyword “ATP_number”. These values default tozero.
Use the “biomass” keyword to set the initial biomass concentration, in mg/kg. Youcan set this value as a field variable (see the Heterogeneity appendix to the GWB
Reactive Transport Modeling Guide).The “growth_yield” keyword sets the microbe’s growth yield in mg biomass/mol of
reaction progress, and “decay_con” sets its decay constant in sec�1; both valuesdefault to zero.
133
GWB Reference Manual
6.53 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
log fugacity O2(g) = -65log activity U++++ = -10
6.54 mobility
mobility = <surface_type> <field_variable> <steady | transient>
File ! Open ! Sorbing Surfaces. . . ! mobility
Use the “mobility” command to set up a complexing surface in your model as amobile colloid. A mobile colloid is composed of the mineral (or minerals) associatedwith a complexing surface, as well as the ion complexes present on that surface.Only datasets with model type “twolayer” as set in the dataset header are surfacecomplexation models, and hence only those datasets can be used to form a mobilecolloid.
Mobility refers to the fraction of the surface in question that can move in the modelby advection and dispersion. A surface with a mobility of one moves freely, whereasa mobility of zero sets the surface to be stationary. Intermediate values arise, forexample, when some of the surface is attached to the medium, or when colloid motionis impeded by electrostatic interactions. By default in the software the mobility of anysurface is zero.
To set a mobile colloid, begin by reading in a surface complexation dataset using the“surface_data” command. Then, use the “mobility” command, referencing the surface’slabel, to set the colloid’s mobility. The label is given at the head of the surface dataset,on a line beginning “Surface type”. The label in dataset “FeOH.sdat”, for example, is“HFO”. If you omit the label, the program will assume you are referring to the surfacecomplexation dataset most recently read.
You can define the mobility as a field variable, which means you can have theprogram calculate mobility using an equation, script, or compiled function you provide.When you set the “transient” keyword, the program upon undertaking each time stepin the simulation evaluates mobility at each nodal block. In the “steady” case, whichis the default, the program evaluates mobility at each block just once, at the start ofthe run.
Example:
134
React Commands
surface_data FeOH.sdatmobility HFO = 100%
where “HFO” is the label for the surface defined by dataset “FeOH.sdat”.Restore the default behavior of immobility by entering a command such as
mobility HFO ?
6.55 noprecip
no-precip <off>
Config ! Iteration. . .
Usethe“noprecip”command(also:“noprecip”) topreventnewmineralsfromprecipitatingover the course of a simulation. By default, they are allowed to precipitate. Use:
no-precipno-precip off
See also the “precip” command.
6.56 nswap
nswap = <value | ?>
Config ! Iteration. . .
Use the “nswap” command to set the maximum number of times that the program mayswap entries in the basis in an attempt to converge to a stable mineral assemblage. Bydefault, this variable is set to 30. To restore the default value, type the command withno argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
6.57 nswap0
nswap0 = <value | ?>
Config ! Iteration. . .
135
GWB Reference Manual
Use the “nswap0” command to set the maximum number of times that the program mayswap entries in the basis in an attempt to converge to a stable mineral assemblagefor the initial system. By default, this variable is set to 200. To restore the defaultvalue, type the command with no argument or with an argument of “?”. To see thecurrent setting of this variable, type “show variables”.
6.58 oxygen
oxygen <fluid | reactant | segregated mineral> = <value>
Config ! Isotopes. . .
Use the “oxygen” command to set the 18O isotopic composition of the initial fluid,reactant species (aqueous species, minerals, or gases) or segregated minerals. Thecomposition may be set on any scale (e.g., SMOW), but you must be consistentthroughout the calculation. Example:
oxygen fluid = -10, Quartz = 15
The commands
oxygen removeoxygen off
clear all settings for oxygen isotopes from the calculation.
6.59 pause
pause
Use the “pause” command to cause React to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
6.60 pe
pe = <value>
Basis ! pe
Use the “pe” command to set oxidation state in the initial system in terms of pe.Example:
136
React Commands
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, “fix”, and “slide”commands.
6.61 permeability
permeability <intercept = field_variable | ?> <unit> <steady | transient> \<porosity = field_variable | ?> <steady | transient> \<mineral = field_variable | ?> <steady | transient>
Medium ! A (porosity)
B (intercept) darcy
add
You use the “permeability” command to set the correlation by which the programcalculates sediment permeability. React calculates this value as a reported variableconsistent with X1t and X2t, but does not use it in its calculations.
The correlation gives log permeability in any of the units listed in the Units Recognized
appendix (darcys by default) as a linear function of the porosity (expressed as avolume fraction) of a nodal block and, optionally, the volume fractions of one or moreminerals. The “transient” keyword causes the model to evaluate the coefficient inquestion continuously over the course of the simulation, if it is set with an equation,script, or function.
Examples:
permeability intercept = -11 cm2 porosity = 15permeability Kaolinite = -8
The latter command adds a term for the mineral Kaolinite to the existing correlation.To remove a term from the correlation, set a value of “?”. The entry
permeability Kaolinite = ?
for example, removes the correlation entry for that mineral.The default correlation is
logk D �5C15�
137
GWB Reference Manual
where k is permeability in darcys and � is porosity (expressed as a fraction).
6.62 pH
pH = <value>
Basis ! pH
Use the “pH” command to set pH in the initial system. Example:
pH = 5
is equivalent to
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
6.63 phrqpitz
phrqpitz
File ! Open ! Thermo Data. . . ! thermo_phrqpitz.tdat
Use the “phrqpitz” command to set the program to calculate species’ activitycoefficients using the HarvieMøllerWeare equations, as implemented in the USGSprogram PHRQPITZ. Executing this command automatically sets the input dataset ofthermodynamic data to “thermo_phrqpitz.tdat”. Note that dataset “thermo_phrqpitz.tdat”is primarily intended to support calculations at or near 25°C.
6.64 pickup
pickup <system => <entire | fluid>pickup reactants = <entire | fluid | minerals>
Run ! Pickup
Use the “pickup” command to take the results of a reaction path as the starting pointfor a new reaction path. You may pick up the entire system, or just the fluid or mineralsresulting from a reaction path, and use this as your new initial system or reactant list.Default choices are “system” and “entire”. Examples:
138
React Commands
pickuppickup fluidpickup reactantspickup reactants = minerals
When you do a simple “pickup” (i.e., “pickup system = entire”), the program retainswithin the system all kinetic reactions that were defined in the original path, at thereactions’ endpoint state. A “pickup fluid” (fully, “pickup system = fluid”) commandretains only the kinetic reactions occurring in the fluid – the kinetic redox and aqueouscomplexation reactions – in the new reaction path; kinetic reactions involving minerals,surfaces, a gas phase, or microbes are discarded.
Picking up the entire endpoint system, or just the endpoint minerals, as reactants(i.e., “pickup reactants” or “pickup reactants = minerals”) causes the program to retainthe kinetic reactions involving mineral precipitation and dissolution. In these cases,the other types of kinetic reactions are discarded. The command “pickup reactants =fluid” causes the program to discard any kinetic reactions that may be set.
The commands
pickup TDSpickup density
are obsolete, because releases 7.0 and later of the software calculate the TDS anddensity automatically.
6.65 pitz_dgamma
pitz_dgamma = <value | ?>
Config ! Iteration. . .
Use the “pitz_dgamma” command to control the relative change in an activity coefficient’svalue the program allows during each NewtonRaphson iteration, when a virial activitymodel (“the Pitzer equations”) has been invoked. By default, the program allows a10% change, which corresponds to a value of 0.1.
6.66 pitz_precon
pitz_precon = <value | ?>
Config ! Iteration. . .
Use the “pitz_precon” command to control the maximum number of passes the programtakes through the preconditioning loop before beginning a NewtonRaphson iteration,
139
GWB Reference Manual
when a virial activity model (“the Pitzer equations”) has been invoked. By default, theprogram makes up to 10 passes. In cases of difficult convergence, counterintuitively,it can sometimes be beneficial to decrease this value.
6.67 pitz_relax
pitz_relax = <value | ?>
Config ! Iteration. . .
The “pitz_relax” command controls underrelaxation when evaluating a virial activitymodel (“the Pitzer equations”). The program at each NewtonRaphson iteration assignsactivity coefficients as a weighted average of the newly calculated value and thecorresponding value at the previous iteration level. Setting pitz_relax to zero eliminatesunderrelaxation, so the newly calculated values are used directly; a value of one, incontrast, should be avoided because it would prevent the activity coefficients frombeing updated. By default, the program carries an underrelaxation factor of 0.5.
6.68 pitzer
pitzer
File ! Open ! Thermo Data. . . ! thermo_pitzer.tdat
Use the “pitzer” command to set the program to calculate species’ activity coefficientsusing the Pitzer equations. Executing this command automatically sets the input datasetof thermodynamic data to “thermo_pitzer.tdat”. Note that dataset “thermo_pitzer.tdat”is intended to support calculations at or near 25°C.
6.69 plot
plot <character | bit | on | off>
Config ! Output. . .
Use the “plot” command to set the format of the “React_plot.gtp” dataset. The datasetcan be written in ascii characters, which are humanreadable and can be transferredsafely among computer systems, or as a bitstream, which is faster to read and write,more compact, and more accurate. The command “plot off” causes React to bypasswriting calculation results to the “React_plot.gtp” dataset, which is used to pass inputto Gtplot. By default, the program writes output to the dataset. The command “ploton” (or just “plot”) reenables the output. To see the current setting, type “show print”.
140
React Commands
6.70 pluses
pluses <off>
Config ! Stepping . . .
Use the “pluses” command to cause React to simply output a plus sign (“+”) eachtime it iterates to a solution, rather than printing a banner showing the number ofiterations required and final residual value.
6.71 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
6.72 porosity
porosity = <field_variable | ?>
Medium ! porosity
Use the “porosity” command to set (as a volume fraction) the initial porosity of thesystem. Porosity, the fraction of the system occupied by fluid, is the ratio of fluidvolume to the sum of fluid, mineral, and inert volume.
The examples
porosity = 0.30porosity = 30%
are equivalent.When you specify the porosity, the program will figure the difference between the
volume of a system of the given porosity and fluid volume, and the volume takenup initially in the system by minerals and fluid. The program assigns this differenceas inert, nonreactive volume (see the “inert” command). In this case, the programignores any settings that may have been made with the “inert” command.
141
GWB Reference Manual
When you do not specify an initial porosity with the “porosity” command, on theother hand, the program calculates it from volumes in the system of fluid, minerals,and inert space. To restore this default behavior, enter the command with an argumentof “?”.
6.73 precip
precip <off>
Config ! Iteration. . .
Use the “precip off” command to prevent new minerals from precipitating over thecourse of a simulation. By default, they are allowed to precipitate. Use
precipprecip off
See also the “noprecip” command.
6.74 print
print <option> = <long | short | none>print <off | on>print <numeric | alphabetic>
Config ! Output. . .
Use the “print” command (also: “printout”) to control the amount of detail to be writteninto the “React_output.txt” dataset. For example, the dataset can contain informationabout each aqueous species, information on only species with concentrations greaterthan 10�8 molal, or no species information.
Options, which may be abbreviated to three letters, and their default settings are:
species shortsurfaces longsaturations shortgases longbasis noneorig_basis longelements longreactions nonestagnant none
The “print” command can also be used to arrange entries in the output dataset eithernumerically or alphabetically:
142
React Commands
print numericprint alphabetic
To see the current print settings, type “show print”. Finally, the command “printoff” causes React to bypass writing calculation results to the “React_output.txt” and“React_isotope.txt” datasets. By default, the program writes to the datasets. Thecommand “print on” (or just “print”) reenables the output.
6.75 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
6.76 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
6.77 ratio
ratio <species ratio> = <value>
Basis ! ratio
Use the “ratio” command to constrain an activity ratio in the initial system. Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
143
GWB Reference Manual
6.78 react
react <amount> <unit> <as <element symbol>> \<species | mineral | gas> <cutoff> = <value>
Reactants ! add !
Use the “react” command (abbrev.: “rct”) to define the reactants for the currentsimulation. (To set a kinetic rate law for a reactant, use the “kinetic” command.) Unitsfor the amount of reactant to add over a reaction path can be:
mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 lmol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
Units of mass or volume can be expressed per volume of the porous medium. Examples:
mol/cm3 g/cm3mmol/m3 ug/m3volume% "vol. fract"
Units of mass or volume can be set as absolute rates by appending “/s”, “/day”, “/yr”,or “/m.y.”. For example,
mmol/s g/day cm3/yrmol/kg/s mg/kg/day cm3/kg/yr
Use the “as” keyword to specify reactant masses as elemental equivalents. Forexample, the command
react 10 umol/kg CH3COO- as C
144
React Commands
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
react 20 mg/kg SO4-- as S
would cause the program to add 59.9 mg/kg of sulfate, since the ion’s mole weight isabout 3 times that of sulfur itself.
You can set a cutoff to limit the amount of a reactant. For example, if you set theamount of a reactant to two moles and set a cutoff of one, then React will add onemole of the reactant over the first half of the path and none over the second half.Enter the cutoff value in the same units as the amount of reactant. Examples:
react 10 grams Quartzreact 1e-2 mol Muscovite cutoff = .5e-2react .01 mol/day HCl
See also the “kinetic” and “remove reactant” commands.
6.79 reactants
reactants times <value>
Reactants ! reactants times
Use the “reactants” command to vary the total amounts of the reactants by a givenfactor. Example:
reactants times 1/10
6.80 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Seawater
Control returns to the user after the script has been read unless the script containsa “quit”command. You can also use the “read” command in place of the “data” or“surface_data” command to read a thermo or surface reaction dataset.
145
GWB Reference Manual
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
6.81 remove
remove <basis specie(s)> <reactant(s)>remove basis <basis specie(s)>remove reactant <reactant(s)>
Basis ! select entry(ies) ! delete
Reactants ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries orreactants from consideration in the calculation. Example:
remove Na+remove Quartz Calciteremove reactant H2O
Components can be reentered into the basis using the “swap”, “add”, “activity”, and“fugacity” commands.
6.82 report
report <option>report set_digits <value>
Once the program has completed a calculation, you can use the “report” commandto return aspects of the calculation results. You can use this command from theCommand pane to query the program interactively. More significantly, the “report”command provides a means of communicating calculation results to control scriptsand external programs running GWB programs by remote control.
For arguments available, see the Report Command appendix to this GWB Reference
Manual. For details about control scripts and the plugin feature, see theControl Scripts and Plugin Feature appendices. Use the “set_digits” argument to setthe number of significant digits in the values reported, and the “set_node” argumentto identify the node of interest.
6.83 reset
resetreset system
146
React Commands
reset reactantsreset variables
File ! Reset Configuration
Use the “reset” command to begin defining the chemical system again with a cleanslate. Your current settings will be lost, and all options will be returned to their defaultstates. The command, however, does not alter the setting for the thermo dataset.The “reset system” command resets only the initial system. Similarly, typing “resetreactants” resets the reactant system, and “reset variables” sets each settable variableto its default value.
6.84 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exitedthe program. The program configuration is stored in a file “react_resume.rea” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
6.85 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in Reactformat commands. The dataset can be used as an React input script. Examples:
savesave kspar.rea
If you don’t specify a dataset name, React will ask for one.
6.86 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not only
147
GWB Reference Manual
React commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.rea
within a control script.
6.87 segregate
segregate <mineral(s)>segregate <mineral> <value>segregate <mineral> <initial_value> <final_value>segregate <mineral> <value> Xi = <value> <value> Xi = <value>
Config ! Isotopes. . . ! add
Config ! Isotopes. . . ! select entry(ies) ! delete
The “segregate” command causes minerals to be isolated from isotopic exchange overthe course of a reaction path. By default, a mineral in the equilibrium system remainsin isotopic equilibrium with the fluid and other minerals. A segregated mineral, on theother hand, changes in isotopic composition only when it precipitates from solution; italters the system’s composition only if it dissolves. Example:
segregate Quartz Calcite "Maximum Microcline"
Optionally, a fraction of a mineral’s mass may be isotopically segregated, and thatfraction may vary linearly with reaction progress. Examples:
segregate Quartz 100%, Muscovite 7/10segregate Ca-Saponite 100% 0%segregate Ca-Saponite 80% Xi = .3, 20% Xi = .7
In the latter example, React segregates 80% of the mass of CaSaponite until thereaction progress variable Xi reaches .3, decreases the segregated fractionation untilit reaches 20% when Xi equals .7, and then holds the value constant until the endof the path. To display the isotopically segregated minerals during a React session,type “show isotopes”.
148
React Commands
6.88 show
show <option>show <species | minerals | surfaces> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show gases show showshow altered show initial show speciesshow basis show isotopes show suppressedshow commands show minerals show surfacesshow couples show oxides show systemshow directory show printout show variablesshow elements show reactants
The command “show show” gives a list of show command options. When you type“show species”, “show minerals”, or “show surfaces”, the program lists all speciesor minerals in the thermo database. A long form of the “show species” and “showminerals” commands lets you set the basis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
6.89 simax
simax = <value | ?>
Config ! Iteration. . .
The “simax” command sets in molal units the maximum value of the stoichiometricionic strength used in calculating water activity when the DebyeHückel model isemployed. By default, this variable is set to 3 molal. To restore the default value, typethe command with no argument or with an argument of “?”. To see the current settingof this variable, type “show variables”.
149
GWB Reference Manual
6.90 slide
slide <unit> <species | gas> to <value>
Reactants ! add !
Use the “slide” command to linearly adjust the activity of the specified species, fugacityof the gas, or an activity ratio toward <value>, which is attained at the end of the path.Note that the interpolation is made linearly on the logarithm of activity or fugacity if<value> is set as a log, and that <unit> can be “activity” or “fugacity” (“a” or “f” forshort), “ratio”, “pH”, “pe”, or “Eh”, or omitted. Examples:
slide pH to 5slide activity Cl- to 2/3slide f CO2(g) to 10^-3.5slide log f O2(g) to -65
6.91 sorbate
sorbate <exclude | include>
Config ! Iteration. . .
Use the “sorbate” command to tell the program, when considering sorption ontosurfaces (see the “surface_data” command), whether to include or exclude sorbedspecies in figuring the composition of the initial system. By default, the program doesnot include sorbed species in this calculation. If you set the CaCC concentration to 15mg/kg, for example, the initial system would contain that amount in the fluid and anadditional amount sorbed onto mineral surfaces. If you type the command “sorbateinclude”, however, that amount would apply to the sum of the CaCC sorbed and insolution.
150
React Commands
6.92 start_date
start_date <value | off>
Config ! Stepping. . .
Use the “start_date” command to set an explicit starting date of the reaction. Thiscan be used to coordinate the plotting of dated scatter data samples stored in aGSS spreadsheet on the reaction path in Gtplot. The date should be in the format“MM/DD/YYYY”. Use “off” to return to the default of not set.
start_date 10/30/2008start_date off
6.93 start_time
start_time <value | off>
Config ! Stepping. . .
Use the “start_time” command to set an explicit starting time of the reaction. Thiscan be used to coordinate the plotting of timed scatter data samples stored in aGSS spreadsheet on the reaction path in Gtplot. The time should be in the format“HH:MM:SS”. Use “off” to return to the default of not set.
start_time 11:30:00start_time off
6.94 step_increase
step_increase = <value | ?>
Config ! Stepping. . .
Use the “step_increase” command to set the greatest proportional increase, from onestep to the next, in the size of the time step. This variable does not apply to reactionpaths with logarithmic reaction stepping (see variable “delxi”).
By default, this variable is set to 1.5. To restore the default value, type the commandwith no argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
151
GWB Reference Manual
6.95 step_max
step_max = <value | ?>
Config ! Stepping. . .
Use the “step_max” command to limit the number of reaction steps the program maytake to trace a simulation. Use a “?” to restore the default state, which is no prescribedlimit. To see the current setting, type “show variables”.
6.96 suffix
suffix <string>
Config ! Output. . .
Use the “suffix” command to alter the names of the output datasets (“React_output.txt”,“React_isotope.txt”, “React_plot.gtp”, “Table1.txt”..., and “Btab1.txt”...) by adding atrailing string. Example:
suffix _run2
produces output datasets with names such as “React_output_run2.txt”.
6.97 sulfur
sulfur <fluid | reactant | segregated mineral> = <value>
Config ! Isotopes. . .
Use the “sulfur” command to set the 34S isotopic composition of the initial fluid,reactant species (aqueous species, minerals, or gases) or segregated minerals. Thecomposition may be set on any scale (e.g., CDT), but you must be consistent throughoutthe calculation. Example:
sulfur fluid = +45, H2S(g) = -2
The commands
sulfur removesulfur off
clear all settings for sulfur isotopes from the calculation.
152
React Commands
6.98 suppress
suppress <species, minerals, gases, surface_species | ALL>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species, surfacespecies, minerals, or gases from being considered in a calculation. Example:
suppress H3SiO4- Quartz "Maximum Microcline"
prevents the three entries listed from being loaded from the database. Typing “suppressALL” suppresses all of the minerals in the thermodynamic database.
The “unsuppress” command reverses the process. To suppress all but a few minerals,you could type
suppress ALLunsuppress Quartz Muscovite Kaolinite
6.99 surface_capacitance
surface_capacitance = <value | ?>surface_capacitance on <type> = <value | ?>
File! Open! Sorbing Surfaces. . . ! constant capacitance F/m2
Use this command (abbrev.: “surf_capacitance”) to set, in units of F/m2, the capacitanceof a sorbing surface. When you set this value (or if a value for capacitance is set inthe header of the surface reaction dataset), React will model surface complexationfor the surface in question using the constant capacitance model, rather than the fulltwolayer model.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_capacitance on HFO = 2
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_potential” commands.
153
GWB Reference Manual
6.100 surface_data
surface_data <sorption dataset>surface_data remove <sorption dataset | surface type>surface_data OFF
File ! Open ! Sorbing Surfaces. . . ! add
File ! Open ! Sorbing Surfaces. . . ! select surface(s) ! delete
Use the “surface_data” command (abbrev.: “surf_data”) to specify an input datasetof surface sorption reactions to be considered in the calculation. The dataset nameshould be enclosed in quotes if it contains any unusual characters. Use the “remove”argument to eliminate a surface dataset, specified by name or surface type (e.g.,“HFO”), from consideration. The argument “OFF” disables consideration of all surfacecomplexes.
You can specify more than one sorbing surface in a model by repeating the“surface_data” command for different datasets (a dataset of surface reactions forsorption onto hydrous ferric oxide, as well as example datasets for the ion exchange,Kd , Freundlich, and Langmuir models are distributed with the software). To remove adataset of surface reactions from consideration, you use commands such as
surface_data remove FeOH.sdatsurface_data remove HFOsurface_data OFF
The latter command removes all of the surface datasets that have been loaded.
6.101 surface_potential
surface_potential = <value | ?>surface_potential on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant potential mV
Use this command (abbrev.: “surf_potential”) to set, in units of mV, the electricalpotential for a sorbing surface. When you set this value (or if a value is set in thesurface reaction dataset), React will model surface complexation for the surface inquestion using the constant potential, rather than full twolayer, method.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_potential on HFO = 0
154
React Commands
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_data” commands.
6.102 swap
swap <new basis> <for> <basis species>
Basis !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that you can alter to constrain the composition ofthe initial system. An aqueous species, mineral, gas, or activity ratio can be swappedinto the basis in place of one of the original basis species listed in the database.Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
6.103 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving React. Example:
system "copy React_output.txt React_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the React command with a “$”:
155
GWB Reference Manual
$copy React_output.txt React_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
6.104 TDS
TDS = <value | ?>
Basis ! advanced ! TDS mg/kg
Use the “TDS” command to set in mg/kg the total dissolved solids for the initial fluid,if you don’t want the program to calculate this value automatically. The program usesthe TDS when needed to convert input constraints into molal units.
To restore automatic calculation of the TDS, type the command with no argumentor with an argument of “?”. To see the variable’s current setting, type “show variables”.
6.105 temperature
temperature = <value> <unit>temperature initial = <value> <unit> final = <value> <unit>temperature initial = <value> <unit> reactants = <value> <unit>temperature isothermal | polythermaltemperature reset
Basis ! temperature initial C ! normal
slide temperature to C sliding temperature
reactant temperature C reactant mixing
----------------------------hold isothermal
Use the “temperature” command (also: “T”) to set the temperature of the system orreactants. The Units Recognized appendix lists possible units, which default to “C”.Examples:
temperature 25 CT initial = 25 C, final = 300 CT initial = 398 K, reactants = 498 K
156
React Commands
Temperature values can range over the span of the thermo dataset, from 0°C to 300°Cfor “thermo.tdat”; 25°C is the default.
The “isothermal” (or “constant”) keyword causes the program to hold temperatureconstant at the initial value, regardless of other settings; the “polythermal” (or “varying”)keyword reverses that setting. The “reset” (or “off’) keyword restores temperaturesettings to their default states.
6.106 theta
theta = <value | ?>
Config ! Stepping. . .
Use the “theta” command to set the time weighting variable used in evaluating kineticrate laws. The value may vary from zero (full weighting at the old time level) to one(full weighting at the new time level). By default, this variable is set to 0.6. To restorethe default value, type the command with no argument or with an argument of “?”. Tosee the current setting of this variable, type “show variables”.
6.107 timax
timax = <value | ?>
Config ! Iteration. . .
The “timax” command sets in molal units the maximum value of ionic strength used incalculating species’ activity coefficients when the DebyeHückel model is employed.By default, this variable is set to 3 molal. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
6.108 time
time <start = <value> <unit>> <end = <value> <unit>>time = off
Basis ! time start day end day
Use the “time” command (also: “t”) to set the time span of a kinetic reaction path.The starting time, by default, is zero. Unit choices are listed in the Units Recognized
appendix; “day” is the default. Argument “off” switches the program out of kineticmode. Examples:
157
GWB Reference Manual
time end = 100 yearstime start 10 days, end 20 days
6.109 title
title <character string>
Config ! Output. . .
Use the “title” command to set a title to be passed to the graphics program. Example:
title "Yucca Mountain Groundwater"
Be sure to put multiword titles in quotes.
6.110 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
6.111 unsegregate
unsegregate <mineral(s) | ALL>
Config ! Isotopes. . . ! select entry(ies) ! delete
Use the “unsegregate” command to remove minerals from the list of minerals to besegregated isotopically.
158
React Commands
6.112 unsuppress
unsuppress <species, minerals, gases, surface_species | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies, surface species, minerals, or gases that have previously been suppressed.Examples:
unsuppress Quartz Albite "Albite low"unsuppress ALL
The argument “ALL” clears any species, minerals, or gases that have been suppressed.
6.113 unswap
unswap <species | ALL>
Basis ! !
Use the “unswap” command to reverse a basis swap. Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
6.114 usgovt
usgovt
Help ! About React. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
159
GWB Reference Manual
6.115 volume
volume = <value | ?> <unit>
Medium ! bulk volume cm3
Use the “volume” (also “bulk_volume”) command to cause the program to scale theinitial system to a specific size. By default, the program does not scale the system.In this case, the bulk volume Vb
Vb D Vf CVmn CVin CVstag (6.1)
is computed as the sum of the fluid volume Vf , mineral volume Vmn, inert volumeVin, and the volume Vstagof the stagnant zone, if one has been specified using the“dual_porosity” command.
If Xstag is the stagnant fraction of the system, which is zero if a dual porosity modelhas not been invoked, the above equation can be rewritten
�
1�Xstag
�
Vb D Vf CVmn CVin (6.2)
When you use the “volume” command to set the bulk volume Vb, the program scalesthe fluid volume Vf and optionally the mineral and inert volumes, Vmn and Vin, so thesystem fills the specified space.
The command
volume = 2 m3
for example, causes the program to scale the fluid volume Vf and optionally the mineraland inert volumes, Vmn and Vin, so the system occupies 2 m3. Default behavior, inwhich no scaling is performed, can be restored at any time with the command
volume = ?
The unit you use to constrain the amount of each mineral in the system controlswhether or not the program adjusts that mineral’s volume. If you constrain Quartzto “10 cm3”, for example, Quartz will occupy 10 cm3 after scaling. Setting Quartz inrelative units such “volume%” or “mmol/m3”, in contrast, causes the program to fixthe mineral’s volume relative to Vb.
Similarly if you set inert volume in an absolute unit, such as
inert = 50 cm3
the program will honor that constraint and hold Vin steady. The inert portion of thesystem in this example will occupy 50 cm3 after scaling. The command
160
React Commands
inert = 10 volume%
however, causes the program to scale the inert volume to 10% of the system’s bulkvolume.
161
162
X1t Commands
7.1 <unit>
<field_variable> <free> <unit> <as element symbol> <basis entry>
Initial or Fluids ! free kg
To constrain chemical composition, enter a command containing only the above entries.Entries may appear in any order. The qualifier “free” specifies that the constraint appliesto the free rather than to the bulk basis entry. Settings constrain the composition ofthe initial system, a boundary fluid, or globally to all fluids, depending on the currentinput scope (see the “scope” command). X1t recognizes the following units:
By mass or volume:mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 l
By concentration:mol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
By carbonate alkalinity (applied to bicarbonate component):eq_acid meq_acid ueq_acid neq_acideq_acid/kg meq_acid/kg ueq_acid/kg neq_acid/kgeq_acid/l meq_acid/l ueq_acid/l neq_acid/lg/kg_as_CaCO3 mg/kg_as_CaCO3 ug/kg_as_CaCO3 ng/kg_as_CaCO3wt%_as_CaCO3g/l_as_CaCO3 mg/l_as_CaCO3 ug/l_as_CaCO3 ng/l_as_CaCO3
Per volume of the porous medium:mol/cm3 mmol/cm3 umol/cm3 nmol/cm3
163
GWB Reference Manual
kg/cm3 g/cm3 mg/cm3 ug/cm3ng/cm3mol/m3 mmol/m3 umol/m3 nmol/m3kg/m3 g/m3 mg/m3 ug/m3ng/m3volume% "vol. fract."
By activity:activity fugacity ratiopH V pe
Activity and fugacity may be abbreviated to “a” or “f”. Keyword “total” reverses a settingof “free”.
Use the “as” keyword to constrain mass in terms of elemental equivalents. Forexample, the command
CH3COO- = 10 umol/kg as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
20 mg/kg SO4-- as S
would specify 59.9 mg/kg of sulfate, since the ion’s mole weight is about 3 times thatof sulfur itself.
Examples:
55 mmol/kg HCO3-Na+ = 1 molal1 ug/kg U++++10 volume% DolomitepH = 8Eh = .550 Vlog f O2(g) = -60HCO3- = 30 mg/kg as C
You may in a similar fashion constrain the concentration of a kinetic aqueous orsurface complex in the initial system, a boundary fluid, or globally. For example, thecommands
kinetic AlF++AlF++ = 1 umol/kgscope ambient_water
AlF++ = 10 umol/kg
set the concentration of the kinetic complex AlFCC to 1 �mol kg�1 in all fluids, exceptfluid “ambient_water”, where its concentration is ten times greater.
164
X1t Commands
7.2 activity
activity <species> = <field_variable>
Initial or Fluids ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies. The setting applies to the initial system, a boundary fluid, or globally to allfluids, depending on the current input scope (see the “scope” command). Examples:
activity Na+ = 0.3log a H+ = -5
See also the “pH”, “Eh”, “pe”, “ratio”, “fugacity”, “fix”, and “slide” commands.
7.3 add
add <basis species>
Initial or Fluids ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “pH”, “pe”, and “Eh” commands.
7.4 alkalinity
alkalinity = <field_variable> <unit>
Initial or Fluids ! HCO3- mg/kg_as_CaCO3
Use the “alkalinity” command to constrain the total concentration of HCO�
3 to reflectthe solution’s carbonate alkalinity. The setting applies to the initial system, a boundaryfluid, or globally to all fluids, depending on the current input scope (see the “scope”command). You can specify one of the units listed in the Units Recognized appendix;“mg/kg_as_CaCO3” is the default. To use this option, the solution pH must be setexplicitly.
165
GWB Reference Manual
7.5 alter
alter <species | mineral | gas> <log K ’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
7.6 audit
audit <off>
Config ! Stepping. . .
Use the “audit” option to cause the program to perform a mass balance audit duringthe simulation and report at the end of the run the mass imbalance observed for eachoriginal basis entry. Use:
auditaudit off
By default, the program does not perform the audit.
7.7 balance
balance <on> <basis entry>
Initial or Fluids ! unit ! Balance species
Use the “balance” command to specify the basis entry to be used for electrical chargebalancing. The setting applies to the initial system, a boundary fluid, or globally to allfluids, depending on the current input scope (see the “scope” command). The basisentry must be a charged aqueous species. By default, X1t balances on Cl�. Example:
balance on Na+
166
X1t Commands
7.8 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (abbrev.: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
7.9 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
7.10 clipboard
clipboard
Edit ! Copy
The “clipboard” command causes the contents of the Results pane to be copied tothe clipboard, from where it can be pasted into various types of documents.
7.11 conductivity
conductivity <conductivity dataset>
File ! Open ! Conductivity Data. . .
Use the “conductivity” command to change the input file of coefficients used to calculateelectrical conductivity. Example:
167
GWB Reference Manual
conductivity "..\my_conductivity.dat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.Beginning with GWB11, the applications compute electrical conductivity using eitherof two different approaches, the USGS and APHA methods; the USGS method is thedefault. The required coefficients are defined in the files “conductivityUSGS.dat” and“conductivityAPHA.dat”, respectively, which are installed in the same directory as thethermo datasets (commonly “\Program Files\GWB\Gtdata”).
7.12 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
7.13 Courant
Courant = <value | ?>
Config ! Stepping. . .
Use the “Courant” command to constrain the time step according to the Courantcondition. You enter a value for the Courant number, which is the ratio of the distancefluid travels over a time step to the length of the nodal blocks. If you set a Courantnumber of one, then X1t will select a time step over which the fluid will exactly traversethe nodal blocks. For a value of 0.5, the fluid will move halfway across the nodalblocks, and so on. Values greater than one for the Courant number typically giveunstable solutions and are therefore not recommended. By default, X1t assumes aCourant number of 1.0. The “?” argument resets the default value.
168
X1t Commands
7.14 cpr
cpr = <field_variable> <unit> <steady | transient>
Medium ! cpr (minerals) cal/g/C
Use the “cpr” command to set the heat capacity of the rock (mineral) framework. Youcan specify one of the units listed in the Units Recognized appendix; “cal/g°C” is thedefault. This value is used during polythermal simulations in calculating the effectsof advective heat transport. The “transient” keyword causes the model to evaluatethe field variable continuously over the course of the simulation, if it is set with anequation, script, or function.
By default, this variable is set to 0.2 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
7.15 cpu_max
cpu_max = <value | ?>
Config ! Stepping. . .
Use the “cpu_max” command to limit the amount of computing time a simulationmay take. You set the maximum computing time in seconds, or use a “?” to restorethe default state, which is no prescribed limit. To see the current setting, type “showvariables”.
7.16 cpw
cpw = <field_variable> <unit> <steady | transient>
Medium ! cpw (fluid) cal/g/C
Use the “cpw” command to set in cal/g°C the heat capacity of the fluid. You can specifyone of the units listed in the Units Recognized appendix; “cal/g°C” is the default. Thisvalue is used during polythermal simulations in calculating the effects of advectiveheat transport. The “transient” keyword causes the model to evaluate the field variablecontinuously over the course of the simulation, if it is set with an equation, script, orfunction.
By default, this variable is set to 1.0 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
169
GWB Reference Manual
7.17 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
data "..\my_thermo.tdat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
7.18 debyehuckel
debye-huckel
File ! Open ! Thermo Data. . . ! thermo.tdat
The “debyehuckel” command (abbrev.: “dh”) sets the program to calculate species’activity coefficients using the extended DebyeHückel equations. Executing thiscommand automatically sets the input dataset of thermodynamic data to “thermo.tdat”.
7.19 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
170
X1t Commands
7.20 delQ
delQ = <value | ?>
Config ! Stepping. . .
Use the “delQ” command to control the lengths of time steps taken in a simulationaccounting for reaction kinetics. The program limits how much the ion activity productQ can change over a step, for each kinetic reaction considered. The setting for “delQ”is the projected change �Q=Q allowed in the relative value of the activity product.You can set a larger value to permit longer time steps, or a smaller value to improvestability. The default setting is 0.1. Type the command with no argument or with anargument of “?” to restore the default. To see the current setting, type “show variables”.
7.21 deltar
deltar = <field_variable> <unit>
Domain ! delta r cm
The “deltar” (also: “delta_r”) command is a synonym for the “deltax” command,described below. It is provided for clarity when working with radial domains.
7.22 deltax
deltax = <field_variable> <unit>
Domain ! delta x cm
The “deltax” (also: “delta_x”) command sets the length �x of nodal blocks in thefinite difference grid. You can specify one of the units listed in the Units Recognized
appendix; “cm” is the default.When you set a value for �x, the program ignores any setting of the “length”
command and figures the domain length from the values of �x and Nx , the numberof nodal blocks specified along x. For example, the commands
Nx = 100deltax = 1 m
are equivalent to
Nx = 100length = 100 m
171
GWB Reference Manual
You can set �x as a field variable, in order to create grids of varying node density.For example, the commands
Nx = 10deltax = { 1 1 .5 .5 .25 .25 .5 .5 1 1 } m
set a grid in which nodal blocks near the center of the domain are smaller than thosenear the left and right sides. The domain in this case will be 7 m long. See also the“deltar”, “length”, and “Nx” commands.
7.23 delxi
delxi = <value | ?>
Config ! Stepping. . .
Use the “delxi” command to set the maximum length (in terms of reaction progress,which varies from zero to one over the course of the simulation) of the time step. Bydefault, this variable is set to 0.01. To restore the default value, type the command withno argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
7.24 density
density = <value | ?>density = <TDS | chlorinity>
Initial ! advanced ! density g/cm3 TDS chlorinity
Fluids ! advanced ! density g/cm3
You can use the “density” command to set in g/cm3 the fluid density the programuses to convert compositional constraints to molality, the concentration unit it carriesinternally. If you set the initial NaC composition in mg/l, for example, the programneeds to know the density of the initial fluid to determine NaC molality. The settingapplies to the initial system, a boundary fluid, or globally to all fluids, depending onthe current input scope (see the “scope” command).
The program by default converts units using a density value it calculates automatically,as discussed below. This value is sufficient for most purposes, and hence it is generallynot necessary to set fluid density explicitly. You might, however, want to set the densityif you are working at high temperature, but your analysis is expressed per liter ofsolution at room temperature.
You can also use the “density” command to tell the program how to calculate thedefault density it uses to convert units, and the fluid density it reports in the simulation
172
X1t Commands
results. The program normally figures density as that of an NaCl solution with thesame TDS as the fluid in question, at the temperature of interest. With the command“density = chlorinity” you can tell the program to instead use the density of an NaClsolution of equivalent chlorinity.
To restore automatic calculation, type the command with no argument or with anargument of “?”. To see the current setting of this variable, type “show variables”.
7.25 diffusion_coef
diffusion_coef = <field_variable | ?> <unit> <steady | transient>
Medium ! diffusion coefficient cm2/s
Use the “diffusion_coef” command (abbrev.: “diff_coef”) to set a value for the diffusioncoefficient in one of the units listed in the Units Recognized appendix. The “transient”keyword causes the model to evaluate the field variable continuously over the courseof the simulation, if it is set with an equation, script, or function. By default, X1t assumesa diffusion coefficient of 10�6 cm2/s. The “?” argument resets the default value.
7.26 discharge
discharge = <value | ?> <unit>discharge <interval> = <value | ?> <unit>
discharge fluid = <boundary fluid>discharge <interval> fluid = <boundary fluid>discharge <left | right> fluid = <boundary fluid>discharge <left | right> <interval> fluid = <boundary fluid>
Flow ! interval discharge cm/s
Use the “discharge” command to set a value for the specific discharge (fluid volumecrossing a unit area per unit time) of the fluid into the domain, and to set the fluid toappear at the left or right boundary, or both. A positive value represents flow into theleft side of the domain, and negative gives flow rate into the right side.
If the “discharge” command contains the name of a simulation interval, subsequentsettings on the command apply to that interval, rather than the simulation as a whole.This behavior continues to the end of the command, or until the name of anotherinterval is encountered.
By default, discharge is not set and the program calculates flow rate from the headdrop, the permeability of the medium, and the viscosity of the pore fluid. Enter anargument of “?” to set the default condition. If, furthermore, you specify a driving forcefor flow using the “head_drop” command (see discussion later in this section), the
173
GWB Reference Manual
program will unset any value specified for specific discharge and resume calculatingdischarge from the driving force, permeability, and fluid viscosity.
The value may set be in any of the units of velocity or specific discharge listed inthe Units Recognized appendix. The default is cm/s, which is equivlent to cm3/cm2/s.In addition, you may set as the unit “pore_volumes” (or “pv”) to specify discharge interms of the number of times the original pore volume is to be replaced over thecourse of the reaction model.
Examples:
discharge = 15 m/daydischarge = 100 pore_volumesdischarge start = 20 m/day interval-2 = -20 m/day
You can also specify the boundary fluid to appear on either the left and rightboundaries, or both, for the entire simulation or an individual interval. To do so, youuse the “fluid” keyword. In the examples
discharge = .002 m/s fluid = ambient_waterdischarge phase2 left fluid = pit_water
fluid “ambient_water” flows across the left boundary at a discharge of .002 m s�1 overthe course of the simulation, except during interval “phase2”, during which time fluid“pit_water” flows into the left of the domain, but “ambient_water” is found to the right.
7.27 dispersivity
dispersivity = <field_variable | ?> <unit> <steady | transient>
Medium ! longitudinal dispersivity cm
Use the “dispersivity” command to set a value for the hydrodynamic dispersivity. The“transient” keyword causes the model to evaluate the field variable continuously overthe course of the simulation, if it is set with an equation, script, or function. You canspecify one of the units listed in the Units Recognized appendix; “cm” is the default.By default, X1t assumes a value equal to 1% of the length of the domain (see the“length” command). The “?” argument resets the default state.
7.28 dual_porosity
dual_porosity = <on | off> <blocks | spheres | fractures> \<geometry = <blocks | spheres | fractures | ?>> \<volfrac = <field_variable | ?>> \<Nsubnode = <value | ?>> \<<half-width | radius> = <field_variable | ?> <unit>> \
174
X1t Commands
<diff_length = <field_variable | ?> <unit>> \<porosity = <field_variable | ?>> \<retardation = <field_variable | ?>> <steady | transient> \<diff_coef = <field_variable | ?> <unit>> <steady | transient> \<thermal_con = <field_variable | ?> <unit>> <steady | transient> \<theta = <value | ?>> <reset | ?>
Config ! Dual Porosity. . .
Use the “dual_porosity” command (abbrev: “dual”) to configure stagnant zones inthe simulation, using the dual porosity feature. Enable and disable the feature withthe “on” and “off” keywords. Disabling the feature does not affect other settings, soreenabling the feature returns the model to its most recent configuration.
With the “geometry” keyword, you configure the stagnant zone into blocks, spheres,or a fractured domain, the latter being slabs separated by fractures arrayed along thex direction. Alternatively, you can set the three configurations directly with keywords“blocks”, “spheres”, and “fractures”. Keyword “volfrac” sets the fraction of the nodalblock’s bulk volume occupied by the stagnant zone.
The “Nsubnode” (or “nx”) keyword sets the number of nodes into which the stagnantzone within each node will be divided when solving for solute and temperaturedistributions. The “halfwidth” (or “radius”, for spherical geometries) keyword setsthe zone’s characteristic dimension, in units of distance (see the Units Recognized
appendix; default is cm), and keyword “diff_length” sets the distance (same units) fromthe contact with the freeflowing zone over which the model will account for solutediffusion and heat conduction. Use keywords “porosity”, “retardation”, “diff_coef”, and“thermal_con” to set values for the porosity, retardation factor, diffusion coefficient,and thermal conductivity of the stagnant zone. The default unit for the diffusioncoefficient is cm2/s, and thermal conductivity defaults to cal/cm/s/°C units; see theUnits Recognized appendix for a list of options.
By default, the stagnant zone is configured in blocks divided into 5 subnodes. Youmust specify a value for the volume fraction of the stagnant zone, as well as one forthe halfwidth (or radius); the diffusion length defaults to the latter value. The programuses whatever values are set for the freeflowing zone in the node in question asdefault values for the porosity, diffusion coefficient, and thermal conductivity of thestagnant zone; the retardation factor defaults to a value of one.
The “theta” keyword sets time weighting (0 � � � 1) for the numerical solution ofdiffusive transport within the stagnant zone. A weight � D 0 assigns the explicit method,and larger values invoke an implicit solution. By default, the program chooses �
automatically, using the explicit method unless it would force too many more timesteps than would otherwise be necessary. In that case, the program uses the implicitmethod (� D 0:6), which requires more computing effort per time step, but can takelong steps without becoming numerically unstable.
You can append the “transient” keyword when setting several of the parameters:the diffusion coefficient, thermal conductivity, and retardation factor. If the variable
175
GWB Reference Manual
is defined by an equation, script, or external function, it will then be reevaluatedcontinuously over the course of the run.
As an example, the command
dual_porosity geometry = spheres, radius = 50 cm, volfrac = 75%
configures the stagnant zone into spheres of halfmeter radius that occupy threequarters of the domain. The command
dual_porosity reset
enables the feature after restoring default settings for each keyword.
7.29 dx_init
dx_init = <value | ?>
Config ! Stepping. . .
Use the “dx_init” command to set the length of the initial time step. You set this valuein terms of reaction progress, which varies from zero to one over the course of thesimulation. By default, the variable is ignored. To restore the default state, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
7.30 dxplot
dxplot = <value | ?> <linear | log> <exact | approx>
Config ! Output. . .
Use the “dxplot” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “X1t_plot.xtp”dataset, and to specify the entries be spaced on a linear or logarithmic scale. Avalue of zero causes the program to write the results after each time step, which canproduce unwieldy amounts of output.
The command
dxplot = .1 linear
for example, causes the program to write entries for when reaction progress is .1, .2,.3, . . . , and 1.0. Alternatively, the commands
176
X1t Commands
dx_init = .001dxplot = .5 log
produce entries at .001, .003, .01, .03, .1, .3, and 1.0 (see the “dx_init” command).The arguments “exact” and “approx” define whether the program will constrain the
sizes of time steps to give entries that match the specified increment exactly (thedefault case), or will output entries whenever the time stepping meets or exceeds theincrement.
By default, this variable is set to 0.02, “linear”, and “exact”. To restore the defaultsettings, type the command with no argument or with an argument of “?”. To see thecurrent settings, type “show variables”.
7.31 dxprint
dxprint = <value | ?> <linear | log> <exact | approx>
Config ! Output. . .
Use the “dxprint” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “X1t_output.txt”dataset, and to specify the entries be spaced on a linear or logarithmic scale. Avalue of zero causes the program to write the results after each time step, which canproduce unwieldy amounts of output.
The command
dxprint = .1 linear
for example, causes the program to write entries for when reaction progress is .1, .2,.3, . . . , and 1.0. Alternatively, the commands
dx_init = .001dxprint = .5 log
produce entries at .001, .003, .01, .03, .1, .3, and 1.0 (see the “dx_init” command).The arguments “exact” and “approx” define whether the program will constrain the
sizes of time steps to give entries that match the specified increment exactly (thedefault case), or will output entries whenever the time stepping meets or exceeds theincrement.
By default, this variable is set to 0.1, “linear”, and “exact”. To restore the defaultsettings, type the command with no argument or with an argument of “?”. To see thecurrent settings, type “show variables”.
177
GWB Reference Manual
7.32 Eh
Eh = <field_variable> <unit>
Initial or Fluids ! Eh
Use the “Eh” command to set Eh in the initial system. Example:
Eh = 200 mV
sets the system’s oxidation state to correspond to an Eh of 0.2 volt. The setting appliesto the initial system, a boundary fluid, or globally to all fluids, depending on the currentinput scope (see the “scope” command). See also the “activity”, “pH”, “pe”, “fugacity”,“fix”, and “slide” commands.
7.33 epsilon
epsilon = <value | ?>
Config ! Iteration. . .
Use the “epsilon” command to set the convergence criterion (dimensionless) foriterating to a solution of the equations representing the distribution of chemical mass.By default, this variable is set to 5�10�11 . To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
7.34 exchange_capacity
exchange_capacity = <field_variable | ?> <units>exchange_capacity on <type> = <field_variable | ?> <units>
File ! Open ! Sorbing Surfaces. . . ! exchange capacity eq
Use the “exchange_capacity” command (abbrev.: “ex_capacity” or “exch_capacity”) toset the exchange capacitiy (i.e., the CEC) of the system when modeling ion exchangereactions or sorption according to Langmuir isotherms. For ion exchange reactions,you set units of electrical equivalents (“eq”, “meq”, and so on) or equivalents per gramof dry sediment (“eq/g”, “meq/g”, . . . ). For Langmuir reactions, you similarly set a valuein mole units: “mol”, “mmol”, “mol/g”, “mmol/g”. If you set units per gram of sediment,the program multiplies the value entered by the mass of rock in the system (includingequilibrium and kinetic minerals as well as inert volume) to get the system’s capacity.
178
X1t Commands
If you read in a surface that sorbs by ion exchange or Langmuir isotherms, youmust set a value for its exchange capacity. If you have set more than one sorbingsurface (using the “surface_data” command), you identify the surface in question byits “type”. For example
exchange_capacity on IonEx = .0008 eq/g
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the surface represented by the sample dataset “IonEx.sdat”,for example, is “IonEx”. You can use the “show” command to display the “type” ofeach active surface. See also the “surface_data” and “inert” commands.
7.35 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula and mole volume) about species, minerals, and gasesin the dataset. Example:
explain Analcime
7.36 explain_step
explain_step <off>
Config ! Stepping. . .
The “explain_step” option causes the program to report on the Results pane the factorcontrolling the length of each time step, whenever the step size is limited by the needto maintain numerical stability.
7.37 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . .
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of data
179
GWB Reference Manual
provided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation.
When the “extrapolate” option is invoked, the program will estimate log K ’s asfunctions of temperature by making a polynomial fit to the data provided. Use thisoption with considerable care.
7.38 fix
fix <unit> <species | gas>
Reactants ! add !
Use the “fix” command to hold the activity of a species, fugacity of a gas, or an activityratio constant over the course of a run. The <unit> can be “activity” or “fugacity” (“a”or “f” for short), “ratio”, “pH”, “pe”, or “Eh”, or it can be omitted. Examples:
fix pHfix a H+fix f O2(g)fix ratio Ca++/Na+^2
7.39 fugacity
fugacity <gas> = <field_variable>
Initial or Fluids ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) in theinitial system. The setting applies to the initial system, a boundary fluid, or globally toall fluids, depending on the current input scope (see the “scope” command). Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
180
X1t Commands
See also the “activity”, “ratio”, “pH”, “Eh”, “pe”, “fix”, and “slide” commands.
7.40 go
go <boundary | initial | single | ask>
Run ! GoRun ! Go InitialRun ! Go Single
Results ! Run
Use the “go” command to initiate calculation of a model based on the currentconfiguration. Used with the “boundary” argument, the command causes the programto calculate only the composition of the boundary fluids. With the “initial” argument,the program calculates the initial state of the medium as well as the composition ofthe boundary fluids, but does not trace a reaction model. Typing the command withthe argument “single” causes the simulation to run on a single processor, regardlessof the setting for the “threads” command.
Upon completing a simulation, the program normally presents a dialog box askingif you would like to continue the simulation over an extended time span. This optionappears if you have triggered the calculation by entering “go” from the keyboard,selecting “Go” from the menubar, or moving to the Results pane and clicking the Runbutton, but not if you are reading commands from a file or running a control script.Typing
go ask
causes the program to offer the option to continue the simulation in all cases.
7.41 grep
grep <string>
File ! View ! .\X1t_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “X1t_output.txt” (or the current output dataset, as modifiedby the “suffix” command) containing the string “Albite”.
181
GWB Reference Manual
7.42 hmw
h-m-w
File ! Open ! Thermo Data. . . ! thermo_hmw.tdat
Use the “hmw” command (abbrev.: “hmw”) to set the program to calculate species’activitycoefficientsbyusingtheHarvieMøllerWeareequations.Executingthiscommandautomatically sets the input dataset of thermodynamic data to “thermo_hmw.tdat”.Note that dataset “thermo_hmw.tdat” supports calculations at 25°C only.
7.43 head_drop
head_drop = <value | ?> <unit>head_drop <interval> = <value | ?> <unit>
head_drop fluid = <boundary fluid>head_drop <interval> fluid = <boundary fluid>head_drop <left | right> fluid = <boundary fluid>head_drop <left | right> <interval> fluid = <boundary fluid>
Flow ! interval head drop cm
Use the “head_drop” (also: “pot_drop”) command to set a value for the decrease inhydraulic head (in length units) or hydraulic potential (in units of pressure) acrossthe medium. This decrease provides the driving force for fluid flow. The programsets hydraulic head or potential along the left boundary to the value specified in thecommand, and sets head or potential along the right boundary to zero.
At each step in the simulation, the program uses the head or potential values at theboundaries, along with the permeability and fluid viscosity, to calculate the flow field.Setting a positive head or potential drop drives flow from left to right, and a negativevalue drives flow in the opposite direction.
You set the head drop for a specific interval by including the interval name, or forall intervals by omitting it.
The “head_drop” command also lets you specify the boundary fluids to set to the leftand right sides of the domain, in the same fashion as you would use the “discharge”command.
The program recognizes hydraulic head in units of length, as listed in theUnits Recognized appendix, and hydraulic potential in units of pressure. By default,values are taken in atm.
Examples:
182
X1t Commands
head_drop = 150 cmpot_drop = 0.1 atmhead_drop start = 4 m phase2 = 2 m
By default, the head drop is set to zero. To return to the default value, enter thecommand
head_drop = ?
7.44 heat_source
heat_source = <field_variable | ?> <unit> <steady | transient> \<temp_min = <value | ?> <C>> <temp_max = <value | ?> <C>>
Medium ! internal heat source
temperature: minimum C maximum C
cal/cm3/s
Use the “heat_source” command (also: “heat_src”) to set the rate of internal heatproduction within the medium. You can specify one of the units listed in theUnits Recognized appendix; “cal/cm3/s” is the default. The “transient” keyword causesthe model to evaluate the field variable continuously over the course of the simulation,if it is set with an equation, script, or function. By default, the program does not accountfor internal heat production. The “?” argument resets the default value of zero.
The “temp_min” and “temp_max” keywords (also: “tempmax”, “tempmin”) set theallowable temperature range for the simulation. These values serve two purposes.
First, the simulation will give an error message and stop if temperature at anypoint in the domain falls more than 5°C less than the minimum value, or exceeds themaximum value by more than this amount.
Second, unless the “extrap” option is set, the model will load for the simulation onlythose species for which log K values are available in the thermodynamic dataset overthe allowable temperature range. Values for the keywords default to the temperaturespan of the thermodynamic database, as set in the database header.
7.45 height
height = <value> <unit>
Domain ! height (z) cm
183
GWB Reference Manual
Use the “height” command to set the height along z of the medium. You can use anyunit of distance listed in the Units Recognized appendix; “cm” is the default.
By default, the domain is 1 cm in height. See also the “length” and “width” commands.
7.46 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
7.47 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands, and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
7.48 inert
inert = <field_variable | ?> <units>
Medium ! inert volume cm3
Use the “inert” command to set the volume of nonreacting space in the system. Youmay set a value in units of volume, including cm3, m3, and l, as well as volume%and “vol. fract.”. The default setting is zero and the default unit is cm3.
Assuming you have not set a value for the initial fluid fraction in the system using the“porosity” command, the program figures the porosity over the course of the calculationas a derived variable. Specifically, it divides the fluid volume by the sum of the fluidvolume, mineral volume, and inert volume, and reports this value as a result.
When you have set a value for initial porosity with the “porosity” command, on theother hand, the program works in the contrary sense. In this case, it calculates theinert volume as that required to form a system of the specified initial porosity; theprogram now ignores any entry you may have set using the “inert” command.
To restore the default state, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show”.
184
X1t Commands
7.49 interval
interval <interval> start = <value> <unit>interval <interval> fluid = <boundary fluid>interval <interval> <left | right> = <boundary fluid>interval <interval> rename <new name>
Intervals !
at day left right
The “interval” command sets the properties of a named simulation interval, creatingit if necessary. The first interval is named “start”, and the terminating point for the runis labeled “end”, but you can create any number of intervening intervals.
For each interval, you set the starting time with keyword “start”, and the boundaryfluid to use during the simulation interval with keyword “fluid”. The default time is zerodays, and you create fluids with the “scope” command. In the absence of a keyword,the command expects the starting time. You can use keyword combinations “left fluid”and “right fluid” to set separate fluids on the left and right sides of the domain.
You can also rename the interval, using keyword “rename”. You cannot, however,rename “start” or “end”.
For example, the commands
interval start fluid = fluid1interval phase2 start = 1 year, fluid = fluid2interval phase3 start = 4 years, left fluid = fluid3A, right fluid = fluid3Binterval end 10 years
configure a simulation spanning 10 years and consisting of three reaction intervals,each with a different boundary fluid, or fluids.
7.50 itmax
itmax = <value | ?>
Config ! Iteration. . .
Use the “itmax” command to set the maximum number of iterations that may be takenin an attempt to converge to a solution for the equations representing the distributionof chemical mass.
By default, this variable is set to 999. To restore the default value, type the commandwith no argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
185
GWB Reference Manual
7.51 Kd
Kd <off>
Config ! Iteration. . .
The “Kd” command controls whether the program calculates Kd distribution coefficientsfor sorbing components, in units of liters per kg sediment mass. This calculationrequires that the mineral mass in the system (as specified for individual mineralsand/or in terms of inert volume) be set correctly.
7.52 kinetic
kinetic <species | mineral | gas> <variable> = <value>kinetic <species | mineral | gas> <variable> = <field_variable> \
<steady | transient>kinetic <species | mineral | gas> <apower | mpower(species)> = <value>kinetic <species> <boundary fluid> = <value> <unit>kinetic <redox(label)> <variable> = <value>kinetic <redox(label)> <variable> = <field_variable> <steady | transient>kinetic <redox(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <variable> = <value>kinetic <microbe(label)> <variable> = <field_variable> <steady | transient>kinetic <microbe(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <apower | mpower(species)> = <value> \
<apowerA | mpowerA(species)> = <value> \<apowerD | mpowerD(species)> = <value>
Reactants ! add !
Use the “kinetic” command to set variables defining a kinetic rate law for (1) dissolutionor precipitation of any mineral in the initial system or reactant list, (2) the associationor dissociation of any aqueous or surface complex in the system modeled, (3) thetransfer of gases into or out of an external reservoir, (4) a redox reaction, includingthose promoted by catalysis or enzymes, or (5) a microbial metabolism.
In the first three cases, you identify the kinetic reaction by the name of the species,mineral, or gas involved. In the case of a redox reaction, you set a label that begins
186
X1t Commands
with the characters “redox”, such as “redox1” or “redoxFe”. For a microbial reaction,set a label that starts with “microbe”, such as “microbeEcoli”.
The rate law you specify in a “kinetic” command, by default, applies to the dissolutionof a mineral, dissociation of a complex, dissolution of a gas, or forward progress of aredox or microbial reaction. The synonymous keywords “forward”, “dissolution”, and“dissociation” set this behavior. Including in a “kinetic” command the keyword “reverse”or its synonyms “precipitation”, “complexation”, “association”, or “exsolution” invokesthe opposite behavior. In this case, the rate law applies to the reverse reaction: mineralprecipitation, complex association, or gas exsolution.
You can append the “transient” keyword when setting the following field variables:rate constant, specific surface area, activation energy, preexponential factor, nucleusarea, and critical saturation index. If the variable is defined by an equation, script, orexternal function, it will then be reevaluated continuously over the course of the run.
See also the “react” and “remove reactant” commands.
The following paragraphs apply to all types of kinetic reactions. You set the rate constant either directly using the “rate_con” keyword, or by setting an activation energyand preexponential factor with keywords “act_en” and “preexp”. In the absence ofpromoting and inhibiting species (see next paragraph), you set the rate constant andpreexponential factor in (1) mol/cm2 sec for mineral and gas transfer reactions, (2)molal/sec or molal/cm2 sec (the latter when accounting for heterogeneous catalysis)for complexation and redox reactions, and (3) mol/mg sec for microbial reactions. Theactivation energy is specified in J/mol. Example:
kinetic "Albite low" rate_con = 1e-15
You can set “rate_con”, “act_en”, and “preexp” as field variables (see the Heterogeneity
appendix to the GWB Reactive Transport Modeling Guide).You use the “apower” or “mpower” (also “apow” or “mpow”) keyword to specify
any promoting or inhibiting species in the kinetic rate law. Keyword “apower” setsthe exponent of a species activity, and “mpower” the exponent of a species molality.Promoting species have positive powers, and the powers of inhibiting species arenegative. For example, the command
kinetic "Albite low" apower(H+) = 1
sets HC as a promoting species, the activity of which is raised to a power of one. Youcan use aqueous species, gas species (represented by fugacity), surface complexes(molal concentration), and solvent water (activity) as promoting and inhibiting species.
The “order1” and “order2” keywords set nonlinear rate laws. Keyword “order1”represents the power of the Q=K term, and “order2” represents the power of the (1 Q=K/ term.
Use the “rate_law” keyword to set the form of the kinetic rate law for a specificmineral, redox reaction, or microbial metabolism. You may set the keyword equal to (1)a character string containing the rate law, (2) the name of a file containing a basiclike
187
GWB Reference Manual
script, or (3) the name of a function in a library. The name of a file containing a ratelaw script must end in “.bas”. To specify a function from a library, set the name of adynamic link library (DLL) separated from the function name by a colon (“:”), such as“rate_laws.dll:my_ratelaw”; the library file must end in “.dll”. To return to the program’sbuiltin rate law, enter “rate_law = off” or “rate_law = ?”.
The following paragraphs apply to dissolution and precipitation reactions. You set the
specific surface area of a kinetic mineral (in cm2/g) with the “surface” keyword. Forexample,
kinetic "Albite low" surface = 1000
The “crossaffinity” option lets you use the saturation state of one mineral to modelthe reaction rate of another, as is sometimes useful for example in studying glassdissolution. To do so, you use the “xaffin” option. For (a hypothetical) example, thecommand
kinetic Quartz xaffin = Cristobalite
causes the program to calculate the reaction rate of quartz according to the fluid’ssaturation state with respect to cristobalite. The command
kinetic Quartz xaffin = OFF
turns off the option.Finally, you use the “nucleus” and “critSI” keywords to set the area available for
nucleation (in cm2/cm3 fluid volume) and the critical saturation index above which themineral can nucleate. Each of these values, by default, is zero.
Keywords “surface”, “nucleus”, and “critSI” can be set as field variables (see theHeterogeneity appendix to the GWB Reactive Transport Modeling Guide).
The following paragraphs apply to reactions for aqueous and surface complexes.When you specify a kinetic reaction for the association of an aqueous complex orsurface complex, or its dissociation, you can set the complex’s initial concentrationdirectly. The concentration can be set heterogeneously, as a field variable. If you donot specify an initial concentration, or set an entry of “?”, the program takes thecomplex at the start of the simulation to be in equilibrium with the initial fluid.
You specify the initial concentration within a “kinetic” command or as a separatecommand line. For example, the commands
kinetic AlF++ rate_con = 3.3e-6, mpow(AlF++) = 1AlF++ = 1 umol/kg
are equivalent to
188
X1t Commands
kinetic AlF++ 1 umol/kg rate_con = 3.3e-6, mpow(AlF++) = 1
Either case defines a kinetic reaction for decomposition of the AlFCC ion pair, settingit initially to a free concentration of 1 �mol kg�1.
In X1t and X2t, you can similarly set the species’ concentration within the boundaryfluids directly
kinetic AlF++scope fluid-1
AlF++ = 4 umol/kgscope fluid-2
AlF++ = 8 umol/kg
or on a “kinetic” command
kinetic AlF++ fluid-1 = 4 umol/kg, fluid-2 = 8 umol/kg
If you do not set a value for a boundary fluid, or set it to “?”, the program takes thespecies to be in equilibrium with the fluid.
The following paragraphs apply to gas transfer reactions. Use the “f_ext” keyword tospecify the fugacity of the gas in question in the external reservoir, and keyword“contact” to set, in cm2/kg of water, the contact area between fluid and externalreservoir. Example:
kinetic CO2(g) f_ext = 10^-3.5, contact = 10
Both values can be set as field variables, as described in the Heterogeneity appendixto the GWB Reactive Transport Modeling Guide.
If you do not set a value for the gas’ external fugacity, or set “f_ext = ?”, the programuses the fugacity in the initial fluid, at the start of the simulation, and the externalfugacity.
The following paragraphs apply to redox reactions. You set the form of the redoxreaction to be considered as a character string, using the “rxn” (or “reaction”) keyword.For example,
kinetic redox-1 rxn = "Fe++ + 1/4 O2(aq) + H+ -> Fe+++ + 1/2 H2O"
To specify that the reaction be promoted by a heterogeneous catalyst, set keyword“catalyst” to the name of the catalyzing mineral, or simply to “on”. In the former case,you use keyword “surface” to set the specific surface area of the catalytic mineral (incm2/g). If you have set “catalyst = on”, however, you use the “surface” keyword to settotal catalytic area, in cm2. Setting “catalyst = off” disables the catalysis feature.
189
GWB Reference Manual
To set an enzymatically promoted reaction, set keyword “me” to the name of theaqueous species serving as the enzyme, or simply to the value to be used as theenzyme’s molality. In the former case, the program tracks the enzyme molality mE
over the course of the simulation from the calculated distribution of species. If youhave set a numeric value for mE using the “mE” keyword, the program uses this valuedirectly. You may alternatively specify the enzyme species or its activity aE usingkeyword “aE”, in which case variables mE , mA, and mP in the rate law are replacedby the activities aE , aA, and aP .
For an enzymatic reaction, you further set the halfsaturation constants KA and KP
for the forward and reverse reactions in molal with the “KA” and “KP” keywords. Youmust set a value for KA, but may omit KP , in which case the mP /KP term in the ratelaw will be ignored. Setting “enzyme = off” disables the enzyme feature.
The following paragraphs apply to microbial reactions.Yousettheformofthemetabolicreaction using the “rxn” (or “reaction”) keyword, in the same manner as with redoxreactions. For example,
kinetic microbe-1 rxn = "CH4(aq) + 2 O2(aq) -> HCO3- + H+ + H2O"
Set the halfsaturation constants KD and KA for the electron donating and acceptingreactions with the “KD” and “KA” keywords. These values default to zero.
You set the powers of species in the numerator of the rate law with the “mpower”keyword, as with other types of kinetic reactions. Use keywords “mpowerD” and“mpowerA” (or “mpowD” and “mpowA”) to set the powers PD, etc., of species from theelectron accepting and donating reactions, respectively, within the product functionsin the rate law’s denominator. For example,
kinetic microbe-1 mpower(CH4(aq)) = 1, mpowerD(CH4(aq)) = 1
sets the power of the electrondonating species CH4(aq) to one in both the rate lawnumerator and denominator. Keywords “PKD” and “PKA” set the overall powers PKD
and PKA of the electron donating and accepting terms in the denominator of the ratelaw; by default, these are one.
You set the free energy �GATP of ATP hydrolysis (in kJ/mol) with the “ATP_energy”keyword, and the value of nATP with keyword “ATP_number”. These values default tozero.
Use the “biomass” keyword to set the initial biomass concentration, in mg/kg. Youcan set this value as a field variable (see the Heterogeneity appendix to the GWB
Reactive Transport Modeling Guide).The “growth_yield” keyword sets the microbe’s growth yield in mg biomass/mol of
reaction progress, and “decay_con” sets its decay constant in sec�1; both valuesdefault to zero.
190
X1t Commands
7.53 left
left fluid = <boundary fluid>left <interval> fluid = <boundary fluid>left = <normal | inlet | outlet>
Flow ! boundaries: left
Use the “left” command to control the boundary condition at the left side of the domain:the fluid to appear at the boundary, and whether solutes can diffuse and disperse,and heat conduct, across the boundary.
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the leftboundary, for the entire simulation or an individual interval. For example, the commands
left fluid = ambient_waterleft phase2 fluid = pit_water
set fluid “ambient_water” on the left boundary over the course of the simulation, exceptduring interval “phase2”, in which case fluid “pit_water” is found on the boundary.
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
You can force the program to treat the left side of the domain as an inlet or freeoutlet boundary, regardless of the direction of fluid migration. Keyword “inlet” causesthe program to allow diffusion, hydrodynamic dispersion and heat conduction acrossthe left bound, whereas keyword “outlet” creates an insulated boundary sealed againsttransport by these processes:
left outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
See also the “right”, “discharge”, “head drop”, and “interval” commands.
191
GWB Reference Manual
7.54 length
length = <value> <unit>
Domain ! length (x) cm
Use the “length” command to set the length along x of the medium. You can useany unit of distance listed in the Units Recognized appendix; “cm” is the default. Bydefault, the domain is 100 cm long. See also the “width” and “height” commands.
7.55 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
log fugacity O2(g) = -65log activity U++++ = -10
7.56 mobility
mobility = <surface_type> = <field_variable> <steady | transient>mobility = <surface_type> = <value>mobility = <surface_type> <initial = <field_variable> <steady | transient>> \
<boundary_fluid> = <value>
File ! Open ! Sorbing Surfaces. . . ! mobility
fluids ! fluid
Use the “mobility” command to set up a complexing surface in your model as amobile colloid. A mobile colloid is composed of the mineral (or minerals) associatedwith a complexing surface, as well as the ion complexes present on that surface.Only datasets with model type “twolayer” as set in the dataset header are surfacecomplexation models, and hence only those datasets can be used to form a mobilecolloid.
Mobility refers to the fraction of the surface in question that can move in the modelby advection and dispersion. A surface with a mobility of one moves freely, whereasa mobility of zero sets the surface to be stationary. Intermediate values arise, forexample, when some of the surface is attached to the medium, or when colloid motionis impeded by electrostatic interactions. By default in the software the mobility of anysurface is zero.
192
X1t Commands
To set a mobile colloid, begin by reading in a surface complexation dataset using the“surface_data” command. Then, use the “mobility” command, referencing the surface’slabel, to set the colloid’s mobility. The label is given at the head of the surface dataset,on a line beginning “Surface type”. The label in dataset “FeOH.sdat”, for example, is“HFO”. If you omit the label, the program will assume you are referring to the surfacecomplexation dataset most recently read.
You can define the mobility of the domain (i.e., “initial” scope) as a field variable,which means you can have the program calculate mobility using an equation, script,or compiled function you provide. When you set the “transient” keyword, the programupon undertaking each time step in the simulation evaluates mobility at each nodalblock. In the “steady” case, which is the default, the program evaluates mobility ateach block just once, at the start of the run.
You can further define colloid mobility in a boundary fluid. If you do not set a value,mobility in an inlet stream is taken as the initial value assigned the first interior nodein the simulation.
In its simplest form, the command sets mobility for the current scope, either theinitial system or a boundary fluid. You can, however, set mobility for one or morescopes with a single command, by citing each scope’s name.
For example, since “HFO” is the label for the surface defined by dataset “FeOH.sdat”,the commands
surface_data FeOH.sdatscope initial
mobility HFO = 100%scope inlet_fluid1
mobility HFO = 0%
are equivalent to
surface_data FeOH.sdatmobility HFO initial = 100%, inlet_fluid1 = 0%
Restore the default behavior of immobility by entering a command such as
mobility HFO ?
7.57 noprecip
no-precip <off>
Config ! Iteration. . .
Usethe“noprecip”command(also:“noprecip”) topreventnewmineralsfromprecipitatingover the course of a simulation. By default, they are allowed to precipitate. Use:
193
GWB Reference Manual
no-precipno-precip off
See also the “precip” command.
7.58 nswap
nswap = <value | ?>
Config ! Iteration. . .
Use the “nswap” command to set the maximum number of times that the program mayswap entries in the basis in an attempt to converge to a stable mineral assemblage. Bydefault, this variable is set to 30. To restore the default value, type the command withno argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
7.59 Nx
Nx = <value | ?>
Domain ! nodes (Nx)
Use the “Nx” command to set in the simulation the number of nodal blocks along thex direction. By default, the program divides the medium into ten blocks along x.
7.60 pause
pause
Use the “pause” command to cause X1t to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
7.61 pe
pe = <field_variable>
Initial or Fluids ! pe
194
X1t Commands
Use the “pe” command to set oxidation state in the initial system in terms of pe. Thesetting applies to the initial system, a boundary fluid, or globally to all fluids, dependingon the current input scope (see the “scope” command). Example:
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, “fix”, and “slide”commands.
7.62 permeability
permeability <intercept = field_variable | ?> <unit> <steady | transient> \<porosity = field_variable | ?> <steady | transient> \<mineral = field_variable | ?> <steady | transient>
Medium ! A (porosity)
B (intercept) darcy
add
You use the “permeability” command to set the correlation by which the programcalculates sediment permeability. The correlation gives log permeability in any of theunits listed in the Units Recognized appendix (darcys by default) as a linear functionof the porosity (expressed as a volume fraction) of a nodal block and, optionally, thevolume fractions of one or more minerals. The “transient” keyword causes the modelto evaluate the coefficient in question continuously over the course of the simulation,if it is set with an equation, script, or function.
Examples:
permeability intercept = -11 cm2 porosity = 15permeability Kaolinite = -8
The latter command adds a term for the mineral Kaolinite to the existing correlation.To remove a term from the correlation, set a value of “?”. The entry
permeability Kaolinite = ?
for example, removes the correlation entry for that mineral.
195
GWB Reference Manual
The default correlation is
logk D �5C15�
where k is permeability in darcys and � is porosity (expressed as a fraction).
7.63 pH
pH = <field_variable>
Initial or Fluids ! pH
Use the “pH” command to set pH in the initial system. The setting applies to the initialsystem, a boundary fluid, or globally to all fluids, depending on the current input scope(see the “scope” command). Example:
pH = 5
is equivalent to
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
7.64 phrqpitz
phrqpitz
File ! Open ! Thermo Data. . . ! thermo_phrqpitz.tdat
Use the “phrqpitz” command to set the program to calculate species’ activitycoefficients using the HarvieMøllerWeare equations, as implemented in the USGSprogram PHRQPITZ. Executing this command automatically sets the input dataset ofthermodynamic data to “thermo_phrqpitz.tdat”. Note that dataset “thermo_phrqpitz.tdat”is primarily intended to support calculations at or near 25°C.
7.65 pitz_dgamma
pitz_dgamma = <value | ?>
Config ! Iteration. . .
196
X1t Commands
Use the “pitz_dgamma” command to control the relative change in an activity coefficient’svalue the program allows during each NewtonRaphson iteration, when a virial activitymodel (“the Pitzer equations”) has been invoked. By default, the program allows a10% change, which corresponds to a value of 0.1.
7.66 pitz_precon
pitz_precon = <value | ?>
Config ! Iteration. . .
Use the “pitz_precon” command to control the maximum number of passes the programtakes through the preconditioning loop before beginning a NewtonRaphson iteration,when a virial activity model (“the Pitzer equations”) has been invoked. By default, theprogram makes up to 10 passes. In cases of difficult convergence, counterintuitively,it can sometimes be beneficial to decrease this value.
7.67 pitz_relax
pitz_relax = <value | ?>
Config ! Iteration. . .
The “pitz_relax” command controls underrelaxation when evaluating a virial activitymodel (“the Pitzer equations”). The program at each NewtonRaphson iteration assignsactivity coefficients as a weighted average of the newly calculated value and thecorresponding value at the previous iteration level. Setting pitz_relax to zero eliminatesunderrelaxation, so the newly calculated values are used directly; a value of one, incontrast, should be avoided because it would prevent the activity coefficients frombeing updated. By default, the program carries an underrelaxation factor of 0.5.
7.68 pitzer
pitzer
File ! Open ! Thermo Data. . . ! thermo_pitzer.tdat
Use the “pitzer” command to set the program to calculate species’ activity coefficientsusing the Pitzer equations. Executing this command automatically sets the input datasetof thermodynamic data to “thermo_pitzer.tdat”. Note that dataset “thermo_pitzer.tdat”is intended to support calculations at or near 25°C.
197
GWB Reference Manual
7.69 plot
plot <character | bit | on | off>
Config ! Output. . .
Use the “plot” command to set the format of the “X1t_plot.xtp” dataset. The datasetcan be written in ascii characters, which are humanreadable and can be transferredsafely among computer systems, or as a bitstream, which is faster to read and write,more compact, and more accurate. The command “plot off” causes X1t to bypasswriting calculation results to the “X1t_plot.xtp” dataset, which is used to pass input toXtplot. By default, the program writes output to the dataset. The command “plot on”(or just “plot”) reenables the output. To see the current setting, type “show print”.
7.70 pluses
pluses <off | on | multicore | banner>
Config ! Stepping. . .
The “pluses” command controls whether the program writes a plus sign (“+”) to thescreen each time it converges to a solution of the chemical equations at a nodal block(keyword “on”); by default, it does not (keyword “off”). You can also set the programto write a distinct symbol for each thread active in tracing the simulation (keyword“multicore”), allowing you to observe the model as it runs in parallel. You can alsospecify the program write a banner giving details such as the number of iterationsrequired for convergence and the final residuals (keyword “banner”). The latter optionproduces unwieldy amounts of output, except for simple simulations.
7.71 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
198
X1t Commands
7.72 porosity
porosity = <field_variable | ?>
Medium ! porosity
Use the “porosity” command to set (as a volume fraction) the initial porosity of themedium. Porosity, the fraction of a nodal block occupied by fluid, is the ratio of fluidvolume to the sum of fluid, mineral, and inert volume.
The examples
porosity = 0.30porosity = 30%
are equivalent.When you specify the porosity, the program will at each nodal block figure the
difference between the volume taken up initially by minerals and fluid, and the block’sbulk volume. The program assigns this difference as inert, nonreactive volume (seethe “inert” command). In this case, the program ignores any settings that may havebeen made with the “inert” command.
When you do not specify an initial porosity with the “porosity” command, on the otherhand, the program calculates it from volumes in the nodal block of fluid, minerals, andinert space. To restore this default behavior, enter the command with an argument of“?”.
7.73 precip
precip <off>
Config ! Iteration. . .
Use the “precip off” command to prevent new minerals from precipitating over thecourse of a simulation. By default, they are allowed to precipitate. Use
precipprecip off
See also the “noprecip” command.
199
GWB Reference Manual
7.74 print
print <option> = <long | short | none>print <off | on>print <numeric | alphabetic>
Config ! Output. . .
Use the “print” command (also: “printout”) to control the amount of detail to be writteninto the “X1t_output.txt” dataset. For example, the dataset can contain informationabout each aqueous species, information on only species with concentrations greaterthan 10�8 molal, or no species information.
By default, the program does not produce these datasets, which can become quitelengthy. The command “print on” (or just “print”) causes them to be written, and “printoff” disables them.
Options, which may be abbreviated to three letters, and their default settings are:
species shortsurfaces longsaturations shortgases longbasis noneorig_basis longelements longreactions nonestagnant none
The “stagnant” option includes in the printout the diffusive profile within the stagnantzone, when the dual porosity feature is in use.
The “print” command can also be used to arrange entries in the output dataseteither numerically or alphabetically:
print numericprint alphabetic
To see the current print settings, type “show print”.
7.75 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
200
X1t Commands
7.76 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
7.77 radial
radial <r1 = value> <unit> <r2 = value> <unit><angle = value> <unit> <normal|reverse>
radial <off|on>
Domain !
Linear
SphericalReverse radialReverse spherical
Radial
Radial
Use the “radial” command (also: “wedge”) to set a radial flow system extending fromradius “r1” to radius “r2”, where “r1” is less than “r2”. Radii may be entered in units ofdistance (see the Units Recognized appendix); “cm” is the default. Keyword “angle”gives the angle of divergence of the medium, in “radians” (the default) or “degrees”. Bydefault, this value is 0.1 radians. To return to a linear geometry, type “radial off”. The“normal” keyword sets the domain to narrow from right to left; the “reverse” keywordsets it narrowing from left to right. See also the “spherical” command.
7.78 ratio
ratio <species ratio> = <value>
Initial or Fluids ! ratio
Use the “ratio” command to constrain an activity ratio in the initial system. The settingapplies to the initial system, a boundary fluid, or globally to all fluids, depending onthe current input scope (see the “scope” command). Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
201
GWB Reference Manual
7.79 react
react <amount (field_variable)> <unit> <as <element symbol>> \<species | mineral | gas> <cutoff> = <field_variable>
Reactants ! add !
Use the “react” command (abbrev.: “rct”) to define the reactants for the currentsimulation. (To set a kinetic rate law for a reactant, use the “kinetic” command.) Unitsfor the amount of reactant to add over a reaction path can be:
mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 lmol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
Units of mass or volume can be expressed per volume of the porous medium. Examples:
mol/cm3 g/cm3mmol/m3 ug/m3volume% "vol. fract"
Units of mass or volume can be set as absolute rates by appending “/s”, “/day”, “/yr”,or “/m.y.”. For example,
mmol/s g/day cm3/yrmol/kg/s mg/kg/day cm3/kg/yrmol/cm3/s kg/m3/yr m3/m3/yr volume%/m.y.
The latter units refer to rates per cm3 or m3 of porous medium, per unit time.Use the “as” keyword to specify reactant masses as elemental equivalents. For
example, the command
202
X1t Commands
react 10 umol/kg CH3COO- as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
react 20 mg/kg SO4-- as S
would cause the program to add 59.9 mg/kg of sulfate, since the ion’s mole weight isabout 3 times that of sulfur itself.
You can set a cutoff to limit the amount of a reactant. For example, if you set theamount of a reactant to two moles and set a cutoff of one, then X1t will add one moleof the reactant over the first half of the path and none over the second half. Enter thecutoff value in the same units as the amount of reactant. Examples:
react 10 grams Quartzreact 1e-2 mol Muscovite cutoff = .5e-2react .01 mol/day HCl
See also the “kinetic” and “remove reactant” commands.
7.80 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Seawater
Control returns to the user after the script has been read unless the script containsa “quit”command. You can also use the “read” command in place of the “data” or“surface_data” command to read a thermo or surface reaction dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
7.81 remove
remove <basis specie(s)> <reactant(s)> <interval(s)> <boundary fluid(s)>remove basis <basis specie(s)>remove reactant <reactant(s)>remove interval <interval(s)>
203
GWB Reference Manual
remove scope <boundary fluid(s)>
Initial or Fluids ! select entry(ies) ! delete
Reactants ! select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries orreactants from consideration in the calculation. Example:
remove Na+remove Quartz Calciteremove reactant H2O
Components can be reentered into the basis using the “swap”, “add”, “activity”, and“fugacity” commands. You can also use the “remove” command to remove boundaryfluids and simulation intervals
remove scope inlet_fluid1remove interval phase2
from the run configuration.
7.82 report
report <option>report set_digits <value>report set_node <index>
Once the program has completed a calculation, you can use the “report” commandto return aspects of the calculation results. You can use this command from theCommand pane to query the program interactively. More significantly, the “report”command provides a means of communicating calculation results to control scriptsand external programs running GWB programs by remote control.
For arguments available, see the Report Command appendix to this GWB Reference
Manual. For details about control scripts and the plugin feature, see theControl Scripts and Plugin Feature appendices. Use the “set_digits” argument to setthe number of significant digits in the values reported, and the “set_node” argumentto identify the node of interest.
7.83 reset
resetreset systemreset reactants
204
X1t Commands
reset variables
File ! Reset Configuration
Use the “reset” command to begin defining the chemical system again with a cleanslate. Your current settings will be lost, all options will be returned to their defaultstates. The command, however, does not alter the setting for the thermo dataset.The “reset system” command resets only the initial system. Similarly, typing “resetreactants” resets the reactant system, and “reset variables” sets each settable variableto its default value.
7.84 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exitedthe program. The program configuration is stored in a file “x1t_resume.x1t” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
7.85 right
right fluid = <boundary fluid>right <interval> fluid = <boundary fluid>right = <normal | inlet | outlet>
Flow ! boundaries: right
Use the “right” command to control the boundary condition at the right side of thedomain: the fluid to appear at the boundary, and whether solutes can diffuse anddisperse, and heat conduct, across the boundary.
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the rightboundary, for the entire simulation or an individual interval. For example, the commands
right fluid = ambient_waterright phase2 fluid = pit_water
205
GWB Reference Manual
set fluid “ambient_water” on the right boundary over the course of the simulation, exceptduring interval “phase2”, in which case fluid “pit_water” is found on the boundary.
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
You can force the program to treat the right side of the domain as an inlet or freeoutlet boundary, regardless of the direction of fluid migration. Keyword “inlet” causes theprogram to allow diffusion, hydrodynamic dispersion and heat conduction across theright bound, whereas keyword “outlet” creates an insulated boundary sealed againsttransport by these processes:
right outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
See also the “left”, “discharge”, “head drop”, and “interval” commands.
7.86 save
save <dataset>
File ! Save As. . .
Use the “save” command to write the current chemical system into a dataset in X1t
format commands. The dataset can be used as an X1t input script. Examples:
savesave kspar.x1t
If you don’t specify a dataset name, X1t will ask for one.
7.87 scope
scope <initial | boundary fluid>scope <initial | boundary fluid> = <initial | boundary fluid>scope <boundary fluid> rename <new name>
Initial or Fluids
Initial or Fluids ! copy
The “scope” command defines whether subsequent user commands apply to theinitial condition of the medium, to a boundary fluid, or globally, to all fluids that have
206
X1t Commands
been defined. The scope is initially set global. When you enter a scope commandwith “initial” as an argument
scope initial
the scope is set to the initial system. For any other argument
scope my_fluid
the scope is set to a boundary fluid of that name, creating it if necessary.Entering the command without an argument
scope
returns the scope global, as does entering any command of global meaning, such as“react” or “kinetic”. To see the current scope, type “show scope”.
The “scope” command can also be used to copy constraints on fluid compositionand temperature from one aspect of the calculation to another. For example, thecommand
scope my_fluid2 = my_fluid1
copies the basis constraints, temperature, TDS, and density from a boundary fluid“my_fluid1” to another “my_fluid2”.
scope inlet = initial
sets the inlet fluid to be the same as the fluid in the initial system.You can rename a boundary fluid, but not the initial system, using the “rename”
keyword.
7.88 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not onlyX1t commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
207
GWB Reference Manual
read GWB_files\\My_file.x1t
within a control script.
7.89 show
show <option>show <species | minerals | surfaces> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show gases show showshow altered show initial show speciesshow basis show kinetic show suppressedshow boundary show minerals show surfacesshow commands show oxides show systemshow couples show printout show variablesshow directory show reactantsshow elements show scope
The command “show show” gives a list of show command options. When you type“show species”, “show minerals”, or “show surfaces”, the program lists all speciesor minerals in the thermo database. A long form of the “show species” and “showminerals” commands lets you set the basis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
7.90 simax
simax = <value | ?>
Config ! Iteration. . .
208
X1t Commands
The “simax” command sets in molal units the maximum value of the stoichiometricionic strength used in calculating water activity when the DebyeHückel model isemployed. By default, this variable is set to 3 molal. To restore the default value, typethe command with no argument or with an argument of “?”. To see the current settingof this variable, type “show variables”.
7.91 slide
slide <unit> <species | gas> to <field_variable>
Reactants ! add !
Use the “slide” command to linearly adjust the activity of the specified species, fugacityof the gas, or an activity ratio toward <value>, which is attained at the end of the path.Note that the interpolation is made linearly on the logarithm of activity or fugacity if<value> is set as a log, and that <unit> can be “activity” or “fugacity” (“a” or “f” forshort), “ratio”, “pH”, “pe”, or “Eh”, or omitted. Examples:
slide pH to 5slide activity Cl- to 2/3slide f CO2(g) to 10^-3.5slide log f O2(g) to -65
7.92 sorbate
sorbate <exclude | include>
Config ! Iteration. . .
Use the “sorbate” command to tell the program, when considering sorption ontosurfaces (see the “surface_data” command), whether to include or exclude sorbedspecies in figuring the composition of the initial system. By default, the program doesnot include sorbed species in this calculation. If you set the CaCC concentration to 15mg/kg, for example, the initial system would contain that amount in the fluid and anadditional amount sorbed onto mineral surfaces. If you type the command “sorbate
209
GWB Reference Manual
include”, however, that amount would apply to the sum of the CaCC sorbed and insolution.
7.93 spherical
spherical <r1 = value> <unit> <r2 = value> <unit><angle = value> <unit> <normal|reverse>
spherical <off|on>
Domain !
Linear
Reverse radialReverse spherical
Radial
Spherical
RadialSpherical
Use the “spherical” command (also: “spike”) to set a spherical flow system extendingfrom radius “r1” to radius “r2”, where “r1” is less than “r2”. Radii may be entered inunits of distance (see the Units Recognized appendix); “cm” is the default. Keyword“angle” gives the angle of divergence of the medium, in “radians” (the default) or“degrees”. By default, this value is 0.1 radians. To return to a linear geometry, type“spherical off”. The “normal” keyword sets the domain to narrow from right to left; the“reverse” keyword sets it narrowing from left to right. See also the “radial” command.
7.94 start_date
start_date <value | off>
Config ! Stepping. . .
Use the “start_date” command to set an explicit starting date of the reaction. Thiscan be used to coordinate the plotting of dated scatter data samples stored in aGSS spreadsheet on the reaction path in Xtplot. The date should be in the format“MM/DD/YYYY”. Use “off” to return to the default of not set.
start_date 10/30/2008start_date off
7.95 start_time
start_time <value | off>
Config ! Stepping. . .
210
X1t Commands
Use the “start_time” command to set an explicit starting time of the reaction. Thiscan be used to coordinate the plotting of timed scatter data samples stored in aGSS spreadsheet on the reaction path in Xtplot. The time should be in the format“HH:MM:SS”. Use “off” to return to the default of not set.
start_time 11:30:00start_time off
7.96 step_increase
step_increase = <value | ?>
Config ! Stepping. . .
Use the “step_increase” command to set the greatest proportional increase, from onestep to the next, in the size of the time step. By default, this variable is set to 2.0. Torestore the default value, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show variables”.
7.97 step_max
step_max = <value | ?>
Config ! Stepping. . .
Use the “step_max” command to limit the number of reaction steps the program maytake to trace a simulation. Use a “?” to restore the default state, which is no prescribedlimit. To see the current setting, type “show variables”.
7.98 suffix
suffix <string>
Config ! Output. . .
Use the “suffix” command to alter the names of the output datasets (“X1t_output.txt”and “X1t_plot.xtp”) by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “X1t_output_run2.txt”.
211
GWB Reference Manual
7.99 suppress
suppress <species, minerals, gases, surface_species | ALL>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species, surfacespecies, minerals, or gases from being considered in a calculation. Example:
suppress H3SiO4- Quartz "Maximum Microcline"
prevents the three entries listed from being loaded from the database. Typing “suppressALL” suppresses all of the minerals in the thermodynamic database.
The “unsuppress” command reverses the process. To suppress all but a few minerals,you could type
suppress ALLunsuppress Quartz Muscovite Kaolinite
7.100 surface_capacitance
surface_capacitance = <value | ?>surface_capacitance on <type> = <value | ?>
File! Open! Sorbing Surfaces. . . ! constant capacitance F/m2
Use this command (abbrev.: “surf_capacitance”) to set, in units of F/m2, the capacitanceof a sorbing surface. When you set this value (or if a value for capacitance is setin the header of the surface reaction dataset), X1t will model surface complexationfor the surface in question using the constant capacitance model, rather than the fulltwolayer model.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_capacitance on HFO = 2
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_potential” commands.
212
X1t Commands
7.101 surface_data
surface_data <sorption dataset>surface_data remove <sorption dataset | surface type>surface_data OFF
File ! Open ! Sorbing Surfaces. . . ! add
File ! Open ! Sorbing Surfaces. . . ! select surface(s) ! delete
Use the “surface_data” command (abbrev.: “surf_data”) to specify an input datasetof surface sorption reactions to be considered in the calculation. The dataset nameshould be enclosed in quotes if it contains any unusual characters. Use the “remove”argument to eliminate a surface dataset, specified by name or surface type (e.g.,“HFO”), from consideration. The argument “OFF” disables consideration of all surfacecomplexes.
You can specify more than one sorbing surface in a model by repeating the“surface_data” command for different datasets (a dataset of surface reactions forsorption onto hydrous ferric oxide, as well as example datasets for the ion exchange,Kd , Freundlich, and Langmuir models are distributed with the software). To remove adataset of surface reactions from consideration, you use commands such as
surface_data remove FeOH.sdatsurface_data remove HFOsurface_data OFF
The latter command removes all of the surface datasets that have been loaded.
7.102 surface_potential
surface_potential = <value | ?>surface_potential on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant potential mV
Use this command (abbrev.: “surf_potential”) to set, in units of mV, the electricalpotential for a sorbing surface. When you set this value (or if a value is set in the surfacereaction dataset), X1t will model surface complexation for the surface in questionusing the constant potential, rather than full twolayer, method.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_potential on HFO = 0
213
GWB Reference Manual
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_data” commands.
7.103 swap
swap <new basis> <for> <basis species>
Initial or Fluids !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that you can alter to constrain the composition ofthe initial system. An aqueous species, mineral, gas, or activity ratio can be swappedinto the basis in place of one of the original basis species listed in the database. Theswap operates on either the initial system, a boundary fluid, or globally on all fluids,depending on the current input scope (see the “scope” command). Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
7.104 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving X1t. Example:
system "copy X1t_output.txt X1t_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the X1t command with a “$”:
214
X1t Commands
$copy X1t_output.txt X1t_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
7.105 TDS
TDS = <value | ?>
Initial or Fluids ! advanced ! TDS mg/kg
Use the “TDS” command to set in mg/kg the total dissolved solids for the currentinput scope, if you don’t want the program to calculate this value automatically. Theprogram uses the TDS when needed to convert input constraints into molal units.The setting applies to the initial system, a boundary fluid, or globally to all fluids,depending on the current input scope (see the “scope” command).
To restore automatic calculation of the TDS, type the command with no argumentor with an argument of “?”. To see the variable’s current setting, type “show variables”.
7.106 temperature
temperature = <field_variable> <unit>temperature = <value> <unit>temperature initial = <field_variable> <unit> <boundary fluid> = <value> <unit>temperature isothermaltemperature constant = <on | off>temperature reset
Initial ! temperature C
Fluids ! temperature C
Use the “temperature” command (also: “T”) to set the temperature of the initial systemor the boundary fluids. The Units Recognized appendix lists possible units, whichdefault to “C”. By default, the initial system and boundary fluids are set to 25°C and,in the absence of a heat source, the simulation proceeds isothermally.
In its simple usage, the command sets the temperature of the current scope:
scope initialtemperature = 25 C
215
GWB Reference Manual
scope inlet_fluid1temperature = 100 C
but you can also specify scope as a keyword on the command line
temperature initial = 25 C, inlet_fluid1 = 100 C
In the example, hot fluid invades an initially cool domain.Keyword “isothermal” sets the boundary fluid temperature(s) to the initial temperature
for the domain. Keyword “constant” causes the program to hold temperature at eachnodal block invariant over the course of the simulation, and the “reset” keyword returnstemperature variables to their default state.
You should enter temperature values within the range of the thermo dataset in use.For the default dataset “thermo.tdat”, the range is 0°C to 300°C.
7.107 thermal_cond
thermal_cond = <field_variable | ?> <unit> <steady | transient>
Medium ! thermal conductivity cal/cm/s/C
Use the “thermal_cond” command (abbrev.: “tcond”) to set the thermal conductivity of thefluidsaturated medium. You can specify one of the units listed in the Units Recognized
appendix; “cal/cm/sec/°C”is thedefault.Thisvalue isusedduringpolythermalsimulationsin calculating the effects of advective heat transport.
By default, this variable is set to 0.004 cal/cm/s/°C. The “transient” keyword causesthe model to evaluate the field variable continuously over the course of the simulation,if it is set with an equation, script, or function. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show system”.
7.108 theta
theta = <value | ?>
Config ! Stepping. . .
Use the “theta” command to set the time weighting variable used in evaluating kineticrate laws. The value may vary from zero (full weighting at the old time level) to one(full weighting at the new time level). By default, this variable is set to 0.6. To restorethe default value, type the command with no argument or with an argument of “?”. Tosee the current setting of this variable, type “show variables”.
216
X1t Commands
7.109 threads
threads = <value | ?>
Config ! Stepping. . .
Use the “threads” command to control the number of threads the program spawnswhen running a simulation. Using more than one thread on multicore or multiprocessorcomputers, the program runs in parallel, dividing the computing work among thecomputing cores available. By default (use the “?” argument), the program spawns onethread for each computing core. Typing the command without an argument returnsthe current setting and the number of computing cores available.
7.110 timax
timax = <value | ?>
Config ! Iteration. . .
The “timax” command sets in molal units the maximum value of ionic strength used incalculating species’ activity coefficients when the DebyeHückel model is employed.By default, this variable is set to 3 molal. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
7.111 time
time start = <value> <unit> <interval> = <value | ?> <unit> \end = <value> <unit>
Intervals ! start at day
interval_1 at day
end at day
Use the “time” command (abbrev.: “t”) to set the time span (keywords “start” and “end”)of the simulation, and the start times for individual simulation intervals. The startingtime for the run, by default, is zero. Unit choices are listed in the Units Recognized
appendix; “day” is the default. Examples:
time end = 100 yearstime start 10 days, end 20 daystime phase2 = 1 year, phase3 = 2 years, end = 10 years
217
GWB Reference Manual
Note that starting times and the end time are commonly and perhaps more clearlyspecified instead on the “intervals” command.
7.112 title
title <character string>
Config ! Output. . .
Use the “title” command to set a title to be passed to the graphics program. Example:
title "Yucca Mountain Groundwater"
Be sure to put multiword titles in quotes.
7.113 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
7.114 unsuppress
unsuppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies, minerals, or gases that have previously been suppressed. Examples:
unsuppress Quartz Albite "Albite low"unsuppress ALL
The argument “ALL” clears any species, minerals, or gases that have been suppressed.
218
X1t Commands
7.115 unswap
unswap <species | ALL>
Initial or Fluids ! !
Use the “unswap” command to reverse a basis swap. The swap reversal operates oneither the initial system, a boundary fluid, or globally on all fluids, depending on thecurrent input scope (see the “scope” command). Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
7.116 usgovt
usgovt
Help ! About X1t. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
7.117 width
width = <value> <unit>
Domain ! width (y) cm
Use the “width” command to set the width along y of the medium. You can useany unit of distance listed in the Units Recognized appendix; “cm” is the default.This command has no effect when modeling flow in radial coordinates. Domain widthdefaults to 1 cm in X1t. See also the “length” and “height” commands.
219
GWB Reference Manual
7.118 xtplot
xtplot <xtplot options>
Run ! Xtplot
The “xtplot” command launches program Xtplot from the X1t command line, invokinginput from the current graphics interface dataset (by default, “X1t_plot.xtp”; see the“suffix” command). For example,
xtplot xyplot
starts Xtplot initially showing an xy plot.
7.119 Xstable
Xstable = <value>
Config ! Stepping. . .
Use the “Xstable” command to control how the stability criterion for dispersive transportand thermal conduction is applied. A value of one sets the theoretically largest stabletime step for an ideal situation. X1t simulations are not necessarily ideal (for example,the solute may react and the medium may not be uniform), so this limiting time stepmay in fact be too large to be stable. Setting “Xstable” to a value smaller than oneresults in a more stringent constraint on the time step, and hence greater stability.The default value for this variable is 1.0, the theoretical limit. See also the “Courant”command.
220
X2t Commands
8.1 <unit>
<field_variable> <free> <unit> <as element symbol> <basis entry>
Initial or Fluids ! free kg
To constrain chemical composition, enter a command containing only the above entries.Entries may appear in any order. The qualifier “free” specifies that the constraint appliesto the free rather than to the bulk basis entry. Settings constrain the composition ofthe initial system, a boundary fluid, or globally to all fluids, depending on the currentinput scope (see the “scope” command). X2t recognizes the following units:
By mass or volume:mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 l
By concentration:mol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
By carbonate alkalinity (applied to bicarbonate component):eq_acid meq_acid ueq_acid neq_acideq_acid/kg meq_acid/kg ueq_acid/kg neq_acid/kgeq_acid/l meq_acid/l ueq_acid/l neq_acid/lg/kg_as_CaCO3 mg/kg_as_CaCO3 ug/kg_as_CaCO3 ng/kg_as_CaCO3wt%_as_CaCO3g/l_as_CaCO3 mg/l_as_CaCO3 ug/l_as_CaCO3 ng/l_as_CaCO3
Per volume of the porous medium:mol/cm3 mmol/cm3 umol/cm3 nmol/cm3
221
GWB Reference Manual
kg/cm3 g/cm3 mg/cm3 ug/cm3ng/cm3mol/m3 mmol/m3 umol/m3 nmol/m3kg/m3 g/m3 mg/m3 ug/m3ng/m3volume% "vol. fract."
By activity:activity fugacity ratiopH V pe
Activity and fugacity may be abbreviated to “a” or “f”. Keyword “total” reverses a settingof “free”.
Use the “as” keyword to constrain mass in terms of elemental equivalents. Forexample, the command
CH3COO- = 10 umol/kg as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
20 mg/kg SO4-- as S
would specify 59.9 mg/kg of sulfate, since the ion’s mole weight is about 3 times thatof sulfur itself.
Examples:
55 mg/kg HCO3-Na+ = 1 molal1 ug/kg U++++10 volume% DolomitepH = 8Eh = .550 Vlog f O2(g) = -60HCO3- = 30 mg/kg as C
You may in a similar fashion constrain the concentration of a kinetic aqueous orsurface complex in the initial system, a boundary fluid, or globally. For example, thecommands
kinetic AlF++AlF++ = 1 umol/kgscope ambient_water
AlF++ = 10 umol/kg
set the concentration of the kinetic complex AlFCC to 1 �mol kg�1 in all fluids, exceptfluid “ambient_water”, where its concentration is ten times greater.
222
X2t Commands
8.2 activity
activity <species> = <field_variable>
Initial or Fluids ! activity
Use the “activity” command (abbrev.: “a”) to constrain the activity of an aqueousspecies. The setting applies to the initial system, a boundary fluid, or globally to allfluids, depending on the current input scope (see the “scope” command). Examples:
activity Na+ = 0.3log a H+ = -5
See also the “pH”, “Eh”, “pe”, “ratio”, “fugacity”, “fix”, and “slide” commands.
8.3 add
add <basis species>
Initial or Fluids ! add
Use the “add” command to include a basis species in the calculation. Example:
add HCO3-
See also the “swap”, “activity”, “fugacity”, “pH”, “pe”, and “Eh” commands.
8.4 alkalinity
alkalinity = <field_variable> <unit>
Initial or Fluids !
HCO3- mg/kg_as_CaCO3
Use the “alkalinity” command to constrain the total concentration of HCO�
3 to reflectthe solution’s carbonate alkalinity. The setting applies to the initial system, a boundaryfluid, or globally to all fluids, depending on the current input scope (see the “scope”command). You can specify one of the units listed in the Units Recognized appendix;“mg/kg_as_CaCO3” is the default. To use this option, the solution pH must be setexplicitly.
223
GWB Reference Manual
8.5 alter
alter <species | mineral | gas> <log K ’s>
Config ! Alter Log Ks. . .
Use the “alter” command to change values of the equilibrium constant for the reactionof a species, mineral, or gas. Equilibrium constants are given as log(10) K ’s at theeight principal temperatures specified in the current thermo dataset, most commonly0°C, 25°C, 60°C, 100°C, 150°C, 200°C, 250°C, and 300°C. Values of “500” representa lack of data at the corresponding temperature. Example:
alter Quartz -4.5 -4 -3.5 -3.1 -2.7 -2.4 -2.2 -2
Type “show alter” to list altered log K ’s; the “unalter” command reverses the process.
8.6 audit
audit <off>
Config ! Stepping. . .
Use the “audit” option to cause the program to perform a mass balance audit duringthe simulation and report at the end of the run the mass imbalance observed for eachoriginal basis entry. Use:
auditaudit off
By default, the program does not perform the audit.
8.7 balance
balance <on> <basis entry>
Initial or Fluids ! unit ! Balance species
Use the “balance” command to specify the basis entry to be used for electrical chargebalancing. The setting applies to the initial system, a boundary fluid, or globally to allfluids, depending on the current input scope (see the “scope” command). The basisentry must be a charged aqueous species. By default, X1t balances on Cl�. Example:
balance on Na+
224
X2t Commands
8.8 bottom
bottom fluid = <boundary fluid>bottom <interval> fluid = <boundary fluid>bottom = <normal | inlet | outlet>
Flow ! boundaries: bottom
In simulations in which the flow field is imported, and only such simulations, use the“bottom” command to control the boundary condition at the bottom side of the domain:the fluid to appear at the boundary, and whether solutes can diffuse and disperse,and heat conduct, across the boundary.
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the bottomboundary, for the entire simulation or an individual interval. For example, the commands
bottom fluid = ambient_waterbottom phase2 fluid = pit_water
set fluid “ambient_water” on the bottom boundary over the course of the simulation,except during interval “phase2”, in which case fluid “pit_water” is found on the boundary.
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
You can force the program to treat the bottom of the domain as an inlet or freeoutlet boundary, regardless of the direction of fluid migration. Keyword “inlet” causesthe program to allow diffusion, hydrodynamic dispersion and heat conduction acrossthe bottom bound, whereas keyword “outlet” creates an insulated boundary sealedagainst transport by these processes:
bottom outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
See also the “left”, “top”, “right”, “discharge”, “head drop”, and “interval” commands.
225
GWB Reference Manual
8.9 chdir
chdir <directory> <ALL>
File ! Working Directory. . .
Use the “chdir” command (abbrev.: “work_dir”, “cd”) to change the working directory.The program reads input scripts relative to the current working directory and writesoutput into it. Typing the command “chdir” without an argument causes the program todisplay the name of the working directory. The “ALL” argument changes the workingdirectories of all of the GWB apps. The command
chdir ~
changes to the user’s home directory, if one is defined by the operating system.
8.10 clear
clear
View ! Clear Screen
Use the “clear” command (abbrev.: “c”) or rightclick in the text window and chooseClear Screen to clear it.
8.11 clipboard
clipboard
Edit ! Copy
The “clipboard” command causes the contents of the Results pane to be copied tothe clipboard, from where it can be pasted into various types of documents.
8.12 conductivity
conductivity <conductivity dataset>
File ! Open ! Conductivity Data. . .
Use the “conductivity” command to change the input file of coefficients used to calculateelectrical conductivity. Example:
226
X2t Commands
conductivity "..\my_conductivity.dat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.Beginning with GWB11, the applications compute electrical conductivity using eitherof two different approaches, the USGS and APHA methods; the USGS method is thedefault. The required coefficients are defined in the files “conductivityUSGS.dat” and“conductivityAPHA.dat”, respectively, which are installed in the same directory as thethermo datasets (commonly “\Program Files\GWB\Gtdata”).
8.13 couple
couple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “couple” command to enable any redox coupling reactions that have beendisabled with the “decouple” command. You specify one or more redox species orelements. For example, the command
couple Carbon
couples all redox reactions involving the element carbon. Argument “ALL” enables allof the coupling reactions in the thermo dataset.
8.14 Courant
Courant = <value | ?>
Config ! Stepping. . .
Use the “Courant” command to constrain the time step according to the Courantcondition. You enter a value for the Courant number, which is the ratio of the distancefluid travels over a time step to the length of the nodal blocks. If you set a Courantnumber of one, then X2t will select a time step over which the fluid will exactly traversethe nodal blocks. For a value of 0.5, the fluid will move halfway across the nodalblocks, and so on. Values greater than one for the Courant number typically giveunstable solutions and are therefore not recommended. By default, X2t assumes aCourant number of 1.0. The “?” argument resets the default value.
227
GWB Reference Manual
8.15 cpr
cpr = <field_variable> <unit> <steady | transient>
Medium ! cpr (minerals) cal/g/C
Use the “cpr” command to set the heat capacity of the rock (mineral) framework. Youcan specify one of the units listed in the Units Recognized appendix; “cal/g°C” is thedefault. This value is used during polythermal simulations in calculating the effectsof advective heat transport. The “transient” keyword causes the model to evaluatethe field variable continuously over the course of the simulation, if it is set with anequation, script, or function.
By default, this variable is set to 0.2 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
8.16 cpu_max
cpu_max = <value | ?>
Config ! Stepping. . .
Use the “cpu_max” command to limit the amount of computing time a simulationmay take. You set the maximum computing time in seconds, or use a “?” to restorethe default state, which is no prescribed limit. To see the current setting, type “showvariables”.
8.17 cpw
cpw = <field_variable> <unit> <steady | transient>
Medium ! cpw (fluid) cal/g/C
Use the “cpw” command to set in cal/g°C the heat capacity of the fluid. You can specifyone of the units listed in the Units Recognized appendix; “cal/g°C” is the default. Thisvalue is used during polythermal simulations in calculating the effects of advectiveheat transport. The “transient” keyword causes the model to evaluate the field variablecontinuously over the course of the simulation, if it is set with an equation, script, orfunction.
By default, this variable is set to 1.0 cal/g°C. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
228
X2t Commands
8.18 data
data <thermo dataset> <verify>
File ! Open ! Thermo Data. . .
Use the “data” command to change the input file of thermodynamic data. Example:
data "..\my_thermo.tdat"
The dataset name may need to be enclosed in quotes if it contains unusual characters.The “verify” option causes the program to read the named dataset only if it has notalready been read.
8.19 debyehuckel
debye-huckel
File ! Open ! Thermo Data. . . ! thermo.tdat
The “debyehuckel” command (abbrev.: “dh”) sets the program to calculate species’activity coefficients using the extended DebyeHückel equations. Executing thiscommand automatically sets the input dataset of thermodynamic data to “thermo.tdat”.
8.20 decouple
decouple <redox species | element(s) | ALL>
Config ! Redox Couples. . . ! select couple(s) ! select with. . .
Use the “decouple” command to disable the coupling reactions for one or more redoxspecies, in order to calculate a model assuming redox disequilibrium. The redoxspecies then become available for use as basis species and may be constrainedindependently of the original basis entries. You can disable as many coupling reactionsas you want.
You specify either one or more redox species or elements. For example, the command
decouple Carbon
decouples all redox reactions involving the element carbon. Argument “ALL” disablesall of the coupling reactions in the thermo dataset. Use the “couple” command toenable coupling reactions, once they have been disabled.
229
GWB Reference Manual
8.21 delQ
delQ = <value | ?>
Config ! Stepping. . .
Use the “delQ” command to control the lengths of time steps taken in a simulationaccounting for reaction kinetics. The program limits how much the ion activity productQ can change over a step, for each kinetic reaction considered. The setting for “delQ”is the projected change �Q=Q allowed in the relative value of the activity product.You can set a larger value to permit longer time steps, or a smaller value to improvestability. The default setting is 0.1. Type the command with no argument or with anargument of “?” to restore the default. To see the current setting, type “show variables”.
8.22 deltar
deltar = <field_variable> <unit>
Domain ! delta r cm
The “deltar” (also: “delta_r”) command is a synonym for the “deltax” command,described below. It is provided for clarity when working with radial domains.
8.23 deltax
deltax = <field_variable> <unit>
Domain ! delta x cm
The “deltax” (also: “delta_x”) command sets the length �x of nodal blocks in thefinite difference grid. You can specify one of the units listed in the Units Recognized
appendix; “cm” is the default.When you set a value for �x, the program ignores any setting of the “length”
command and figures the domain length from the values of �x and Nx , the numberof nodal blocks specified along x. For example, the commands
Nx = 10deltax = 1 m
are equivalent to
Nx = 10Length = 10 m
230
X2t Commands
You can set �x as a field variable, in order to create grids of varying node density.For example, the commands
Nx = 10deltax = { 1 1 .5 .5 .25 .25 .5 .5 1 1 } m
set a grid in which nodal blocks near the center of the domain are smaller than thosenear the left and right sides. The domain in this case will be 7 m long. See also the“deltay”, “length”, and “Nx” commands.
8.24 deltay
deltay = <field_variable> <unit>
Domain ! delta y cm
The “deltay” (also: “delta_y”) command sets the width �y of nodal blocks in thefinite difference grid. You can specify one of the units listed in the Units Recognized
appendix; “cm” is the default.When you set a value for�y, the program ignores any setting of the “width” command
and figures the domain length from the values of �y and Ny , the number of nodalblocks specified along y. For example, the commands
Ny = 10deltay = 1 m
are equivalent to
Ny = 10width = 10 m
You can set �y as a field variable, in order to create grids of varying node density.For example, the commands
Ny = 10deltay = { 1 | 1 | .5 | .5 | .25 .25 | .5 | .5 | 1 | 1 } m
set a grid in which nodal blocks near the center of the domain are smaller than thosenear the bottom and top. (Notice the use of vertical bars to separate entries in thefield variable, since the �y vector runs vertically.) The domain in this case will be 7m wide. See also the “deltax”, “width”, and “Ny” commands.
231
GWB Reference Manual
8.25 delxi
delxi = <value | ?>
Config ! Stepping. . .
Use the “delxi” command to set the maximum length (in terms of reaction progress,which varies from zero to one over the course of the simulation) of the time step. Bydefault, this variable is set to 0.01. To restore the default value, type the command withno argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
8.26 density
density = <value | ?>density = <TDS | chlorinity>
Initial ! advanced ! density g/cm3 TDS chlorinity
Fluids ! advanced ! density g/cm3
You can use the “density” command to set in g/cm3 the fluid density the programuses to convert compositional constraints to molality, the concentration unit it carriesinternally. If you set the initial NaC composition in mg/l, for example, the programneeds to know the density of the initial fluid to determine NaC molality. The settingapplies to the initial system, a boundary fluid, or globally to all fluids, depending onthe current input scope (see the “scope” command).
The program by default converts units using a density value it calculates automatically,as discussed below. This value is sufficient for most purposes, and hence it is generallynot necessary to set fluid density explicitly. You might, however, want to set the densityif you are working at high temperature, but your analysis is expressed per liter ofsolution at room temperature.
You can also use the “density” command to tell the program how to calculate thedefault density it uses to convert units, and the fluid density it reports in the simulationresults. The program normally figures density as that of an NaCl solution with thesame TDS as the fluid in question, at the temperature of interest. With the command“density = chlorinity” you can tell the program to instead use the density of an NaClsolution of equivalent chlorinity.
To restore automatic calculation, type the command with no argument or with anargument of “?”. To see the current setting of this variable, type “show variables”.
232
X2t Commands
8.27 diffusion_coef
diffusion_coef = <field_variable | ?> <unit> <steady | transient>
Medium ! diffusion coefficient cm2/s
Use the “diffusion_coef” command (abbrev.: “diff_coef”) to set a value for the diffusioncoefficient in one of the units listed in the Units Recognized appendix. The “transient”keyword causes the model to evaluate the field variable continuously over the courseof the simulation, if it is set with an equation, script, or function. By default, X2t assumesa diffusion coefficient of 10�6 cm2/s. The “?” argument resets the default value.
8.28 discharge
discharge = <value | open | closed | ?> <unit>discharge <interval> = <value | open | closed | ?> <unit>discharge <left | right> = <value | open | closed | ?> <unit>discharge <left | right> <interval> = <value | open | closed | ?> <unit>
discharge fluid = <boundary fluid>discharge <interval> fluid = <boundary fluid>discharge <left | right> fluid = <boundary fluid>discharge <left | right> <interval> fluid = <boundary fluid>
discharge x = <field_variable> <unit> y = <field_variable> <unit>discharge x <interval> = <field_variable> <unit>discharge y <interval> = <field_variable> <unit>discharge <bottom | top> fluid = <boundary fluid>discharge <bottom | top> <interval> fluid = <boundary fluid>
Flow ! interval 1: discharge cm/s
Use the “discharge” command to set a value for the specific discharge (fluid volumecrossing a unit area per unit time) across the domain’s left or right boundary, or both,and to set the fluid to appear at the boundary or boundaries. Alternatively, you canuse this command to import a groundwater flow field from another program.
You use the “left” or “right” keyword to specify the boundary in question. If neitherside is specified, the command sets flow across both boundaries, which can notuncommonly lead to contradictory boundary conditions. For example, there is no flowfield that can honor boundary conditions in which the right and left discharges arethe equal, if there is an injecting or producing well within the domain. For this reason,you typically set discharge across the left or the right boundary, but not both.
Keyword “closed” sets a zero flux across the boundary or boundaries in question,and “open” returns the boundary or boundaries to the default state.
233
GWB Reference Manual
If the “discharge” command contains the name of a simulation interval, subsequentsettings on the command apply to that interval, rather than the simulation as a whole.This behavior continues to the end of the command, or until the name of anotherinterval is encountered.
By default, both boundaries are held open to flow and the discharge across them isdetermined from the permeability of the domain, the fluid viscosity, the driving force forflow (set using the “head_drop” command), and the rates at which fluid is producedfrom or injected into any wells. A value of “?” returns the setting for the boundary inquestion, or both boundaries, to the default condition.
When, on the other hand, you specify the discharge across one or, less commonly,bothof theboundaries, the programuses this value (or values) togetherwith permeability,viscosity, and the well production and injection rates to determine the flow pattern.
A value for discharge may be set in any of the units of velocity or specific dischargelisted in the Units Recognized appendix. The default is cm/s, which is equivlent tocm3/cm2/s. In addition, you may use the unit “pore_volumes” (or “pv”) to specifydischarge in terms of the number of times the original pore volume is to be replacedover the course of the reaction model.
Examples:
discharge left = 15 m/daydischarge right = -100 pore_volumesdischarge right = ?discharge right start = 10 m/yr interval-2 = 20 m/yr
A positive value represents flow from left to right, and a negative value denotes flowin the opposite direction.
You can also specify the boundary fluid to appear on either or both the left andright boundaries, for the entire simulation or an individual interval. To do so, you usethe “fluid” keyword. In the examples
discharge left = .002 m/s fluid = ambient_waterdischarge left phase2 fluid = pit_water
fluid “ambient_water” flows across the left boundary at a discharge of .002 m s�1
over the course of the simulation, except during interval “phase2”, in which case fluid“pit_water” flows into the domain. In a simulation employing an imported flow field,and only such a simulation, you may as well set the fluids to appear at the bottomand top of the domain.
Alternatively, you can use this command together with the “x” and “y” keywords toimport a flow field from another program. To do so, prepare a table of the specificdischarge along x from node to node in the domain, and a second table containing similarvalues for flow along y. For information on preparing tables, see the Heterogeneity
appendix to the GWB Reactive Transport Modeling Guide.When importing a flow field, the xdirection table should contain NxC1 columns
and Ny rows of values. The first table column holds values for flow across the left
234
X2t Commands
boundary into or out of the first column of nodes. The second table column representsflow from the first column of nodes to the second, and so on, until the last column,which holds values for flow across the right boundary. Similarly, the ydirection tablehas Nx columns and NyC1 rows, the first row representing flow across the bottombound and the last for flow across the top.
You can use the “modflow” command to import flow fields directly from the results of aMODFLOW model. In this case, settings made using the “discharge” and “head_drop”commands are ignored. For more information, see the Importing From MODFLOW
appendix to the GWB Reactive Transport Modeling Guide.See also the “left”, “right”, and “head_drop” commands.
8.29 dispersivity
dispersivity long = <field_variable> | ?> <unit> <steady | transient> \trans = <field_variable> | ?> <unit> <steady | transient>
dispersivity = <field_variable> | ?> <unit>
Medium ! longitudinal dispersivity cm
transverse dispersivity cm
Use the “dispersivity” command to set values for the longitudinal and transversecomponents of the hydrodynamic dispersivity. The “transient” keyword causes themodel to evaluate the field variable continuously over the course of the simulation, ifit is set with an equation, script, or function. You can specify one of the units listed inthe Units Recognized appendix; “cm” is the default. Example:
dispersivity long = 100 cm, trans = 10 cm
Note that the longitudinal component is greater than or equal to the transversecomponent. By default, X2t assumes a value equal to 1% of the length of the domain(see the “length” command) for the longitudinal component; the transverse componentis set to 10% of the longitudinal value. The second form of the command sets bothcomponents to a single value. The “?” argument resets the default state.
8.30 dual_porosity
dual_porosity = <on | off> <blocks | spheres | fractures> \<geometry = <blocks | spheres | fractures | ?>> \<volfrac = <field_variable | ?>> \<Nsubnode = <value | ?>> \<<half-width | radius> = <field_variable | ?> <unit>> \<diff_length = <field_variable | ?> <unit>> \<porosity = <field_variable | ?>> \<retardation = <field_variable | ?>> <steady | transient> \
235
GWB Reference Manual
<diff_coef = <field_variable | ?> <unit>> <steady | transient> \<thermal_con = <field_variable | ?> <unit>> <steady | transient> \<theta = <value | ?>> <reset | ?>
Config ! Dual Porosity. . .
Use the “dual_porosity” command (abbrev: “dual”) to configure stagnant zones inthe simulation, using the dual porosity feature. Enable and disable the feature withthe “on” and “off” keywords. Disabling the feature does not affect other settings, soreenabling the feature returns the model to its most recent configuration.
With the “geometry” keyword, you configure the stagnant zone into blocks, spheres,or a fractured domain, the latter being slabs separated by fractures arrayed along thex direction. Alternatively, you can set the three configurations directly with keywords“blocks”, “spheres”, and “fractures”. Keyword “volfrac” sets the fraction of the nodalblock’s bulk volume occupied by the stagnant zone.
The “Nsubnode” (or “nx”) keyword sets the number of nodes into which the stagnantzone within each node will be divided when solving for solute and temperaturedistributions. The “halfwidth” (or “radius”, for spherical geometries) keyword setsthe zone’s characteristic dimension, in units of distance (see the Units Recognized
appendix; default is cm), and keyword “diff_length” sets the distance (same units) fromthe contact with the freeflowing zone over which the model will account for solutediffusion and heat conduction. Use keywords “porosity”, “retardation”, “diff_coef”, and“thermal_con” to set values for the porosity, retardation factor, diffusion coefficient,and thermal conductivity of the stagnant zone. The default unit for the diffusioncoefficient is cm2/s, and thermal conductivity defaults to cal/cm/s/°C units; see theUnits Recognized appendix for a list of options.
By default, the stagnant zone is configured in blocks divided into 5 subnodes. Youmust specify a value for the volume fraction of the stagnant zone, as well as one forthe halfwidth (or radius); the diffusion length defaults to the latter value. The programuses whatever values are set for the freeflowing zone in the node in question asdefault values for the porosity, diffusion coefficient, and thermal conductivity of thestagnant zone; the retardation factor defaults to a value of one.
The “theta” keyword sets time weighting (0 � � � 1) for the numerical solution ofdiffusive transport within the stagnant zone. A weight � D 0 assigns the explicit method,and larger values invoke an implicit solution. By default, the program chooses �
automatically, using the explicit method unless it would force too many more timesteps than would otherwise be necessary. In that case, the program uses the implicitmethod (� D 0:6), which requires more computing effort per time step, but can takelong steps without becoming numerically unstable.
You can append the “transient” keyword when setting several of the parameters:the diffusion coefficient, thermal conductivity, and retardation factor. If the variableis defined by an equation, script, or external function, it will then be reevaluatedcontinuously over the course of the run.
As an example, the command
236
X2t Commands
dual_porosity geometry = spheres, radius = 50 cm, volfrac = 75%
configures the stagnant zone into spheres of halfmeter radius that occupy threequarters of the domain. The command
dual_porosity reset
enables the feature after restoring default settings for each keyword.
8.31 dx_init
dx_init = <value | ?>
Config ! Stepping. . .
Use the “dx_init” command to set the length of the initial time step. You set this valuein terms of reaction progress, which varies from zero to one over the course of thesimulation. By default, the variable is ignored. To restore the default state, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
8.32 dxplot
dxplot = <value | ?> <linear | log> <exact | approx>
Config ! Output. . .
Use the “dxplot” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “X2t_plot.xtp”dataset, and to specify the entries be spaced on a linear or logarithmic scale. Avalue of zero causes the program to write the results after each time step, which canproduce unwieldy amounts of output.
The command
dxplot = .1 linear
for example, causes the program to write entries for when reaction progress is .1, .2,.3, . . . , and 1.0. Alternatively, the commands
dx_init = .001dxplot = .5 log
produce entries at .001, .003, .01, .03, .1, .3, and 1.0 (see the “dx_init” command).
237
GWB Reference Manual
The arguments “exact” and “approx” define whether the program will constrain thesizes of time steps to give entries that match the specified increment exactly (thedefault case), or will output entries whenever the time stepping meets or exceeds theincrement.
By default, this variable is set to 0.02, “linear”, and “exact”. To restore the defaultsettings, type the command with no argument or with an argument of “?”. To see thecurrent settings, type “show variables”.
8.33 dxprint
dxprint = <value | ?> <linear | log> <exact | approx>
Config ! Output. . .
Use the “dxprint” command to set the interval in reaction progress (which varies fromzero to one over the course of the simulation) between entries in the “X2t_output.txt”dataset, and to specify the entries be spaced on a linear or logarithmic scale. Avalue of zero causes the program to write the results after each time step, which canproduce unwieldy amounts of output.
The command
dxprint = .1 linear
for example, causes the program to write entries for when reaction progress is .1, .2,.3, . . . , and 1.0. Alternatively, the commands
dx_init = .001dxprint = .5 log
produce entries at .001, .003, .01, .03, .1, .3, and 1.0 (see the “dx_init” command).The arguments “exact” and “approx” define whether the program will constrain the
sizes of time steps to give entries that match the specified increment exactly (thedefault case), or will output entries whenever the time stepping meets or exceeds theincrement.
By default, this variable is set to 0.1, “linear”, and “exact”. To restore the defaultsettings, type the command with no argument or with an argument of “?”. To see thecurrent settings, type “show variables”.
8.34 Eh
Eh = <field_variable> <unit>
Initial or Fluids ! Eh
238
X2t Commands
Use the “Eh” command to set Eh in the initial system. Example:
Eh = 200 mV
sets the system’s oxidation state to correspond to an Eh of 0.2 volt. The setting appliesto the initial system, a boundary fluid, or globally to all fluids, depending on the currentinput scope (see the “scope” command). See also the “activity”, “pH”, “pe”, “fugacity”,“fix”, and “slide” commands.
8.35 epsilon
epsilon = <value | ?>
Config ! Iteration. . .
Use the “epsilon” command to set the convergence criterion (dimensionless) foriterating to a solution of the equations representing the distribution of chemical mass.By default, this variable is set to 5�10�11 . To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
8.36 exchange_capacity
exchange_capacity = <field_variable | ?> <units>exchange_capacity on <type> = <field_variable | ?> <units>
File ! Open ! Sorbing Surfaces. . . ! exchange capacity eq
Use the “exchange_capacity” command (abbrev.: “ex_capacity” or “exch_capacity”) toset the exchange capacitiy (i.e., the CEC) of the system when modeling ion exchangereactions or sorption according to Langmuir isotherms. For ion exchange reactions,you set units of electrical equivalents (“eq”, “meq”, and so on) or equivalents per gramof dry sediment (“eq/g”, “meq/g”, . . . ). For Langmuir reactions, you similarly set a valuein mole units: “mol”, “mmol”, “mol/g”, “mmol/g”. If you set units per gram of sediment,the program multiplies the value entered by the mass of rock in the system (includingequilibrium and kinetic minerals as well as inert volume) to get the system’s capacity.
If you read in a surface that sorbs by ion exchange or Langmuir isotherms, youmust set a value for its exchange capacity. If you have set more than one sorbingsurface (using the “surface_data” command), you identify the surface in question byits “type”. For example
exchange_capacity on IonEx = .0008 eq/g
239
GWB Reference Manual
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the surface represented by the sample dataset “IonEx.sdat”,for example, is “IonEx”. You can use the “show” command to display the “type” ofeach active surface. See also the “surface_data” and “inert” commands.
8.37 explain
explain <species | mineral(s) | gas(es) | surface_species>
Config ! Show. . . ! select species
Use the “explain” command to get more information (such as the mole weight of aspecies or a mineral’s formula and mole volume) about species, minerals, and gasesin the dataset. Example:
explain Analcime
8.38 explain_step
explain_step <off>
Config ! Stepping. . .
The “explain_step” option causes the program to report on the Results pane the factorcontrolling the length of each time step, whenever the step size is limited by the needto maintain numerical stability.
8.39 extrapolate
extrapolate <off>
Config ! Alter Log Ks. . .
Use the “extrapolate” option to cause the program to extrapolate log K ’s for reactionsforming species, minerals, and gases to temperatures outside the range of dataprovided in the thermo dataset. Missing entries in the dataset are marked by valuesof 500. Normally, the program will not load species, minerals, or gases whose log Kvalues do not span the temperature range of the calculation.
When the “extrapolate” option is invoked, the program will estimate log K ’s asfunctions of temperature by making a polynomial fit to the data provided. Use thisoption with considerable care.
240
X2t Commands
8.40 fix
fix <unit> <species | gas>
Reactants ! add !
Use the “fix” command to hold the activity of a species, fugacity of a gas, or an activityratio constant over the course of a run. The <unit> can be “activity” or “fugacity” (“a”or “f” for short), “ratio”, “pH”, “pe”, or “Eh”, or it can be omitted. Examples:
fix pHfix a H+fix f O2(g)fix ratio Ca++/Na+^2
8.41 fugacity
fugacity <gas> = <field_variable>
Initial or Fluids ! fugacity
Use the “fugacity” command (abbrev.: “f”) to set gas fugacities (on an atm scale) in theinitial system. The setting applies to the initial system, a boundary fluid, or globally toall fluids, depending on the current input scope (see the “scope” command). Examples:
fugacity O2(g) = .2f CO2(g) = 0.0003log f S2(g) = -30
See also the “activity”, “ratio”, “pH”, “Eh”, “pe”, “fix”, and “slide” commands.
8.42 go
go <boundary | initial | single | ask>
241
GWB Reference Manual
Run ! GoRun ! Go InitialRun ! Go Single
Results ! Run
Use the “go” command to initiate calculation of a model based on the currentconfiguration. Used with the “boundary” argument, the command causes the programto calculate only the composition of the boundary fluids. With the “initial” argument,the program calculates the initial state of the medium as well as the composition ofthe boundary fluids, but does not trace a reaction model. Typing the command withthe argument “single” causes the simulation to run on a single processor, regardlessof the setting for the “threads” command.
Upon completing a simulation, the program normally presents a dialog box askingif you would like to continue the simulation over an extended time span. This optionappears if you have triggered the calculation by entering “go” from the keyboard,selecting “Go” from the menubar, or moving to the Results pane and clicking the Run
button, but not if you are reading commands from a file or running a control script.Typing
go ask
causes the program to offer the option to continue the simulation in all cases.
8.43 grep
grep <string>
File ! View ! .\X2t_output.txt ! Edit ! Find
Use the “grep” command to search for each occurrence of the given character stringin the current output dataset. For example, use
grep Albite
to obtain a list of each line in “X2t_output.txt” (or the current output dataset, as modifiedby the “suffix” command) containing the string “Albite”.
8.44 hmw
h-m-w
File ! Open ! Thermo Data. . . ! thermo_hmw.tdat
242
X2t Commands
Use the “hmw” command (abbrev.: “hmw”) to set the program to calculate species’activitycoefficientsbyusingtheHarvieMøllerWeareequations.Executingthiscommandautomatically sets the input dataset of thermodynamic data to “thermo_hmw.tdat”.Note that dataset “thermo_hmw.tdat” supports calculations at 25°C only.
8.45 head_drop
head_drop = <value | ?> <unit>head_drop <interval> = <value | ?> <unit>
head_drop fluid = <boundary fluid>head_drop <interval> fluid = <boundary fluid>head_drop <left | right> fluid = <boundary fluid>head_drop <left | right> <interval> fluid = <boundary fluid>head_drop <bottom | top> fluid = <boundary fluid>head_drop <bottom | top> <interval> fluid = <boundary fluid>
Flow ! flow field: calculated !
interval 1: head drop cm
Use the “head_drop” (also: “pot_drop”) command to set a value for the decrease inhydraulic head (in length units) or hydraulic potential (in units of pressure) acrossthe medium. This decrease provides the driving force for fluid flow. The programsets hydraulic head or potential along the left boundary to the value specified in thecommand, and sets head or potential along the right boundary to zero.
At each step in the simulation, the program uses the head or potential values atthe boundaries along with the permeability, fluid viscosity, and the rates of productionor injection at any wells to calculate the flow field. Setting a positive head or potentialdrop drives flow from left to right, and a negative value drives flow in the oppositedirection.
You set the head drop for a specific interval by including the interval name, or forall intervals by omitting it.
The “head_drop” command also lets you specify the boundary fluids to set tothe left and right sides of the domain, in the same fashion as you would use the“discharge” command. In a simulation employing an imported flow field, and only sucha simulation, you may set the fluids to appear at the bottom and top of the domain.
The program recognizes hydraulic head in units of length, as listed in theUnits Recognized appendix, and hydraulic potential in units of pressure. By default,values are taken in atm.
Examples:
243
GWB Reference Manual
head_drop = 150 cmpot_drop = 0.1 atmhead_drop start = 4 m phase2 = 2 m
By default, the head drop is set to zero. To return to the default value, enter thecommand
head_drop = ?
8.46 heat_source
heat_source = <field_variable | ?> <unit> <steady | transient> \<temp_min = <value | ?> <C>> <temp_max = <value | ?> <C>>
Medium ! internal heat source
temperature: minimum C maximum C
cal/cm3/s
Use the “heat_source” command (also: “heat_src”) to set the rate of internal heatproduction within the medium. You can specify one of the units listed in theUnits Recognized appendix; “cal/cm3/s” is the default. The “transient” keyword causesthe model to evaluate the field variable continuously over the course of the simulation,if it is set with an equation, script, or function. By default, the program does not accountfor internal heat production. The “?” argument resets the default value of zero.
The “temp_min” and “temp_max” keywords (also: “tempmax”, “tempmin”) set theallowable temperature range for the simulation. These values serve two purposes.
First, the simulation will give an error message and stop if temperature at anypoint in the domain falls more than 5°C less than the minimum value, or exceeds themaximum value by more than this amount.
Second, unless the “extrap” option is set, the model will load for the simulation onlythose species for which log K values are available in the thermodynamic dataset overthe allowable temperature range. Values for the keywords default to the temperaturespan of the thermodynamic database, as set in the database header.
8.47 height
height = <value> <unit>
Domain ! height (z) cm
244
X2t Commands
Use the “height” command to set the height along z of the medium. You can use anyunit of distance listed in the Units Recognized appendix; “cm” is the default.
By default, the domain is 1 cm in height. See also the “length” and “width” commands.
8.48 help
help <help | subject>
Help
Use the “help” command (also: “man”) to display online documentation for the GWBpackage. The command “help help” shows a list of the types of documentation available.
8.49 history
history
Run ! History. . .
Use the “history” command to view a list of previously executed commands. Youcan reexecute commands in the History. . . dialog box by doubleclicking on acommand, selecting one or more commands, and then choosing Execute, or with ahistory substitution command, as explained in the User Interface appendix to thisguide.
8.50 inert
inert = <field_variable | ?> <units>
Medium ! inert volume cm3
Use the “inert” command to set the volume of nonreacting space in the system. Youmay set a value in units of volume, including cm3, m3, and l, as well as volume%and “vol. fract.”. The default setting is zero and the default unit is cm3.
Assuming you have not set a value for the initial fluid fraction in the system using the“porosity” command, the program figures the porosity over the course of the calculationas a derived variable. Specifically, it divides the fluid volume by the sum of the fluidvolume, mineral volume, and inert volume, and reports this value as a result.
When you have set a value for initial porosity with the “porosity” command, on theother hand, the program works in the contrary sense. In this case, it calculates theinert volume as that required to form a system of the specified initial porosity; theprogram now ignores any entry you may have set using the “inert” command.
To restore the default state, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show”.
245
GWB Reference Manual
8.51 interval
interval <interval> start = <value> <unit>interval <interval> fluid = <boundary fluid>interval <interval> <left | right | bottom | top> = <boundary fluid>interval <interval> rename <new name>
Intervals !
at day left right
The “interval” command sets the properties of a named simulation interval, creatingit if necessary. The first interval is named “start”, and the terminating point for the runis labeled “end”, but you can create any number of intervening intervals.
For each interval, you set the starting time with keyword “start”, and the boundaryfluid to use during the simulation interval with keyword “fluid”. The default time is zerodays, and you create fluids with the “scope” command. In the absence of a keyword,the command expects the starting time.
You can use keyword combinations “left fluid” and “right fluid” to set separate fluidson the left and right sides of the domain. In a simulation employing an imported flowfield, and only such a simulation, you can also set the fluids to appear at the bottomand top of the domain.
You can also rename the interval, using keyword “rename”. You cannot, however,rename “start” or “end”.
For example, the commands
interval start fluid = fluid1interval phase2 start = 1 year, fluid = fluid2interval phase3 start = 4 years, left fluid = fluid3A, right fluid = fluid3Binterval end 10 years
configure a simulation spanning 10 years and consisting of three reaction intervals,each with a different boundary fluid, or fluids.
8.52 itmax
itmax = <value | ?>
Config ! Iteration. . .
Use the “itmax” command to set the maximum number of iterations that may be takenin an attempt to converge to a solution for the equations representing the distributionof chemical mass.
By default, this variable is set to 999. To restore the default value, type the commandwith no argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
246
X2t Commands
8.53 Kd
Kd <off>
Config ! Iteration. . .
The “Kd” command controls whether the program calculates Kd distribution coefficientsfor sorbing components, in units of liters per kg sediment mass. This calculationrequires that the mineral mass in the system (as specified for individual mineralsand/or in terms of inert volume) be set correctly.
8.54 kinetic
kinetic <species | mineral | gas> <variable> = <value>kinetic <species | mineral | gas> <variable> = <field_variable> \
<steady | transient>kinetic <species | mineral | gas> <apower | mpower(species)> = <value>kinetic <species> <boundary fluid> = <value> <unit>kinetic <redox(label)> <variable> = <value>kinetic <redox(label)> <variable> = <field_variable> <steady | transient>kinetic <redox(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <variable> = <value>kinetic <microbe(label)> <variable> = <field_variable> <steady | transient>kinetic <microbe(label)> <apower | mpower(species)> = <value>kinetic <microbe(label)> <apower | mpower(species)> = <value> \
<apowerA | mpowerA(species)> = <value> \<apowerD | mpowerD(species)> = <value>
Reactants ! add !
Use the “kinetic” command to set variables defining a kinetic rate law for (1) dissolutionor precipitation of any mineral in the initial system or reactant list, (2) the associationor dissociation of any aqueous or surface complex in the system modeled, (3) thetransfer of gases into or out of an external reservoir, (4) a redox reaction, includingthose promoted by catalysis or enzymes, or (5) a microbial metabolism.
In the first three cases, you identify the kinetic reaction by the name of the species,mineral, or gas involved. In the case of a redox reaction, you set a label that begins
247
GWB Reference Manual
with the characters “redox”, such as “redox1” or “redoxFe”. For a microbial reaction,set a label that starts with “microbe”, such as “microbeEcoli”.
The rate law you specify in a “kinetic” command, by default, applies to the dissolutionof a mineral, dissociation of a complex, dissolution of a gas, or forward progress of aredox or microbial reaction. The synonymous keywords “forward”, “dissolution”, and“dissociation” set this behavior. Including in a “kinetic” command the keyword “reverse”or its synonyms “precipitation”, “complexation”, “association”, or “exsolution” invokesthe opposite behavior. In this case, the rate law applies to the reverse reaction: mineralprecipitation, complex association, or gas exsolution.
You can append the “transient” keyword when setting the following field variables:rate constant, specific surface area, activation energy, preexponential factor, nucleusarea, and critical saturation index. If the variable is defined by an equation, script, orexternal function, it will then be reevaluated continuously over the course of the run.
See also the “react” and “remove reactant” commands.
The following paragraphs apply to all types of kinetic reactions. You set the rate constant either directly using the “rate_con” keyword, or by setting an activation energyand preexponential factor with keywords “act_en” and “preexp”. In the absence ofpromoting and inhibiting species (see next paragraph), you set the rate constant andpreexponential factor in (1) mol/cm2 sec for mineral and gas transfer reactions, (2)molal/sec or molal/cm2 sec (the latter when accounting for heterogeneous catalysis)for complexation and redox reactions, and (3) mol/mg sec for microbial reactions. Theactivation energy is specified in J/mol. Example:
kinetic "Albite low" rate_con = 1e-15
You can set “rate_con”, “act_en”, and “preexp” as field variables (see the Heterogeneity
appendix to the GWB Reactive Transport Modeling Guide).You use the “apower” or “mpower” (also “apow” or “mpow”) keyword to specify
any promoting or inhibiting species in the kinetic rate law. Keyword “apower” setsthe exponent of a species activity, and “mpower” the exponent of a species molality.Promoting species have positive powers, and the powers of inhibiting species arenegative. For example, the command
kinetic "Albite low" apower(H+) = 1
sets HC as a promoting species, the activity of which is raised to a power of one. Youcan use aqueous species, gas species (represented by fugacity), surface complexes(molal concentration), and solvent water (activity) as promoting and inhibiting species.
The “order1” and “order2” keywords set nonlinear rate laws. Keyword “order1”represents the power of the Q=K term, and “order2” represents the power of the (1 Q=K/ term.
Use the “rate_law” keyword to set the form of the kinetic rate law for a specificmineral, redox reaction, or microbial metabolism. You may set the keyword equal to (1)a character string containing the rate law, (2) the name of a file containing a basiclike
248
X2t Commands
script, or (3) the name of a function in a library. The name of a file containing a ratelaw script must end in “.bas”. To specify a function from a library, set the name of adynamic link library (DLL) separated from the function name by a colon (“:”), such as“rate_laws.dll:my_ratelaw”; the library file must end in “.dll”. To return to the program’sbuiltin rate law, enter “rate_law = off” or “rate_law = ?”.
The following paragraphs apply to dissolution and precipitation reactions. You set the
specific surface area of a kinetic mineral (in cm2/g) with the “surface” keyword. Forexample,
kinetic "Albite low" surface = 1000
The “crossaffinity” option lets you use the saturation state of one mineral to modelthe reaction rate of another, as is sometimes useful for example in studying glassdissolution. To do so, you use the “xaffin” option. For (a hypothetical) example, thecommand
kinetic Quartz xaffin = Cristobalite
causes the program to calculate the reaction rate of quartz according to the fluid’ssaturation state with respect to cristobalite. The command
kinetic Quartz xaffin = OFF
turns off the option.Finally, you use the “nucleus” and “critSI” keywords to set the area available for
nucleation (in cm2/cm3 fluid volume) and the critical saturation index above which themineral can nucleate. Each of these values, by default, is zero.
Keywords “surface”, “nucleus”, and “critSI” can be set as field variables (see theHeterogeneity appendix to the GWB Reactive Transport Modeling Guide).
The following paragraphs apply to reactions for aqueous and surface complexes.When you specify a kinetic reaction for the association of an aqueous complex orsurface complex, or its dissociation, you can set the complex’s initial concentrationdirectly. The concentration can be set heterogeneously, as a field variable. If you donot specify an initial concentration, or set an entry of “?”, the program takes thecomplex at the start of the simulation to be in equilibrium with the initial fluid.
You specify the initial concentration within a “kinetic” command or as a separatecommand line. For example, the commands
kinetic AlF++ rate_con = 3.3e-6, mpow(AlF++) = 1AlF++ = 1 umol/kg
are equivalent to
249
GWB Reference Manual
kinetic AlF++ 1 umol/kg rate_con = 3.3e-6, mpow(AlF++) = 1
Either case defines a kinetic reaction for decomposition of the AlFCC ion pair, settingit initially to a free concentration of 1 �mol kg�1.
In X1t and X2t, you can similarly set the species’ concentration within the boundaryfluids directly
kinetic AlF++scope fluid-1
AlF++ = 4 umol/kgscope fluid-2
AlF++ = 8 umol/kg
or on a “kinetic” command
kinetic AlF++ fluid-1 = 4 umol/kg, fluid-2 = 8 umol/kg
If you do not set a value for a boundary fluid, or set it to “?”, the program takes thespecies to be in equilibrium with the fluid.
The following paragraphs apply to gas transfer reactions. Use the “f_ext” keyword tospecify the fugacity of the gas in question in the external reservoir, and keyword“contact” to set, in cm2/kg of water, the contact area between fluid and externalreservoir. Example:
kinetic CO2(g) f_ext = 10^-3.5, contact = 10
Both values can be set as field variables, as described in the Heterogeneity appendixto the GWB Reactive Transport Modeling Guide.
If you do not set a value for the gas’ external fugacity, or set “f_ext = ?”, the programuses the fugacity in the initial fluid, at the start of the simulation, and the externalfugacity.
The following paragraphs apply to redox reactions. You set the form of the redoxreaction to be considered as a character string, using the “rxn” (or “reaction”) keyword.For example,
kinetic redox-1 rxn = "Fe++ + 1/4 O2(aq) + H+ -> Fe+++ + 1/2 H2O"
To specify that the reaction be promoted by a heterogeneous catalyst, set keyword“catalyst” to the name of the catalyzing mineral, or simply to “on”. In the former case,you use keyword “surface” to set the specific surface area of the catalytic mineral (incm2/g). If you have set “catalyst = on”, however, you use the “surface” keyword to settotal catalytic area, in cm2. Setting “catalyst = off” disables the catalysis feature.
250
X2t Commands
To set an enzymatically promoted reaction, set keyword “me” to the name of theaqueous species serving as the enzyme, or simply to the value to be used as theenzyme’s molality. In the former case, the program tracks the enzyme molality mE
over the course of the simulation from the calculated distribution of species. If youhave set a numeric value for mE using the “mE” keyword, the program uses this valuedirectly. You may alternatively specify the enzyme species or its activity aE usingkeyword “aE”, in which case variables mE , mA, and mP in the rate law are replacedby the activities aE , aA, and aP .
For an enzymatic reaction, you further set the halfsaturation constants KA and KP
for the forward and reverse reactions in molal with the “KA” and “KP” keywords. Youmust set a value for KA, but may omit KP , in which case the mP /KP term in the ratelaw will be ignored. Setting “enzyme = off” disables the enzyme feature.
The following paragraphs apply to microbial reactions.Yousettheformofthemetabolicreaction using the “rxn” (or “reaction”) keyword, in the same manner as with redoxreactions. For example,
kinetic microbe-1 rxn = "CH4(aq) + 2 O2(aq) -> HCO3- + H+ + H2O"
Set the halfsaturation constants KD and KA for the electron donating and acceptingreactions with the “KD” and “KA” keywords. These values default to zero.
You set the powers of species in the numerator of the rate law with the “mpower”keyword, as with other types of kinetic reactions. Use keywords “mpowerD” and“mpowerA” (or “mpowD” and “mpowA”) to set the powers PD, etc., of species from theelectron accepting and donating reactions, respectively, within the product functionsin the rate law’s denominator. For example,
kinetic microbe-1 mpower(CH4(aq)) = 1, mpowerD(CH4(aq)) = 1
sets the power of the electrondonating species CH4(aq) to one in both the rate lawnumerator and denominator. Keywords “PKD” and “PKA” set the overall powers PKD
and PKA of the electron donating and accepting terms in the denominator of the ratelaw; by default, these are one.
You set the free energy �GATP of ATP hydrolysis (in kJ/mol) with the “ATP_energy”keyword, and the value of nATP with keyword “ATP_number”. These values default tozero.
Use the “biomass” keyword to set the initial biomass concentration, in mg/kg. Youcan set this value as a field variable (see the Heterogeneity appendix to the GWB
Reactive Transport Modeling Guide).The “growth_yield” keyword sets the microbe’s growth yield in mg biomass/mol of
reaction progress, and “decay_con” sets its decay constant in sec�1; both valuesdefault to zero.
251
GWB Reference Manual
8.55 left
left fluid = <boundary fluid>left <interval> fluid = <boundary fluid>left = <open | closed>left = <interval> <open | closed>left = <normal | inlet | outlet>
Flow ! flow field: calculated !
interval 1:
left boundary
open
closed
discharge cm/s
Flow ! boundaries: left
Use the “left” command to control the boundary condition at the left side of the domain:the fluid to appear at the boundary, whether the boundary is open or closed, andwhether solutes can diffuse and disperse, and heat conduct, across the boundary.
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the leftboundary, for the entire simulation or an individual interval. For example, the commands
left fluid = ambient_waterleft phase2 fluid = pit_water
set fluid “ambient_water” on the left boundary over the course of the simulation, exceptduring interval “phase2”, in which case fluid “pit_water” is found on the boundary.
Keywords “open” and “closed” set the left boundary of the domain open or closedto flow. By default, the boundary is open. The commands
left = openleft = closed
are equivalent to the commands
discharge left = ?discharge left = 0
252
X2t Commands
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
You can force the program to treat the left side of the domain as an inlet or freeoutlet boundary, regardless of the direction of fluid migration. Keyword “inlet” causesthe program to allow diffusion, hydrodynamic dispersion and heat conduction acrossthe left bound, whereas keyword “outlet” creates an insulated boundary sealed againsttransport by these processes:
left outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
See also the “right”, “discharge”, “head drop”, and “interval” commands.
8.56 length
length = <value> <unit>
Domain ! length (x) cm
Use the “length” command to set the length along x of the medium. You can useany unit of distance listed in the Units Recognized appendix; “cm” is the default. Bydefault, the domain is 100 cm long. See also the “width” and “height” commands.
8.57 log
log <variable> = <value>
Use the “log” command to set variables on a logarithmic scale. Examples:
log fugacity O2(g) = -65log activity U++++ = -10
8.58 mobility
mobility = <surface_type> = <field_variable> <steady | transient>mobility = <surface_type> = <value>mobility = <surface_type> <initial = <field_variable> <steady | transient>> \
<boundary_fluid> = <value>
253
GWB Reference Manual
File ! Open ! Sorbing Surfaces. . . ! mobility
fluids ! fluid
Use the “mobility” command to set up a complexing surface in your model as amobile colloid. A mobile colloid is composed of the mineral (or minerals) associatedwith a complexing surface, as well as the ion complexes present on that surface.Only datasets with model type “twolayer” as set in the dataset header are surfacecomplexation models, and hence only those datasets can be used to form a mobilecolloid.
Mobility refers to the fraction of the surface in question that can move in the modelby advection and dispersion. A surface with a mobility of one moves freely, whereasa mobility of zero sets the surface to be stationary. Intermediate values arise, forexample, when some of the surface is attached to the medium, or when colloid motionis impeded by electrostatic interactions. By default in the software the mobility of anysurface is zero.
To set a mobile colloid, begin by reading in a surface complexation dataset using the“surface_data” command. Then, use the “mobility” command, referencing the surface’slabel, to set the colloid’s mobility. The label is given at the head of the surface dataset,on a line beginning “Surface type”. The label in dataset “FeOH.sdat”, for example, is“HFO”. If you omit the label, the program will assume you are referring to the surfacecomplexation dataset most recently read.
You can define the mobility of the domain (i.e., “initial” scope) as a field variable,which means you can have the program calculate mobility using an equation, script,or compiled function you provide. When you set the “transient” keyword, the programupon undertaking each time step in the simulation evaluates mobility at each nodalblock. In the “steady” case, which is the default, the program evaluates mobility ateach block just once, at the start of the run.
You can further define colloid mobility in a boundary fluid. If you do not set a value,mobility in an inlet stream is taken as the initial value assigned the first interior nodein the simulation.
In its simplest form, the command sets mobility for the current scope, either theinitial system or a boundary fluid. You can, however, set mobility for one or morescopes with a single command, by citing each scope’s name.
For example, since “HFO” is the label for the surface defined by dataset “FeOH.sdat”,the commands
surface_data FeOH.sdatscope initial
mobility HFO = 100%scope inlet_fluid1
mobility HFO = 0%
are equivalent to
254
X2t Commands
surface_data FeOH.sdatmobility HFO initial = 100%, inlet_fluid1 = 0%
Restore the default behavior of immobility by entering a command such as
mobility HFO ?
8.59 modflow
modflow <discretization dataset> <short> <long>
Flow ! flow field: imported from modflow !
all intervals: set modflow file
Use the “modflow” command to import a groundwater flow field from the results ofa MODFLOW simulation. You specify the name of the discretization file, such as“MyRun.dis”. X2t will read data from this file as well as a budget file with the sameroot name (“MyRun.bud”). In the example
modflow "My Flow Field.dis"
X2t will expect to find the MODFLOW data in files “My Flow Field.dis” and“My Flow Field.bud”.
The dataset name should be enclosed in quotes if it contains spaces or unusualcharacters. Alternatively, you may specify only the root of the file name. For example,if you type
modflow MyModflow
X2t will open files “MyModflow.dis” and “MyModflow.bud”.The “short” and “long” options control the level of detail in the MODFLOW
log file “mf_log.txt”, which X2t creates in the user’s profile directory (found bytyping %appdada% in the Windows Explorer Address bar, e.g., “C:\Documents andSettings\userName\Application Data\GWB). For details, refer to the Importing from
MODFLOW appendix to the GWB Reactive Transport Modeling Guide. By default,X2t assumes the “short” option.
255
GWB Reference Manual
8.60 noprecip
no-precip <off>
Config ! Iteration. . .
Usethe“noprecip”command(also:“noprecip”) topreventnewmineralsfromprecipitatingover the course of a simulation. By default, they are allowed to precipitate. Use:
no-precipno-precip off
See also the “precip” command.
8.61 nswap
nswap = <value | ?>
Config ! Iteration. . .
Use the “nswap” command to set the maximum number of times that the program mayswap entries in the basis in an attempt to converge to a stable mineral assemblage. Bydefault, this variable is set to 30. To restore the default value, type the command withno argument or with an argument of “?”. To see the current setting of this variable,type “show variables”.
8.62 Nx
Nx = <value | ?>
Domain ! nodes (Nx)
Use the “Nx” command to set in the simulation the number of nodal blocks along thex direction. By default, the program divides the medium into ten blocks along x.
8.63 Ny
Ny = <value | ?>
Domain ! nodes (Ny)
Use the “Ny” command to set in the simulation the number of nodal blocks along they direction. By default, the program divides the medium into ten blocks along y.
256
X2t Commands
8.64 offdiag
off-diag <off>
Medium ! mass transport include off-diagonal terms in dispersion tensor
Use the “offdiag” command to enable or disable the inclusion of the “offdiagonal”dispersion coefficients (i.e., Dxy and Dyx/ when calculating the effects of masstransport. By default, these terms are not included. The terms come into play whenmodeling hydrodynamic dispersion where groundwater flow is not aligned with the x
or y coordinate axis.
8.65 pause
pause
Use the “pause” command to cause X2t to pause temporarily during input. Thiscommand is useful when you are debugging scripts.
8.66 pe
pe = <field_variable>
Initial or Fluids ! pe
Use the “pe” command to set oxidation state in the initial system in terms of pe. Thesetting applies to the initial system, a boundary fluid, or globally to all fluids, dependingon the current input scope (see the “scope” command). Example:
pe = 10
is equivalent to
log activity e- = -10
where “e” is the electron. See also the “activity”, “Eh”, “pH”, “fugacity”, “fix”, and “slide”commands.
8.67 permeability
permeability <intercept = field_variable | ?> <unit> <steady | transient> \<porosity = field_variable | ?> <steady | transient> \
257
GWB Reference Manual
<kxky = field_variable | ?> <steady | transient> \<mineral = field_variable | ?> <steady | transient>
Medium ! A (porosity)
B (intercept) darcy
kx/ky (anisotropy)
add
You use the “permeability” command to set the correlation by which the programcalculates sediment permeability. The correlation gives log permeability in any of theunits listed in the Units Recognized appendix (darcys by default) as a linear functionof the porosity (expressed as a volume fraction) of a nodal block and, optionally, thevolume fractions of one or more minerals. The “transient” keyword causes the modelto evaluate the coefficient in question continuously over the course of the simulation,if it is set with an equation, script, or function.
Examples:
permeability intercept = -11 cm2 porosity = 15permeability Kaolinite = -8
The latter command adds a term for the mineral Kaolinite to the existing correlation.To remove a term from the correlation, set a value of “?”. The entry
permeability Kaolinite = ?
for example, removes the correlation entry for that mineral.The default correlation is
logk D �5C15�
where k is permeability in darcys and � is porosity (expressed as a fraction).
8.68 pH
pH = <field_variable>
Initial or Fluids ! pH
Use the “pH” command to set pH in the initial system. The setting applies to the initialsystem, a boundary fluid, or globally to all fluids, depending on the current input scope(see the “scope” command). Example:
258
X2t Commands
pH = 5
is equivalent to
log activity H+ = -5
See also the “activity”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
8.69 phrqpitz
phrqpitz
File ! Open ! Thermo Data. . . ! thermo_phrqpitz.tdat
Use the “phrqpitz” command to set the program to calculate species’ activitycoefficients using the HarvieMøllerWeare equations, as implemented in the USGSprogram PHRQPITZ. Executing this command automatically sets the input dataset ofthermodynamic data to “thermo_phrqpitz.tdat”. Note that dataset “thermo_phrqpitz.tdat”is primarily intended to support calculations at or near 25°C.
8.70 pitz_dgamma
pitz_dgamma = <value | ?>
Config ! Iteration. . .
Use the “pitz_dgamma” command to control the relative change in an activity coefficient’svalue the program allows during each NewtonRaphson iteration, when a virial activitymodel (“the Pitzer equations”) has been invoked. By default, the program allows a10% change, which corresponds to a value of 0.1.
8.71 pitz_precon
pitz_precon = <value | ?>
Config ! Iteration. . .
Use the “pitz_precon” command to control the maximum number of passes the programtakes through the preconditioning loop before beginning a NewtonRaphson iteration,when a virial activity model (“the Pitzer equations”) has been invoked. By default, theprogram makes up to 10 passes. In cases of difficult convergence, counterintuitively,it can sometimes be beneficial to decrease this value.
259
GWB Reference Manual
8.72 pitz_relax
pitz_relax = <value | ?>
Config ! Iteration. . .
The “pitz_relax” command controls underrelaxation when evaluating a virial activitymodel (“the Pitzer equations”). The program at each NewtonRaphson iteration assignsactivity coefficients as a weighted average of the newly calculated value and thecorresponding value at the previous iteration level. Setting pitz_relax to zero eliminatesunderrelaxation, so the newly calculated values are used directly; a value of one, incontrast, should be avoided because it would prevent the activity coefficients frombeing updated. By default, the program carries an underrelaxation factor of 0.5.
8.73 pitzer
pitzer
File ! Open ! Thermo Data. . . ! thermo_pitzer.tdat
Use the “pitzer” command to set the program to calculate species’ activity coefficientsusing the Pitzer equations. Executing this command automatically sets the input datasetof thermodynamic data to “thermo_pitzer.tdat”. Note that dataset “thermo_pitzer.tdat”is intended to support calculations at or near 25°C.
8.74 plot
plot <character | bit | on | off>
Config ! Output. . .
Use the “plot” command to set the format of the “X2t_plot.xtp” dataset. The datasetcan be written in ascii characters, which are humanreadable and can be transferredsafely among computer systems, or as a bitstream, which is faster to read and write,more compact, and more accurate. The command “plot off” causes X2t to bypasswriting calculation results to the “X2t_plot.xtp” dataset, which is used to pass input toXtplot. By default, the program writes output to the dataset. The command “plot on”(or just “plot”) reenables the output. To see the current setting, type “show print”.
260
X2t Commands
8.75 pluses
pluses <off | on | multicore | banner>
Config ! Stepping. . .
The “pluses” command controls whether the program writes a plus sign (“+”) to thescreen each time it converges to a solution of the chemical equations at a nodal block(keyword “on”); by default, it does not (keyword “off”). You can also set the programto write a distinct symbol for each thread active in tracing the simulation (keyword“multicore”), allowing you to observe the model as it runs in parallel. You can alsospecify the program write a banner giving details such as the number of iterationsrequired for convergence and the final residuals (keyword “banner”). The latter optionproduces unwieldy amounts of output, except for simple simulations.
8.76 polymorphs
polymorphs <mineral>
Config ! Show. . . ! Minerals ! select mineral
Use the “polymorphs” command to list each polymorph (mineral identical incomposition to the specified mineral) in the current database. Example:
polymorphs Albite
8.77 porosity
porosity = <field_variable | ?>
Medium ! porosity
Use the “porosity” command to set (as a volume fraction) the initial porosity of themedium. Porosity, the fraction of a nodal block occupied by fluid, is the ratio of fluidvolume to the sum of fluid, mineral, and inert volume.
The examples
porosity = 0.30porosity = 30%
are equivalent.
261
GWB Reference Manual
When you specify the porosity, the program will at each nodal block figure thedifference between the volume taken up initially by minerals and fluid, and the block’sbulk volume. The program assigns this difference as inert, nonreactive volume (seethe “inert” command). In this case, the program ignores any settings that may havebeen made with the “inert” command.
When you do not specify an initial porosity with the “porosity” command, on the otherhand, the program calculates it from volumes in the nodal block of fluid, minerals, andinert space. To restore this default behavior, enter the command with an argument of“?”.
8.78 precip
precip <off>
Config ! Iteration. . .
Use the “precip off” command to prevent new minerals from precipitating over thecourse of a simulation. By default, they are allowed to precipitate. Use
precipprecip off
See also the “noprecip” command.
8.79 print
print <option> = <long | short | none>print <off | on>print <numeric | alphabetic>
Config ! Output. . .
Use the “print” command (also: “printout”) to control the amount of detail to be writteninto the “X1t_output.txt” dataset. For example, the dataset can contain informationabout each aqueous species, information on only species with concentrations greaterthan 10�8 molal, or no species information.
By default, the program does not produce these datasets, which can become quitelengthy. The command “print on” (or just “print”) causes them to be written, and “printoff” disables them.
Options, which may be abbreviated to three letters, and their default settings are:
species shortsurfaces longsaturations short
262
X2t Commands
gases longbasis noneorig_basis longelements longreactions nonestagnant none
The “stagnant” option includes in the printout the diffusive profile within the stagnantzone, when the dual porosity feature is in use.
The “print” command can also be used to arrange entries in the output dataseteither numerically or alphabetically:
print numericprint alphabetic
To see the current print settings, type “show print”.
8.80 pwd
pwd
File ! Working Directory. . .
The “pwd” command returns the name of the current working directory. The commandhas the same effect as typing “show directory”. See the “chdir” command.
8.81 quit
quit
File ! Quit
Use the “quit” command (also: “end”, “q”) to exit the program. Touching Ctrl+Q servesthe same purpose as the “quit” command.
8.82 radial
radial <r1 = value> <unit> <r2 = value> <unit><angle = value> <unit> <normal|reverse>
radial <off|on>
263
GWB Reference Manual
Domain !
Linear
SphericalRadial
RadialAxisymmetric
Rectilinear
Reverse axisymmetricAxisymmetric
Use the “radial” command (also: “axisymmetric” or “wedge”) to set a 2D radial (i.e.,axisymmetric) flow system extending from radius “r1” to radius “r2”, where “r1” isless than “r2”. Radii may be entered in units of distance (see the Units Recognized
appendix); “cm” is the default. Keyword “angle” gives the angle of divergence of themedium, in “radians” (the default) or “degrees”. By default, this value is 0.1 radians. Toreturn to a linear geometry, type “radial off”. The “normal” keyword sets the domainto narrow from right to left; the “reverse” keyword sets it narrowing from left to right.
8.83 ratio
ratio <species ratio> = <value>
Initial or Fluids ! ratio
Use the “ratio” command to constrain an activity ratio in the initial system. The settingapplies to the initial system, a boundary fluid, or globally to all fluids, depending onthe current input scope (see the “scope” command). Example:
swap Ca++/Na+^2 for Ca++ratio Ca++/Na+^2 = 0.2
See also the “activity”, “pH”, “Eh”, “pe”, “fugacity”, “fix”, and “slide” commands.
8.84 react
react <amount (field_variable)> <unit> <as <element symbol>> \<species | mineral | gas> <cutoff> = <field_variable>
Reactants ! add !
Use the “react” command (abbrev.: “rct”) to define the reactants for the currentsimulation. (To set a kinetic rate law for a reactant, use the “kinetic” command.) Unitsfor the amount of reactant to add over a reaction path can be:
264
X2t Commands
mol mmol umol nmolkg g mg ug ngeq meq ueq neqcm3 m3 km3 lmol/kg mmol/kg umol/kg nmol/kgmolal mmolal umolal nmolalmol/l mmol/l umol/l nmol/lg/kg mg/kg ug/kg ng/kgwt% "wt fraction"g/l mg/l ug/l ng/leq/kg meq/kg ueq/kg neq/kgeq/l meq/l ueq/l neq/l
Units of mass or volume can be expressed per volume of the porous medium. Examples:
mol/cm3 g/cm3mmol/m3 ug/m3volume% "vol. fract"
Units of mass or volume can be set as absolute rates by appending “/s”, “/day”, “/yr”,or “/m.y.”. For example,
mmol/s g/day cm3/yrmol/kg/s mg/kg/day cm3/kg/yrmol/cm3/s kg/m3/yr m3/m3/yr volume%/m.y.
The latter units refer to rates per cm3 or m3 of porous medium, per unit time.Use the “as” keyword to specify reactant masses as elemental equivalents. For
example, the command
react 10 umol/kg CH3COO- as C
specifies 5 umol/kg of acetate ion, since each acetate contains two carbons, whereas
react 20 mg/kg SO4-- as S
would cause the program to add 59.9 mg/kg of sulfate, since the ion’s mole weight isabout 3 times that of sulfur itself.
You can set a cutoff to limit the amount of a reactant. For example, if you set theamount of a reactant to two moles and set a cutoff of one, then X1t will add one moleof the reactant over the first half of the path and none over the second half. Enter thecutoff value in the same units as the amount of reactant. Examples:
265
GWB Reference Manual
react 10 grams Quartzreact 1e-2 mol Muscovite cutoff = .5e-2react .01 mol/day HCl
See also the “kinetic” and “remove reactant” commands.
8.85 read
read <dataset>
File ! Open ! Read Script. . .
Use the “read” command to begin reading commands from a script stored in a dataset.Example:
read Seawater
Control returns to the user after the script has been read unless the script containsa “quit”command. You can also use the “read” command in place of the “data” or“surface_data” command to read a thermo or surface reaction dataset.
When typing a “read” command, you can use the spelling completion featureto complete dataset names: touch “[tab]” or “[esc]” to cycle through the possiblecompletions, or Ctrl+D to list possible completions.
8.86 remove
remove <basis specie(s)> <reactant(s)> <interval(s)> <boundary fluid(s)> \<well(s)> <well interval(s)>
remove basis <basis specie(s)>remove reactant <reactant(s)>remove interval <interval(s)>remove scope <boundary fluid(s)>remove well <well(s)>remove well <well> interval <interval(s)>remove wells
Initial or Fluids or Reactants !
select entry(ies) ! delete
Use the “remove” command (also: “rm”) to eliminate one or more basis entries orreactants from consideration in the calculation. Example:
266
X2t Commands
remove Na+remove Quartz Calciteremove reactant H2O
Components can be reentered into the basis using the “swap”, “add”, “activity”, and“fugacity” commands. You can also use the “remove” command to remove boundaryfluids and simulation intervals
remove scope inlet_fluid1remove interval phase2
from the run configuration. Finally, you can remove wells, or well intervals:
remove well injectionremove well extraction-8 interval pumping-2
The command
remove wells
removes all the wells that have been defined.
8.87 report
report <option>report set_digits <value>report set_node <x-index> <y-index>
Once the program has completed a calculation, you can use the “report” commandto return aspects of the calculation results. You can use this command from theCommand pane to query the program interactively. More significantly, the “report”command provides a means of communicating calculation results to control scriptsand external programs running GWB programs by remote control.
For arguments available, see the Report Command appendix to this GWB Reference
Manual. For details about control scripts and the plugin feature, see theControl Scripts and Plugin Feature appendices. Use the “set_digits” argument to setthe number of significant digits in the values reported, and the “set_node” argumentto identify the node of interest.
8.88 reset
resetreset systemreset reactants
267
GWB Reference Manual
reset variables
File ! Reset Configuration
Use the “reset” command to begin defining the chemical system again with a cleanslate. Your current settings will be lost, all options will be returned to their defaultstates. The command, however, does not alter the setting for the thermo dataset.The “reset system” command resets only the initial system. Similarly, typing “resetreactants” resets the reactant system, and “reset variables” sets each settable variableto its default value.
8.89 resume
resume
File ! Resume
Use the “resume” command to restore the configuration from when you last exitedthe program. The program configuration is stored in a file “x2t_resume.x2t” in yourprofile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”).Your current configuration is discarded.
8.90 right
right fluid = <boundary fluid>right <interval> fluid = <boundary fluid>right = <open | closed>right = <interval> <open | closed>right = <normal | inlet | outlet>
Flow ! flow field: calculated !
interval 1:
right boundary
open
closed
discharge cm/s
Flow ! boundaries: right
Use the “right” command to control the boundary condition at the right side of thedomain: the fluid to appear at the boundary, whether the boundary is open or closed,and whether solutes can diffuse and disperse, and heat conduct, across the boundary.
268
X2t Commands
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the rightboundary, for the entire simulation or an individual interval. For example, the commands
right fluid = ambient_waterright phase2 fluid = pit_water
set fluid “ambient_water” on the right boundary over the course of the simulation, exceptduring interval “phase2”, in which case fluid “pit_water” is found on the boundary.
Keywords “open” and “closed” set the right boundary of the domain open or closedto flow. By default, the boundary is open. The commands
right = openright = closed
are equivalent to the commands
discharge right = ?discharge right = 0
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
You can force the program to treat the right side of the domain as an inlet or freeoutlet boundary, regardless of the direction of fluid migration. Keyword “inlet” causes theprogram to allow diffusion, hydrodynamic dispersion and heat conduction across theright bound, whereas keyword “outlet” creates an insulated boundary sealed againsttransport by these processes:
right outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
See also the “left”, “discharge”, “head drop”, and “interval” commands.
8.91 save
save <dataset>
File ! Save As. . .
269
GWB Reference Manual
Use the “save” command to write the current chemical system into a dataset in X2t
format commands. The dataset can be used as an X2t input script. Examples:
savesave kspar.x2t
If you don’t specify a dataset name, X2t will ask for one.
8.92 scope
scope <initial | boundary fluid>scope <initial | boundary fluid> = <initial | boundary fluid>scope <boundary fluid> rename <new name>
Initial or Fluids
Initial or Fluids ! copy
The “scope” command defines whether subsequent user commands apply to theinitial condition of the medium, to a boundary fluid, or globally, to all fluids that havebeen defined. The scope is initially set global. When you enter a scope commandwith “initial” as an argument
scope initial
the scope is set to the initial system. For any other argument
scope my_fluid
the scope is set to a boundary fluid of that name, creating it if necessary.Entering the command without an argument
scope
returns the scope global, as does entering any command of global meaning, such as“react” or “kinetic”. To see the current scope, type “show scope”.
The “scope” command can also be used to copy constraints on fluid compositionand temperature from one aspect of the calculation to another. For example, thecommand
scope my_fluid2 = my_fluid1
copies the basis constraints, temperature, TDS, and density from a boundary fluid“my_fluid1” to another “my_fluid2”.
270
X2t Commands
scope inlet = initial
sets the inlet fluid to be the same as the fluid in the initial system.You can rename a boundary fluid, but not the initial system, using the “rename”
keyword.
8.93 script
scriptscript end
Use the “script” command to mark the beginning, and optionally the end, of a controlscript. Control scripts differ from standard input files in that they can contain not onlyX2t commands, but control structures such as loops and ifelse branches. Controlscripts follow the Tcl syntax, described in www.tcl.tk and mini.net/tcl, as well as severalwidely available textbooks.
Withinacontrolscript,filenamesarewrittenwithdouble ratherthansinglebackslashes.For example, a “read” command might appear as
read GWB_files\\My_file.x2t
within a control script.
8.94 show
show <option>show <species | minerals | surfaces> <with | w/> <basis entry | string>
Config ! Show. . .
Use the “show” command to display specific information about the current system ordatabase. Examples:
show show gases show showshow altered show initial show speciesshow basis show kinetic show suppressedshow boundary show minerals show surfacesshow commands show oxides show systemshow couples show printout show variablesshow directory show reactants show wellsshow elements show scope
271
GWB Reference Manual
The command “show show” gives a list of show command options. When you type“show species”, “show minerals”, or “show surfaces”, the program lists all speciesor minerals in the thermo database. A long form of the “show species” and “showminerals” commands lets you set the basis species or match string directly:
show species with Al+++show minerals w/ chal
There is also a compound form of the “show couples” command:
show coupling reactions
This command produces a complete list of the redox couples, in reaction form.
8.95 simax
simax = <value | ?>
Config ! Iteration. . .
The “simax” command sets in molal units the maximum value of the stoichiometricionic strength used in calculating water activity when the DebyeHückel model isemployed. By default, this variable is set to 3 molal. To restore the default value, typethe command with no argument or with an argument of “?”. To see the current settingof this variable, type “show variables”.
8.96 slide
slide <unit> <species | gas> to <field_variable>
Reactants ! add !
Use the “slide” command to linearly adjust the activity of the specified species, fugacityof the gas, or an activity ratio toward <value>, which is attained at the end of the path.Note that the interpolation is made linearly on the logarithm of activity or fugacity if
272
X2t Commands
<value> is set as a log, and that <unit> can be “activity” or “fugacity” (“a” or “f” forshort), “ratio”, “pH”, “pe”, or “Eh”, or omitted. Examples:
slide pH to 5slide activity Cl- to 2/3slide f CO2(g) to 10^-3.5slide log f O2(g) to -65
8.97 sorbate
sorbate <exclude | include>
Config ! Iteration. . .
Use the “sorbate” command to tell the program, when considering sorption ontosurfaces (see the “surface_data” command), whether to include or exclude sorbedspecies in figuring the composition of the initial system. By default, the program doesnot include sorbed species in this calculation. If you set the CaCC concentration to 15mg/kg, for example, the initial system would contain that amount in the fluid and anadditional amount sorbed onto mineral surfaces. If you type the command “sorbateinclude”, however, that amount would apply to the sum of the CaCC sorbed and insolution.
8.98 start_date
start_date <value | off>
Config ! Stepping. . .
Use the “start_date” command to set an explicit starting date of the reaction. Thiscan be used to coordinate the plotting of dated scatter data samples stored in aGSS spreadsheet on the reaction path in Xtplot. The date should be in the format“MM/DD/YYYY”. Use “off” to return to the default of not set.
start_date 10/30/2008start_date off
8.99 start_time
start_time <value | off>
Config ! Stepping. . .
273
GWB Reference Manual
Use the “start_time” command to set an explicit starting time of the reaction. Thiscan be used to coordinate the plotting of timed scatter data samples stored in aGSS spreadsheet on the reaction path in Xtplot. The time should be in the format“HH:MM:SS”. Use “off” to return to the default of not set.
start_time 11:30:00start_time off
8.100 step_increase
step_increase = <value | ?>
Config ! Stepping. . .
Use the “step_increase” command to set the greatest proportional increase, from onestep to the next, in the size of the time step. By default, this variable is set to 2.0. Torestore the default value, type the command with no argument or with an argumentof “?”. To see the current setting of this variable, type “show variables”.
8.101 step_max
step_max = <value | ?>
Config ! Stepping. . .
Use the “step_max” command to limit the number of reaction steps the program maytake to trace a simulation. Use a “?” to restore the default state, which is no prescribedlimit. To see the current setting, type “show variables”.
8.102 suffix
suffix <string>
Config ! Output. . .
Use the “suffix” command to alter the names of the output datasets (“X2t_output.txt”and “X2t_plot.xtp”) by adding a trailing string. Example:
suffix _run2
produces output datasets with names such as “X2t_output_run2.txt”.
274
X2t Commands
8.103 suppress
suppress <species, minerals, gases, surface_species | ALL>
Config ! Suppress. . .
Use the “suppress” command (also: “kill”) to prevent certain aqueous species, surfacespecies, minerals, or gases from being considered in a calculation. Example:
suppress H3SiO4- Quartz "Maximum Microcline"
prevents the three entries listed from being loaded from the database. Typing “suppressALL” suppresses all of the minerals in the thermodynamic database.
The “unsuppress” command reverses the process. To suppress all but a few minerals,you could type
suppress ALLunsuppress Quartz Muscovite Kaolinite
8.104 surface_capacitance
surface_capacitance = <value | ?>surface_capacitance on <type> = <value | ?>
File! Open! Sorbing Surfaces. . . ! constant capacitance F/m2
Use this command (abbrev.: “surf_capacitance”) to set, in units of F/m2, the capacitanceof a sorbing surface. When you set this value (or if a value for capacitance is setin the header of the surface reaction dataset), X2t will model surface complexationfor the surface in question using the constant capacitance model, rather than the fulltwolayer model.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_capacitance on HFO = 2
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_potential” commands.
275
GWB Reference Manual
8.105 surface_data
surface_data <sorption dataset>surface_data remove <sorption dataset | surface type>surface_data OFF
File ! Open ! Sorbing Surfaces. . . ! add
File ! Open ! Sorbing Surfaces. . . ! select surface(s) ! delete
Use the “surface_data” command (abbrev.: “surf_data”) to specify an input datasetof surface sorption reactions to be considered in the calculation. The dataset nameshould be enclosed in quotes if it contains any unusual characters. Use the “remove”argument to eliminate a surface dataset, specified by name or surface type (e.g.,“HFO”), from consideration. The argument “OFF” disables consideration of all surfacecomplexes.
You can specify more than one sorbing surface in a model by repeating the“surface_data” command for different datasets (a dataset of surface reactions forsorption onto hydrous ferric oxide, as well as example datasets for the ion exchange,Kd , Freundlich, and Langmuir models are distributed with the software). To remove adataset of surface reactions from consideration, you use commands such as
surface_data remove FeOH.sdatsurface_data remove HFOsurface_data OFF
The latter command removes all of the surface datasets that have been loaded.
8.106 surface_potential
surface_potential = <value | ?>surface_potential on <type> = <value | ?>
File ! Open ! Sorbing Surfaces. . . ! constant potential mV
Use this command (abbrev.: “surf_potential”) to set, in units of mV, the electricalpotential for a sorbing surface. When you set this value (or if a value is set in the surfacereaction dataset), X2t will model surface complexation for the surface in questionusing the constant potential, rather than full twolayer, method.
If you have set more than one sorbing surface (using the “surface_data” command),you identify the surface in question by its “type”. For example,
surface_potential on HFO = 0
276
X2t Commands
The “type” associated with each surface is listed at the top of each dataset of surfacereactions. The “type” of the hydrous ferric oxide surface represented by the dataset“FeOH.sdat”, for example, is “HFO”. You can use the “show” command to displaythe “type” of each active surface. See also the “ionic_strength”, “temperature”, and“surface_data” commands.
8.107 swap
swap <new basis> <for> <basis species>
Initial or Fluids !
Use the “swap” command to change the set of basis entries. All reactions are writtenin terms of a set of basis species that you can alter to constrain the composition ofthe initial system. An aqueous species, mineral, gas, or activity ratio can be swappedinto the basis in place of one of the original basis species listed in the database. Theswap operates on either the initial system, a boundary fluid, or globally on all fluids,depending on the current input scope (see the “scope” command). Examples:
swap CO3-- for HCO3-swap Quartz for SiO2(aq)swap CO2(g) for H+swap O2(g) for O2(aq)swap Ca++/Na+^2 for Ca++
The new species must contain in its composition the original basis species beingswapped out (you can’t swap lead for gold). For example, CO2(g) is composed ofHCO�
3 , HC, and water. The reactions in the thermo dataset (once modified to reflectenabled redox couples) show the basis entries for which a species may be swapped.For a list of original basis species, type “show basis”. To reverse a swap, type “unswap<species>”.
8.108 system
system <system command>
Use the “system” command to execute a command on the computer’s operatingsystem (a “DOS command”) without leaving X2t. Example:
system "copy X2t_output.txt X2t_output2.txt"
Enclose multiword system commands in quotes. An alternative way to fork a systemcommand is to begin the X2t command with a “$”:
277
GWB Reference Manual
$copy X2t_output.txt X2t_output2.txt
In this case, no quotation marks are needed.When a “system” command is executed, a “Command Prompt” window will appear
briefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
8.109 TDS
TDS = <value | ?>
Initial or Fluids ! advanced ! TDS mg/kg
Use the “TDS” command to set in mg/kg the total dissolved solids for the currentinput scope, if you don’t want the program to calculate this value automatically. Theprogram uses the TDS when needed to convert input constraints into molal units.The setting applies to the initial system, a boundary fluid, or globally to all fluids,depending on the current input scope (see the “scope” command).
To restore automatic calculation of the TDS, type the command with no argumentor with an argument of “?”. To see the variable’s current setting, type “show variables”.
8.110 temperature
temperature = <field_variable> <unit>temperature = <value> <unit>temperature initial = <field_variable> <unit> <boundary fluid> = <value> <unit>temperature isothermaltemperature constant = <on | off>temperature reset
Initial ! temperature C
Fluids ! temperature C
Use the “temperature” command (also: “T”) to set the temperature of the initial systemor the boundary fluids. The Units Recognized appendix lists possible units, whichdefault to “C”. By default, the initial system and boundary fluids at set to 25°C and, inthe absence of a heat source, the simulation proceeds isothermally.
In its simple usage, the command set the temperature of the current scope:
scope initialtemperature = 25 C
278
X2t Commands
scope inlet_fluid1temperature = 100 C
but you can also specify scope as a keyword on the command line
temperature initial = 25 C, inlet_fluid1 = 100 C
In the example, hot fluid invades an initially cool domain.Keyword “isothermal” sets the boundary fluid temperature(s) to the initial temperature
for the domain. Keyword “constant” causes the program to hold temperature at eachnodal block invariant over the course of the simulation, and the “reset” keyword returnstemperature variables to their default state.
You should enter temperature values within the range over of the thermo datasetin use. For the default dataset “thermo.tdat”, the range is 0°C to 300°C.
8.111 thermal_cond
thermal_cond = <field_variable | ?> <unit> <steady | transient>
Medium ! thermal conductivity cal/cm/s/C
Use the “thermal_cond” command (abbrev.: “tcond”) to set the thermal conductivity of thefluidsaturated medium. You can specify one of the units listed in the Units Recognized
appendix; “cal/cm/sec/°C”is thedefault.Thisvalue isusedduringpolythermalsimulationsin calculating the effects of advective heat transport.
By default, this variable is set to 0.004 cal/cm/s/°C. The “transient” keyword causesthe model to evaluate the field variable continuously over the course of the simulation,if it is set with an equation, script, or function. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show system”.
8.112 theta
theta = <value | ?>
Config ! Stepping. . .
Use the “theta” command to set the time weighting variable used in evaluating kineticrate laws. The value may vary from zero (full weighting at the old time level) to one(full weighting at the new time level). By default, this variable is set to 0.6. To restorethe default value, type the command with no argument or with an argument of “?”. Tosee the current setting of this variable, type “show variables”.
279
GWB Reference Manual
8.113 threads
threads = <value | ?>
Config ! Stepping. . .
Use the “threads” command to control the number of threads the program spawnswhen running a simulation. Using more than one thread on multicore or multiprocessorcomputers, the program runs in parallel, dividing the computing work among thecomputing cores available. By default (use the “?” argument), the program spawns onethread for each computing core. Typing the command without an argument returnsthe current setting and the number of computing cores available.
8.114 timax
timax = <value | ?>
Config ! Iteration. . .
The “timax” command sets in molal units the maximum value of ionic strength used incalculating species’ activity coefficients when the DebyeHückel model is employed.By default, this variable is set to 3 molal. To restore the default value, type thecommand with no argument or with an argument of “?”. To see the current setting ofthis variable, type “show variables”.
8.115 time
time start = <value> <unit> <interval> = <value | ?> <unit> \end = <value> <unit>
Intervals ! start at day
interval_1 at day
end at day
Use the “time” command (abbrev.: “t”) to set the time span (keywords “start” and “end”)of the simulation, and the start times for individual simulation intervals. The startingtime for the run, by default, is zero. Unit choices are listed in the Units Recognized
appendix; “day” is the default. Examples:
time end = 100 yearstime start 10 days, end 20 daystime phase2 = 1 year, phase3 = 2 years, end = 10 years
280
X2t Commands
Note that starting times and the end time are commonly and perhaps more clearlyspecified instead on the “intervals” command.
8.116 title
title <character string>
Config ! Output. . .
Use the “title” command to set a title to be passed to the graphics program. Example:
title "Yucca Mountain Groundwater"
Be sure to put multiword titles in quotes.
8.117 top
top fluid = <boundary fluid>top <interval> fluid = <boundary fluid>top = <normal | inlet | outlet>
Flow ! boundaries: top
In simulations in which the flow field is imported, and only such simulations, use the“top” command to control the boundary condition at the top side of the domain: thefluid to appear at the boundary, and whether solutes can diffuse and disperse, andheat conduct, across the boundary.
If the command contains the name of a simulation interval, subsequent settingson the command apply to that interval, rather than the simulation as a whole. Thisbehavior continues to the end of the command, or until the name of another intervalis encountered.
You use the “fluid” keyword to specify the boundary fluid to appear on the topboundary, for the entire simulation or an individual interval. For example, the commands
top fluid = ambient_watertop phase2 fluid = pit_water
set fluid “ambient_water” on the top boundary over the course of the simulation, exceptduring interval “phase2”, in which case fluid “pit_water” is found on the boundary.
The program by default uses “inlet/free outlet” boundary conditions: where fluid flowsinto the domain, solute mass can advect, diffuse, and disperse across the boundary,but where it exits the domain, transport occurs by advection alone. Similarly, heat canconduct across an inlet, but not an outlet.
281
GWB Reference Manual
You can force the program to treat the top of the domain as an inlet or free outletboundary, regardless of the direction of fluid migration. Keyword “inlet” causes theprogram to allow diffusion, hydrodynamic dispersion and heat conduction across thetop bound, whereas keyword “outlet” creates an insulated boundary sealed againsttransport by these processes:
top outlet
In either case, the advective transport of solute mass and heat depends on thedirection and rate of fluid migration, and is not affected by the command setting
Seealso the“left”, “bottom”, “right”, “discharge”, “headdrop”, and “interval”commands.
8.118 unalter
unalter <species | mineral | gas | ALL>
Config ! Alter Log Ks. . . ! select entry(ies) ! delete
Use the “unalter” command to reverse the effect of having changed the log K ’s for aspecies, mineral, or gas reaction. Example:
unalter Quartz
In this case, the log K values for quartz revert to those in the current thermodynamicdataset. The argument “ALL” resets the log K ’s for all species, minerals, and gases.
8.119 unsuppress
unsuppress <species, minerals, gases | ALL>
Config ! Suppress. . .
Use the “unsuppress” command (also: “include”) to include in the calculation aqueousspecies, minerals, or gases that have previously been suppressed. Examples:
unsuppress Quartz Albite "Albite low"unsuppress ALL
The argument “ALL” clears any species, minerals, or gases that have been suppressed.
282
X2t Commands
8.120 unswap
unswap <species | ALL>
Initial or Fluids ! !
Use the “unswap” command to reverse a basis swap. The swap reversal operates oneither the initial system, a boundary fluid, or globally on all fluids, depending on thecurrent input scope (see the “scope” command). Example:
unswap Quartz (or unswap SiO2(aq))
to reverse the effect of the command
swap Quartz for SiO2(aq)
At this point, SiO2(aq) is back in the basis. The “ALL” argument reverses all basisswaps.
8.121 usgovt
usgovt
Help ! About X2t. . .
Display the restricted rights legend that governs use, duplication, or disclosure by theU.S. Government.
8.122 well
well <name> <x = <value> <unit>> <y = <value> <unit>> \<<rate | inject> = <value> <unit>> \<<head | potential> = <value> <unit>> \<start = <value> <unit>> <end = <value> <unit>> \<fluid = <boundary fluid>>
well <name> interval <interval> \<<rate | inject> = <value> <unit>> \<<head | potential> = <value> <unit>> \<start = <value> <unit>> <end = <value> <unit>> \
283
GWB Reference Manual
<fluid = <boundary fluid>>well <name> rename <new name>well <name> interval <interval> rename <new name>well
Wells ! well_1 x cm y cm
interval-1 fluid start day end day
rate cm3/s
or
potential atm
add
Use the “well” command to define wells and set well properties. Create a well byissuing the “well” command with a new well name. If you omit the well name fromthe command line, the program assumes the command applies to the most recentlyreferenced well, the name of which is given by typing “well” without arguments. Type“show wells” to see a list of wells and their properties.
To define a well, you need to set its position along the x and y directions, with the“x” and “y” keywords. You set position in units of distance (see the Units Recognized
appendix); cm is the default. The x position can vary from zero to the length of thedomain, and the y position can vary from zero to the domain’s width.
You need to set also either the well’s injection rate with the “rate” or “inject” keyword,or its hydraulic head or hydraulic potential with the “head” or “potential” keyword. Youset injection rates in units of flow rate (Units Recognized) such as cm3/s, the default;head in distance units, defaulting to cm; and hydraulic potential in pressure units,which default to atm. A negative rate sets a producing rather than injecting well.
You then use the “fluid” keyword to associate a fluid with the well. Specifically, youneed to set a fluid for each injecting well, and each well set at known head. Producingwells, however, need not be associated with a fluid.
For example, in the commands
well well-1 x = 13 m, y = 22 m, rate = 14 m3/day, fluid = injected_fluidwell well-2 x = 1.9 km, y = .38 km, head = 210 m, fluid = fluid-2
well “well1” injects 14 m3 day�1 of the fluid “injected_fluid”, whereas “well2” operatesat known head, and as such may either inject fluid “fluid2” or produce water fromthe domain, depending on the flow field calculated by X2t.
A well by default operates over the course of the X2t simulation, but you can specifya specific time range with the “start” and “end” keywords. For example, the commands
284
X2t Commands
time start 0 years, end 10 yearswell well-1 x = 2 km, y = 3 kmwell well-2 x = 1.5 km, y = 8 km, start = 2 years, end = 3 years
set well “well=1” to operate from 0 years to 10 years, whereas “well2” operates overonly part of the simulation, from 2 years to 3 years.
You can further define discrete operating intervals for a single well, using the“interval” keyword. For example, executing the commands
well well-1 x = 1.2 km, y = 13.7 kmwell well-1 interval period-1 end 120 days rate = 0.2 m3/min fluid = fluid-1well well-1 interval period-2 start 120 days rate = 0.3 m3/min fluid = fluid-2
well “well1” will inject fluid1 at 0.2 m3 min�1 until the simulation reaches 120 days,after which it will inject fluid2 at 0.3 m3 min�1. Note there may be any number ofintervals, and you may leave hiatuses among them, during which the well does notoperate.
Finally, you can use the “rename” keyword to recast the name of a well or a wellinterval. For example, after running the commands
well your_well rename my_wellwell my_well interval your_interval rename my_interval
interval “your_interval” of well “your_well” is known as “my_interval”, and the well isnow “my_well”.
See also the “remove” command.
8.123 width
width = <value> <unit>
Domain ! width (y) cm
Use the “width” command to set the width along y of the medium. You can use anyunit of distance listed in the Units Recognized appendix; “cm” is the default. Domainwidth defaults to 100 cm in X2t. See also the “length” and “height” commands.
8.124 xtplot
xtplot <xtplot options>
Run ! Xtplot
285
GWB Reference Manual
The “xtplot” command launches program Xtplot from the X2t command line, invokinginput from the current graphics interface dataset (by default, “X2t_plot.xtp”; see the“suffix” command). For example,
xtplot map
starts Xtplot initially showing a map view plot.
8.125 Xstable
Xstable = <value>
Config ! Stepping. . .
Use the “Xstable” command to control how the stability criterion for dispersive transportand thermal conduction is applied. A value of one sets the theoretically largest stabletime step for an ideal situation. X2t simulations are not necessarily ideal (for example,the solute may react and the medium may not be uniform), so this limiting time stepmay in fact be too large to be stable. Setting “Xstable” to a value smaller than oneresults in a more stringent constraint on the time step, and hence greater stability.The default value for this variable is 1.0, the theoretical limit. See also the “Courant”command.
286
Appendix: Thermo Datasets
The databases of thermodynamic data used by the programs are ascii (or character)files that you edit with TEdit, the thermo editor supplied as part of the GWB software.You can alternatively change a thermo file using a text editor, such as “Notepad”under MS Windows.
You are free to alter existing databases such as “thermo.tdat” by changing data oradding species, minerals, and so on. When changing a database, it is a good idea tocopy the original database to a file with a new name, and then alter that file. You canalso create your own databases by following the dataset format.
You access the new file from the GWB apps with the “read” command, or by openingthe File !Open !Thermo Data. . . dialog. You can set a specific dataset to be readby default when one of the GWB apps starts. To do so, set the dataset as the defaultthermodynamic file in File !Preferences. . . (see Thermodynamic datasets in theIntroduction to the GWB Essentials Guide).
The information in this Appendix applies to the “oct13” format, which is usedbeginning with the GWB10 release. A description of legacy datasets appears at theend of the Appendix.
A.1 Thermodynamic dataset format
Each thermo dataset is composed of the following sections:
1. Header lines, which identify the dataset
2. Data tables
3. Elements included in the dataset
4. Basis species
5. Redox couples
6. Aqueous species
7. Free electron
8. Minerals
9. Gases
287
GWB Reference Manual
10. Oxide components
11. Virial coefficients, for datasets invoking a virial (“Pitzer”) activity model
Sections 3–10 begin with a header line such as
46 elements
which identifies the number of elements, species, and so on in each section. Thecount is ignored in the current software, but very old GWB releases require it to beaccurate. A line
-end-
marks the end of each section.You can include comment lines, identified by a “*” as the first character, freely
within the dataset. The programs read the data wordbyword, so it is not necessaryto count spaces or align columns when adding new data.
A.1.1 Header lines
A group of header lines appears at the top of the dataset:
dataset of thermodynamic data for gwb programsdataset format: oct13activity model: debye-huckel
These lines identify the dataset, its format, and the activity model to be invoked.The current format is “oct13”; earlier formats are described in the last section of thisAppendix. The activity model should be “debyehuckel”, “hmw”, “phrqpitz” (currentlyequivalent to “hmw”), “phreeqc”, “wateq4f”, or “minteq”. The “pitzer” activity modelis outmoded and no longer supported.
A.1.2 Data tables
The following section contains tables showing how various coefficients vary withtemperature. The first table contains eight principal temperatures at which the datatables and log K ’s for species and so on are tabulated.
* temperatures0.0000 25.0000 60.0000 100.0000
150.0000 200.0000 250.0000 300.0000
Most commonly, the principal temperatures are 0°C, 25°C, 60°C, 100°C, 150°C, 200°C,250°C, and 300°C, but you can choose other values.
In isothermal runs in which temperature is set to one of the principal temperatures,the GWB applications take the corresponding value from each data table. In a runat 25°C, given the principal temperatures above, for example, the application takes
288
Thermo Datasets
the second entry in each table in the header section, and the second log K entryfor each chemical species in the dataset. Where temperature differs from a principaltemperature, the application fits each table to a polynomial
v D ao Ca1T Ca2T2 Ca3T
3 Ca4T4
with respect to temperature T , in °C. You can use Rxn to quickly see the polynomialfit of the log K for any chemical species:
react Quartzlonggo
for example.Following the temperature table are tables giving pressure, coefficients for calculating
parameters in activity coefficient correlations, and so on, at each of the principaltemperatures. The tables look like:
* pressures1.0134 1.0134 1.0134 1.01344.7600 15.5490 39.7760 85.9270
* debye huckel a (adh).4913 .5092 .5450 .5998.6898 .8099 .9785 1.2555
...
The parameters in these tables are
Pressure, in atm,
The DebyeHückel parameters A, B, and PB ,
Coefficients for calculating the activity coefficients for CO2 and some otherelectrically neutral species, and
Coefficients for calculating the activity of water.
A.1.3 Elements
The next section contains the elements of which species and so on in the databaseare composed, and each element’s chemical symbol and mole weight. The entries inthis section look like
Oxygen (O ) mole wt.= 15.9994Silver (Ag) mole wt.= 107.8680Aluminum (Al) mole wt.= 26.9815
289
GWB Reference Manual
Americium (Am) mole wt.= 241.0600...
A.1.4 Basis species
The basis species for the dataset, beginning with water (H2O), are defined in thenext section. The entry for each species contains its charge, ion size parameter inangstroms (for calculating its activity coefficient), mole weight (g/mol), and elementalcomposition
H2Ocharge= 0.0 ion size= 0.0 A mole wt.= 18.01522 elements in species1.000 O 2.000 H
Ag+charge= 1.0 ion size= 2.5 A mole wt.= 107.86801 elements in species1.000 Ag
Al+++charge= 3.0 ion size= 9.0 A mole wt.= 26.98151 elements in species1.000 Al
Am+++charge= 3.0 ion size= 9.0 A mole wt.= 241.06001 elements in species1.000 Am
...
The ion size parameter (ao/ has special meaning for neutrally charged aqueous speciesin the thermo dataset. For neutral species with ao � 0, the species’ activity coefficientis set to one. When ao D �1/2, the activity coefficient is calculated from the “CO2”coefficients in the data table section, according to equation 8.6 in the “Geochemicaland Biogeochemical Reaction Modeling” text. When ao � �1, the logarithm of theactivity coefficient is set to the product PB � I , where PB is given by the data tablesabove, and I is true ionic strength.
Whenever a database is to include protonation and deprotonation reactions, the listof basis entries needs to include the hydrogen ion, HC, labeled as “H+”. Databasestreating redox require as part of the list either dissolved dioxygen, O2.aq/, or dissolveddihydrogen H2.aq/; the species must be labeled, respectively, “O2(aq)” and “H2(aq)”.The species you choose, O2.aq/ or H2.aq/, is the database’s “redox pivot”.
A.1.5 Redox couples
Redox coupling reactions for the dataset are found in the following section. TheFeCCC/FeCC couple, for example, is represented
290
Thermo Datasets
Fe+++charge= 3.0 ion size= 9.0 A mole wt.= 55.84704 species in reaction-0.500 H2O 1.000 Fe++ 1.000 H+0.250 O2(aq)-10.0553 -8.4878 -6.6954 -5.0568-3.4154 -2.0747 -0.8908 0.2679
The first two lines identify the redox species and give its charge, ion size parameter,and mole weight.
The subsequent lines show the reaction by which the redox species dissociates.This reaction can be written in terms of any of the basis species in the previoussection of the dataset, or any redox species that have been defined to this point inthe current section. You may also use gaseous dioxygen or dihydrogen, or the freeelectron, as described in the next paragraph. Note that you set reactions in the dataset3 species per line, until the reaction is complete. The final lines give log K values forthis reaction at each of the principal temperatures.
The manner in which you represent electron acceptance and donation in the couplingreactions depends on the redox pivot you have chosen. Where the pivot is O2.aq/,you may balance redox reactions in terms of aqueous or gaseous dioxygen, “O2(aq)”or “O2(g)”:
Fe+++charge= 3.0 ion size= 9.0 A mole wt.= 55.8470 g4 species in reaction-0.500 H2O 1.000 Fe++ 1.000 H+0.250 O2(g)-9.3901 -7.7630 -5.9309 -4.2756-2.6496 -1.3462 -0.2258 0.8704
Or, you may set a halfcell reaction in terms of the free electron, “e”
Fe+++charge= 3.0 ion size= 9.0 A mole wt.= 55.8470 g2 species in reaction
1.000 Fe++ -1.000 e-13.3713 13.0127 12.5821 12.190311.8236 11.5751 11.4559 11.5415
Similarly, where the pivot is H2.aq/, you may use “H2(aq)”, “H2(g)”,
Fe+++charge= 3.0 ion size= 9.0 A mole wt.= 55.8470 g
291
GWB Reference Manual
3 species in reaction1.000 Fe++ 1.000 H+ -0.500 H2(g)13.6804 13.0127 12.2194 11.487310.7750 10.2446 9.8895 9.7741
or “e”.In datasets that do not include a redox pivot within the basis, you would normally
not include redox coupling reactions. In that case, the section would look like
0 redox couples-end-
A.1.6 Aqueous species
The next section contains the aqueous species to be considered in addition to thebasis and redox species. The entry for CaClC, for example, is
CaCl+charge= 1.0 ion size= 4.0 A mole wt.= 75.53302 species in reaction
1.000 Ca++ 1.000 Cl--0.9687 -0.7000 -0.5157 -0.4688-0.5789 -0.8602 -1.3560 -2.2451
The entry contains the reaction for dissociating the species to the basis and redoxspecies, and the log K values for this reaction.
To maintain the software’s ability to couple and decouple redox reactions, youshould balance reactions in this and following sections by avoiding the use, whereverpossible, of O2.aq/, O2.g/, H2.aq/, H2.g/, and e�. To do so, you balance the reactionsin terms of species of the same oxidation state as the species in question. The entryfor H2S(aq), for example,
H2S(aq)charge= 0.0 ion size= 4.0 A mole wt.=
34.0758 g2 species in reaction
1.000 H+ 1.000 HS--7.6500 -6.9500 -6.6800 -6.6100-6.7900 -7.1700 -7.7200 -8.4300
is properly balanced in terms of the redox species HS�, rather than the basis speciesSO4
��.
292
Thermo Datasets
A.1.7 Free electron
The halfcell reaction representing takeup of the free electron is written in a form thatreflects the database’s redox pivot. Where the pivot is O2.aq/, the reaction is writtenin terms of either “O2(aq)” or “O2(g)”:
e-charge= -1.0 ion size= 0.0 A mole wt.= 0.0000 g3 species in reaction
0.500 H2O -0.250 O2(g) -1.000 H+22.7614 20.7757 18.5130 16.465814.4732 12.9213 11.6817 10.6711
For H2.aq/, the reaction is given in terms of “H2(aq)” or “H2(g)”:
e-charge= -1.0 ion size= 0.0 A mole wt.= 0.0000 g2 species in reaction
0.500 H2(g) -1.000 H+-0.3091 0.0000 0.3627 0.70301.0486 1.3305 1.5663 1.7673
A.1.8 Minerals
Minerals to be included in the database are found in the next section. The entry forthe sodium feldspar albite looks like
Albite type= feldsparformula= NaAlSi3O8mole vol.= 100.250 cc mole wt.= 262.2230 g5 species in reaction
2.000 H2O 1.000 Na+ 1.000 Al+++3.000 SiO2(aq) -4.000 H+
3.9160 3.0973 1.9915 0.9454-0.0499 -0.8183 -1.5319 -2.5197
The initial lines in the entry give the mineral’s name, type, formula, and molar volume(cm3/mol) and weight (g/mol). The remaining lines give the reaction by which themineral decomposes to basis and redox species and the corresponding log K valuesat the principal temperatures. As with the aqueous species, the reaction should bewritten without change in oxidation state, if possible.
A.1.9 Gases
The next section contains the gases considered. The entry for CO2(g), for example, is
293
GWB Reference Manual
CO2(g)mole wt.= 44.0098 g3 species in reaction-1.000 H2O 1.000 H+ 1.000
HCO3--7.6827 -7.8184 -8.0628 -8.3849-8.8297 -9.3208 -9.8841 -10.6132
The first lines give the name and mole weight (g/mol) of the gas. As before, theremaining lines give the gas’ dissociation reaction and corresponding log K values.
A.1.10 Oxide components
The oxide components are used as reactants in simulations that, for example, modelthe dissolution of a glass phase. An example is
Al2O3mole wt.= 101.9616 g3 species in reaction-6.000 H+ 2.000 Al+++ 3.000 H2O
Note that since components are fictive entities used to describe bulk composition,they have no thermodynamic stability and hence there are no entries for log K values.
A.1.11 Virial coefficients
Datasets that invoke the virial activity model include a final section containing the virialcoefficients and any data for describing variation of the coefficients with temperature.The coefficients ˇ.0/, ˇ.1/, ˇ.2/, c�, � , �, and can vary with temperature; they varyin value according to the polynomial
ˇ D ˇ25 Cc1 .TK �Tr/Cc2
�
1
TK
�1
Tr
�
Cc3 ln
�
TK
Tr
�
Cc4
�
T 2K �T 2
r
�
Cc5
�
1
T 2K
�1
T 2r
�
Here, ˇ represents the virial coefficient in question and ˇ25 is its value at 25°C, TK isabsolute temperature, and Tr is 298.15 K.
Each coefficient is defined on a line containing at a minimum the value at 25°C andoptionally one or more of the polynomial coefficients c1 � c5. Any omitted entries forthe polynomial are treated as zero values. Hence, a line containing ˇ25 and c1 definesthe virial coefficient in terms of its 25°C value and its first temperature derivative.
There are four segments of virial coefficients in the section:
Values of ˇ.0/, ˇ.1/, ˇ.2/, c� , ˛.1/, and ˛.2/ for cationanion pairs,
Values of � for anionanion pairs,
Values of � for ionneutral species pairs, and
294
Thermo Datasets
Values of for species triplets.
An example block for the cationanion pair NaCCl� is
Na+ Cl-beta0 = 0.0765 0.008946 -777.03 -4.4706 -3.3158E-6beta1 = 0.2664 6.1608E-5 0.0 0.0 1.0715E-6beta2 = 0.0cphi = 0.00127 -4.655E-5 33.317 0.09421alpha = 2.0alpha2 = 0.0
In this case, the value of ˇ.0/ at 25°C is 0.0765, and the value’s temperature variation isdefinedbypolynomialcoefficients c1–c4 of0:008946, �777:03, �4:4706, and�3:3158�10�6.
A.1.12 Legacy formats
Two legacy formats for the thermo databases may be used with current releases of thesoftware. The legacy formats, labeled “oct94” and “feb94”, are functionally identical,except the former is preferred for “hmw” and “phrqpitz” activity models, and latteraccepts the outmoded “pitzer” model. GWB releases 9.0 and earlier work only withthese formats; they do not accept databases in the current “oct13” format.
The differences between the legacy and current formats are summarized below.
A.1.12.1 Tables
The legacy datasets include four additional tables:
One table containing the log K values for the halfcell reaction
2 H2O � O2.g/C4 HC C4 e�
and
Three tables holding the log K values for the solubilities of the gases O2(g),H2(g), and N2(g). Only the values for O2(g) are used by the software.
A.1.12.2 Redox couples
Redox coupling reactions in the legacy datasets can be balanced only in terms of“O2(aq)” as the electron acceptor.
A.1.12.3 Free electron
Legacy databases do not include a reaction representing takeup of the free electron.Instead, the software constructs the reaction from the first table mentioned above.
295
296
Appendix: User Interface
The command line interface for Rxn, Act2, Tact, SpecE8, React, X1t, and X2t includes anumber of special features that you will find increasingly helpful as you gain experience.This appendix provides a more complete description of the user interface than givenpreviously.
B.1 Spelling completion
Rxn, Act2, Tact, SpecE8, React, X1t, and X2t can complete the spelling of chemicaland mineral names. The feature also completes the names of program commandsand dataset names. To complete a spelling, begin typing the name and touch the tab(or, on most computers, escape) key. For example, if you type
1 free mole Musc[tab]
the program will complete the line
1 free mole Muscovite
When the program cannot identify a unique name from the letters provided, it willcycle through the possible completions with subsequent tab key presses. To list thepossible completions, you can type Ctrl+D. For example, if you type
swap Al2ˆD
the program will respond with
Al2(OH)2++++ Al2(SO4)3 Al2(SO4)3:6H2Oswap Al2|
leaving the cursor (“j”) in position to continue the command.
297
GWB Reference Manual
B.2 History substitution
Rxn, Act2, Tact, SpecE8, React, X1t, and X2t maintain history lists. Previously executedcommands are stored in the user’s profile directory (e.g., “c:\Documents and Settings\jones\Application Data\GWB”) in datasets such as “rxn_history.dat”. If you type thecommand
history 10
the program lists the previous ten commands executed.Each of the history substitution functions of the Cshell are available within the
programs. For example, typing
!!!10!swap!?HCO3
causes the program to reexecute, respectively, the previous command, commandnumber 10, the last command that began with “swap”, and the last command thatcontained the string “HCO3”.
Entries of the form
^string1^string2
replace the occurrence of “string1” with “string2” in the previous command, so thatyou can avoid retyping lengthy commands after simple errors. Finally, typing
!10-15
causes the program to reexecute commands 10 through 15. This latter feature is anextension to the Cshell protocol.
298
User Interface
B.3 Special characters
The following special characters are used in the Command pane in Rxn, Act2, Tact,SpecE8, React, X1t, and X2t:
Ctrl+D Show choices for spelling completion of chemical names,
commands, or file names.
Ctrl+F Clear screen.
Ctrl+H Backspace over a character.
Ctrl+N Scroll forward through your command history to give the nextcommand in list.
Ctrl+P Scroll backward through your command history to give the previouscommand in list.
Ctrl+U Backspace over entire line of input.
Ctrl+W Backspace over previous word of input.
Tab or Cycle through choices for spelling completion of chemical names,Esc commands, or file names.
\ Continue a command from one line to the next.
B.4 Calculator
Programs Rxn, Act2, Tact, SpecE8, React, X1t, and X2t provide an online calculatorwith these functions:
+ Addition
- Subtraction
* Multiplication
/ Division
ˆ Exponentiation
( ) Grouping of terms
ln Natural logarithm
log Common logarithm
abs Absolute value
sqrt Square root
exp Exponentiation of e
sin, cos, Trigonometric functions
tan, cot, (arguments in radians)
sec, csc
e Value of e
pi Value of �
The online calculator is especially useful to a geochemist for converting numbers totheir logarithms and vice versa, but can be used to evaluate any numerical expression.To use the calculator, type an expression at the prompt. Examples:
299
GWB Reference Manual
log .000310^-4.5(200 - 32) * 5/9
In each case, the program evaluates the expression and returns its numerical value.
B.5 Startup files
Upon startup, Rxn looks for a file such as “rxn_startup.rxn” in a user’s profile directory(found by typing %appdata% in the Windows Explorer Address bar, e.g.,“c:\Documents and Settings\jones\Application Data\GWB”) and executes any commands in it; theothermodeling programssimilarly look forfilesnamed“act2_startup.ac2”,“spece8_startup.sp8”, and so on. These datasets provide a means for you to customizethe working environment of each program. An “act2_startup.ac2” file including thecommands
background greyfont Times
for example, will cause Act2 to produce plots with grey backgrounds and Timeslettering, unless told otherwise.
B.6 Help pages
You can obtain online help for any of the programs on the Docs pane of the GWBdashboard, or using the “Help” pulldown menu on the menubar of any GWB program.The entire manual set, including this User’s Guide, can be accessed from the “Help”pulldown. The manuals are installed in electronic form as pdf files (which have a “.pdf”suffix) in the same directory as the GWB software.
B.7 System commands
You can execute (“fork”) DOS commands from the command lines of Rxn, Act2, Tact,SpecE8, React, X1t, and X2t. To do so, type a “$” followed by the desired DOScommand. Example:
$print React_output.txt
When a system command is executed, a “Command Prompt” window will appearbriefly on your screen. Due to limitations of the Windows operating system, you cannotfork a command that requires user input, and you will not be able to see any output(including error messages) that might be generated by the command.
300
User Interface
B.8 Text size in the GWB windows
You can control the font and size of the text within the program shells for Rxn, Act2,Tact, SpecE8, React, X1t, and X2t by choosing the desired font and point size fromView ! Appearance. . . . "Reset" will change the point size back to the default value.
B.9 Keyboard shortcuts
Ctrl+Break Break program (used during program execution, it stops thecalculation and returns you to the command prompt).
Ctrl+A Select all.
Ctrl+C Copy.
Ctrl+Shift+C Load conductivity data (SpecE8, React, X1t, X2t).
Ctrl+F Clear screen.
Ctrl+G Go, run calculation of the model.
Ctrl+Shift+G Load scatter data (Act2, Tact).
Ctrl+Shift+G Go single, run on a single processor (X1t, X2t).
Ctrl+I Go initial, calculate the initial state of the medium (React, X1t, X2t).
Ctrl+Shift+L Launch Gtplot or Xtplot to show results (SpecE8, React, X1t, X2t).
Ctrl+M Save image... (Act2, Tact).
Ctrl+N Add an entry to the basis.
Ctrl+O Read script (open data file).
Ctrl+Q Quit the program.
Ctrl+R Reset configuration.
Ctrl+Shift+R Resume, restore the configuration from when the program was last exited.
Ctrl+S Save As...
Ctrl+Shift+S Load sorbing surfaces (Rxn, SpecE8, React, X1t, X2t).
Alt+S Reset the size of the window to the default.
Ctrl+T Load thermo dataset.
Ctrl+Shift+T Load reaction trace (Act2, Tact).
Ctrl+U Update trace (Act2, Tact).
Ctrl+V Paste.
Ctrl+Shift+W Change working directory.
Ctrl+X Cut.
Ctrl+Y Redo (GSS).
Ctrl+Z Undo (GSS).
F1 GWB Reference Manual.
301
302
Appendix: Graphics Output
Programs Act2, Tact, Gtplot, and Xtplot can render plots on a variety of devices,including your computer screen and blackandwhite and color printers. The programscan also save your plots in a variety of graphics formats; you can later import theseimages to documents, web pages, or presentations that you prepare with othersoftware. Finally, you can copy your plots to the MS Windows clipboard and pastethem directly into other applications, in a format meaningful to the application.
C.1 Clipboard
To copy the current plot to the clipboard, select Edit ! Copy from the menubar on thegraphics window, or touch Ctrl+C. You can then paste the plot directly into a varietyof word processing and presentation graphics programs.
If you paste the plot into MS PowerPoint, it will appear as an EMF (an MS EnhancedMetafile) graphic object. Pasting into Adobe Illustrator places a native AI graphic.
If you paste a plot from Gtplot or Xtplot into MS Excel or a text editor such asNotepad or MS Word, the numerical values of the data points that make up the lineson the plot will appear in spreadsheet format.
You can control the format in which the plot is copied to the clipboard by selectingEdit ! Copy As. You can choose to copy the plot as an AI object, an EMF object, abitmap, or the data points in the plot, as tab delimited or space delimited text. Usethe tab delimited option to paste the data into a spreadsheet program like MS Excel.For examining the data in a text file created with an editor like Notepad or MS Word,the space delimited option writes a nicely aligned table.
303
GWB Reference Manual
“Paste” in Excel or Word
inserts numerical values
In MS Word or MS Excel, use Paste Special. . . to paste the plot as a pictureinstead.
“Paste Special...” in Excel or Word inserts a picture
C.2 Saving images
In many cases you will want to adjust label positions or change the annotation orcoloring on your plot. Such changes can be made quickly using an illustration programsuch as PowerPoint. You can, furthermore, save images and import them into yourreports or documents prepared with a word processor such as MS Word.
304
Graphics Output
To save an image, select File ! Save Image. . . from the menubar, then chooseone of the file formats supported:
PNG (.png)
JPEG (.jpg)
TIFF (.tif)
Bitmap (.bmp)
Enhanced Metafile (.emf)
Adobe Illustrator (.ai)
PDF File (.pdf)
Scalable Vector Graphics (.svg)
Compressed SVG (.svgz)
Encapsulated PostScript (.eps)
Color PostScript (.ps)
BlackandWhite PostScript (.ps)
Gtplot and Xtplot also support:
Spreadsheet File (Tab delimited) (.txt)
Text File (Space delimited) (.txt)
The programs save the plot images to files with names such as “Image_1.eps”,“Image_2.eps”, and so on; the suffix represents the file format (Encapsulated PostScript,in this case), as shown above.
Note that since each of these graphics formats has its own limitations, the plot onceimported to another program may appear somewhat different than on your computerscreen. Using your illustration program or word processor, however, you can quicklyalter the diagram’s appearance to suit your needs.
When saving a PNG, JPEG, TIFF, or bitmap file, you may specify the quality ofthe saved image by choosing its resolution: High, Medium, Low, or Custom. UseCustom. . . to set the pixel width and height of the image, and to choose whether topreserve the aspect ratio of the plot.
Use the Spreadsheet File (Tab delimited) or Text File (Space delimited) optionto save into a table the numerical coordinates of the data points on the plot. Thespreadsheet table may be read directly into many popular spreadsheet programs.
Certain graphics types support font embedding. PDF files should always displayand print properly, regardless of fonts installed on the system. PostScript files shouldalso, if you have used the option to embed fonts. If you may want to edit the PostScriptfile, however, you should deselect the option to embed fonts, because programs such
305
GWB Reference Manual
as Adobe Illustrator may restrict your ability to edit a document using embedded fonts(due to potential copyright/licensing issues). To edit these files, be sure that all of therequired fonts are installed on your computer (see Font for data markers below).
When importing AI graphics to Adobe Illustrator, the program may prompt you toupdate the legacy text before you can edit the file. In this case, choose "Update". Youneed to release the clipping mask before you attempt to edit individual elements ofthe plot. Use the "Ungroup" and "Group" functions when repositioning or modifyingelements.
C.3 Font for data markers
We supply a special TrueType font “GWBSymbol” to provide for data markers on scatterplots produced with Act2, Tact, Gtplot, and Xtplot. The font is installed automaticallyon your computer when you install the GWB software.
The “GWBSymbol” font is not subject to copyright, so you can share it freely. If, forexample, you send graphics output to a colleague, you can send her the font to installon her machine. In this way, the data markers on the plots will appear correctly.
306
Appendix: Scatter Data
Act2, Tact, Gtplot and Xtplot can overlay data points (scatter data) on the diagramsthat they produce. The preferred way to add scatter data is to import it from a GSS
spreadsheet (“.gss” file, see the Using GSS chapter of the GWB Essentials Guide).The old method of importing a specially formatted table from a text file still works,however.
To use this method to overlay a scatter plot of data points onto a diagram, firstprepare a table of the data in a plain text (“.txt”) file created with an editor like Notepad.
The first line in the table is a header that names each column; e.g., Na+, pH, andso on. Enclose multiword names in quotes (e.g., "Mass solution", "Dissolved solids",etc.).
Subsequent lines contain the numeric data. A lack of data may be indicated by astring such as “n/d”. To add error bars to the data points, enter a triplet of valuesseparated by vertical bars (|). The values represent the minimum extreme of the errorbar, the data point, and the maximum extreme. Exclude blank spaces from the triplet,or enclose it in quotes. The entry 0.5|2.0|3.5, for example, signifies a data point at 2.0with an error bar extending from 0.5 to 3.5. The entry 0.5||3.5 prescribes the sameerror bar, omitting the symbol representing the data point.
The columns may be separated by any number of spaces or tabs. Comments maybe placed anywhere in the table following a “#” sign. Comments extend from the #sign to the end of the line. You may also include, as separators in the table, blanklines or lines of dashes () underscores (_), or equal signs (=).
You may represent individual data points with a special symbol from among thechoices in Figure 12.1, and choose the symbol’s color and point size. To do so, appendany or all of the following to the data line in question: the symbol name, its color, andits point size, using a string such as “12pt”.
To load the dataset, select File ! Open ! Scatter Data. . . . Choosing the fileselection dialog’s Edit button allows you to modify the contents of the scatter data file.To see the changes on the diagram, use the Open button to reload the data file aftersaving the changes. You may clear the scatter data by choosing the OFF button.
307
GWB Reference Manual
square box
blot circle
triangle delta
yield del
diamond caution
bullet degree
star pentagram
hourglass mobius
C plus � cross
Figure 12.1 Symbols for plotting scatter data.
D.1 Act2 and Tact
To overlay a scatter plot of data points onto an Act2 or Tact diagram, first prepare atable of the data in terms of log activities and fugacities. The first line identifies eachof the table’s columns in terms of a species or gas name, the ratio of two species orgases, or with the special labels “pH”, “Eh”, “pe” and “T(C)”. The species or gas namesshould be those that appear on the diagram axes, or the original basis members of thethermodynamic dataset. When the axis variable is an activity ratio, the label shouldbe formatted as numerator species^power/denominator species^power. A power of1 does not need to be written explicitly. The activity ratio aCaCC/a2
HC, for example,should be written Ca++/H+^2.
Subsequent lines contain the numeric data in logarithmic form, except for the linearvariables pH, Eh, pe, and temperature data. An example of a table dataset to be usedwith Act2 is
pH Na+ Ca++ HCO3------------------------------------------------------------6.5 -4.3 -3.9 -3.3 red square 12pt5.9 -3.2 -5.1 -4.0 # sample UI-46.8 -4.4 -3.6 n/d
Once the table is prepared, click on File ! Open ! Scatter Data. . . to select thedataset. The program will read the data and project them onto the diagram. The Act2
and Tact command
scatter dataset_name
serves the same purpose.
308
Scatter Data
D.2 Gtplot
Gtplot can overlay scatter data points on all of the plot types, except the pie and barcharts. To add scatter data to the “special” plots (ternary plot, Piper diagram, etc.),you specify the fluid composition, expressed in terms of thermodynamic components,as described below.
The first line in the table is a header that names each column; e.g., Temperature, pH,Carbon, Na+, and so on. Enclose multiword names in quotes (e.g., "Ionic strength","Dissolved solids", etc.). You label the columns as follows:
Components: Enter the component name (Ca++, SiO2(aq), etc.).
Minerals: Enter the mineral name as it appears in the Gtplot menus (Quartz,Kaolinite, etc.).
Species concentration: Enter the species name in parenthesis following the word“molality” (e.g., molality(Na+), molality(NaSO4), etc.).
Species activity: Enter the species name in parenthesis following the word “activity”(e.g., activity(Na+), activity(NaHCO3), etc.).
Species activity coefficients: Enter the species name in parenthesis following theword “gamma” (gamma(Na+), gamma(NaCl), etc.).
Elemental composition: Enter the element name (Oxygen, Carbon, etc.).
Fugacities: Enter the name of the gas (CO2(g), Steam, etc.).
Mineral saturation: Enter the mineral name in parenthesis following the word“logQoverK” (e.g., logQoverK(Albite), "logQoverK(Albite high)", etc.).
Isotopic composition: Enter the fluid or mineral name in parenthesis following theisotope label (2H, 18O, etc.). Examples: "2–H(Bulksystem)", 18O(CO2(aq)).
Sorbed fractions: Enter the component name in parenthesis following the word“Xsorbed” (e.g., Xsorbed(Pb++)).
Chemical parameters and physical parameters: Enter the variable name as itappears in the Gtplot menus (Eh, "Dissolved solids", etc.).
The scatter dataset should contain numerical values for any of the following:
The composition of the fluid, minerals, sorbate, and bulk system, expressed interms of thermodynamic components. The components are the original basisentries in the thermo dataset, plus any decoupled redox species.
One of the other variables (pH, Dissolved solids, Carbonate alkalinity, etc.)passed to Gtplot from SpecE8 or React. These variables are those that appearin diagrams, or are used to calculate unit conversions.
The masses of minerals in the modeled system.
309
GWB Reference Manual
The concentrations, activities and activity coefficients of the dissolved species(Fe++, Na+, etc.).
The elemental composition of the fluid, minerals, and bulk system.
The fugacities of gases in the fluid.
The saturation indices (log Q=K) for various minerals.
The stable isotopic compositions of the fluid, minerals in bulk, individual minerals,and the entire system.
The fractions of the various components sorbed onto mineral surfaces.
You enter the numerical values in terms of the following units:
Enter component masses in mg/kg. In this case, concentrations are expressedin terms of the component species, such as HCO3 or SO4. A bicarbonateconcentration, then, is entered directly in units of mg HCO3/kg.
Masses of minerals over the reaction path are entered in grams.
The unit for species concentration is molality. The activities and the activitycoefficients of dissolved species are unitless.
Elemental compositions are entered in mg/kg. These values are expressed interms of the elements, a convention not always followed when reporting anioniccompositions. In creating a dataset, you need to convert analyses given in mgHCO3/kg to mg C/kg, for example, SO4 to sulfur, and so on.
Gas fugacities are unitless.
Mineral saturation is entered as the saturation index, log Q=K.
Isotopic composition is entered in permil on the scale (e.g., SMOW) assumed inthe React calculation.
Sorbed fractions are entered as fractions.
Values for the chemical and physical parameters are entered in their native units,which are the units shown when you first select a variable in the XY Plot dialog.The native unit for temperature, for example, is °C, ionic strength and Eh aregiven in molal and volts, and fO2 is entered as log fugacity. The native units forMass solution and Mass H2O are kg; those for Carbonate alkalinity are mg/kgas CaCO3.
A lack of data may be indicated by a string such as “n/d”.
An example of a table dataset to be used with SpecE8 is
pH Na+ Fe++ "Dissolved solids"----------------------------------------------------------
310
Scatter Data
3.3 .15 5 10002.6 .12 15 8006. .5 n/d 200 # Buffalo Bayou4.3 .75 0.1 450
To render these data, run SpecE8 on a problem containing NaC and FeCC to producea “SpecE8_plot.gtp” file, start Gtplot, and load the scatter dataset with File ! Open
! Scatter Data. . . . From the Plot menu, choose the XY Plot, for example, and setNaC and FeCC on the axes.
Now, if you choose an appropriate unit for the axis (�g/kg, mg/kg, g/kg, or wt%),the data points for the NaC and FeCC columns appear on the plot. You may chooseanother unit, such as molal concentration or grams, but you must first include in thescatter dataset columns for Mass H2O and Mass solution so that Gtplot can convertthe data from mg/kg to the plotting unit; if you do not do so, Gtplot assumes a valueof 1 kg for both variables.
In plots showing the variable “HCO3 + CO3”, you should enter a value in the scatterdataset for Carbonate alkalinity, in mg/kg as CaCO3, so that Gtplot can render thevariable correctly. If you do not enter a value for alkalinity, the program will render thevariable in terms of the reported HCO3 concentration, if available, in which case thediagram produced will not account for the speciation of carbonate.
To assign symbols to each column of variables on an xy plot, add a line to thetable with symbol names (or a place holder such as “--”). Set symbol color and pointsize in a similar manner. For example, adding the lines
-- -- circle square-- -- red green-- -- 24pt 30pt
to the example above causes FeCC concentration to be represented by 24pt red circles,and Dissolved solids by 30pt green squares. Choose from among colors shown onthe Choose Color. . . dialog, enclosing multiword colors in quotes (e.g., "Cornflowerblue"). To set marker point size, use fields like 15pt, 30pt, and so on.
To assign symbols to each sample (i.e., each line in the dataset), append any orall of the following to the data line in question: the symbol name, its color, and itspoint size. The symbol specifications on the sample line will be used to representeach sample in all of the special plots. On an xy plot, you may choose whether toassign the symbol, its color, and its size according to the variable (by analyte) or thesample (by sample). For example, the table
pH Na+ Fe++ "Dissolved solids"-----------------------------------------------------------------------------3.3 .15 5 1000 circle 24pt red2.6 .12 15 800 box 24pt green6. .5 n/d 200 delta 24pt blue4.3 .75 0.1 450 caution 24pt yellow
311
GWB Reference Manual
-- -- circle square-- -- red green-- -- 24pt 30pt
would allow great flexibility in how to depict the data on an xy plot.An example of a table dataset to be used with React is
pH Eh Iron Sulfur-----------------------------------------------------------------------------3.3 .15 5 1002.6 .12 15 806. .5 n/d 20 # Buffalo Bayou4.3 .75 0.1 45
To render these data, run React on a problem containing iron and sulfur to produce a“React_plot.gtp” file, start Gtplot, and load the scatter dataset with the File ! Open
! Scatter Data. . . option. From Plot ! XY Plot. . . choose to plot the elementalcomposition of the fluid. (Similarly, if you had entered data in columns labeled Fe++and SO4–, you would choose to plot components in the fluid.) Select either pH or Ehas the variable for the x axis, and iron, sulfur, or both, for the y axis.
Now, if you choose an appropriate unit for the y axis (�g/kg, mg/kg, g/kg, or wt%),the data points for the iron and sulfur columns appear plotted against pH or Eh.You may choose another unit, such as molal concentration or grams, but you mustfirst include in the scatter dataset columns for Mass H2O and Mass solution so thatGtplot can convert the data from mg/kg to the plotting unit; if you do not do so, Gtplot
assumes a value of 1 kg for both variables.In “special” plots (Piper diagrams, etc.) showing the variable “HCO3 + CO3”, you
should enter a value in the scatter dataset for Carbonate alkalinity, in mg/kg as CaCO3,so that Gtplot can render the variable correctly. If you do not enter a value for alkalinity,the program will render the variable in terms of the reported HCO3 concentration, ifavailable, in which case the diagram produced will not account for the speciation ofcarbonate.
In order to see TDS represented as circles on Piper, ternary, and Durov diagrams,you should enter a value for “Dissolved solids” for each sample.
In a similar fashion, you could plot Eh against pH by choosing the “Chemicalparameters” option from Plot ! XY Plot. . . . If scatter values lie outside the plot axisranges, touch Ctrl+Z.
A second example of a scatter dataset to be used with React is
"Rxn progress" activity(NaCl) "logQoverK(Albite low)"---------------------------------------------------------------------------------------
.3 5.13e-9 .2
.5 5.15e-9 .1
.7 5.17e-9 .15
.9 5.19e-9 n/d
312
Scatter Data
To render these data, run React on a problem containing sodium and silicon to producea “React_plot.gtp” file, start Gtplot, and load the scatter dataset with the File ! Open
! Scatter Data. . . option. From Plot ! XY Plot. . . choose to plot “Species activities”.Select “Reaction Progress” as the variable for the x axis, and “NaCl” for the y axis.Choose to plot “Mineral Saturation” to show the scatter data for saturation index ofthe mineral “Albite low”.
D.3 Xtplot
Xtplot can overlay scatter data points on all of the plot types, except the pie and barcharts. The first line in the table is a header that names each column. Examples:Length, Temperature, Carbon, Na+, etc. Enclose multiword names in quotes (e.g.,"Ionic strength", "Dissolved solids", etc).
Label the column as follows:
Components: Enter the component name (Ca++, SiO2(aq), etc.).
Minerals: Enter the mineral name as it appears in the Xtplot menus (Quartz,Kaolinite, etc.).
Species Concentration: Enter the species name in parenthesis following the word“molality” (molality(Na+), molality(NaSO4), etc.).
Species Activity: Enter the species name in parenthesis following the word “activity”(activity(Na+), activity(NaHCO3), etc.).
Species Activity Coefficients: Enter the species name in parenthesis followingthe word “gamma” (gamma(Na+), gamma(NaCl), etc.).
Elemental Composition: Enter the element name (Oxygen, Carbon, etc.).
Fugacities: Enter the name of the gas (CO2(g), Steam, etc.).
Mineral Saturation: Enter the mineral name in parenthesis following the word“logQoverK” (logQoverK(Albite), "logQoverK(Albite high)", etc.).
Sorbed Fractions: Enter the component name in parenthesis following the word“Xsorbed” (e.g., Xsorbed(Pb++)).
Chemical parameters and Physical parameters: Enter the variable name as itappears in the Xtplot menus (Eh, "Dissolved solids", etc.).
Label position and time as Length, Width, or Time.
An example of a table dataset to be used with Xtplot is
Time pH Zinc Sulfur-----------------------------------------------------------------------------.15 3.3 5 100.30 2.6 15 80
313
GWB Reference Manual
.50 6. n/d 20 # Sample 98-010
.55 4.3 0.1 45
To render these data, run X1t or X2t on a problem containing zinc and sulfur to producean “X1t_plot.xtp” or “X2t_plot.xtp” file. Start Xtplot and load the scatter dataset withFile ! Open ! Scatter Data. . . . From Plot ! XY Plot. . . choose to plot the elementalcomposition of the fluid versus time. (Similarly, if you had entered data in columnslabeled “Fe++” and “SO4–”, you would choose to plot components in the fluid.) Selectzinc, sulfur, or both, as variables to plot on the y axis.
Now, if you choose an appropriate unit for the y axis (�g/kg, mg/kg, g/kg, or wt%),the data points for the zinc and sulfur columns appear plotted against time. You maychoose another unit, such as molal concentration or grams, but you must first includein the scatter dataset columns for "Mass H2O" and "Mass solution" so that Xtplot canconvert the data from mg/kg to the plotting unit.
In “special” plots (Piper diagrams, etc.) showing the variable “HCO3 + CO3”, youshould enter a value in the scatter dataset for Carbonate alkalinity, in mg/kg as CaCO3,so that Xtplot can render the variable correctly. If you do not enter a value for alkalinity,the program will render the variable in terms of the reported HCO3 concentration, ifavailable, in which case the diagram produced will not account for the speciation ofcarbonate.
Alternatively, choose to plot “Chemical parameters” and set pH as the y axis variable.In this case, the scatter values for the column labeled pH appear on the plot. If scattervalues lie outside the plot axis ranges, touch Ctrl+Z.
A second example of a scatter dataset to be used with Xtplot is
Length Width activity(NaOH) logQoverK(NaBr)-----------------------------------------------------------------------------
2e4 2e4 5e-12 -124e4 4e4 6e-12 -106e4 6e4 7e-12 -68e4 8e4 8e-12 n/d
To render these data, run X1t or X2t on a problem containing sodium to produce a“X1t_plot.xtp” or “X2t_plot.xtp” file, start Xtplot, and load the dataset with File ! Open
! Scatter Data. . . . From Plot ! XY Plot. . . choose to plot “Species activities” andset “NaOH” as the yaxis variable. Select “X position” as the variable for the x axis.Choose to plot “Mineral Saturation” to show the scatter data for saturation index of“NaBr”. You must include both “Length” (X position) and “Width” (Y position) valuesto show the scatter data on a mapview plot.
You can choose to represent each sample (i.e., each line in the dataset) with a userdefined symbol. To assign symbols, append the symbol name to the line in question.In a similar fashion, you can assign the symbol’s color and point size. For example, ifyou enter a line
314
Scatter Data
210 12.5 110 red 24pt square
the corresponding data point will appear as a red, 24 point square. Choose fromamong colors shown on the Choose Color. . . dialog, enclosing multiword colors inquotes (e.g., "Cornflower blue"). To set marker point size, use fields like 15pt, 30pt,and so on.
You can further assign a default symbol to each column whose variable is plottedalong the y axis, as well as the symbol’s default color and point size. To do so, add aline to the table with symbol names (or a place holder such as “--”), symbol colors,or symbol sizes. Adding the lines
-- -- box cross-- -- blue red-- -- 12pt 16pt
to the first example in this section causes zinc concentration to be represented on aplot of elemental composition by 12 point blue boxes, and sulfur by 16 pt red crosses.The symbol specifications on the sample line will be used to represent each sample inall of the special plots. On an xy plot, you may choose whether to assign the symbol,its color, and its size according to the variable (by analyte) or the sample (by sample).
315
316
Appendix: Report Command
The “report” command returns the results calculated by a GWB program. The commandis available in programs Rxn, SpecE8, React, X1t, and X2t. After you have run theprogram (i.e., after you have selected Run ! Go, or otherwise triggered the calculation),you can use the “report” command to retrieve the program results.
You can use the “report” command from the Command pane as a way to explore thecalculation results interactively. More commonly, the command is used when writingcontrol scripts (see Control Scripts), or when invoking the programs with the pluginfeature (see Plugin Feature) or by remote control (see Remote Control), as a methodof transmitting calculation results to the script or controlling program. You might, forexample, type
report pH
on React’s Command pane. The program would respond with the most recentlycalculated value of pH. Typing the command
report options
shows a list of the keywords (i.e., pH in the example above) for the “report” commandavailable in the GWB program in use.
Enclose multiword arguments, such as species names, in quotes. For example,
report mass_reacted "Albite low"
To change the number of significant digits in the numerical results returned by the“report” command (from the default of four), type, for example
report set_digits 8
In X1t, you can specify the node of interest by typing
report set_node 5
317
GWB Reference Manual
for example. The command above tells the program to return values associated withthe node with index number 5. Similarly, in X2t, you might type
report set_node 8 8
giving first an xdirection, then ydirection index. Note that in Xt, node indices varyfrom 0 to the total number of nodes, less one. Indexing starts in the bottom left cornerof the domain and increases from left to right in the bottom row, then the next highestrow, and so on.
Depending on the keyword, the report command may return a simple value, severalvalues, or a whole vector of values. You can affect what is returned by using thearguments shown in boldface in the tables below. The “concentration” keyword is agood example.
concentration <type w/ optional argument> <name(s) | index>. . .types: related arguments:original <fluid | system | sorbed | stagnant>current <fluid | system | sorbed>aqueoussurfaceelements <fluid | system | sorbed | stagnant>minerals
Selecting from the list of types, you can enter a command such as
report concentration surface
which will cause the program to return a vector of values for all of the surface speciesin the system. You may modify the vector of values returned for the “original” or“current” basis or “elements” with one of the related arguments. For example, typing
report concentration original fluid
will return a vector of values for the fluid component of the original basis.The symbol . . . represents the possibility of entering within a report command a
number of arguments. For example, <name(s) j index>. . . means that if you type
report concentration current H+ Na+ Cl-
the program will return three values, one for each of the species listed. Typing
report concentration 0 1 2
will return three values, one for each of the first three species in the list of aqueousspecies. Note that list indices start with zero, not one.
318
Report Command
Referencing a list of species, elements, minerals and so on by index could bevaluable especially when invoking the programs with the plugin feature. For example,it would be possible to call a report command within a loop to return a value for eachaqueous species in this way:
report nspecies
to get the number of aqueous species,
report species
to get the list of the names of the aqueous species in order, then within the loop
report activity #
(where # is the loop index) to retrieve the activity of each species.To find the default unit, if any, for a “report” command, type
report get_default_units <keyword>
You can set the unit that you want values reported in. All subsequent reportcommands will try to use this unit to display returned values until it is reset. If theunit conversion fails, “ANULL” (999999) will be returned. Use “?” to resume using thedefault unit for each command. Use “get_units” to see the current unit, if set.
report set_units "mg/kg"report set_units ?report get_units
319
GWB Reference Manual
Keyword Arguments Description
activity <aqueous | surface>
<name(s) | index>...
Species’ activities
alkalinity Alkalinity
basis <original | current> <index>... Names of basis entries
biomass <reactant(s) | index>... Biomass concentration
boltzman <species | index>... Boltzman factors for surfacespecies
bulk_volume Bulk volume of nodal block
cat_area <reactant(s) | index>... Areas of catalyzing surfaces
charge <type> <name(s) | index>...
original | current | aqueous |surface
Chargeoncomponentsorspecies
chlorinity Chlorinity
coef_dispersion Coefficient of dispersion
concentration <type> <name(s) | index>...
original <fluid | system | sorbed| stagnant | colloid>
current <fluid | system | sorbed>
aqueoussurfaceelements <fluid | system | sorbed| stagnant | colloid>
minerals
Concentration of components,species, or elements
couples <index>... Names of redox couples
discharge Specific discharge
Deltat Length of current time step
EC Electrical conductivity
Eh <system | couples>
<name(s) | index>...
The system Eh or Nernst Ehvalues for redox couples
elements <index>... Names of elements
320
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
double 3 3 3 3
mg/kg sol’n as CaCO3 double 3 3 3 3
strings 3 3 3 3
mg/kg double 3 3 3
double 3 3 3 3
cm3 double 3 3 3 3
cm2 double 3 3 3
double 3 3 3 3
molal double 3 3 3 3
cm2/s double 3
molal double 3 3 3 3
strings 3 3 3 3
cm3/cm2 s double 3 3
s double 3 3 3
�S/cm or umho/cm double 3 3 3 3
volts double 3 3 3 3
strings 3 3 3 3
321
GWB Reference Manual
Keyword Arguments Description
equil_eqn Equilibrium equation as a textstring
equil_favors Whether reaction products orreactants are favored
equil_temp Equilibrium temperature
freeflowing Volume of freeflowing zone innodal block
FA <reactant(s) | index>... Kinetic factor for electonacceptance by microbes
FD <reactant(s) | index>... Kinetic factor for electondonation by microbes
fugacity <gas(es) | index>... Gas fugacities
gamma <aqueous | surface>
<name(s) | index>...
Species’ activity coefficients
gases <index>... Names of gases
get_default_units <keyword> Default unit for command
get_units Current unit, if set
hardness Hardness
hardness_carb Carbonate
hardness_ncarb Noncarbonate
hyd_pot Hydraulic potential
imbalance Charge imbalance
imbalance_error Error percentage
inert_volume Inert volume in system
IS or Tionst System ionic strength
logfO2 Log fugacity of O2
logk Log equilibrium constant
logks List of log K’s at principle temperatures
322
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
string 3
string 3
string 3
cm3 double 3 3 3 3
double 3 3 3
double 3 3 3
double 3 3 3 3
double 3 3 3 3
strings 3 3 3 3
string 3 3 3 3 3
string 3 3 3 3 3
mg/kg sol’n as CaCO3 double 3 3 3 3
mg/kg sol’n as CaCO3 double 3 3 3 3
mg/kg sol’n as CaCO3 double 3 3 3 3
bar double 3 3
eq/kg double 3 3 3 3
% error double 3 3 3 3
cm3 double 3 3 3 3
molal double 3 3 3 3
log fugacity double 3 3 3 3
double 3
double 3
323
GWB Reference Manual
Keyword Arguments Description
logQoverK or SI <minerals | reactants>
<name(s) | index>...
Saturation index for mineralsor reactants
mass <type> <name(s) | index>...
original <fluid | system | sorbed| stagnant | colloid>
current <fluid | system | sorbed>
aqueoussurfaceelements <fluid | system | sorbed| stagnant | colloid>
minerals
Mass of components, species,or elements
mass_reacted <reactant(s) | index>... Mass of a reactant that hasreacted
mass_remaining <reactant(s) | index>... Mass of a reactant remaining toreact
minerals <current | all> <index>... Names of minerals
mv <mineral(s) | index>... Mineral molar volume
mw <type> <name(s) | index>...
original | current | aqueous |surface | elements | minerals |gases
Mole weight of components,species, or elements
nbasis Number of basis entries
ncouples Number of redox couples
nelements Number of elements
ngases Number of gases
nlogks Number of log K values in list
nminerals <current | all> Number of minerals
Nnode Numberofnodalblocks indomain
nreactants Number of reactants, kinetic reactions
nsorbed Number of sorbed species
324
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
log Q=K double 3 3 3 3
moles double 3 3 3 3
moles double 3 3 3
moles double 3 3 3
strings 3 3 3 3
cm3/mol double 3 3 3 3
g/mol double 3 3 3 3
int 3 3 3 3
int 3 3 3 3
int 3 3 3 3
int 3 3 3 3
int 3
int 3 3 3 3
int 3 3
int 3 3 3
int 3 3 3 3
325
GWB Reference Manual
Keyword Arguments Description
nsorbing_surfaces Number of sorbing surfacetypes
nspecies Number of aqueous species
nsurf_species Number of surface species
Nx Number of nodes along x
Ny Number of nodes along y
options List of keywords for the reportcommand
pe <system | couples>
<name(s) | index>...
The system pe or theoreticalpe for redox couples
permeability Sediment permeability
pH System pH
polyfit Coefficients for polynomial fitof log K to temperature
porosity Porosity
pressure Pressure
PV Pore volumes displaced
QoverK <minerals | reactants>
<name(s) | index>...
Q/K for a mineral or reactant
rate_con <reactant(s) | index>... Rate constants for kinetic reactions
reactant_area <reactant(s) | index>... Surface areas of kinetic minerals
reactants <index>... Names of reactants and kineticreactions
reaction Chemical reaction as a textstring
rock_mass Mass of minerals in system orblock
rock_volume Volume of minerals in systemor block
326
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
int 3 3 3 3
int 3 3 3 3
int 3 3 3 3
int 3 3
int 3
strings 3 3 3 3 3
double 3 3 3 3
darcy � �m2 double 3 3 3 3
double 3 3 3 3
doubles 3
volume fraction double 3 3 3 3
bars double 3 3 3 3
double 3 3 3
double 3 3 3
(varies) double 3 3 3
cm2 double 3 3 3
strings 3 3 3
string 3
kg double 3 3 3 3
cm3 double 3 3 3 3
327
GWB Reference Manual
Keyword Arguments Description
rxn_rate <reactant(s) | index>... Reaction rates
set_digits <significant digits> Set number of significant digits in results
set_node <node index | x y> Results are associated with the nodeindex or the x and y node indices
set_units <unit | ?> Report results in a unit different thanthe default
SIS or Sionst Stoichiometric ionic strength
soln_density Solution density
soln_mass Solution mass
soln_viscosity Viscosity of fluid
soln_volume Volume of fluid
sorb_area <surface_type(s) | index>... Areas of sorbing surfaces
sorbed <index>... Names of sorbed species
sorbing_surfaces Names of sorbing surface types
species <index>... Names of aqueous species
stagnant Volume of stagnant zone in nodal block
success Returns a value of one if the GWBapplication has successfully completeda calculation, zero if it has not or if thelast calculation failed
surf_charge <surface_type(s) | index>... Electrical charge on sorbing surfaces
surf_potential <surface_type(s) | index>... Electrical potential of sorbing surfaces
surf_species <index>... Names of surface species
TDS Total dissolved solids
temperature or TC, Tempc Temperature
temps List of principle temperatures
Tend Final time of simulation
Time Current point in time
328
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
mol/kg s double 3 3 3
int 3 3 3 3 3
int 3 3
string 3 3 3 3 3
molal double 3 3 3 3
g/cm3 double 3 3 3 3
kg double 3 3 3 3
cp double 3 3 3 3
cm3 double 3 3 3 3
cm2 double 3 3 3 3
strings 3 3 3 3
strings 3 3 3 3
strings 3 3 3 3
cm3 double 3 3 3 3
int 3 3 3 3 3
�C/cm2 double 3 3 3 3
mV double 3 3 3 3
strings 3 3 3 3
mg/kg double 3 3 3 3
°C double 3 3 3 3
°C doubles 3
s double 3 3 3
s double 3 3 3
329
GWB Reference Manual
Keyword Arguments Description
TK Aboslute temperature
total_biomass Biomass in system or block
total_reacted Mass reacted into system or block
TPF <reactant(s) | index>... Thermodynamic potential factor
Tstart Beginning time of simulation
velocity Fluid velocity
Watact Activity of water
watertype Ion type of water
Wmass Water mass
xcoef_dispersion x coefficient of dispersion
xdischarge x specific discharge
Xfree Freeflowing fraction
Xi Reaction progress
xpermeability x permeability
xsorbed <name(s) | index>... Sorbed fraction of an original basisentry
xvelocity Fluid velocity along x
xycoef_dispersion xy coefficient of dispersion
ycoef_dispersion y coefficient of dispersion
ydischarge y specific discharge
ypermeability y permeability
yvelocity Fluid velocity along y
330
Report Command
Default units Return type Rxn SpecE8 React X1t X2t
K double 3 3 3 3
mg/kg double 3 3 3
g double 3 3 3
double 3 3 3
s double 3 3 3
cm/s double 3 3
double 3 3 3 3
string 3 3 3 3
kg double 3 3 3 3
cm2/s double 3
cm3/cm2 s double 3
double 3 3 3 3
double 3 3 3
darcy � �m2 double 3
double 3 3 3 3
cm/s double 3
cm2/s double 3
cm2/s double 3
cm3/cm2 s double 3
darcy � �m2 double 3
cm/s double 3
331
332
Appendix: Control Scripts
When you read an ordinary script in one of the GWB applications (Rxn, Act2, Tact,SpecE8, React, X1t, or X2t), the application steps through the script linebyline,executing the commands encountered, until it reaches the script’s end. A controlscript differs from an ordinary script in that it can contain control statements, such asassignments, loops, and ifthenelse constructs.
This appendix describes how to set up a control script and gives an example of sucha script. The Multiple Analyses appendix to this guide shows a further example ofhow control scripts can be applied, in this case to add the results of GWB calculationsto a spreadsheet containing the results of a number of chemical analyses.
A control script can occupy an entire script file, or just a portion of one. The controlscript is preceded by the statement
script
The control script terminates at the end of the file, or with the statement
script end
The lines within the control script may be either application commands (e.g., commandsrecognized by React) or control statements.
When writing file names within control scripts, following Tcl syntax, you use doublerather than single backslashes (i.e., “\\” instead of “\”) as separators. In addition, youenclose filenames containing spaces or special characters with braces (“{. . . }”). Forexample, the application commands
read GWB\react.readata "c:\Program Files\GWB\gtdata\thermo.data"
would appear as
read GWB\\react.readata {"c:\\Program Files\\GWB\\gtdata\\thermo.data"}
within a control script.
333
GWB Reference Manual
F.1 Control statements
The applications recognize control statements in the form of Tcl commands. Tcl(pronounced “tickle”) is an opensource scripting language, designed to be easy tolearn and use. You can find information about the Tcl syntax on various web sitessuch as www.tcl.tk and mini.net/tcl, as well as a number of widely available textbooks(you can search on “Tcl” at www.amazon.com).
In Tcl, you define a variable with the “set” command, and use a “$” in front of thevariable name to reference its value. For example, the commands
set pH 4.5set label "The pH is"puts "$label $pH"
assign a value of 4.5 to a variable named “pH” and a literal string to variable “label”,and then write them to the screen using the “puts” command.
Other useful commands include
for Define a loop
while Define a loop
eval Evaluate a command
expr Evaluate an expression
if {...} Set an ifthenelse blockelseif {...}
else
proc Define a procedure
open Open a file
close Close a file
gets Get input from a file or prompt
puts Output data to a file or prompt
info commands List Tcl commands
If you write procedures (using the “proc” command), you should be careful not toname them using GWB keywords, or the names of species in the thermo dataset.For example, if you were to name a procedure “Fe++”, you would no longer be ableto constrain the concentration of ferrous iron.
Before beginning to write a command script, you will want to consult a more completeTcl reference to learn a few details of the language syntax.
F.2 Interacting with the application program
You can use the Tcl “eval” command to construct a GWB command and execute itwithin the GWB application. In a React control script, for example, the Tcl command
eval {"pH =" $value}
334
Control Scripts
causes pH in the React run to be set to the contents of variable “value”.You can interrogate the GWB application program about its calculation results using
the “report” command. For example, once you have calculated a geochemical modelusing React, the commmand
report pH
returns the predicted pH. You can set the value of a variable “new_pH” in a commandscript to this value with the Tcl command
set new_pH [eval report pH]
F.3 Example control script
The following control script uses program React to search for the rate constant thatdescribes the results of a hydrothermal experiment. In the experiment, 1 kg of waterwith an initial silica concentration of 1 mg/kg reacts at 100°C with 5000 g of quartz.
After 5 days, the silica concentration is observed to be .55 mmolal. The scriptsearches for a rate constant in the range 10�16 to 10�14 mol/cm2 sec that explainsthis result. In the script, React commands are shown in bold face, for clarity, whereasTcl commands are shown in normal typeface.
time begin = 0 days, end = 5 daysT = 100SiO2(aq) = 1 mg/kgreact 5000 g Quartzkinetic Quartz surface = 1000
script startproc find_ratecon {low high species conc} {
set gotit 0for {set i 0} {$i < 50} {incr i 1} {
set test [expr {($low + $high) / 2}]eval {kinetic Quartz rate_con = $test}goset back [eval report molality $species]if {[expr {abs($back - $conc)}] < 1e-6} {
set gotit 1break
}if {$back < $conc} {
set low $test} else {set high $test}
}if {$gotit} {
335
GWB Reference Manual
puts "The optimum rate constant is $test mol/cm2 s"puts "The control script converged in $i iterations"
} else {puts "The control script did not converge"
}}# Find the rate constant for Quartz dissolution that gives a# SiO2(aq) concentration of .00055 molal after 5 days.find_ratecon 1e-16 1e-14 "SiO2(aq)" .00055script end
F.4 Tcl license agreement
GWB control scripts are evaluated according to the Tcl scripting language, using opensource software distributed under the following license agreeement:
This software is copyrighted by the Regents of the University of California, SunMicrosystems, Inc., Scriptics Corporation, and other parties. The following terms applyto all files associated with the software unless explicitly disclaimed in individual files. Theauthors hereby grant permission to use, copy, modify, distribute, and license this softwareand its documentation for any purpose, provided that existing copyright notices areretainedinallcopiesandthatthisnoticeis includedverbatiminanydistributions.Nowrittenagreement, license, or royalty fee is required for any of the authorized uses. Modificationsto this software may be copyrighted by their authors and need not follow the licensingtermsdescribedhere,provided that thenewtermsare clearly indicated onthefirstpageofeach file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORSBE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITSDOCUMENTATION,ORANYDERIVATIVESTHEREOF,EVENIFTHEAUTHORSHAVEBEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS ANDDISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUTNOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THIS SOFTWAREIS PROVIDED ON AN “AS IS” BASIS, AND THE AUTHORS AND DISTRIBUTORSHAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiringthis software on behalf of the U.S. government, the Government shall have only“Restricted Rights” in the software and related documentation as defined in the FederalAcquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring thesoftware on behalf of the Department of Defense, the software shall be classified as“Commercial Computer Software” and the Government shall have only “RestrictedRights” as defined in Clause 252.2277013 (c) (1) of DFARs. Notwithstanding theforegoing, the authors grant the U.S. Government and others acting in its behalfpermission to use and distribute the software in accordance with the terms specifiedin this license.
336
Appendix: Plugin Feature
The GWB plugin feature is implemented as a DynamicLink Library (DLL). For easeof use, GWB provides wrapper classes for C++, Fortran, Java, Perl, and Python thathandle loading the DLL, binding to the needed functions, and conversion to C datatypes. You might create your own wrapper for the plugin feature in other languages.
You can plugin the capabilities of Rxn, SpecE8, React, X1t, and X2t to a programthat you write using the GWB plugin feature.
In writing a program of your own, for example, you might need to determine thesaturation state of calcite in a fluid of arbitrary composition. Instead of developingcode to calculate the distribution of mass and mineral saturation states in a fluid, youcould use SpecE8 from within your program to do the work for you.
Similarly, you could use the plugin feature to balance reactions with Rxn, or figurethe results of irreversible reaction paths with React.
In each case, you would configure the GWB plugin with text commands, triggerthe calculation with a “go” command, and then retrieve the calculation results to usefor your own purposes.
You transfer the results from the GWB plugin with the “results” function, an interfacefor the “report” command (documented in the Report Command appendix to this GWB
Reference Manual).You may also simply read datasets, such as “SpecE8_output.txt”, produced by the
GWB applications, into your program.The following sections describe and give examples of how to take advantage of the
plugin feature when developing your software with specific languages and compilers.
337
GWB Reference Manual
I.1 C++
GWB provides a GWBplugin wrapper class contained in the header file “GWBplugin.h”,and the GWBplugin.dll export library “GWBplugin.lib” to link to. These are installed inthe “src” subdirectory of the GWB installation directory. In order to locate the GWBDLLs the GWBplugin class uses, you must add the GWB installation directory to thePATH environment variable.
This is the C++ wrapper class provided in GWBplugin.h:
// GWBplugin.h
#define ANULL -999999.0 // marker for an undefined value
class GWBplugin {public:
GWBplugin();~GWBplugin();int initialize(const char* app_name, const char* file_name = NULL,
const char* cmds = NULL);int exec_cmd(char* uline);int results(void* data, const char* value, const char* units = NULL,
int ix = 0, int jy = 0);};
I.1.1 Initializing the GWB application
Within your code, first create a GWBplugin object.
#include "GWBplugin.h"
GWBplugin myPlugin;
Next, use the “initialize” function to start the GWB application of interest by passingthe application name, an optional output file name, and any commandline typearguments. The “initialize” function must be called before calling any of the otherfunctions.
int initialize (const char* app_name,const char* file_name = NULL,const char* cmds = NULL
);
Parameters:app_name
338
Plugin Feature
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional)
String containing the name of the file you want the GWB output written to. Thiscan be NULL or an empty string if you do not want the output to be written to a file.cmds (optional)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be NULL or an empty string.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
Nonzero on success and zero on failure.Examples
Some examples of how to start the GWB plugin in various ways:
// plug-in SpecE8 with no output written and no command-line optionsint success = myPlugin.initialize("spece8");
// plug-in React with output written to output.txt and no command-line optionsint success = myPlugin.initialize("react", "output.txt");
// plug-in X1t with no output written, no working directory change,// and input read from pb_contam.x1tint success = myPlugin.initialize("x1t", NULL, "-nocd
-i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"");
I.1.2 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
int exec_cmd (char* uline // command string to be sent to the GWB application
);
339
GWB Reference Manual
Return value
Nonzero on success and zero on failure.Examples
myPlugin.exec_cmd("3 mmol H+");myPlugin.exec_cmd("2 mmol Ca++");myPlugin.exec_cmd("5 mmolar Cl-");myPlugin.exec_cmd("go"); // trigger the calculation
I.1.3 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”function. The keywords, arguments, default units, and return types are the same asthose listed in the table in the Report Command chapter of this reference manual.
To use the “results” function, you provide the address of a data block to fill, alongwith the report command and keywords, optional desired units, and the node locationof choice (X1t and X2t only).
int results(void* data,const char* value,const char* units = NULL,int ix = 0,int jy = 0
);
Parameters:data
Address of data block to fill. This can be NULL to determine data block size.value
String containing the report command keyword and arguments.units (optional)
String containing the units you want the results returned in. This can be NULL oran empty string if you want the results returned in the default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
The number of values written (or to be written) to the data block.Remarks
To determine the size of data block you will need, first call this function with thedata parameter as NULL and with the rest of the parameters filled. If you know thatthe report command you are using only returns a single value, you can simply passa pointer to the correct data type. See the Report Command chapter for details ondata types and available keywords.
340
Plugin Feature
Examples
// get aqueous species namesint ndata = myPlugin.results(NULL, "species");char** Species = new char*[ndata];myPlugin.results(Species, "species");
// get aqueous species concentrations in mg/kgdouble* Conc = new double[ndata];myPlugin.results(Conc, "concentration aqueous", "mg/kg");
// get pH at node 3,5double pH = ANULL;myPlugin.results(&pH, "pH", NULL, 3, 5);
If the command fails for any reason, for example if the requested data doesn’t existor the specified unit conversion failed, the data will be filled with ANULL (999999.0).
I.1.4 C++ code examples using the plugin feature
Normally you would use the GWB plugin within your program with no output beingwritten to a file. The following is an example of this:
#include "C:/Program Files/Gwb/src/GWBplugin.h"
int main(int argc, char* argv[ ]){
// create the plug-in objectGWBplugin* myGWBrun = new GWBplugin();
// start the GWB programif (myGWBrun->initialize("spece8", NULL, "-nocd")) { // started successfully
printf("Beginning run.\n");// configure SpecE8 and trigger calculationchar* cmds[3] = {"pH = 8", "molality Cl- = .05", "go"};for(int i = 0; i < 3; i++)
myGWBrun->exec_cmd(cmds[i]);printf("Finished run.\n\n");
// retrieve resultsdouble pH;myGWBrun->results(&pH, "pH");
double Cl;myGWBrun->results(&Cl, "concentration Cl-"); // in default unitsprintf("concentration of Cl- in molal is %10.4g\n", Cl);myGWBrun->results(&Cl, "concentration Cl-", "mg/kg"); // in different units
341
GWB Reference Manual
printf("concentration of Cl- in mg/kg %10.4g\n", Cl);
// get size of dataint nspec = myGWBrun->results(NULL, "species");
// create data blocksconst char** Name = new const char*[nspec];double* Spec = new double[nspec];
// send data pointer with keyword and argumentsmyGWBrun->results(Name, "species");myGWBrun->results(Spec, "concentration aqueous", "mg/kg");
printf("\n There are %d aqueous species\n\n", nspec);for(int i = 0; i < nspec; i++)
printf("%-4s = %10.4g mg/kg\n", Name[i], Spec[i]);
delete[ ] Name;delete[ ] Spec;
}else {
// handle failure to start within your program}delete myGWBrun;return 0;
}
To familiarize yourself with the plugin feature, you might want the GWB program’snormal output and results to be written to the console and to text files. The followingcode shows examples of this:
#include "C:/Program Files (x86)/Gwb/src/GWBplugin.h"#include <stdio.h>
int main(int argc, char* argv[ ]){
fprintf(stdout, "Starting program SpecE8\n");
GWBplugin* myGWBrun = new GWBplugin();
if (myGWBrun->initialize("spece8","test_output.txt","-nocd -i \"C:/Program Files (x86)/Gwb/Script/Freshwater.sp8\"-s \"C:/Program Files (x86)/Gwb/Gtdata/FeOH.sdat\""))
{ // started successfully
fprintf(stdout, "writing output to test_output.txt\n");
342
Plugin Feature
myGWBrun->exec_cmd("show surfaces"); // write to output file
fprintf(stdout, "Executing test\n");
FILE *fp;if ((fp=fopen("test_results.txt", "w")) == NULL) {
fprintf(stderr, "can't open test_results.txt\n");}else {
fprintf(stdout, "writing results to test_results.txt\n");
char* cmds[3] = {"pH = 8", "molality Cl- = .05", "go"};for(int i = 0; i < 3; i++)
myGWBrun->exec_cmd(cmds[i]);
double pH;myGWBrun->results(&pH, "pH");fprintf(fp, "pH = %4.1f\n", pH);
double Cl;myGWBrun->results(&Cl, "concentration Cl-");fprintf(fp, "Cl = %12.5e molal\n", Cl);
myGWBrun->results(&Cl, "concentration Cl-", "mg/kg");if(Cl != ANULL)
fprintf(fp, "Cl = %12.5e mg/kg\n\n", Cl);else
fprintf(fp, "unit conversion failed - Cl = ANULL\n\n");
int nspec = myGWBrun->results(NULL, "species");const char** Name = new const char*[nspec];double* Spec = new double[nspec];
if (myGWBrun->results(Name, "species")) {if (myGWBrun->results(Spec, "concentration aqueous")) {
for (int i = 0; i < nspec; i++)fprintf(fp, "%-32s %12.5e molal\n", Name[i], Spec[i]);
}if (myGWBrun->results(Spec, "concentration aqueous", "mg/kg")) {
for (int i = 0; i < nspec; i++)fprintf(fp, "%-32s %12.5e mg/kg\n", Name[i], Spec[i]);
}}
if (fp)fclose(fp);
343
GWB Reference Manual
delete[ ] Name;delete[ ] Spec;
}}else
fprintf(stderr, "SpecE8 failed to start\n");
delete myGWBrun;
fprintf(stdout, "press return to exit> ");getchar();
return 0;}
I.1.5 C++ compiling and linking
The GWB plugin has been tested on C++ compilers from Microsoft, Intel, and GCC.The version of the compiler you are using must be the same as the version of GWBinstalled (32bit vs. 64bit).
To compile the GWBplugin Example1 on the command line with the Microsoft orIntel compiler, follow these steps:
// open the Microsoft Visual Studio or Intel Command Prompt
// create a working folder and change to that foldermkdir "%homepath%\GWBplugin"cd "%homepath%\GWBplugin"
// copy the "src" folder from GWB installation (default install path shown)copy /Y "C:\Program Files (x86)\GWB\src"
// add the GWB installation folder to your pathset path=C:\Program Files (x86)\GWB;%path%
// compile the example file and tell the compiler to use the GWBplugin librarycl GWBplugin_Cpp_Example1.cpp GWBplugin.lib // Microsoft// oricl GWBplugin_Cpp_Example1.cpp GWBplugin.lib // Intel
// run the example programGWBplugin_Cpp_Example1.exe
To compile the GWBplugin Example1 on the command line with MinGW, MSYS,and g++, follow these steps:
344
Plugin Feature
// launch the MinGW shell
// create a working folder and change to that foldermkdir -p ~/GWBplugincd ~/GWBplugin
// copy the "src" folder from GWB installation (default install path shown)cp /c/program\ files\ \(x86\)/gwb/src/* .
// add the GWB installation folder to your pathPATH=/c/program\ files\ \(x86\)/gwb:$PATH
// compile the example file and tell the compiler to use the GWBplugin libraryg++ GWBplugin_Cpp_Example1.cpp GWBplugin.lib -o
GWBplugin_Cpp_Example1.exe // all on one line
// run the example program./GWBplugin_Cpp_Example1.exe
To compile the GWBplugin Example1 in Microsoft Visual Studio, follow these steps:
// open Visual Studio
// create a new project (Ctrl+Shift+N)
// select the "Visual C++" project type and use the "Empty Project" template
// select Project->Add Existing Item... (Shift+Alt+A)// browse to the "src" subfolder of the GWB installation, select the// "GWBplugin_Cpp_example1.cpp" file and click "Add"
// open Project->Properties->Configuration Properties
// 64-bit only:// select Configuration Manager...-> <New...>-> x64-> OK
// next to Configuration: select "All configurations"
// next to Platform: select Win32 for 32-bit builds or x64 for 64-bit builds
// under Configuration Properties->
// C/C++->General->Additional Include Directories -// add the GWB installation "src" folder// "c:\program files (x86)\gwb\src"
// Linker->Input->Additional Dependencies -
345
GWB Reference Manual
// add the GWBplugin.lib library// "c:\program files (x86)\gwb\src\gwbplugin.lib"
// Debugging->Environment -// add the GWB install folder to the path// path=%path%;c:\program files (x86)\gwb
// build using Build->Build Solution
// run using Debug->Start Without Debugging
Note: If you need to debug your program you must attach a debugger after the"initialize" call to GWBplugin. A good way to do this is to put in a getchar() call thatwill pause the program until you can attach the debugger.
346
Plugin Feature
I.2 Fortran
GWB provides a Fortran interface, “GWBplugin.f90”, and the GWBplugin.dll exportlibrary “GWBplugin.lib” to link to. These are installed in the “src” subdirectory of theGWB installation directory. The GWB plugin has been tested on Fortran compilersfrom Intel and GCC. The version of the compiler you are using must be the same asthe version of GWB installed (32bit vs. 64bit).
This is the Fortran wrapper interface provided in GWBplugin.f90:
// GWBplugin.f90
MODULE GWBpluginModule
INTEGER, PARAMETER :: ANULL = -999999 ! marker for undefined valueINTEGER, PARAMETER :: GWB_MAX_RESPONSE = 32
TYPE GWBplugin
FUNCTION initialize(plugin, app_name, file_name, cmds) RESULT(retval)TYPE(GWBplugin), INTENT(out), TARGET :: pluginCHARACTER(LEN = *), INTENT(in) :: app_nameCHARACTER(LEN = *), INTENT(in), OPTIONAL :: file_name, cmdsINTEGER(C_INT) :: retval
FUNCTION exec_cmd(plugin, uline) RESULT(retval)TYPE(GWBplugin), INTENT(in), TARGET :: pluginCHARACTER(LEN = *), INTENT(in) :: ulineINTEGER(C_INT) :: retval
FUNCTION results(plugin, f_data, f_value, f_units, ix, jy) RESULT(retval)TYPE(GWBplugin), INTENT(in), TARGET :: plugin! f_data :
CHARACTER(LEN = GWB_MAX_RESPONSE), INTENT(out),OPTIONAL :: f_data(:)
!orREAL(8), INTENT(out), OPTIONAL :: f_data(:)
!orINTEGER, INTENT(out), OPTIONAL :: f_data(:)
CHARACTER(LEN = *), INTENT(in) :: f_valueCHARACTER(LEN = *), INTENT(in), OPTIONAL :: f_unitsINTEGER, INTENT(in), OPTIONAL :: ix, jyINTEGER(C_INT) :: retval
SUBROUTINE destroy(plugin)TYPE(GWBplugin), INTENT(in), TARGET :: plugin
347
GWB Reference Manual
I.2.1 Initializing the GWB application
Within your code, first create a GWBplugin object.
INCLUDE "GWBplugin.f90"
USE GWBpluginModuleTYPE(GWBplugin) :: myPlugin
Next, use the “initialize” function to start the GWB application of interest by passingthe application name, an optional output file name, and any commandline typearguments.
FUNCTION initialize(plugin, app_name, file_name, cmds) RESULT(retval)TYPE(GWBplugin), INTENT(out), TARGET :: pluginCHARACTER(LEN = *), INTENT(in) :: app_nameCHARACTER(LEN = *), INTENT(in), OPTIONAL :: file_name, cmdsINTEGER(C_INT) :: retval
Parameters:plugin
An instance of type GWBplugin.app_name
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional)
String containing the name of the file you want the GWB output written to. Thiscan be an empty string if you do not want the output to be written to a file.cmds (optional)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be an empty string.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
Nonzero on success and zero on failure.Examples
Some examples of how to start the GWB plugin in various ways:
348
Plugin Feature
INTEGER :: success
! plug-in SpecE8 with no output written and no command-line optionssuccess = initialize(myPlugin, "spece8")
! plug-in React with output written to output.txt and no command-line optionssuccess = initialize(myPlugin, "react", "output.txt")
! plug-in X1t with no output written, no working directory change,! and input read from pb_contam.x1tsuccess = initialize(myPlugin, "x1t", "",&
'-nocd -i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"')
Function "destroy" is used at the end of the program to free up the underlying memoryassociated with the GWBplugin object.
CALL destroy(myPlugin)
I.2.2 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
FUNCTION exec_cmd(plugin, uline) RESULT(retval)TYPE(GWBplugin), INTENT(in), TARGET :: pluginCHARACTER(LEN = *), INTENT(in) :: uline ! command string to be sent
! to the GWB applicationINTEGER(C_INT) :: retval
Return value
Nonzero on success and zero on failure.Examples
err = exec_cmd(myPlugin, "3 mmol H+")err = exec_cmd(myPlugin, "2 mmol Ca++")err = exec_cmd(myPlugin, "5 mmolar Cl-")err = exec_cmd(myPlugin, "go") ! trigger the calculation
I.2.3 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”function. The keywords, arguments, default units, and return types are the same asthose listed in the table in the Report Command chapter of this reference manual.
349
GWB Reference Manual
To use the “results” function, you provide the address of a data block to fill, alongwith the report command and keywords, optional desired units, and the node locationof choice (X1t and X2t only).
FUNCTION results(plugin, f_data, f_value, f_units, ix, jy) RESULT(retval)TYPE(GWBplugin), INTENT(in), TARGET :: plugin! f_data :
CHARACTER(LEN = GWB_MAX_RESPONSE), INTENT(out),OPTIONAL :: f_data(:)
!orREAL(8), INTENT(out), OPTIONAL :: f_data(:)
!orINTEGER, INTENT(out), OPTIONAL :: f_data(:)
CHARACTER(LEN = *), INTENT(in) :: f_valueCHARACTER(LEN = *), INTENT(in), OPTIONAL :: f_unitsINTEGER, INTENT(in), OPTIONAL :: ix, jyINTEGER(C_INT) :: retval
Parameters:plugin
An instance of type GWBplugin.f_data
Address of data block to fill, omit it to find the size of data block needed.f_value
String containing the report command keyword and arguments.f_units (optional)
String containing the units you want the results returned in. This can be an emptystring if you want the results returned in the default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
The number of values written (or to be written) to the data block.Remarks
To determine the size of data block you will need, first call this function with thedata parameter omitted and with the rest of the parameters filled. If you know that thereport command you are using only returns a single value, you can simply pass anarray of size 1 of the correct data type. See the Report Command chapter for detailson data types and available keywords.Examples
! get aqueous species namesINTEGER :: nspecnspec = results(myPlugin, "species");CHARACTER(LEN=GWB_MAX_RESPONSE), ALLOCATABLE :: Species(:)
350
Plugin Feature
ALLOCATE(Species(nspec))results(myPlugin, Species, "species")
! get aqueous species concentrations in mg/kgREAL(8), ALLOCATABLE :: Conc(:)ALLOCATE(Conc(nspec))results(myPlugin, Conc, "concentration aqueous", "mg/kg")
! get pH at node 3,5REAL(8) :: pH(1)results(myPlugin, pH, "pH", "", 3, 5)
A named constant with the maximum size of strings output by the “results” commandis declared in the module:
INTEGER, PARAMETER :: GWB_MAX_RESPONSE = 32
If the command fails for any reason, for example if the requested data doesn’texist or the specified unit conversion failed, the data block will be filled with ANULL(999999).
I.2.4 Fortran code examples using the plugin feature
The following are Fortran code examples that do the same things as the C++ codeexamples above. This is a code example using the GWB plugin within your programwith no output being written to a file:
INCLUDE "C:\Program Files (x86)\Gwb\src\GWBplugin.f90"
PROGRAM FortranPlugin_Example1USE GWBpluginModuleIMPLICIT NONE
INTEGER :: nspec, err, iTYPE(GWBplugin) :: myGWBrunCHARACTER (LEN=GWB_MAX_RESPONSE), ALLOCATABLE :: Name(:)REAL(8), ALLOCATABLE :: Spec(:)REAL(8) :: pH(1), Cl(1)CHARACTER(LEN=255), dimension(3), PARAMETER :: &
cmds = [character(len=255) :: &"pH = 8", "molality Cl- = .05", "go"]
! create and start the GWB programIF (initialize(myGwbrun, "spece8", "", "-nocd") /= 0) THEN
! started successfully
WRITE(*,*) "Beginning run."
351
GWB Reference Manual
! configure SpecE8 and trigger calculationDO i = 1, 3
err = exec_cmd(myGwbrun, cmds(i))END DO
WRITE(*,*) "Finished run."WRITE(*,*)
! retrieve resultserr = results(myGwbrun, pH, "pH")err = results(myGwbrun, Cl, "concentration Cl-")WRITE(*,'("concentration of Cl- in molal is ", G10.3)') Clerr = results(myGwbrun, Cl, "concentration Cl-", "mg/kg")WRITE(*,'("concentration of Cl- in mg/kg is ", G10.3)') ClWRITE(*,*)
! get size of datanspec = results(myGwbrun, "species");WRITE(*,'(There are", I2, " aqueous species")') nspecWRITE(*,*)
! create data blocksALLOCATE(Name(nspec))ALLOCATE(Spec(nspec))
! send data pointer with keyword and argumentserr = results(myGwbrun, Name, "species")err = results(myGwbrun, Spec, "concentration aqueous", "mg/kg")
DO i = 1, nspecWRITE(*,'(A4, " = ", G10.3, " mg/kg")') Name(i), Spec(i)
END DOWRITE(*,*)
! use the data in your program
DEALLOCATE(Name)DEALLOCATE(Spec)
ELSE! handle failure to start within your program
END IF
CALL destroy(myGwbrun)
END PROGRAM FortranPlugin_Example1
352
Plugin Feature
Code example with the GWB application’s normal output and results written to theconsole or to text files:
INCLUDE "C:\Program Files (x86)\Gwb\src\GWBplugin.f90"
PROGRAM FortranPlugin_Example2USE GWBpluginModuleIMPLICIT NONE
INTEGER :: nspec, err, iTYPE (GWBplugin) :: myGWBrunCHARACTER (LEN=GWB_MAX_RESPONSE), ALLOCATABLE :: Name(:)REAL(8), ALLOCATABLE :: Spec(:)REAL(8) :: pH(1), Cl(1)CHARACTER(LEN=255), dimension(3), PARAMETER :: &
cmds = [character(len=255) :: &"pH = 8", "molality Cl- = .05", "go"]
CHARACTER :: a
WRITE(*,*) "Starting program SpecE8"
IF (initialize(myGwbrun, "spece8" , "test_output.txt",&'-nocd -i "C:/Program Files (x86)/Gwb/Script/Freshwater.sp8"&&-s "C:/Program Files (x86)/Gwb/Gtdata/FeOH.sdat"') /= 0) THEN
err = exec_cmd(myGwbrun, "show surfaces")
WRITE(*,*) "Executing Test"
OPEN(10, file = 'test_results.txt')WRITE(*,*) "Writing results to test_results.txt"
DO i = 1, 3err = exec_cmd(myGwbrun, cmds(i))
END DO
err = results(myGwbrun, pH, "pH")WRITE(10, '("pH = ", F4.1)') pH
err = results(myGwbrun, Cl, "concentration Cl-")WRITE(10, '("Cl = ", ES12.5, " molal")') Cl
err = results(myGwbrun, Cl, "concentration Cl-", "mg/kg")
IF (err /= ANULL) THENWRITE(10, '("Cl = ", ES12.5, " mg/kg")') Cl
ELSEWRITE(10,*) "unit conversion failed - CL = ANULL"
353
GWB Reference Manual
END IF
WRITE(10,*)
nspec = results(myGwbrun, "species");
ALLOCATE(Name(nspec))ALLOCATE(Spec(nspec))
IF (results(myGwbrun, Name, "species") /= 0) THENIF (results(myGwbrun, Spec, "concentration aqueous") /= 0) THEN
DO i = 1, nspecWRITE(10, '(A32, ES12.5, " molal")') Name(i), Spec(i)
END DOEND IF
WRITE(10,*)WRITE(10,*)
IF (results(myGwbrun, Spec, "concentration aqueous", "mg/kg") /= 0) THENDO i = 1, nspec
WRITE(10, '(A32, ES12.5, " mg/kg")') Name(i), Spec(i)END DO
END IFEND IF
CLOSE(10)
DEALLOCATE(Name)DEALLOCATE(Spec)
END IF
CALL destroy(myGwbrun)
WRITE(*,*) "enter any letter to exit> "READ(*,*) a
END PROGRAM FortranPlugin_Example2
I.2.5 Fortran compiling
The GWB plugin has been tested on Fortran compilers from Intel and GCC. Theversion of the compiler you are using must be the same as the version of GWBinstalled (32bit vs. 64bit).
To compile the GWBplugin Example1 on the command line with Intel’s Fortrancompiler, follow these steps:
354
Plugin Feature
! open the Intel Command Prompt
! create a working folder and change to that foldermkdir "%homepath%\GWBplugin"cd "%homepath%\GWBplugin"
! copy the "src" folder from GWB installation (default install path shown)copy /Y "C:\Program Files (x86)\GWB\src"
! add the GWB installation folder to your pathset path=C:\Program Files (x86)\GWB;%path%
! compile the example file and tell the compiler to use the GWBplugin libraryifort GWBplugin_Fortran_Example1.f90 GWBplugin.lib
! run the exampleGWBplugin_Fortran_Example1.exe
To compile the GWBplugin Example1 on the command line with MinGW, MSYS,and gfortran, follow these steps:
! launch the MinGW Shell
! create a working folder and change to that foldermkdir -p ~/GWBplugincd ~/GWBplugin
! copy the "src" folder from GWB installation (default install path shown)cp /c/program\ files\ \(x86\)/gwb/src/* .
! add the GWB installation folder to your pathPATH=/c/program\ files\ \(x86\)/gwb:$PATH
! compile the example file and tell the compiler to use the GWBplugin librarygfortran GWBplugin_Fortran_Example1.f90 GWBplugin.lib -o
GWBplugin_Fortran_Example1.exe ! all on one line
! run the example./GWBplugin_Fortran_Example1.exe
To compile the GWBplugin Example1 in Microsoft Visual Studio with Intel’s Fortrancompiler, follow these steps:
! open Visual Studio
! create a new project (Ctrl+Shift+N)
355
GWB Reference Manual
! select the "Intel(R) Visual Fortran" project type,! select "Console Application", and use the "Empty Project" template
! select Project->Add Existing Item... (Shift+Alt+A)! browse to the "src" subfolder of the GWB installation,! select the "GWBplugin_Fortran_example1.f90" file and click "Add"
! open Project->Properties->Configuration Properties
! 64-bit only:! select Configuration Manager...-> <New...>-> x64-> OK
! next to Configuration: select "All configurations"
! next to Platform: select Win32 for 32-bit builds or x64 for 64-bit builds
! under Configuration Properties->
! Fortran->General->Additional Include Directories -! add the GWB installation "src" folder! "c:\program files (x86)\gwb\src"
! Linker->Input->Additional Dependencies -! add the GWBplugin.lib library! "c:\program files (x86)\gwb\src\gwbplugin.lib"
! Debugging->Environment -! add the GWB install folder to the path! path=%path%;c:\program files (x86)\gwb
! build using Build->Build Solution
! run using Debug->Start Without Debugging
Note: If you need to debug your program you must attach a debugger after the"initialize" call to GWBplugin, otherwise your program will encounter a runtime error.
356
Plugin Feature
I.3 Java
GWB provides a GWBplugin wrapper class contained in the file “GWBplugin.java”,the already compiled JAR file “GWBplugin.jar”, and the GWBplugin.dll export library“GWBplugin.lib” to link to. These are installed in the “src” subdirectory of the GWBinstallation directory. In order to locate the GWB DLLs the GWBplugin class uses,you must add the GWB installation directory to the PATH environment variable.
To compile your program you will need to have a Java Development Kit (JDK)installed. The version of the Java virtual machine must match the version of GWBinstalled (32bit vs. 64bit). For loading the DLL and conversion to C data types,the GWBplugin class depends on the Java Native Access library (JNA). If you don’talready have this library installed it can be obtained from java.net. Both GWBplugin.jarand the JAR file for JNA need to be added to your CLASSPATH.
// GWBplugin.java
package GWBplugin;
import com.sun.jna.*;import com.sun.jna.ptr.PointerByReference;
This is the Java wrapper class provided by GWBplugin.jar in the “src” subdirectoryof the GWB installation directory:
public class GWBplugin {
static public double ANULL = -999999;
public GWBplugin();public int initialize(String app_name, String file_name = null,
String cmds = null);public int exec_cmd(String uline);public int results(Object data, String value, String units = null,
int ix = 0, int jy = 0);public void destroy();
}
I.3.1 Initializing the GWB application
Within your code, first create a GWBplugin object.
import GWBplugin.GWBplugin;
GWBplugin myPlugin = new GWBplugin();
357
GWB Reference Manual
Next, use the “initialize” function to start the GWB application of interest by passingthe application name, an optional output file name, and any commandline typearguments. The “initialize” function must be called before calling any of the otherfunctions.
public int initialize (String app_name,String file_name = null,String cmds = null
);
Parameters:app_name
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional)
String containing the name of the file you want the GWB output written to. Thiscan be null or an empty string if you do not want the output to be written to a file.cmds (optional)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be null or an empty string.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
Nonzero on success and zero on failure.Examples
Some examples of how to start the GWB plugin in various ways:
// plug-in SpecE8 with no output written and no command-line optionsint success = myPlugin.initialize("spece8");
// plug-in React with output written to output.txt and no command-line optionsint success = myPlugin.initialize("react", "output.txt");
// plug-in X1t with no output written, no working directory change,// and input read from pb_contam.x1t
358
Plugin Feature
int success = myPlugin.initialize("x1t", null, "-nocd-i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"");
Function "destroy" can be used at the end of the program to free up the underlyingmemory associated with the GWBplugin object.
myPlugin.destroy();
I.3.2 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
public int exec_cmd (String uline // command string to be sent to the GWB application
);
Return value
Nonzero on success and zero on failure.Examples
myPlugin.exec_cmd("3 mmol H+");myPlugin.exec_cmd("2 mmol Ca++");myPlugin.exec_cmd("5 mmolar Cl-");myPlugin.exec_cmd("go"); // trigger the calculation
I.3.3 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”function. The keywords, arguments, default units, and return types are the same asthose listed in the table in the Report Command chapter of this reference manual.
To use the “results” function, you provide an array of the proper data type, alongwith the report command and keywords, optional desired units, and the node locationof choice (X1t and X2t only).
public int results(Object data,String value,String units = null,int ix = 0,int jy = 0
);
Parameters:
359
GWB Reference Manual
data
Array of data to fill. This can be null or of type int[ ], double[ ], or String[ ].value
String containing the report command keyword and arguments.units (optional)
String containing the units you want the results returned in. This can be null or anempty string if you want the results returned in the default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
The number of values written (or to be written) to the array.Remarks
To determine the size of array you will need, first call this function with the dataparameter as null and with the rest of the parameters filled.
If the command fails for any reason, for example if the requested data doesn’t existor the specified unit conversion failed, the data will be filled with GWBplugin.ANULL(999999).Examples
// get aqueous species namesint ndata = myPlugin.results(null, "species");String Species[ ] = new String[ndata];myPlugin.results(Species, "species");
// get aqueous species concentrations in mg/kgdouble Conc[ ] = new double[ndata];myPlugin.results(Conc, "concentration aqueous", "mg/kg");
// get pH at node 3,5double pH[ ] = new double[1];myPlugin.results(pH, "pH", null, 3, 5);
I.3.4 Java code examples using the plugin feature
Normally you would use the GWB plugin within your program with no output beingwritten to a file. The following is an example of this:
import GWBplugin.GWBplugin;
// run with "java -Xss10m Example1"// to avoid possible stack_overflow_exception
class Example1 {
public static void main(String[ ] args) {
360
Plugin Feature
// create the plug-in objectGWBplugin myGWBrun = new GWBplugin();
// start the GWB programif(myGWBrun.initialize("spece8", "", "-nocd") != 0) {
// started successfullySystem.out.println("Beginning run.");
// configure SpecE8 and trigger calculationString[ ] cmds = {"pH = 8", "molality Cl- = .05", "go"};for(int i=0; i<3; i++)
myGWBrun.exec_cmd(cmds[i]);
System.out.println("Finished run.");
// retrieve resultsdouble pH[ ] = new double[1];myGWBrun.results(pH, "pH");
double Cl[ ] = new double[1];// in default unitsmyGWBrun.results(Cl, "concentration Cl-");System.out.println(String.format("concentration of Cl- in molal
is %10.4g" ,Cl[0]));// in different unitsmyGWBrun.results(Cl, "concentration Cl-", "mg/kg");System.out.println(String.format("concentration of Cl- in mg/kg
is %10.4g", Cl[0]));
// get size of dataint nspec = myGWBrun.results(null, "species");
// create data blocksString Name[ ] = new String[nspec];double Spec[ ] = new double[nspec];
// send data arrays with keyword and argumentsmyGWBrun.results(Name, "species");myGWBrun.results(Spec, "concentration aqueous", "mg/kg");
System.out.println(String.format("There are %d aqueous species.",nspec));
for(int i=0; i<nspec; i++)System.out.println(String.format("%-4s = %10.4g mg/kg",
Name[i], Spec[i]));
361
GWB Reference Manual
myGWBrun.destroy();}
}}
To familiarize yourself with the plugin feature, you might want the GWB program’snormal output and results to be written to the console and to text files. The followingcode shows examples of this:
import GWBplugin.GWBplugin;import java.io.*;
// run with "java -Xss10m Example2"// to avoid possible stack_overflow_exception
class Example2 {public static void main(String[ ] args) {
try {System.out.println("Starting program SpecE8");
GWBplugin myGWBrun = new GWBplugin();
if(myGWBrun.initialize("spece8","test_output.txt","-nocd -i \"c:/program files (x86)/gwb/script/freshwater.sp8\"-s \"c:/program files (x86)/gwb/gtdata/feoh.sdat\"") != 0) {
// started successfullySystem.out.println("writing output to test_output.txt.");
myGWBrun.exec_cmd("show surfaces"); // write to output file
System.out.println("Executing test");
FileOutputStream fos;PrintStream fp;
fos = new FileOutputStream("test_results.txt");fp = new PrintStream(fos);System.out.println("writing results to test_results.txt");
String[ ] cmds = {"pH = 8", "molality Cl- = .05", "go"};for(int i=0; i<3; i++)
myGWBrun.exec_cmd(cmds[i]);
double pH[ ] = new double[1];myGWBrun.results(pH, "pH");fp.println(String.format("pH = %4.1f ", pH[0]));
362
Plugin Feature
double Cl[ ] = new double[1];myGWBrun.results(Cl, "concentration Cl-");fp.println(String.format("Cl = %12.5e molal", Cl[0]));myGWBrun.results(Cl, "concentration Cl-", "mg/kg");if(Cl[0] != GWBplugin.ANULL)
fp.println(String.format("Cl = %12.5e mg/kg", Cl[0]));else
fp.println("unit conversion failed - Cl = ANULL");fp.println("");
// get size of dataint nspec = myGWBrun.results(null, "species");
// create data blocksString Name[ ] = new String[nspec];double Spec[ ] = new double[nspec];
// send data arrays with keyword and argumentsif(myGWBrun.results(Name, "species") != 0) {
if(myGWBrun.results(Spec, "concentration aqueous") != 0){for(int i=0; i<nspec; i++)
fp.println(String.format("%-32s %12.5e molal",Name[i], Spec[i]));
}fp.println("");fp.println("");if(myGWBrun.results(Spec, "concentration aqueous", "mg/kg") != 0){
for(int i=0; i<nspec; i++)fp.println(String.format("%-32s %12.5e mg/kg",
Name[i], Spec[i]));}
}fp.close();
myGWBrun.destroy();
BufferedReader br = new BufferedReader(newInputStreamReader(System.in));
String input = null;System.out.println("press return to exit> ");input = br.readLine();
}}catch (Exception e){
e.printStackTrace();
363
GWB Reference Manual
}}
}
I.3.5 Java command line
This example of how to run the GWBplugin Example1 on the command line with Javaassumes that you have a Java development kit installed.
To run Example1 on the command line with Java, follow these steps:
// open the command promptcmd.exe
// create a working folder and change to that foldermkdir "%homepath%\GWBplugin"cd "%homepath%\GWBplugin"
// copy the "src" folder from GWB installation (default install path shown)copy /Y "C:\Program Files (x86)\GWB\src"
// add the GWB installation folder to your pathset path=C:\Program Files (x86)\GWB;%path%
// add the JDK bin folder to your path if it is not already thereset path=C:\Program Files (x86)\Java\jdk1.7.0_05\bin;%path%
// add the GWBplugin JAR file to your classpathset classpath=C:\Program Files (x86)\GWB\src\GWBplugin.jar;%classpath%
// Add the Java Native Access JAR file to your classpath// (substitute the location you downloaded it to)set classpath=%homepath%\downloads\jna.jar;%classpath%
// compile the example filejavac GWBplugin_Java_Example1.java
// run the example with Java// (-Xss 10m increases the stack size, the default stack is usually too small)java -Xss10m Example1
364
Plugin Feature
I.4 Perl
GWB provides a GWBplugin wrapper class contained in the Perl module file“GWBplugin.pm” which handles dealing with the C data type conversion and callingthe DLL. In order to locate the GWB DLLs the GWBplugin class uses, you must addthe GWB installation directory to the PATH environment variable.
Since Perl is a dynamically typed language, there are some minor differences withits "results" functions compared to statically typed languages.
To use the GWBplugin class from the GWBplugin module, you must first add the"src" folder in the GWB installation to Perl’s module search path and then tell it touse the GWBplugin module.
#! /usr/bin/perl -w
## add explicit location of GWBplugin.pm to libuse lib '/program files (x86)/gwb/src';
## or by relative pathuse lib '.';
## use GWBplugin moduleuse GWBplugin;
The GWBplugin module depends on the Perl Win32::API module. As of now thismodule is only available for the 32bit version of Perl, so you will need the 32bitversions of Perl and GWB installed to use the provided GWBplugin wrapper for Perl.You can install the Win32::API module with the Perl Package Manager with the followingcommand:
ppm install Win32-API
This is the Perl wrapper class provided in GWBplugin.pm in the "src" directory ofthe GWB installation folder:
# GWBplugin.pm
package GWBplugin;
our $ANULL = -999999;
sub initialize # (app_name, file_name = 0, cmds = 0)sub exec_cmd # (uline)sub results # (value, units = 0, ix = 0, jy = 0)sub destroy #
365
GWB Reference Manual
I.4.1 Initializing the GWB application
Within your code, first create a GWBplugin object.
my $myPlugin = new GWBplugin();
Next, use the “initialize” function to start the GWB application of interest by passingthe application name, an optional output file name, and any commandline typearguments. The “initialize” function must be called before calling any of the otherfunctions.
sub initialize # (app_name,file_name = 0,cmds = 0)
Parameters:app_name
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional)
String containing the name of the file you want the GWB output written to. Thiscan be a zero or an empty string if you do not want the output to be written to a file.cmds (optional)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be a zero or an empty string fordefaults.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return valueNonzero on success and zero on failure.
Examples
# plug-in SpecE8 with no output written and no command-line optionsmy $success = $myPlugin->initialize("spece8");
# plug-in React with output written to output.txt and no command-line options
366
Plugin Feature
my $success = $myPlugin->initialize("react", "output.txt");
# plug-in X1t with no output written, no working directory change,# and input read from pb_contam.x1tmy $success = $myPlugin->initialize("x1t", "", "-nocd
-i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"");
Function "destroy" can be used at the end of the program to free up the underlyingmemory associated with the GWBplugin object.
$myPlugin->destroy();
I.4.2 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
sub exec_cmd # (uline # command string to be sent to the GWB application
)
Return value
Nonzero on success and zero on failure.Examples
$myPlugin->exec_cmd("3 mmol H+");$myPlugin->exec_cmd("2 mmol Ca++");$myPlugin->exec_cmd("5 mmolar Cl-");$myPlugin->exec_cmd("go"); # trigger the calculation
I.4.3 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”functions. The keywords, arguments, default units, and return types are the same asthose listed in the table in the Report Command chapter of this reference manual.Use the "results" functions by providing the report command and keywords, optionaldesired units, and the node location of choice (X1t and X2t only).
# results functionsub results # (value, units = 0, ix = 0, jy = 0)
Parameters:value
String containing the report command keyword and arguments.
367
GWB Reference Manual
units (optional)String containing the units you want the results returned in. This can be a zero or
an empty string if you want the results returned in the default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
Array containing the requested results.Remarks
The data is returned as an array, even when requesting a single value.If the command fails for any reason, for example if the requested data doesn’t exist
or the specified unit conversion failed, the data will be filled with ANULL (999999).Examples
# get aqueous species namesmy @species = $myPlugin->results("species");
# get aqueous species concentrations in mg/kgmy @conc = $myPlugin->results("concentration aqueous", "mg/kg");
# get pH at node 3,5my ($pH) = $myPlugin->results("pH", "", 3,5);
I.4.4 Perl code examples using the plugin feature
Normally you would use the GWB plugin within your program with no output beingwritten to a file. The following is an example of this:
#! /usr/bin/perl -w
## add explicit location of GWBplugin.pm to lib# use lib '/program files (x86)/gwb/src';
## or by relative pathuse lib '.';
## use GWBplugin moduleuse GWBplugin;
# create the plug-in objectmy $myGWBrun = new GWBplugin();
# start the GWB programif ($myGWBrun->initialize("spece8", "", "-nocd")) {
print "Beginning run.\n";
368
Plugin Feature
my @cmds = ("pH = 8", "molality Cl- = .05", "go");foreach my $cmd (@cmds) {
$myGWBrun->exec_cmd($cmd);}print "Finished run.\n\n";
# retrieve resultsmy ($pH) = $myGWBrun->results("pH");
my ($Cl) = $myGWBrun->results("concentration Cl-");printf("concentration of Cl- in molal is %10.4g\n", $Cl);($Cl) = $myGWBrun->results("concentration Cl-", "mg/kg");printf("concentration of Cl- in mg/kg is %10.4g\n", $Cl);
my @species = $myGWBrun->results("species");my @conc = $myGWBrun->results("concentration aqueous", "mg/kg");my $nspec = @species;
print "\nThere are " . $nspec . " aqueous species.\n\n";
for(my $i=0; $i<$nspec; $i++) {printf("%-4s = %10.4g mg/kg\n", $species[$i], $conc[$i]);
}
$myGWBrun->destroy();}
To familiarize yourself with the plugin feature, you might want the GWB program’snormal output and results to be written to the console and to text files. The followingcode shows examples of this:
#! /usr/bin/perl -w
## add explicit location of GWBplugin.pm to lib# use lib '/program files (x86)/gwb/src';
## or by relative pathuse lib '.';
## use GWBplugin moduleuse GWBplugin;
print "Starting program SpecE8\n";
my $myGWBrun = new GWBplugin();
369
GWB Reference Manual
if ($myGWBrun->initialize("spece8","test_output.txt","-nocd \-i \"c:/program files (x86)/gwb/script/freshwater.sp8\" \-s \"c:/program files (x86)/gwb/gtdata/feoh.sdat\"")) {
print "writing output to test_output.txt\n";$myGWBrun->exec_cmd("show surfaces");print "Executing test\n";open FP, ">test_results.txt" or die $!;print "writing results to test_results.txt\n";my @cmds = ("pH = 8", "molality Cl- = .05", "go");foreach my $cmd (@cmds){
$myGWBrun->exec_cmd($cmd);}
my ($pH) = $myGWBrun->results("pH");printf FP ("pH = %4.1f\n", $pH);
my ($Cl) = $myGWBrun->results("concentration Cl-");printf FP ("Cl = %12.5e molal\n", $Cl);
($Cl) = $myGWBrun->results("concentration Cl-", "mg/kg");if($Cl ne $ANULL) {
printf FP ("Cl = %12.5e mg/kg\n\n", $Cl);}else {
print FP "unit conversion failed - Cl = ANULL\n\n";}
my @Name = $myGWBrun->results("species");my @Spec = $myGWBrun->results("concentration aqueous");my $nspec = @Name;for(my $i=0; $i<$nspec; $i++) {
printf FP ("%-32s %12.5e molal\n", $Name[$i], $Spec[$i]);}@Spec = $myGWBrun->results("concentration aqueous", "mg/kg");print FP "\n\n";for (my $i=0; $i<$nspec; $i++) {
printf FP ("%-32s %12.5e mg/kg\n", $Name[$i], $Spec[$i]);}
$myGWBrun->destroy();print "press return to exit> ";<>;close(FP);
}
370
Plugin Feature
I.4.5 Perl command line
This example of how to run the GWBplugin Example1 on the command line with Perlassumes that you have (32bit/x86) ActivePerl for Windows installed. This exampleshould work with other versions of Perl, but instructions on how to obtain the Win32::APImodule may be different.
To run Example1 on the command line with Perl, follow these steps:
# open the command promptcmd.exe
# create a working folder and change to that foldermkdir "%homepath%\GWBplugin"cd "%homepath%\GWBplugin"
# copy the "src" folder from GWB installation (default install path shown)copy /Y "C:\Program Files (x86)\GWB\src"
# add the GWB installation folder to your pathset path=C:\Program Files (x86)\GWB;%path%
# if you haven’t already installed the Win32::API module, do so nowppm install Win32-API
# run the example with Perlperl GWBplugin_Perl_Example1.pl
371
GWB Reference Manual
I.5 Python
GWB provides a GWBplugin wrapper class contained in the Python script file“GWBplugin.py” which handles dealing with the C data type conversion and callingthe DLL. In order to locate the GWB DLLs the GWBplugin class uses, you must addthe GWB installation directory to the PATH environment variable.
Since Python is a dynamically typed language, there are some minor differenceswith its “results” functions compared to statically typed languages.
To include GWBplugin.py in your Python script, you first need to append the “src”folder of the GWB installation to sys.path in Python, then import the class.
import os,sys
## append full path to GWBplugin.py ...sys.path.append("c:/program files (x86)/gwb/src")
## or relative path ...sys.path.append(os.path.abspath('.'))
# import GWBplugin classfrom GWBplugin import *
This is the Python wrapper class provided in GWBplugin.py in the “src” directoryof the GWB installation folder:
# GWBplugin.py
ANULL = -999999
class GWBplugin:Name = "GWBplugin"def _ _init_ _(self):def initialize (self, app_name, file_name = None, cmds = None):def exec_cmd (self, uline):def results (self, value, units = None, ix = 0, jy = 0):def destroy (self):
I.5.1 Initializing the GWB application
Within your code, first create a GWBplugin object.
myPlugin = GWBplugin()
Next, use the “initialize” function to start the GWB application of interest by passingthe application name, an optional output file name, and any commandline type
372
Plugin Feature
arguments. The “initialize” function must be called before calling any of the otherfunctions.
def initialize (self,app_name,file_name = None,cmds = None):
Parameters:app_name
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional)
String containing the name of the file you want the GWB output written to. Thiscan be None or an empty string if you do not want the output to be written to a file.cmds (optional)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be None or an empty string fordefaults.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
Nonzero on success and zero on failure.Examples
# plug-in SpecE8 with no output written and no command-line optionssuccess = myPlugin.initialize("spece8")
# plug-in React with output written to output.txt and no command-line optionssuccess = myPlugin.initialize("react", "output.txt")
# plug-in X1t with no output written, no working directory change,# and input read from pb_contam.x1tsuccess = myPlugin.initialize("x1t", "", "-nocd
-i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"")
373
GWB Reference Manual
Function “destroy" can be used at the end of the program to free up the underlyingmemory associated with the GWBplugin object.
myPlugin.destroy()
I.5.2 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
def exec_cmd (self,uline # command string to be sent to the GWB application
):
Return value
Nonzero on success and zero on failure.Examples
myPlugin.exec_cmd("3 mmol H+")myPlugin.exec_cmd("2 mmol Ca++")myPlugin.exec_cmd("5 mmolar Cl-")myPlugin.exec_cmd("go") # trigger the calculation
I.5.3 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”functions. The keywords, arguments, default units, and return types are the same asthose listed in the table in the Report Command chapter of this reference manual.Use the “results” functions by providing the report command and keywords, optionaldesired units, and the node location of choice (X1t and X2t only).
# results functiondef results (self, value, units = None, ix = 0, jy = 0):
Parameters:value
String containing the report command keyword and arguments.units (optional)
String containing the units you want the results returned in. This can be None oran empty string if you want the results returned in the default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
374
Plugin Feature
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
Array containing the requested results.Remarks
The data is returned as an array, even when requesting a single value.If the command fails for any reason, for example if the requested data doesn’t exist
or the specified unit conversion failed, the data will be filled with ANULL (999999).Examples
# get aqueous species namesSpecies = myPlugin.results("species")
# get aqueous species concentrations in mg/kgConc = myPlugin.results("concentration aqueous", "mg/kg")
# get pH at node 3,5pH = myPlugin.results("pH", "", 3,5)[0]
I.5.4 Python code examples using the plugin feature
Normally you would use the GWB plugin within your program with no output beingwritten to a file. The following is an example of this:
import os,sys
## append full path to GWBplugin.py ...# sys.path.append("c:/program files (x86)/gwb/src")
## or relative path ...sys.path.append(os.path.abspath('.'))
# import GWBplugin classfrom GWBplugin import *
# create the plug-in objectmyGWBrun = GWBplugin()
# start the GWB programif myGWBrun.initialize("spece8", "", "-nocd"):
print "Beginning run."
cmds = ["pH = 8", "molality Cl- = .05", "go"]for cmd in cmds:
myGWBrun.exec_cmd(cmd)
print "Finished run.\n"
375
GWB Reference Manual
#retrieve resultspH = myGWBrun.results("pH")[0]
Cl = myGWBrun.results("concentration Cl-")[0]print "concentration of Cl- in molal is %10.4g" % ClCl = myGWBrun.results("concentration Cl-", "mg/kg")[0]print "concentration of Cl- in mg/kg is %10.4g" % Cl
species = myGWBrun.results("species")conc = myGWBrun.results("concentration aqueous", "mg/kg")
print "\nThere are" , len(species) , "aqueous species.\n"for i in range(len(species)):
print "%-4s = %10.4g mg/kg" % (species[i], conc[i])
myGWBrun.destroy()
To familiarize yourself with the plugin feature, you might want the GWB program’snormal output and results to be written to the console and to text files. The followingcode shows examples of this:
import os,sys
## append full path to GWBplugin.py ...# sys.path.append("c:/program files (x86)/gwb/src")
## or relative path ...sys.path.append(os.path.abspath('.'))
# import GWBplugin classfrom GWBplugin import *
print "Starting program SpecE8"
myGWBrun = GWBplugin()
if myGWBrun.initialize("spece8","test_output.txt","-nocd \-i \"c:/program files (x86)/gwb/script/freshwater.sp8\" \-s \"c:/program files (x86)/gwb/gtdata/feoh.sdat\""):
print "writing output to test_output.txt"myGWBrun.exec_cmd("show surfaces")print "Executing test"fp = open("test_results.txt", "w")if fp.closed:
376
Plugin Feature
stderr.write("can’t open test_results.txt")else:
print "writing results to test_results.txt"cmds = ["pH = 8", "molality Cl- = .05", "go"]for cmd in cmds:
myGWBrun.exec_cmd(cmd)
pH = myGWBrun.results("pH")[0]fp.write("pH = %4.1f\n" % pH)
Cl = myGWBrun.results("concentration Cl-")[0]fp.write("Cl = %12.5e molal\n" % Cl)
Cl = myGWBrun.results("concentration Cl-", "mg/kg")[0]if Cl != ANULL:
fp.write("Cl = %12.5e mg/kg\n\n" % Cl)else:
fp.write("unit conversion failed - Cl = ANULL\n\n")
Name = myGWBrun.results("species")Spec = myGWBrun.results("concentration aqueous")for i in range(len(Name)):
fp.write("%-32s %12.5e molal\n" % (Name[i], Spec[i]))Spec = myGWBrun.results("concentration aqueous", "mg/kg")fp.write("\n\n")for i in range(len(Name)):
fp.write("%-32s %12.5e mg/kg\n" % (Name[i], Spec[i]))fp.close()
myGWBrun.destroy()raw_input("press return to exit> ")
I.5.5 Python command line
The GWB plugin has been tested with Python for Windows version 2.7.3. The versionof Python you are using must be the same as the version of GWB installed (32bitvs. 64bit).
To run the GWBplugin Example1 on the command line with Python, follow thesesteps:
# open the command promptcmd.exe
# create a working folder and change to that foldermkdir "%homepath%\GWBplugin"cd "%homepath%\GWBplugin"
# copy the "src" folder from GWB installation (default install path shown)
377
GWB Reference Manual
copy /Y "C:\Program Files (x86)\GWB\src"
# add the GWB installation folder to your pathset path=C:\Program Files (x86)\GWB;%path%
# run the example with Pythonpython GWBplugin_Python_Example1.py
378
Plugin Feature
I.6 MATLAB
GWB provides a GWBplugin wrapper class contained in the MATLAB script file"GWBplugin.m" which handles dealing with the C data type conversion and callingthe DLL. In order to locate the GWB DLLs the GWBplugin class uses, you must addthe GWB installation directory to the PATH environment variable.
Since MATLAB is a dynamically typed language, there are some minor differenceswith its "results" functions compared to statically typed languages.
To begin, locate the directory in which the GWB software is installed on yourcomputer. Most commonly, the installation is in directory "C:\Program Files\Gwb" for64 bit GWB, which we’ll assume here, or in "C:\Program Files (x86)\Gwb" for the 32bit version.
Add the GWB installation directory (e.g., "C:\Program Files\Gwb") to your PATHenvironmental variable, either from the Windows Control Panel before starting MATLAB,or by issuing the command
setenv(’PATH’,[getenv(’PATH’),’;C:\Program Files\GWB’]);
from within MATLAB.Next, set up a C compiler in MATLAB using the command "mex setup", as described
in the MATLAB documentation. The compiler might be cl, icl, or gcc; it should alreadyhave been installed on your computer.
Now, compile within MATLAB the file "GWBpluginMex.cpp" and associated headerfile "class_handle.hpp", which are located in the "src" subdirectory, to produce aMATLAB library. The command to do this is
mex "C:\Program Files\Gwb\src\GWBpluginMex.cpp"-I"C:\Program Files\Gwb\src"-L"C:\Program Files\Gwb" -lgwbplugin
I.6.1 GWBplugin MATLAB wrapper class overview
This is a synopsis of the MATLAB wrapper class provided in "GWBplugin.m", whichcan be found in the "src" directory of the GWB installation folder:
classdef GWBplugin < handleproperties (SetAccess = private, Hidden = true)
objectHandle;endmethods
function this = GWBplugin(varargin)this.objectHandle = GWBpluginMex(’new’);GWBpluginMex(’initialize’, this.objectHandle, varargin{:});
end
379
GWB Reference Manual
function delete(this)GWBpluginMex(’delete’, this.objectHandle);
end
function exec_cmd(this, varargin)GWBpluginMex(’exec_cmd’, this.objectHandle, varargin{:});
end
function result = results(this, varargin)result = GWBpluginMex(’results’, this.objectHandle, varargin{:});
endend
end
I.6.2 Initializing the GWB application
Within your MATLAB script you begin by creating a "GWBplugin" object, passing theapplication name (e.g., ’spece8’), an optional file name for the GWB application towrite output to, and any commandline type arguments.
myGWBrun = GWBplugin(app_name, file_name, cmds):
Parameters:app_name
A string containing the GWB application name you wish to use. Valid options arerxn, spece8, react, x1t, and x2t.file_name (optional)
A string containing the name of the file you want the GWB application to write itsoutput to. Omit or pass an empty array if you do not want to write output to a file.cmds (optional)
A string containing commandline options you could normally pass to the applicationwhen running it from the commandline. Can be omitted or an empty array.
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
380
Plugin Feature
The handle of the GWB plugin, or zero on failure.Remarks
For this function to succeed you must have your GWB installation folder added tothe PATH environment variable so all the required DLLs can be found.
Output to the file is not performed in MATLAB until the GWBplugin object has beencleared from memory. To do this, enter the MATLAB ’clear’ command.Examples
% plug-in SpecE8 with no output written and no optionsmyGWBrun = GWBplugin(’spece8’);...
% plug-in React with output written to output.txt and no optionsmyGWBrun = GWBplugin(’react’,’output.txt’);...
% plug-in X1t with no output written, no working directory change,% and read input from pb_contam.x1tmyGWBrun = GWBplugin(’x1t’,[ ],’-nocd
-i \"c:/Program Files/gwb/script/pb_contam.x1t\"’);
I.6.3 Configuring and executing calculations
Use the “exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
exec_cmd(myGWBrun, uline):
Parameter
uline
A string containing the command you wish to send to the GWB application.Return value
Nonzero on success and zero on failure.Remarks
You may include more than one GWB command in a single call.Examples
exec_cmd(myGWBrun, ’3 mmol H+’)exec_cmd(myGWBrun, ’2 mmol/kg Ca++’, ’4 mmol/kg Cl-’, ’go’)
I.6.4 Retrieving the results
Transfer calculation results from the GWB application to your program with the “results”function. The keywords, arguments, default units, and return types are the same as
381
GWB Reference Manual
those listed in the table in the Report Command chapter of this reference manual.Use the "results" functions by providing the report command and keywords, optionaldesired units, and the node location of choice (X1t and X2t only).
results(myGWBrun, value, units, ix, jy):
Parameters:value
String containing the report command keyword and arguments.units (optional)
String containing the units you would like the results returned in. Omit or pass anempty array if you want default units.ix (optional)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.jy (optional)
Y node position. This is only used when running X2t, otherwise it is ignored.Return value
Array containing the requested results.Remarks
If you request a single value, it is returned as an array of length one.If the command fails for any reason, for example if the requested data doesn’t exist
or the specified unit conversion failed, an empty array is returned.Parameter ix is used when running X1t and X2t; otherwise it is ignored. Paramter
jy is similarly used only when running X2t.Examples
Cl = results(myGWBrun,’concentration Cl-’); % in default unitsfprintf(’concentration of Cl- in molal is %10.4g\n’,Cl);
Cl = results(myGWBrun,’concentration Cl-’,’mg/kg’); % in different unitsfprintf(’concentration of Cl- in mg/kg is %10.4g\n’,Cl);
Name = results(myGWBrun,’species’);Spec = results(myGWBrun,’concentration aqueous’,’mg/kg’);
fprintf(’\n There are %i aqueous species\n\n’,length(Name));for i = 1:length(Name)
fprintf(’%-4s = %10.4g mg/kg\n’,Namei,Spec(i));end
I.6.5 Cleaning up
The "delete" function is designed to free up the underlying memory associated withthe GWBplugin object. Due to a known issue in MATLAB, we recommend you reuseexisting plugin instances, rather than destroy and recreate them.
To reuse an instance, issue the command
382
Plugin Feature
exec_cmd(myGWBrun, ’reset’);
I.6.6 MATLAB code examples using the plugin feature
Normally you would use the GWB plugin within your program with no output beingwritten to a file. The following is an example of this:
% Only needed if the GWB install directory is not in the PATH% environment variablesetenv(’PATH’,[getenv(’PATH’),’;C:\Program Files\Gwb’]);
% Create the plugin object and start the GWB programmyGWBrun = GWBplugin(’spece8’,[ ],’-nocd’);
disp(’Beginning run’);exec_cmd(myGWBrun,’pH = 8’,’molality Cl- = .05’,’go’);disp(’Finished run’);
% Ensure run was successfulif results(myGWBrun,’Success’)
%retrieve resultspH = results(myGWBrun,’pH’);
Cl = results(myGWBrun,’concentration Cl-’); % in default unitsfprintf(’concentration of Cl- in molal is %10.4g\n’,Cl);Cl = results(myGWBrun,’concentration Cl-’,’mg/kg’); % in different unitsfprintf(’concentration of Cl- in mg/kg is %10.4g\n’,Cl);
Name = results(myGWBrun,’species’);Spec = results(myGWBrun,’concentration aqueous’,’mg/kg’);
fprintf(’\n There are %i aqueous species\n\n’,length(Name));for i = 1:length(Name)
fprintf(’%-4s = %10.4g mg/kg\n’,Name{i},Spec(i));end
end
To familiarize yourself with the plugin feature, you might want the GWB program’snormal output and results to be written to the console and to text files. The followingcode shows examples of this:
% Only needed if the GWB install directory is not in the PATH% environment variablesetenv(’PATH’,[getenv(’PATH’),’;C:\Program Files\Gwb’]);ANULL = -999999.0;
disp(’Starting program SpecE8’);
383
GWB Reference Manual
myGWBrun = GWBplugin(’spece8’,’test_output.txt’, ...’-nocd -i "C:/Program Files/Gwb/Script/Freshwater.sp8" ...-s "C:/Program Files/Gwb/Gtdata/FeOH.dat’);
disp(’writing output to test_output.txt’);exec_cmd(myGWBrun,’show surfaces’); % write to output file
disp(’Executing test’);
fp=fopen(’test_results.txt’, ’w’);if fp < 0
disp(’cant open test_results.txt’);else
disp(’writing results to test_results.txt’);exec_cmd(myGWBrun,’pH = 8’,’molality Cl- = .05’,’go’);
pH = results(myGWBrun,’pH’);fprintf(fp,’pH = %4.1f \n’, pH);
Cl = results(myGWBrun,’concentration Cl-’);fprintf(fp,’Cl = %12.5e molal\n’, Cl);
Cl = results(myGWBrun,’concentration Cl-’,’mg/kg’);if(Cl ~= ANULL)
fprintf(fp,’Cl = %12.5e mg/kg\n\n’, Cl);else
fprintf(fp,’unit conversion failed - Cl = ANULL\n\n’);end
Name = results(myGWBrun,’species’);Spec = results(myGWBrun,’concentration aqueous’);
for i = 1:length(Name)fprintf(fp, ’%-32s %12.5e molal\n’, Name{i}, Spec(i));
endfprintf(fp,’\n\n’);
Spec = results(myGWBrun,’concentration aqueous’,’mg/kg’);for i = 1:length(Name)
fprintf(fp, ’%-32s %12.5e molal\n’, Name{i}, Spec(i));end
fclose(fp);end
384
Plugin Feature
I.6.7 MATLAB command line
The GWB plugin has been tested with MATLAB versions 7.9 and 8.0. The version ofMATLAB you are using must be the same as the version of GWB installed (32bit vs.64bit).
To run the GWBplugin Example1 on the command line with MATLAB, follow thesesteps. First, after opening MATLAB, create a working folder and change to that folder
mkdir ’GWBplugin’cd ’GWBplugin’
Copy the files “GWBplugin.m” and “GWBplugin_Matlab_example1.m” from the “src”folder of GWB installation into the new folder
copyfile (’C:\Program Files\GWB\src\GWBplugin.m’, pwd)copyfile (’C:\Program Files\GWB\src\GWBplugin_Matlab_example1.m’, pwd)
Compile the MATLAB wrapper with the “mex” command
mex "C:\Program Files\Gwb\src\GWBpluginMex.cpp"-I"C:\Program Files\Gwb\src"-L"C:\Program Files\Gwb" -lgwbplugin
You are now ready to run the example script
GWBplugin_Matlab_example1
which should produce output similar to the following:
>>GWBplugin_Matlab_example1
Beginning run.Finished run.
concentration of Cl- in molal is 0.05concentration of Cl- in mg/kg is 1770
There are 4 aqueous species.
Cl- = 1770 mg/kgH+ = 1.139e-05 mg/kgHCl = 1.234e-11 mg/kgOH- = 0.02039 mg/kg
Follow the same procedure to run the second example script, “GWBplugin_Matlab_example2.m”. Congratulations on plugging into the GWB!
385
GWB Reference Manual
I.7 Other languages
Any language that can load DLLs, call C functions from them, and handle some basicC data types should be able to use the GWB plugin feature. You must have your GWBinstallation folder added to the PATH environment variable so that all of the requiredDLLs can be found. The C data types that need to be handled are void*, char*, int*,double*, and int. If the language you want to use is similar to one that a wrapper isprovided for, a good place to start is to look at how that wrapper is implemented.
To create a wrapper class, interface, or whatever makes sense for your targetlanguage, follow these steps:
Load the GWBplugin DLL. Generally this will be done during runtime with a call toLoadLibrary or whatever the equivalent is in the language. Some languages, mostlycompiled and linked ones, can instead link to the export library GWBplugin.lib.
Tell your program about the functions you will call from the DLL. This is usuallydone by giving prototypes in some way or by directly including GWBplugin.h.The DLL functions and their prototypes are listed in the next section.
Encapsulate. Create functions in your wrapper that call the corresponding DLLfunction and handle data type conversions. The wrapper, if possible, should alsohave a void* member variable that can be passed by address to the DLL functions.This void* member variable keeps track of a particular GWBplugin instance.
I.7.1 GWBplugin.dll function prototypes
Following is the list of the definitions and functions exported from GWBplugin.dll thatyour wrapper will need to use. Note that function parameters labeled as (optional)are in fact required when you call the C function. It is suggested, however, that youmake these arguments optional for your own wrapper if possible and use the providedsuggested defaults.
// GWBplugin.h
#define ANULL -999999.0 // marker for an undefined value
extern "C" _ _declspec(dllexport)int c_initialize(void* plugin, const char* app_name,
const char* file_name, const char* cmds);
extern "C" _ _declspec(dllexport)int c_exec_cmd(void* plugin, char* uline);
extern "C" _ _declspec(dllexport)int c_results(void* plugin, void* data, const char* value,
const char* units, int ix, int jy);
386
Plugin Feature
extern "C" _ _declspec(dllexport)int c_results_c(void* plugin, void* data, const char* value,
const char* units, int ix, int jy, int* slen);
extern "C" _ _declspec(dllexport)int c_destroy(void* plugin);
I.7.2 Initializing the GWB application
Within your code, first create a void* equivalent variable or something that can hold apointer data type... i.e. that is 32bits long (for a 32bit application) or 64bits long (fora 64bit application). This will be a member variable of your class if possible.
Next, use the “c_initialize” function to start the GWB application of interest bypassing the address of the void* variable, the application name, an optional outputfile name, and any commandline type arguments. The “c_initialize” function must becalled before calling any of the other functions.
int c_initialize (void* plugin,const char* app_name,const char* file_name,const char* cmds
);
Parameters:plugin
A dereferenceable pointer that points to a pointer which can be assigned a value.It keeps track of a particular pluggedin GWB application.app_name
String containing the GWB application name “rxn”, “spece8”, “react”, “x1t”, or “x2t”.file_name (optional) (default: NULL or empty string)
String containing the name of the file you want the GWB output written to. Thiscan be NULL or an empty string if you do not want the output to be written to a file.cmds (optional) (default: NULL or empty string)
String containing commandline options you could normally pass to the applicationwhen running it from the commandline. This can be NULL or an empty string.
387
GWB Reference Manual
Commandline options:
-cd Change the working directory to the directory containing the input scriptspecified with the -i option.
-nocd Do not change the working directory.
-i <input_script> Read initial input commands from the specified file.
-gtd <gtdata_dir> Set directory to search for thermodynamic datasets.
-cond <cond_data> Set the dataset for calculating electrical conductivity.
-d <thermo_data> Set the thermodynamic dataset.
-s <surf_data> Set a dataset of surface sorption reactions.
-iso <isotope_data> Set a dataset of isotope fractionation factors.
Return value
Nonzero on success and zero on failure.Examples
Some examples of how to start the GWB plugin in various ways:
void* myPlugin = NULL;
// plug-in SpecE8 with no output written and no command-line optionsint success = c_initialize(&myPlugin, "spece8");
// plug-in React with output written to output.txt and no command-line optionsint success = c_initialize(&myPlugin, "react", "output.txt");
// plug-in X1t with no output written, no working directory change,// and input read from pb_contam.x1tint success = c_initialize(&myPlugin, "x1t", NULL, "-nocd
-i \"c:/program files (x86)/gwb/script/pb_contam.x1t\"");
Function "c_destroy" can be used at the end of the program to free up the underlyingmemory associated with the pluggedin GWB application.
c_destroy(&myPlugin);
I.7.3 Configuring and executing calculations
Use the “c_exec_cmd” function to transmit commands to the GWB plugin. Eachapplication has a chapter in this reference manual that is a comprehensive guide tothe commands available. Use these commands to configure the application and thensend a “go” command to trigger the calculations.
int c_exec_cmd(void* plugin,char* uline
);
388
Plugin Feature
Parameters:plugin
A dereferenceable pointer that has already been used with c_initialize. It keepstrack of a particular pluggedin GWB application.uline
String containing the command to be sent to the GWB application.Return value
Nonzero on success and zero on failure.Examples
c_exec_cmd(&myPlugin, "3 mmol H+");c_exec_cmd(&myPlugin, "2 mmol Ca+");c_exec_cmd(&myPlugin, "5 mmolar Cl-");c_exec_cmd(&myPlugin, "go");
I.7.4 Retrieving the results
Transfer calculation results from the GWB application to your program with the“c_results” function. The keywords, arguments, default units, and return types are thesame as those listed in the table in the Report Command chapter of this referencemanual. Use the "c_results" function by providing the plugin parameter, the addressof a data block to fill, the report command and keywords, optional desired units, andthe node location of choice (X1t and X2t only).
int c_results(void* plugin,void* data,const char* value,const char* units,int ix,int jy
);
Parameters:plugin
A dereferenceable pointer that has already been used with c_initialize. It keepstrack of a particular pluggedin GWB application.data
Address of data block to fill. This can be NULL to determine data block size.value
String containing the report command keyword and arguments.units (optional) (default: NULL or empty string)
String containing the units you want the results returned in. This can be NULL oran empty string if you want the results returned in the default units.ix (optional) (default: 0)
X node position. This is only used when running X1t and X2t, otherwise it is ignored.
389
GWB Reference Manual
jy (optional) (default: 0)Y node position. This is only used when running X2t, otherwise it is ignored.
Return value
The number of values written (or to be written) to the data block.Remarks
To determine the size of data block you will need, first call this function with thedata parameter as NULL and with the rest of the parameters filled. If you know thatthe report command you are using only returns a single value, you can simply passa pointer to the correct data type. See the Report Command chapter for details ondata types and available keywords.
If the command fails for any reason, for example if the requested data doesn’t existor the specified unit conversion failed, the data will be filled with ANULL (999999.0).For this reason, you should "#define ANULL 999999.0" (or language equivalent) inyour wrapper.
For languages that are dynamically typed (e.g. Python and Perl), you will eitherneed to create multiple wrapper "results" functions (one for each possible data type:int, double, char*) or pass the expected type as an extra parameter. It is often best toomit the data parameter in the wrapper function. You then can call "c_results" with aNULL value for data to get the size, allocate C compatible memory, call "c_results"with the data parameter, convert data, and then return an array of the results. SeeGWBplugin.pm or GWBplugin.py for examples of this.Examples
// get aqueous species namesint ndata = c_results(&myPlugin, NULL, "species");char** Species = (char**) malloc(sizeof(char*) * ndata);c_results(&myPlugin, Species, "species");
// get aqueous species concentrations in mg/kgdouble* Conc = (double*) malloc(sizeof(double) * ndata);c_results(&myPlugin, Conc, "concentration aqueous", "mg/kg");
// get pH at node 3,5double pH = ANULL;c_results(&myPlugin, &pH, "pH", NULL, 3, 5);
If you are retrieving string values and you need to know the string lengths forconversion purposes, you will need to use the "c_results_c" function. It is equivalentto the "c_results" function, but it also takes an extra parameter which will store thelength of the strings.
int c_results_c(void* plugin,void* data,const char* value,const char* units,
390
Plugin Feature
int ix,int jy,int* slen // address of data block to fill with retrieved string lengths
);
Examples
// get aqueous species namesint ndata = c_results(&myPlugin, NULL, "species");char** Species = (char**) malloc(sizeof(char*) * ndata);int* Lengths = (int*) malloc(sizeof(int) * ndata);c_results_c(&myPlugin, Species, "species", NULL, 0, 0, Lengths);
391
392
Appendix: Multiple Analyses
It is not uncommon to have stored in a spreadsheet the results of a number ofchemical analyses that you would like to enter – one at a time – into one of the GWBapplications. You might wish to use SpecE8, for example, to figure calcite saturationor CO2 fugacity for a group of analyses.
You can store multiple analyses in a GSS spreadsheet, select one or more samples,then launch SpecE8 or React with Analysis ! Launch. . . . An instance will be launchedconfigured with the values in the first sample. Alternatively, you can add calculatedanalytes for all of your analyses to your GSS spreadsheet directly. See “Calculatinganalytes” in the Using GSS chapter of the GWB Essentials Guide.
If you have relatively few analyses in another type of spreadsheet, you may use theGWB’s “drag and drop” feature. Highlight data for each analysis in the spreadsheet,leftclick, drag into the GWB app, and calculate the desired result. For details, referto the Importing data section of the Introduction to the GWB Essentials Guide.
Given a large number of chemical analyses, this procedure becomes tedious. It isbest in this case to prepare a short script that performs the operations automatically,adding the results to the spreadsheet. This appendix describes how to do so.
You may also want to take advantage of the “scatter data” feature of the GWB, whichallows chemical analyses to be overlain as data points on diagrams produced by Act2,Tact, Gtplot, and Xtplot. For more information, refer to the Scatter data sections ofthe corresponding chapter (Using Act2, and so on) in the GWB documentation set.
G.1 Calculation procedure
Suppose you have a number of chemical analyses stored in an Excel spreadsheet,and you would like to add to the spreadsheet results calculated by one of the GWBapplications. To do so, follow this procedure:
Save the spreadsheet from Excel as a tabdelimited text file. Go to File ! Save
As. . . and choose “Text (Tab delimited) (*.txt)” or “Unicode Text (*.txt)” as the filetype. Excel will create a new file with a “.txt” file extension.
Prepare and run a GWB script, such as the one in the next section, that runswithin the GWB application. The script takes the text file as input and produces
393
GWB Reference Manual
a new text file containing the original data as well as the calculation results.The Control Scripts appendix to this GWB Reference Manual describes how toprepare GWB scripts. An example of such a script, which you may take andmodify for your purposes, is given in the next section.
Open (File ! Open. . . ; choose “All Files (*.*) as the file type) the resulting textfile in Excel. You can now save this file as an Excel spreadsheet (a “.xls” file).
The next section carries you through an example of this procedure.
G.2 Example calculation
The files installed under directory “Scripts\Spreadsheet” within the GWB installationdirectory (e.g., “\Program Files\GWB”) provide an example of using a script toprocess multiple analyses from an Excel spreadsheet. To run the example, copy files“Spreadsheet.xls” and “Script.xls” from this directory to a convenient location on yourcomputer, such as the “My Documents” folder.
The analyses are stored in file “Spreadsheet.xls”. Open this file in Excel bydoubleclicking on it. Save it as a tabdelimited text file, as described in the previoussection. This creates a file “Spreadsheet.txt”.
You may examine this file with an editor such as Notepad. It looks like
ID pH HCO3- SO4-- Cl- Ca++ Mg++ Na+GW-12 6.78 585.7 309 56 205.6 63.9 21.4GW-13 6.78 585.7 311 56.2 214.9 66.8 22.6GW-14 6.85 652.8 582 42.6 269.2 89 25.8GW-15 7 558.2 400 65.4 216.2 65.7 32(and so on)
The first line in the file contains column headers including “pH” and various basisspecies, and subsequent lines contain the numerical data. The headers will be usedtogether with the numerical values to create SpecE8 commands such as
pH = 6.78HCO3- = 585.7 mg/kg
File “Script.sp8” contains a SpecE8 script that reads “Spreadsheet.txt”, calculatesCO2 fugacity and calcite saturation, and writes a file “Output.txt”. You can modify thisscript for your own purposes.
The script is shown below. For clarity, SpecE8 commands within the script are listedin bold face and comment lines are in italics; the actual file, of course, is simply atext file.
script start# Set up the input and output.set in_id [open "Spreadsheet.txt" r]set out_id [open "Output.txt" w]
394
Multiple Analyses
fconfigure $out_id -encoding unicode
# First line contains column headers; check for Unicode.gets $in_id headersif {![string is ascii $headers]} {
close $in_idset in_id [open "Spreadsheet.txt " r]fconfigure $in_id -encoding unicodegets $in_id headers
}puts $out_id "$headers\tf CO2\tCalcite SI"
# Loop through remaining lines.gets $in_id alinereport set_digits 4while {$aline != ""} { set i 0
reset; balance on Cl-
# Set basis constraints from input data.foreach a [lrange $aline 1 end] {
incr i 1if {[lindex $headers $i] == "pH"} {
pH = $a} else {
$a = [lindex $headers $i] mg/kg}
}
# Run SpecE8 calculation and write data + results.goforeach a [lrange $aline 0 end] {
puts -nonewline $out_id "$a\t"}if {[report success]} {
puts $out_id \"[report fugacity CO2(g)]\t[report SI Calcite]"
} else {puts $out_id "Did not converge"
}
# Next line of input.gets $in_id aline
}# Clean up.
close $out_id
395
GWB Reference Manual
close $in_idquit
Double click on file “Script.sp8” to start SpecE8 and execute the script. The programwill produce a file “Output.txt” that contains the original data with the values calculatedfor CO2 fugacity and calcite saturation appended as new columns. The file looks like
D pH HCO3- SO4-- ... Na+ f CO2 Calcite SIGW-12 6.78 585.7 309 21.4 0.06537 0.2281GW-13 6.78 585.7 311 22.6 0.06515 0.2427GW-14 6.85 652.8 582 25.8 Did not convergeGW-15 7 558.2 400 32 0.04134 0.4714
Open “Output.txt” in Excel by selecting File ! Open. . . and choosing “All Files(*.*)” for the file type. Follow the Excel “Text Import Wizard”, accepting the default ateach step: “Delimited” file type, “Tab” delimiter, “General” data format. The calculationresults will appear as would any spreadsheet, which you may save as an Excel (“.xls”)file.
396
Appendix: Remote Control
You can run various GWB application programs not only by hand from the keyboard,but by “remote control” from a program or script you write. Note that this is now a legacyfeature that has been replaced by the Plugin Feature, and is no longer supported.Rxn, Act2, Tact, SpecE8, React, X1t, and X2t can be run in this way. The programyou write serves as the “master program”, which controls the GWB application as a“slave program”.
In writing a program of your own, for example, you might need to determine thesaturation state of calcite in a fluid of arbitrary composition. Instead of developingcode to calculate the distribution of mass and mineral saturation states in a fluid, youcould invoke SpecE8 from within your program and let it do the work for you.
Similarly, you could use the remote control feature to balance reactions with Rxn,calculate activity diagrams with Act2, or figure the results of irreversible reactionpaths with React. In each case, you configure the GWB application by sending textcommands, trigger the calculation, and then retrieve the calculation results to use foryour own purposes.
You can transfer the results from the slave application to the master program withthe “report” command, as described in the Report Command appendix to this GWB
Reference Manual. Or, as is especially useful with Act2 and Tact, you can copycalculation results such as activity diagrams to your computer’s clipboard, where theycan be retrieved as graphical images. To do so, you use the “clipboard” command.Finally, you can simply read datasets, such as “SpecE8_output.txt” produced by theGWB applications, into the master program.
Your program, the master program, controls a GWB application as a slave programthrough a interprocess communications device known as a “pipe”. (Pipes are notavailable in MS Windows 98 or ME, so you cannot use the remote control featureunder these operating systems.) There are two ways to set up the communications.You can create two “unnamed pipes”, one for input to and the other for output fromthe GWB application. Or, you can establish a “named pipe”, which allows bidirectionaldata transfer.
Using a named pipe has a couple of advantages over unnamed pipes. First, themaster program’s standard input and output streams are available for use in the normalmanner. Second, by establishing two or more pipes with different names, any numberof copies of the GWB application programs can be invoked simultaneously.
397
GWB Reference Manual
Sending data through a pipe is much like writing to a file, and receiving data islike reading from a file. Running a GWB application by remote control, therefore,involves little more than standard programming techniques already familiar to anyonewith modest programming experience.
To run a GWB application by remote control, you start it from the master programusing the “pipe” command line option. This option is followed by the name of thepipe, or for an unnamed pipe the keyword “stdio”. In MS Windows, pipes are locatedin a pseudodirectory at the top level of the file system called “pipe”.
If the master program, for example, has created an unnamed pipe, it could invokeprogram SpecE8 using the command
spece8 -pipe stdio
In this case, the standard output stream of the master serves as standard input tothe slave, and the slave’s standard output stream is the master’s input stream.
Similarly, if the master program has created a named pipe called “\pipe\mypipe”,it could invoke program SpecE8 by using the command
spece8 -pipe \pipe\mypipe
The master program could then communicate with SpecE8 by writing to and readingfrom the pipe.
The sections below show examples of how the remote control feature can beimplemented in the C++ programming and Tcl scripting languages, using named andunnamed pipes.
H.1 C++ program using unnamed pipes
In writing a program in C++, you will likely find it easiest to use a set of helperfunctions contained in file “RC_helper.cpp”, a copy of which is installed in the “src”subdirectory of the GWB installation directory (e.g., in “\Program Files\GWB\src”).The helper functions in this file include:
OpenGwbApplic Start the GWB program of interest.
SendCommand Transmit a command to the GWB app,
and, optionally, receive the results of the command.
There is a version of each function for unnamed and named pipes. By using thesefunctions, the programmer can avoid worrying about the details of communicationbetween the master and slave programs.
If you #include the header file “RC_helper.h” at the top of your master program,the helper functions will be available. Of course, you can modify and extend thesefunctions for your own purposes, if you wish. The program must also be compiledwith the “RC_helper.cpp” file, also provided in the same location.
In the following example, included in the “src” subdirectory, a console programinvokes React using unnamed pipes to integrate a kinetic rate law for quartz dissolution
398
Remote Control
at 100°C. Array “script” is a vector of pointers to the commands needed to configureReact and trigger the calculation.
The program opens React, sends it the commands in array “script”, uses the “report”command to request the calculation result, which it extracts from React’s responseusing “sscanf”. Note that since the program uses unnamed pipes, output to the consoleis sent via the “stderr” output stream.
/* RC_example1.cpp */
#include "/Program Files/GWB/src/RC_helper.h"#include <stdio.h>
char* script[] = {"reset","time begin = 0 days, end = 5 days","T = 100","SiO2(aq) = 1 umolal","react 5000 g Quartz","kinetic Quartz rate_con = 2.e-15 surface = 1000","go",""
};
int main(int argc, char* argv[]){
char line[200];char discard[20];char** command;double SI_Quartz;
fprintf(stderr, "Starting program React.\n");OpenGwbApplic("\\Program Files\\gwb\\react.exe");
for (command = script; **command; command++)SendCommand(*command);
SendCommand("report SI Quartz", line, sizeof(line));sscanf(line, "%lg", &SI_Quartz);fprintf(stderr, "Value of SI Quartz is %g.\n", SI_Quartz);
SendCommand("quit");
fprintf(stderr, "press return to exit> ");gets(discard);return 0;
}
399
GWB Reference Manual
H.2 C++ program using named pipes
As a second example of a master program written in C++, we open two copies ofReact as slave programs; the copies run simultaneously. To do so, we establish twopipes, using the “Pipe” class defined in “RC_helper.h”. In this case, the standard I/Ochannels are available to the program, so we need not direct console messages to“stderr”.
/* RC_example2.cpp */
#include "/Program Files/GWB/src/RC_helper.h"#include <stdio.h>
char* script1[] = {"reset","time begin = 0 days, end = 5 days","T = 100","SiO2(aq) = 1 umolal","react 5000 g Quartz","kinetic Quartz rate_con = 2.e-15 surface = 1000","go",""
};
char* script2[] = {"reset","time begin = 0 days, end = 5 days","T = 100","SiO2(aq) = 1 umolal","react 5000 g Quartz","kinetic Quartz rate_con = 2.e-15 surface = 750","go",""
};
int main(int argc, char* argv[]){
char line[200];char discard[20];char** command1;char** command2;double SI_Quartz;Pipe pipe1("pipe1");Pipe pipe2("pipe2");
printf("Open two copies of React.\n");OpenGwbApplic(pipe1,
400
Remote Control
"\\Program Files\\gwb\\react.exe");OpenGwbApplic(pipe2,
"\\Program Files\\gwb\\react.exe");
for (command1 = script1, command2 = script2;**command1 || **command2;**command1 ? command1++ : 0, **command2 ? command2++ : 0) {
if (**command1)SendCommand(pipe1, *command1);
if (**command2)SendCommand(pipe2, *command2);
}
SendCommand(pipe1, "report SI Quartz", line, sizeof(line));sscanf(line, "%lg", &SI_Quartz);printf("SI Quartz for 1000 cm2/g is %g.\n", SI_Quartz);
SendCommand(pipe2, "report SI Quartz", line, sizeof(line));sscanf(line, "%lg", &SI_Quartz);printf("SI Quartz for 7500 cm2/g is %g.\n ", SI_Quartz);
SendCommand(pipe1, "quit");SendCommand(pipe2, "quit");
printf("press return to exit> ");gets(discard);return 0;
}
H.3 Tcl script using unnamed pipes
You may find it especially useful to invoke GWB applications from within anotherapplication or calculation environment, such as a spreadsheet, word processor, ormathematical interpreter. You can do so, as long as the environment has scriptingabilities and can open pipes.
As an example, we repeat the first example above in the Tcl scripting language. Asin the C++ example, a number of helper functions are available in file “RC_helper.tcl”,installed with the GWB in subdirectory src. The complete Tcl script is given below.
source RC_helper.tcl
set cmdlist {reset{time begin = 0 days, end = 5 days}{T = 100}{SiO2(aq) = 1 umolal}
401
GWB Reference Manual
{react 5000 g Quartz}{kinetic Quartz rate_con = 2.e-15 surface = 750}go
}
OpenGwbApplic {/Program Files/gwb/react/react.exe}foreach cmd $cmdlist {
SendCommand $cmd}SendCommand {report SI Quartz} lineputs "SI Quartz is $line."SendCommand quit
H.4 Perl script using unnamed pipes
As a final example, we show how to run React by remote control from a Perl script.The example below uses the object oriented Perl module “RC_helper.pm”, includedin the “src” subdirectory of the GWB installation.
#!/usr/bin/env perluse strict;use warnings;use lib "\\Program Files\\Gwb\\src";use RC_helper;
my $script = <<SCRIPT;resettime begin = 0 days, end = 5 daysT = 100SiO2(aq) = 1 umolalreact 5000 g Quartzkinetic Quartz rate_con = 2.e-15 surface = 1000goSCRIPT
print "Starting program React.\n";my $react = RC_helper->new("\\Program Files\\Gwb\\react.exe");for my $command (split /\n/, $script) {
$react->send_command($command);}my $SI_Quartz = $react->send_command("report SI Quartz");print "Value of SI Quartz is $SI_Quartz\n";
$react->send_command("quit");
402
Appendix: Units Recognized
The following is a complete table of the unit names recognized by the GWB. Thequalifier “free” specifies that the constraint applies to the free rather than to the bulkentry. Use the “log” qualifier to set the variable on a logarithmic scale. Examples:
Cl- 4.1 mg/kgCl- 4.1 free mg/kgCl- 0.612784 log free mg/kg
Dimension Units
Mass and mol mmol umol nmol
Concentration molal mmolal umolal nmolal
mol/kg mmol/kg umol/kg nmol/kg
mol/l mmol/l umol/l nmol/l
kg g mg ug
ng
g/kg mg/kg ug/kg ng/kg
wt fraction wt%
g/l mg/l ug/l ng/l
eq meq ueq neq
eq/kg meq/kg ueq/kg neq/kg
eq/l meq/l ueq/l neq/l
mol/cm3 mmol/cm3 umol/cm3 nmol/cm3
kg/cm3 g/cm3 mg/cm3 ug/cm3
ng/cm3
mol/m3 mmol/m3 umol/m3 nmol/m3
kg/m3 g/m3 mg/m3 ug/m3
ng/m3
vol. fract. volume%
403
GWB Reference Manual
Dimension Units
Activity activity ratio
Fugacity fugacity
Electrical V mV pe
Potential (Eh)
pH pH
Percentage %
Time s min hr day
mon yr m.y.
Distance mm cm m km
in ft mi
Reaction Rate mol/s mmol/s umol/s nmol/s
kg/s g/s mg/s ug/s
ng/s
cm3/s m3/s l/s gal/s
ft3/s
mol/min mmol/min umol/min nmol/min
kg/min g/min mg/min ug/min
ng/min
cm3/min m3/min l/min gal/min
ft3/min
mol/hr mmol/hr umol/hr nmol/hr
kg/hr g/hr mg/hr ug/hr
ng/hr
cm3/hr m3/hr l/hr gal/hr
ft3/hr
mol/day mmol/day umol/day nmol/day
kg/day g/day mg/day ug/day
ng/day
cm3/day m3/day l/day gal/day
ft3/day
mol/yr mmol/yr umol/yr nmol/yr
kg/yr g/yr mg/yr ug/yr
ng/yr
cm3/yr m3/yr l/yr gal/yr
ft3/yr
404
Units Recognized
Dimension Units
Reaction Rate mol/m.y. mmol/m.y. umol/m.y. nmol/m.y.
kg/m.y. g/m.y. mg/m.y. ug/m.y.
ng/m.y.
cm3/m.y. m3/m.y. l/m.y. gal/m.y.
ft3/m.y.
mol/cm3/s mmol/cm3/s umol/cm3/s nmol/cm3/s
kg/cm3/s g/cm3/s mg/cm3/s ug/cm3/s
ng/cm3/s
cm3/cm3/s volume%/s
mol/cm3/min mmol/cm3/min umol/cm3/min nmol/cm3/min
kg/cm3/min g/cm3/min mg/cm3/min ug/cm3/min
ng/cm3/min
cm3/cm3/min volume%/min
mol/cm3/hr mmol/cm3/hr umol/cm3/hr nmol/cm3/hr
kg/cm3/hr g/cm3/hr mg/cm3/hr ug/cm3/hr
ng/cm3/hr
cm3/cm3/hr volume%/hr
mol/cm3/day mmol/cm3/day umol/cm3/day nmol/cm3/day
kg/cm3/day g/cm3/day mg/cm3/day ug/cm3/day
ng/cm3/day
cm3/cm3/day volume%/day
mol/cm3/yr mmol/cm3/yr umol/cm3/yr nmol/cm3/yr
kg/cm3/yr g/cm3/yr mg/cm3/yr ug/cm3/yr
ng/cm3/yr
cm3/cm3/yr volume%/yr
mol/cm3/m.y. mmol/cm3/m.y. umol/cm3/m.y. nmol/cm3/m.y.
kg/cm3/m.y. g/cm3/m.y. mg/cm3/m.y. ug/cm3/m.y.
ng/cm3/m.y.
cm3/cm3/m.y. volume%/m.y.
mol/m3/s mmol/m3/s umol/m3/s nmol/m3/s
kg/m3/s g/m3/s mg/m3/s ug/m3/s
ng/m3/s
m3/m3/s
mol/m3/min mmol/m3/min umol/m3/min nmol/m3/min
kg/m3/min g/m3/min mg/m3/min ug/m3/min
ng/m3/min
m3/m3/min
405
GWB Reference Manual
Dimension Units
Reaction Rate mol/m3/hr mmol/m3/hr umol/m3/hr nmol/m3/hr
kg/m3/hr g/m3/hr mg/m3/hr ug/m3/hr
ng/m3/hr
m3/m3/hr
mol/m3/day mmol/m3/day umol/m3/day nmol/m3/day
kg/m3/day g/m3/day mg/m3/day ug/m3/day
ng/m3/day
m3/m3/day
mol/m3/yr mmol/m3/yr umol/m3/yr nmol/m3/yr
kg/m3/yr g/m3/yr mg/m3/yr ug/m3/yr
ng/m3/yr
m3/m3/yr
mol/m3/m.y. mmol/m3/m.y. umol/m3/m.y. nmol/m3/m.y.
kg/m3/m.y. g/m3/m.y. mg/m3/m.y. ug/m3/m.y.
ng/m3/m.y.
m3/m3/m.y.
mol/kg/s mmol/kg/s umol/kg/s nmol/kg/s
g/kg/s mg/kg/s ug/kg/s ng/kg/s
cm3/kg/s
mol/kg/min mmol/kg/min umol/kg/min nmol/kg/min
g/kg/min mg/kg/min ug/kg/min ng/kg/min
cm3/kg/min
mol/kg/hr mmol/kg/hr umol/kg/hr nmol/kg/hr
g/kg/hr mg/kg/hr ug/kg/hr ng/kg/hr
cm3/kg/hr
mol/kg/day mmol/kg/day umol/kg/day nmol/kg/day
g/kg/day mg/kg/day ug/kg/day ng/kg/day
cm3/kg/day
mol/kg/yr mmol/kg/yr umol/kg/yr nmol/kg/yr
g/kg/yr mg/kg/yr ug/kg/yr ng/kg/yr
cm3/kg/yr
mol/kg/m.y. mmol/kg/m.y. umol/kg/m.y. nmol/kg/m.y.
g/kg/m.y. mg/kg/m.y. ug/kg/m.y. ng/kg/m.y.
cm3/kg/m.y.
Flow Rate cm3/s m3/s l/s gal/s
ft3/s
cm3/min m3/min l/min gal/min
ft3/min
406
Units Recognized
Dimension Units
Flow Rate cm3/hr m3/hr l/hr gal/hr
ft3/hr
cm3/day m3/day l/day gal/day
ft3/day
cm3/yr m3/yr l/yr gal/yr
ft3/yr
cm3/m.y. m3/m.y. l/m.y. gal/m.y.
ft3/m.y.
Velocity mm/s cm/s m/s km/s
mm/hr cm/hr m/hr km/hr
mm/day cm/day m/day km/day
mm/mon cm/mon m/mon km/mon
mm/yr cm/yr m/yr km/yr
mm/m.y. cm/m.y. m/m.y. km/m.y.
in/s ft/s mi/s
in/hr ft/hr mi/hr
in/day ft/day mi/day
in/mon ft/mon mi/mon
in/yr ft/yr mi/yr
in/m.y. ft/m.y. mi/m.y.
Specific cm3/cm2/s m3/m2/s ft3/ft2/s
Discharge cm3/cm2/hr m3/m2/hr ft3/ft2/hr
cm3/cm2/day m3/m2/day ft3/ft2/day
cm3/cm2/mon m3/m2/mon ft3/ft2/mon
cm3/cm2/yr m3/m2/yr ft3/ft2/yr
cm3/cm2/m.y. m3/m2/m.y. ft3/ft2/m.y.
Density kg/cm3 g/cm3 mg/cm3 ug/cm3
ng/cm3
kg/m3 g/m3 mg/m3 ug/m3
ng/m3
Titration eq_acid meq_acid ueq_acid neq_acid
Alkalinity eq_acid/kg meq_acid/kg ueq_acid/kg neq_acid/kg
eq_acid/l meq_acid/l ueq_acid/l neq_acid/l
g/kg_as_CaCO3 mg/kg_as_CaCO3 ug/kg_as_CaCO3 ng/kg_as_CaCO3
wt%_as_CaCO3
g/l_as_CaCO3 mg/l_as_CaCO3 ug/l_as_CaCO3 ng/l_as_CaCO3
mmol/l_as_CaCO3
407
GWB Reference Manual
Dimension Units
Titration Acidity eq_base meq_base ueq_base neq_base
eq_base/kg meq_base/kg ueq_base/kg neq_base/kg
eq_base/l meq_base/l ueq_base/l neq_base/l
Sorption Capacity mol/grock mmol/grock umol/grock nmol/grock
Exchange Capacity eq/grock meq/grock ueq/grock neq/grock
Pore Volumes pore_volumes
Dynamic Viscosity cp poise
Pressure Pa MPa atm bar
psi
Permeability m2 cm2 um2
darcy mdarcy udarcy
Diffusion/Dispersion cm2/s m2/s
Coefficients
Distribution l/kg ml/g ml/mg
Coefficients (KDs)
Activity Coefficients act. coef.
Electrical uS/cm umho/cm
Conductivity
Energy J kJ cal kcal
Energy Content J/mol kJ/mol cal/mol kcal/mol
Heat Capacity J/g/C J/kg/K cal/g/C
Thermal Conductivity W/cm/C W/m/K cal/cm/s/C cal/m/s/C
Internal Heat Source J/cm3/s J/cm3/yr J/m3/s J/m3/yr
cal/cm3/s cal/cm3/yr cal/m3/s cal/m3/yr
W/cm3 W/m3
Thermal W/C W/K J/s/C J/s/K
Transmissivity cal/s/C cal/s/K
Percent Removal % removal
Saturation Q/K
Deuterium (2H) SMOW2H
408
Units Recognized
Dimension Units
Tritium (3H) TU
Foaming Agents g/l mg/l ug/l ng/l
Carbon 13 PDB
Percent Modern PMC
Carbon
Oxygen Demand g/l mg/l ug/l ng/l
Oxygen 18 SMOW18O
Sulfur 34 CDT
Odor TON
Turbidity NTU
Corrosivity Cor
Colonies per Volume colonies/ml
Radioactive Emission pCi/l
per Volume
Radioactive Exposure mrem/yr
over Time
Temperature C F K R
Angle radians degrees
Color CU
Number number
Text text
409
410
Index
acidity, 408Act2 commands, 27activity, 5, 27, 53, 78, 111, 165, 223, 320, 404activity coefficients, data for calculating, 288add, 5, 27, 53, 79, 111, 165, 223alkalinity, 79, 111, 165, 223, 320, 407alter, 6, 28, 54, 79, 111, 166, 224angle, 409appendices, 2aqueous species, in thermodynamic dataset,
290, 292audit, 166, 224
background, 28, 54balance, 80, 112, 166, 224banner, 28, 54basis, 320biomass, 320block, 6boltzman, 320bottom, 225bulk_volume, 320
C++ plugin, 338C++ program, 398, 400C++ programs, 341calculation procedure, multiple analyses, 393calculator, 299carbon, 112, 409cat_area, 320charge, 320chdir, 6, 29, 55, 80, 113, 167, 226chlorinity, 320clear, 7, 29, 55, 80, 113, 167, 226clipboard, 7, 29, 55, 80, 113, 167, 226, 303coef_dispersion, 320colonies per volume, 409
color, 409color_by_sample, 29, 55command reference, 1concentration, 320, 403conductivity, 81, 113, 167, 226control script, example, 335control scripts, 333control statements in scripts, 334corrosivity, 409couple, 7, 30, 56, 81, 114, 168, 227couples, 320Courant, 168, 227cpr, 114, 169, 228cpu_max, 115, 169, 228cpw, 115, 169, 228custom, 30, 56custom plugin, 386
data, 7, 30, 56, 81, 115, 170, 229debyehuckel, 82, 116, 170, 229decouple, 8, 31, 57, 82, 116, 170, 229delQ, 116, 171, 230deltar, 171, 230Deltat, 320deltax, 171, 230deltay, 231delxi, 117, 172, 232density, 82, 117, 172, 232, 407deuterium (2H), 408diagram, 31, 57diffusion and dispersion coefficients, 408diffusion_coef, 173, 233discharge, 173, 233, 320dispersivity, 174, 235distance, 404distribution coefficients, 408
411
Index
dual_porosity, 83, 118, 174, 235dump, 119dx_init, 120, 176, 237dxplot, 120, 176, 237dxprint, 120, 177, 238
EC, 320Eh, 8, 32, 58, 84, 121, 178, 238, 320electrical conductivity, 408electrical potential, 404elements, 320elements, in thermodynamic dataset, 289enddump, 121energy, 408energy content, 408epsilon, 84, 121, 178, 239equil_eqn, 322equil_favors, 322equil_temp, 322exchange capacity, 408exchange_capacity, 84, 121, 178, 239explain, 9, 32, 58, 85, 122, 179, 240explain_step, 122, 179, 240extrapolate, 32, 58, 85, 123, 179, 240
FA, 322factor, 9FD, 322fix, 123, 180, 241flash, 124flow rate, 406, 407flowthrough, 124flush, 124foaming agents, 409font, 33, 59font for data markers, 306Fortran plugin, 347Fortran programs, 351free electron, in thermdynamic dataset, 293freeflowing, 322fugacity, 9, 33, 59, 86, 125, 180, 241, 322,
404
gamma, 322gases, 33, 59, 322gases, in thermodynamic dataset, 293get_default_units, 322get_units, 322go, 10, 34, 60, 86, 125, 181, 241
graphics output, 303grep, 34, 60, 86, 125, 181, 242gridlines, 34, 60gtplot, 87, 126
hmw, 87, 126, 182, 242hardness, 322hardness_carb, 322hardness_ncarb, 322head_drop, 182, 243heat capacity, 408heat source, 408heat_source, 126, 183, 244height, 183, 244help, 10, 35, 61, 87, 127, 184, 245help pages, 300history, 10, 35, 61, 87, 127, 184, 245history substitution, 298hyd_pot, 322hydrogen, 127
imbalance, 322imbalance_error, 322inert, 88, 128, 184, 245inert_volume, 322interval, 185, 246ionic_strength, 11IS, 322isotope, 128itmax, 88, 128, 185, 246itmax0, 129
Java plugin, 357Java programs, 360
Kd, 88, 129, 186, 247keyboard shortcuts, 301kinetic, 129, 186, 247
labels, 35, 61left, 191, 252legacy formats, thermodynamic datasets, 295legend, 35, 61length, 192, 253line, 36, 62log, 11, 36, 62, 89, 134, 192, 253logfO2, 322logk, 322logks, 322
412
Index
logQoverK, 324long, 11
mass, 324mass_reacted, 324mass_remaining, 324MATLAB plugin, 379MATLAB programs, 383minerals, 37, 63, 324minerals, in thermodynamic dataset, 293mobility, 89, 134, 192, 253modflow, 255molality, 12mosaic_bounds, 37, 63mosaic_labels, 37, 63multiple analyses, 393multiple analyses, example calculation, 394mv, 324mw, 324
named pipes, 400nbasis, 324ncouples, 324nelements, 324ngases, 324nlogks, 324nminerals, 324Nnode, 324noprecip, 135, 193, 256nreactants, 324nsorbed, 324nsorbing_surfaces, 326nspecies, 326nsurf_species, 326nswap, 135, 194, 256nswap0, 135Nx, 194, 256, 326Ny, 256, 326
odor, 409offdiag, 257options, 326output, 12oxide components, in thermodynamic
dataset, 294oxygen, 136, 409oxygen demand, 409
paper, 38, 64
pause, 12, 39, 64, 90, 136, 194, 257pe, 12, 39, 64, 90, 136, 194, 257, 326percent removal, 408Perl plugin, 365Perl programs, 368Perl script, 402permeability, 90, 137, 195, 257, 326, 408pH, 13, 39, 65, 91, 138, 196, 258, 326, 404phrqpitz, 92, 138, 196, 259pickup, 138pitz_dgamma, 92, 139, 196, 259pitz_precon, 92, 139, 197, 259pitz_relax, 93, 140, 197, 260pitzer, 93, 140, 197, 260Pitzer coefficients, in thermodynamic
dataset, 294plot, 93, 140, 198, 260plugin feature, 337, 338, 347, 351, 357,
365, 372, 379, 386pluses, 141, 198, 261PMC, 409polyfit, 326polymorphs, 13, 40, 65, 94, 141, 198, 261pore volumes, 408porosity, 94, 141, 199, 261, 326precip, 142, 199, 262pressure, 40, 65, 326, 408print, 40, 66, 94, 142, 200, 262PV, 326pwd, 14, 41, 66, 95, 143, 200, 263Python plugin, 372Python programs, 375
Q/K, 408QoverK, 326quit, 14, 41, 66, 95, 143, 201, 263
radial, 201, 263radioactive emission per volume, 409radioactive exposure over time, 409rate_con, 326ratio, 14, 41, 67, 96, 143, 201, 264react, 15, 144, 202, 264React commands, 109reactant_area, 326reactants, 145, 326reaction, 326reaction rate, 404–406read, 15, 41, 67, 96, 145, 203, 266
413
Index
redox coupling reactions, in thermodynamicdataset, 290
remote control, 397remove, 16, 42, 67, 96, 146, 203, 266report, 16, 97, 146, 204, 267report command, 317reset, 16, 42, 68, 97, 146, 204, 267results, 340, 349, 359, 367, 374, 381, 389resume, 17, 42, 68, 97, 147, 205, 268reverse, 17right, 205, 268rock_mass, 326rock_volume, 326Rxn commands, 5rxn_rate, 328
save, 17, 43, 68, 98, 147, 206, 269saving images, 304scatter, 43, 68scatter data, 307scope, 206, 270script, 17, 43, 69, 98, 147, 207, 271scripts, interaction with application, 334segregate, 148set_digits, 328set_node, 328set_units, 328short, 18show, 18, 44, 69, 98, 149, 208, 271SI, 324simax, 99, 149, 208, 272Sionst, 328SIS, 328slide, 150, 209, 272soln_density, 328soln_mass, 328soln_viscosity, 328soln_volume, 328sorb_area, 328sorbate, 99, 150, 209, 273sorbed, 328sorbed_mass, 19sorbing_surfaces, 328sorption capacity, 408SpecE8 commands, 77special characters, 299speciate, 45, 70species, 328specific discharge, 407
spelling completion, 297spherical, 210stagnant, 328start_date, 151, 210, 273start_time, 151, 210, 273startup files, 300step_increase, 151, 211, 274step_max, 152, 211, 274stoich_IS, 19success, 328suffix, 20, 45, 70, 100, 152, 211, 274sulfur, 152, 409suppress, 46, 71, 100, 153, 212, 275surf_charge, 328surf_potential, 328surf_species, 328surface_capacitance, 20, 100, 153, 212, 275surface_charge, 21surface_data, 21, 101, 154, 213, 276surface_potential, 22, 102, 154, 213, 276swap, 22, 46, 71, 102, 155, 214, 277system, 23, 47, 72, 103, 155, 214, 277system commands, 300
Tact commands, 53TC, 328Tcl license agreement, 336Tcl script, 401TDS, 103, 156, 215, 278, 328Tempc, 328temperature, 23, 47, 103, 156, 215, 278,
328, 409temps, 328Tend, 328text size in the GWB windows, 301thermal conductivity, 408thermal transmissivity, 408thermal_cond, 216, 279thermodynamic datasets, 287theta, 157, 216, 279threads, 217, 280timax, 104, 157, 217, 280Time, 328time, 157, 217, 280, 404Tionst, 322title, 47, 72, 104, 158, 218, 281TK, 330top, 281total_biomass, 330
414
Index
total_reacted, 330TPF, 330trace, 48, 73tritium (3H), 409Tstart, 330turbidity, 409
unalter, 24, 48, 73, 104, 158, 218, 282unit, 77, 109, 163, 221unit conversion, 403unnamed pipes, 398, 401, 402unsegregate, 158unspeciate, 49, 73unsuppress, 49, 74, 105, 159, 218, 282unswap, 24, 50, 74, 105, 159, 219, 283user interface, 297usgovt, 25, 50, 75, 106, 159, 219, 283
velocity, 330, 407virial coefficients, in thermodynamic dataset,
294viscosity, 408volume, 106, 160
Watact, 330water_limits, 50, 75watertype, 330well, 283width, 219, 285Wmass, 330
xaxis, 51, 75X1t commands, 163X2t commands, 221xcoef_dispersion, 330xdischarge, 330Xfree, 330Xi, 330xpermeability, 330xsorbed, 330Xstable, 220, 286xtplot, 220, 285xvelocity, 330xycoef_dispersion, 330
yaxis, 51, 76ycoef_dispersion, 330ydischarge, 330ypermeability, 330yvelocity, 330
415