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@-@REVISION@-x64.zip         Windows GUI and CLI for running WEBMOD models.
                                                 64-bit executable compiled using Microsoft
						 Visual C++ 2012 and Intel Visual Fortran
						 2013.

webmod-@VERSION@-@REVISION@-x64.tar.gz      Linux GUI and CLI for running WEBMOD models.
                                                 64-bit executable compiled using GNU g++
						 and gfortran 4.8.4.

webmod-@VERSION@-@REVISION@.tar.gz          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@-@REVISION@-x64.zip
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@-@REVISION@.tar.gz
  
   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@-@REVISION@.source.tar.gz    Uncompress the tar.gz file.
 
   tar -xvpof webmod-@VERSION@-@REVISION@.source.tar   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:  h2osoft@usgs.gov or rmwebb@usgs.gov