iphreeqc/README.Phreeqc.TXT

README.TXT

                                PHREEQC

       A program for speciation, batch-reaction, one-dimensional 
            transport, and inverse geochemical calculations

This file describes three batch versions of PHREEQC for Windows and Linux: (1) A
Windows version with a compiled executable, (2) A Windows version that has source
code that can be compiled with Visual Studio solutions that are generated by CMake,
and (3) A Linux version with source code that can be compiled by a Makefile generated
by configure. For Linux, there is no version with an executable, and compilation is
required.

No graphical user interface exists for Linux. (For Windows, a graphical user
interface, PhreeqcI, is available at
http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/index.html and a
Notepad++ interface is available at http://www.hydrochemistry.eu/downl.html.)


    TABLE OF CONTENTS

    A. Distribution files
    B. Documentation
    C. Installing the Windows batch version of PHREEQC with executable
    D. Compiling and installing the Windows batch version of PHREEQC without executable
    E. Compiling and installing the Linux batch version of PHREEQC 
    F. Running PHREEQC
    G. Description of test cases
    H. Contacts

-----------------------------------------------------------------------------------
A. Distribution files
-----------------------------------------------------------------------------------

   The following distribution packages of the batch version of PHREEQC are available
   for Windows and Linux:
    
phreeqc-@VERSION@-@REVISION@.msi         64-bit batch version with executable
				compiled by using Microsoft Visual C++ 2005
phreeqc-@VERSION@-@REVISION@.zip         For compilation on Windows					 
phreeqc-@VERSION@-@REVISION@.tar.gz      For compilation on Linux

-----------------------------------------------------------------------------------
B. Documentation
-----------------------------------------------------------------------------------

   *The following two user's guides are available in electronic format. Portable
   Document Format (PDF) files are included in the doc subdirectory of the
   PHREEQC program distribution.
   
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.


   *The following two reports document the theory and implementation of
   isotopes in PHREEQC. Portable Document Format (PDF) of Thorstenson and
   Parkhurst (2002) is included in the doc subdirectory of the PHREEQC program
   distribution.

Thorstenson, D.C., and Parkhurst, D.L., 2002, Calculation of individual isotope
   equilibrium constants for implementation in geochemical models: U.S.
   Geological Survey Water-Resources Investigations Report 02-4172, 129 p.
   http://pubs.er.usgs.gov/publication/wri024172.

Thorstenson, D.C., and Parkhurst, D.L., 2004, Calculation of individual isotope
   equilibrium constants for geochemical reactions: Geochimica et Cosmochimica
   Acta, v. 68, no. 11, p. 2449-2465.
   
   *Brief description of the program PhreeqcI.

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 PHREEQC with executable
-----------------------------------------------------------------------------------

Note: the person installing the software generally must have administrator 
rights. 

To install the batch version, double-click phreeqc-@VERSION@-@REVISION@.msi to
execute the installation program and follow the directions on the screen. The batch
version is completely independent from the GUI version.

Default installation is in the directory:
C:\Program Files\USGS\phreeqc-@VERSION@-@REVISION@-x64

which includes subdirectories:
   bin\
   database\
   doc\
   examples\
   src\
   test\

The installation sets environmental variables PATH, PATH_PHREEQC, and PHREEQC_ROOT.
    
-----------------------------------------------------------------------------------   
D. Compiling and installing the Windows batch version of PHREEQC without executable
-----------------------------------------------------------------------------------

In general, to compile the IPhreeqc library, you will need:

   (a) CMake (build process manager)
   (b) a C++ compiler,
   (c) 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. Unzip the distribution file phreeqc-@VERSION@-@REVISION@.zip
  
   The directory phreeqc-@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):

   phreeqc-@VERSION@-@REVISION@      Files related to CMake
     `--database    Database files required during execution
     `--doc         Documentation files 
     `--examples    Examples from user's guide--used in verification tests
     `--src         Source code
     `--test        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:/phreeqc-@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 
             library and header 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 PHREEQC
 
   Open the Visual Studio solution in the build directory defined in CMake.
 	
   The default configuration is "Debug". If you want a release libraries
   (or dlls) and examples,	change the configuration to "Release".
 
   Build ALL_BUILD. 
      IPhreeqc is compiled.
 
   Build RUN_TESTS. Programs that test IPhreeqc are compiled and run, and optionally
   (CMake IPHREEQC_FORTRAN_TESTING option) the Fortran test project.
 	
   Build INSTALL. 
      The executables, PHREEQC database files, and documentation are installed in the
      install directory selected in CMake (denoted "install" in the following
      descriptions).
      
   Install:
      RELEASE.txt                           Release notes
      README.txt                            this readme file
      NOTICE.txt                            User rights notice
 
   Install\bin directory:
      Subdirectories with executables

   Install\Database files:
      Amm.dat
	  ColdChem.dat
	  core10.dat
      frezchem.dat
      iso.dat
      llnl.dat
      minteq.dat
      minteq.v4.dat
      phreeqc.dat
      pitzer.dat
      sit.dat
	  Tipping_Hurley.dat
      wateq4f.dat
 				
   Install\doc files:
      Phreeqc_3_2013_manual.pdf         Manual for PHREEQC version 3
      Phreeqc_2_1999_manual.pdf         Manual for PHREEQC version 2
      phreeqc.txt                       Short explanation for PHREEQC
      phreeqc3.chm                      Latest PHREEQC documentation
      wrir02-4172.pdf                   Documenation of isotope calculations
    
   Install\examples files:
      Input files for the 22 examples described in the version 3 manual
 
   Note: In order to use the CLR version (Charting) the Zedgraph.dll file must be
   registered either by installing the Phreeqc batch version with executable or the
   PhreeqcI MSI, or through the use of the Visual Studio Tool gacutil.
  
-----------------------------------------------------------------------------------   
E. Compiling and installing the Linux batch version of PHREEQC 
-----------------------------------------------------------------------------------

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 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 phreeqc-@VERSION@-@REVISION@.source.tar.gz           Uncompress the tar.gz file.
 
   tar -xvpof phreeqc-@VERSION@-@REVISION@.source.tar          Extract files from the tar file.

   The directory phreeqc-@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):

   phreeqc-@VERSION@-@REVISION@      Files related to configure
     `--config      More configure files
     `--database    Database files required during execution
     `--doc         Documentation files 
     `--examples    Examples from user's guide--used in verification tests
     `--src         Source code
     `--test        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 PHREEQC directory
	    structure.

E.2.  Change directory to the directory that was extracted from the tar file.

      cd phreeqc-@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/phreeqc. 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/phreeqc
        
   Documentation:
        
      install/share/doc/phreeqc
         Phreeqc_3_2013_manual.pdf         Manual for Phreeqc version 3
         Phreeqc_2_1999_manual.pdf         Manual for Phreeqc version 2
         wrir02-4172.pdf                   Documenation of isotope calculations
         phreeqc.txt                       Short explanation for Phreeqc
         RELEASE                           Release notes
         README                            this readme file
         NOTICE                            User rights notice
         phreeqc3.chm                      Compiled HTML documentation
    
    Databases: 
    
      install/share/doc/phreeqc/database
         Amm.dat
         frezchem.dat
         iso.dat
         llnl.dat
         minteq.dat
         minteq.v4.dat
         phreeqc.dat
         pitzer.dat
         sit.dat
         wateq4f.dat
    
    Example input files:
    
      install/share/doc/phreeqc/examples
         Input files for 22 examples documented in the Phreeqc 3 manual

-----------------------------------------------------------------------------------
F. Running PHREEQC
-----------------------------------------------------------------------------------

If PHREEQC has been installed in a directory included in the users' PATH, the
program can be executed from a command line with any of the commands below.

  command to execute PHREEQC     explanation
  -----------------------------  -----------------------------------------
  phreeqc                        The program will query for each of the
                                 needed files.

  phreeqc input                  The input file is named input, the output
                                 file will be named input.out and the
                                 default database file will be used.
  
  phreeqc input output           The input file is named input, the output
                                 file is named output, and the default
                                 database file will be used.
  
  phreeqc input output database  All file names are specified explicitly.
  
  phreeqc input output database screen_output     

                                 All file names are specified explicitly,
                                 and screen output is directed to the
                                 file screen_output.

If phreeqc is not located in a directory in PATH, the executable may be copied to the
current directory. In addition the default database file, phreeqc.dat, or another
desired database may need to be in the current directory.

PHREEQC is run by a script on Linux and a batch file on Windows. The environmental 
variable PHREEQC_DATABASE can be used to specify a default database.

----------------------------------------------------------------------------------- 
G. Description of test cases
-----------------------------------------------------------------------------------

The tests are described in the table below, where 'test' corresponds
to the example number in the PHREEQC manual. 

test  description of test and files                  
----  --------------------------------------------   
  1   Add uranium and speciate seawater

  2   Temperature dependence of solubility                            
      of gypsum and anhydrite                                         
                                                                      
  3   Mixing seawater and groundwater
                                                                      
  4   Evaporation and solution volume

  5   Add oxygen, equilibrate with pyrite, calcite, and goethite.
                                                                      
  6   Reaction path calculations with K-feldspar to phase boundaries                                    

  7   Organic decomposition with fixed-pressure and
      fixed-volume gas phases  
                                                                      
  8   Sorption of zinc on hydrous iron oxides                         
                                                                      
  9   Kinetically controlled oxidation of ferrous iron. 
      Decoupled valence states of iron.                                      
                                                                       
 10   Solid solution of strontianite and aragonite.
                                                                      
 11   Transport and ion exchange.

 12   Advective and diffusive transport of heat and solutes. Constant boundary
      condition at one end, closed at other. The problem is designed so that
      temperature should equal Na-conc (in mmol/kgw) after diffusion.

 13   1D Transport in a Dual Porosity Column With Cation Exchange

 14   Transport with equilibrium_phases, exchange, and surface reactions

 15   1D Transport: Kinetic Biodegradation, Cell Growth, and Sorption 

 16   Inverse modeling of Sierra springs

 17   Inverse modeling of Black Sea water evaporation

 18   Inverse modeling of Madison aquifer
 
 19   Modeling Cd+2 sorption with Linear, Freundlich, and Langmuir isotherms,
      and with a deterministic distribution of sorption sites for organic
      matter, clay minerals, and iron oxyhydroxides
      
 20   Distribution of isotopes between water and calcite
 
 21   Modeling diffusion of HTO, 36Cl-, 22Na+, and Cs+ in a radial diffusion
      cell

 22   Modeling gas solubilities: CO2 at high pressures

-----------------------------------------------------------------------------------
H. Contacts
-----------------------------------------------------------------------------------

Inquiries about this software distribution should be directed to:

e-mail:  h2osoft@usgs.gov or dlpark@usgs.gov