forked from usgs-coupled/webmod
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.TXT
396 lines (288 loc) · 16.9 KB
/
README.TXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
README.TXT
Current versions of this file and the software are available at
https://doi.org/10.5066/F7P26W9K
Water, Energy, and Biogeochemical Model (WEBMOD)
This file describes three batch versions of WEBMOD for Windows and Linux: (1) A
Windows version with a compiled executable, (2) A Linux version with a compiled
executable, and (3) Source code that can be compiled by a Makefile generated by
configure or CMake.
All distributions contain a compiled Java jar executable that can be used as a
graphical user interface to WEBMOD. The interface is a modified version of the
MMS Tool which has a feature called the Parameter Tool as described in the
following:
Markstrom, S.L., and Koczot, K.M., 2008, User’s manual for the object user
interface (OUI)—An environmental resource modeling framework: U.S. Geological
Survey Open File Report 2008–1120, 39 p.
[Also available at http://pubs.usgs.gov/of/2008/1120/.]
Input files are all ASCII files that can be edited with a text editor such as
Notepad or Notepad++. The Notepad++ interface has the additional advantage of
syntax highlighting for PHREEQC input files such as webmod.pqi.
Notepad++ is available at http://www.hydrochemistry.eu/downl.html.
Alternatively, input for two projects, Andrews Creek and DR2 Drain, are
included in the project directories as macro-enabled Microsoft workbooks,
Andrews.xlsm and dr2.xlsm, and can be written to ASCII using the included
macro ExportText.
TABLE OF CONTENTS
A. Distribution files
B. Documentation
C. Installing the Windows batch version of WEBMOD with executable
D. Compiling and installing the Windows batch version of WEBMOD without executable
E. Compiling and installing the Linux batch version of WEBMOD
F. Running WEBMOD
G. Description of three projects
H. Contacts
-----------------------------------------------------------------------------------
A. Distribution files
-----------------------------------------------------------------------------------
The following distribution packages of the batch version of WEBMOD are available
for Windows and Linux:
webmod-@VERSION@-@[email protected] Windows GUI and CLI for running WEBMOD models.
64-bit executable compiled using Microsoft
Visual C++ 2012 and Intel Visual Fortran
2013.
webmod-@VERSION@-@[email protected] Linux GUI and CLI for running WEBMOD models.
64-bit executable compiled using GNU g++
and gfortran 4.8.4.
webmod-@VERSION@-@[email protected] WEBMOD source code.
Requires compilation using configure
or CMake.
-----------------------------------------------------------------------------------
B. Documentation
-----------------------------------------------------------------------------------
Citation for the WEBMOD User's Manual:
Webb, R.M.T., and Parkhurst, D.L., 2017, Water, Energy, and Biogeochemical
Model (WEBMOD), user’s manual, version 1: U.S. Geological Survey Techniques
and Methods, book 6, chap. B35, 171 p., https://doi.org/10.3133/tm6B35.
The Users Manual will be located in .\Distribution\doc\
tm6b35.pdf
Before attempting to simulate chemical reactions in WEBMOD, the chemistry
input file webmod.pqi must run successfully in PHREEQC using the database
phreeqc_web_lite.dat. Therefore the following citations of PHREEQC will
aid the uninitiated:
Parkhurst, D.L., and Appelo, C.A.J., 2013, Description of input and examples
for PHREEQC version 3--A computer program for speciation, batch-reaction,
one- dimensional transport, and inverse geochemical calculations: U.S.
Geological Survey Techniques and Methods, book 6, chap. A43, 497 p.
http://pubs.usgs.gov/tm/06/a43/.
Parkhurst, D.L., and Appelo, C.A.J., 1999, User's guide to PHREEQC (Version
2)-- A computer program for speciation, batch-reaction, one-dimensional
transport, and inverse geochemical calculations: U.S. Geological Survey
Water-Resources Investigations Report 99-4259, 312 p.
http://pubs.er.usgs.gov/publication/wri994259.
Charlton, S.R., and Parkhurst, D.L., 2002, PhreeqcI--A graphical user interface
to the geochemical model PHREEQC: U.S. Geological Survey Fact Sheet
FS-031-02, 2 p.
-----------------------------------------------------------------------------------
C. Installing the Windows batch version of WEBMOD with executable
-----------------------------------------------------------------------------------
Installing consists of extracting the distribution from the webmod-@VERSION@-@[email protected]
file using 7-Zip or Windows built-in "Extract-All..." tool. The "Extract-All..." tool
can be accessed by right-clicking on the zip file. 7-Zip is available at
http://www.7-zip.org.
The zip file contains a top-level directory (webmod-@VERSION@-@REVISION@-x64) which includes
the following subdirectories:
bin\
doc\
lib\
projects\
-----------------------------------------------------------------------------------
D. Compiling and installing the Windows batch version of WEBMOD without executable
-----------------------------------------------------------------------------------
In general, to compile WEBMOD, you will need:
(a) CMake (build process manager)
(b) a C++ compiler,
(c) a Fortran compiler,
(d) familiarity with the compiler and the Windows operating system.
D.1. Download and install CMake
CMake can be downloaded from http://www.cmake.org/. If you download the
executable, CMake is installed when you execute it.
D.2. Extract the distribution file webmod-@VERSION@-@[email protected]
The directory webmod-@VERSION@-@REVISION@ is created when the files are
extracted; if this directory already exists, you may want to delete or rename it
before extracting the files.
The following directory structure is created (the contents of each directory are
shown to the right):
webmod-@VERSION@-@REVISION@ Files related to CMake
`--config Files used by configure on linux systems
`--Distribution Examples from user's guide--limited version of Andrews used in verification test
`--doc Documentation files
`--IPhreeqcMMS IPhreeqc source code
`--lib Java classes for MMS Tool and Parameter Tool GUIs
`--m4 m4 source code used by autoconf
`--mmf_c MMF source code
`--webmod.d WEBMOD Source code
`--Tests Files used to test the compilation
D.3. Generate a Visual Studio solution
CMake has many options other than Visual Studio, but here we assume that you are
using some version of Visual Studio. On the first use of CMake, it may be
necessary to close all Visual Studio instances.
Open CMake.
Fill in the top two lines:
Where is the source code:
The top level directory (ie c:/webmod-@VERSION@-@REVISION@).
Where to build the binaries:
A new directory. It is suggested that the name of the directory include
the characteristics of the library that is built, including the VS
version, and 32/64 bit, such as VS2012_x64.
Click Configure.
From the pulldown menu of the cmake-gui popup, select the 64-bit version
for your Visual Studio. Normally, the default radio button should be
sufficient. Click Finish.
Options in the top panel:
(1) CMAKE_INSTALL_PREFIX--Sets the the install directory where the
compiled program and example input files will be saved. It is
suggested that an INSTALL directory be defined inside the directory
chosen for the binaries.
Click Configure until the screen is not red. If the screen remains red, you will
have to deal with the CMake error messages.
Click Generate.
You should now have a Visual Studio solution file (.sln) in the directory chosen
for the binaries (second line of CMake screen). At any point, you can delete the
contents of the directory and start over. You can make solutions for different
Visual Studios, or different options in other directories.
D.4. Compile and install WEBMOD
Open the Visual Studio solution in the build directory defined in CMake.
The default configuration is "Debug". If you want a release version
change the configuration to "Release".
Build ALL_BUILD.
IPhreeqc is compiled.
mmf is compiled.
webmod is compiled.
all modules and libraries are linked and webmod executable created.
Build RUN_TESTS. Programs that test webmod are compiled and run.
Build INSTALL.
The executables, WEBMOD database files, and documentation are installed in the
install directory selected in CMake (denoted "install" in the following
descriptions).
Install:
README.txt this readme file
NOTICE.txt User rights notice
Install\bin directory:
Subdirectories with executables
Install\lib files:
Java archive files used to run the GUI
Install\doc files:
Manual for WEBMOD version 1
Install\projects directory:
Example input files from the user's manual
-----------------------------------------------------------------------------------
E. Compiling and installing the Linux batch version of WEBMOD
-----------------------------------------------------------------------------------
No support beyond this README file is provided for users compiling their own
versions of the software. In general, to compile the software, you will need:
(a) a C++ compiler, and
(b) a Fortran compiler, and
(c) a minimal level of knowledge of configure, Make, the compiler, and
the Linux operating system.
A Makefile can be generated by configure, and the Makefile can be used to
compile, test, and install the software.
E.1. Extracting the files
Follow the steps below to extract the files from a distribution tar file.
Steps in extracting files Explanation
---------------------------------------- -----------------------------------
gunzip webmod-@VERSION@-@[email protected] Uncompress the tar.gz file.
tar -xvpof webmod-@VERSION@-@[email protected] Extract files from the tar file.
The directory webmod-@VERSION@-@REVISION@ is created when the files are
extracted; if this directory already exists, you may want to delete or rename it
before extracting the files.
The following directory structure is created (the contents of each directory are
shown to the right):
webmod-@VERSION@-@REVISION@ Files related to configure
`--config More configure files
`--Distribution Examples from user's guide--limited version of Andrews used in verification test
`--doc Documentation files
`--IPhreeqcMMS IPhreeqc source code
`--m4 m4 source code used by autoconf
`--mmf_c MMF source code
`--webmod.d WEBMOD Source code
`--Tests Files used to test the compilation
Notes: (a) A compiled executable is not included in the source distribution.
(b) It is recommended that no user files be kept in the WEBMOD directory
structure.
E.2. Change directory to the directory that was extracted from the tar file.
cd webmod-@VERSION@-@REVISION@
E.3. Make a directory, for example, Release.
mkdir Release
E.4. Change directory to Release.
cd Release
E.5. Run configure
Many of the options for configure can be seen by typing:
../configure --help
The most common option: --prefix=dir specifies the directory for installation of
the library. Default is /usr/local, $HOME would install to your home directory.
Run configure as follows:
../configure [options]
E.6. Compile the program
make [-j n]
Optionally, use -j n--where n is the number of compilations make runs in parallel.
E.7. Check that compiled version runs the test cases.
Check may take several minutes.
make check
Results of running the test cases are stored in the directory Release/test
E.8. Install the program.
By default the program is installed in /usr/local/bin and
/usr/local/share/doc/webmod. You can specify an installation prefix other than
"/usr/local" by using the prefix option, --prefix=$HOME for example.
make install
The locations of various files are given below, where "install" is the
installation directory, /usr/local by default, or the value given by the --prefix
option to configure.
Executable:
install/bin/webmod
Documentation:
install/share/doc/webmod
tm6b35.pdf Manual for WEBMOD version 1.0
README.TXT this readme file
Three project directories:
install/share/doc/webmod/projects
Input files for 3 examples documented in the manual
-----------------------------------------------------------------------------------
F. Running WEBMOD
-----------------------------------------------------------------------------------
The WEBMOD executable is installed in the .\bin\ directory. if .\bin\ is in the PATH,
then WEBMOD can be executed in a command window from a selected .\projects directory
such as .\projects\Andrews\ with the following command
webmod -C.\control\webmod.control
The WEBMOD simulation will then be run using inputs and outputs specified in the control
file .\projects\Andrews\control\webmod.control
Alternatively, WEBMOD can be run by a script on Linux (*.sh) or a batch file on Windows (*.bat).
The scripts and batch files are run in the selected \projects\ directory. ie. .\projects\Andrews.
command explanation
----------------------------- -----------------------------------------
webmod.bat or Prints model self-documentation to \control\
webmod.sh directory then runs WEBMOD simulation as
instructed in \control\webmod.control.
webmod_gui.bat or Prints model self-documentation to \control\
webmod_gui.sh directory then begins an interactive session
of WEBMOD simulation using the MMS Tool GUI.
webmod.paramtool.bat or Prints model self-documentation to \control\
webmod.paramtool.sh directory then begins an interactive session
to review and modify WEBMOD parameters using
the Param Tool GUI.
webmod_print.bat or Prints self-documentation files in \control\
webmod_print.sh directory
-----------------------------------------------------------------------------------
G. Description of .\projects\
-----------------------------------------------------------------------------------
Three projects are included with the Distribution. Andrews, DR2, and Andrews_tutorial.
As described in WEBMOD manual.
Andrews\ simulates hydrology and geochemisty for the Andrews Creek watershed in Rocky
Mountain National Park in Colorado. Input chemistry varies as described by biweekly
sampling by the National Atmospheric Deposition Program.
DR2\ simulates hydrology and specific conductivity using chloride as a proxy for specific
conductivity. Precipitation, canal irrigation, and upgradient groundwater are all
assigned constant concentrations as described in .\input\webmod.pqi
Andrews_tutorial\ The project Andrews_tutorial is a deliberately miscalibrated version of
Andrews. As detailed in the User’s Manual in the section “Quick Start Guide > Andrews
Creek simulation and calibration”, the user is instructed to modify two hydrologic
parameters in Andrews_tutorial\input\webmod.params, rain_adj and snow_adj, to better
match observed streamflow, turn on geochemical simulations(chem_sim=1), then modify
the surface to volume ratios in Andrews_tutorial\input\webmod.pqi that determines the
weathering rate of of oligoclase. Upon completion of the 45 steps, the output files in
Andrews_tutorial\output\ will be identical to those in Andrew\output\ after execution
of the WEBMOD simulation in that project directory.
-----------------------------------------------------------------------------------
H. Contacts
-----------------------------------------------------------------------------------
Inquiries about this software distribution should be directed to:
e-mail: [email protected] or [email protected]