README.TXT

                                PHREEQC

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

NOTE: This file describes the batch version of PHREEQC version 3 for Windows
operating systems. Also available for Windows operating systems is a graphical
user interface (GUI), PhreeqcI. This GUI can be downloaded from
http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/index.html. PhreeqcI has
internal documentation for all PHREEQC data input and is a complete interface
to PHREEQC. Alternatively, a Notepad++ interface is available at
http://www.hydrochemistry.eu/downl.html.


                  PHREEQC - Version @VERSION@  @VER_DATE@

Instructions for installation, execution, and testing on Windows operating
systems are provided below. After installation, see the phreeqc.txt file in the
doc directory of the PHREEQC installation for summary information on PHREEQC
and the RELEASE.TXT file for new features and bug fixes.


	  TABLE OF CONTENTS

	  A. Distribution files
	  B. Documentation
	  C. Installing and running the GUI PhreeqcI
	  D. Installing the batch version of PHREEQC
	  E. Compilation (optional)
	  F. Running the batch program
	  G. Testing and examples
	  H. Contacts

A. Distribution files

The following distribution files (containing the software, test data sets,
and information files) are currently available.

phreeqci-@VERSION@.@REVISION@.msi--GUI compiled by using Microsoft Visual C++
                                 2005

phreeqc-@VERSION@.@REVISION@.msi--Batch version compiled by using Microsoft
				Visual C++ 2005, includes source code
                                
B. Documentation

*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.
   
   
*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., 2012, 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/06A43/.

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.
   
C. Installing and running of the GUI PhreeqcI

Note that if the software is to be installed on a server system, 
the person installing the software generally must have administrator 
rights.

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

To execute the GUI, access the program through the start menus of Windows. 

By default, the software is installed in the directory C:\Program
Files\USGS\phreeqci-@VERSION@.  This is the recommended installation directory,
but you may use other directories or disk drives.

Note that program components not installed initially can be installed later,
and any components damaged (for example, by inadvertently overwriting the
directory) can be quickly reinstalled by double-clicking
phreeqci-@VERSION@.@REVISION@.msi--a maintenance version of the installation
program will be executed.


D. Installing and running the batch version of PHREEQC

Note that if the software is to be installed on a server system, the person
installing the software generally must have administrator rights.

To install the software, double-click phreeqc-@VERSION@-@REVISION@.msi to
execute the installation program and follow the directions on the screen. The
installation program optionally will modify the PATH environment variable so
that the PHREEQC program can be executed from any directory, without needing to
type the full pathname of the program's location. The batch version is
completely independent from teh GUI version.

By default, the software is installed in the directory C:\Program
Files\USGS\phreeqc-@VERSION@.  This is the recommended installation directory,
but you may use other directories or disk drives.

Note that program components not installed initially can be installed later,
and any components damaged (for example, by inadvertently overwriting the
directory) can be quickly reinstalled by double-clicking
phreeqc-@VERSION@-@REVISION@.msi--a maintenance version of the installation
program will be executed.

The following directory structure will be created (the contents of each
directory are shown to the right):

   phreeqc-@VERSION@         files NOTICE.TXT, RELEASE.TXT, and this
			  README.Win.TXT; batch file to run PHREEQC
                          
     --database           database files
     --doc                documentation files 
     --examples           examples from user's guide--used in verification tests
     --src                Makefile and source code
       --ClrClass_release phreeqcpp.exe, executable with charting
       --Class_release    phreeqcpp.exe, executable without charting
     --test               batch files to run verification tests

Note:  It is recommended that no user files be kept in the PHREEQC
       directory structure.  If you plan to put files in the PHREEQC
       directory structure, do so only by creating subdirectories.

     
E. Compiling

The source code is provided so that users can generate the executable
themselves.  Little or no support is provided for users generating
their own versions of the software.  In general, to compile a new
version of the software, you will need:

       (a) a C compiler,
       (b) familiarity with the compiler and the Windows operating system.

A Visual Studio project (phreeqcpp.sln) is included in the top-level directory
	for compilation on Windows operating systems.


F. Running the batch program

If PHREEQC has been installed in a directory included in the users' PATH, the
batch program can be executed 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 the option to modify the PATH environment variable was not chosen during
installation, then two options exist: (1) the full pathname to the script that
runs phreeqc can be used in place of "phreeqc" in the above commands (for
example "c:\program files\usgs\phreeqc-@VERSION@\phreeqcpp". Note that because
of the space present in "program files", quotation marks must be used to enter
the full pathname.), or, (2) the executable (installed in
phreeqc-@VERSION@\src\release\phreeqcpp.exe) may be copied to the current
directory; further, the default database file may need to be in the current
directory and named "phreeqc.dat". The default database file is installed in
phreeqc-@VERSION@\database\phreeqc.dat.

The environment variable PHREEQC_DATABASE can be used to specify the
default database for a DOS window session.  This environmental variable
can be set with the command:

  set PHREEQC_DATABASE=c:\mydirectory\myproject\mydata.dat

This environmental variable takes precedence over any default definition
of the database file. If PHREEQC is invoked with at least three
arguments, the third argument is the database file and it takes
precedence over the environmental variable or the default database.                                 

G. Testing and examples

Input files are provided to verify that the program is correctly installed and
running on the system.  The tests execute the examples presented in the user's
guide, which demonstrate most of the program's capabilities. The PHREEQC
"examples" directory contains the input data and the expected results for each
test. 

The "examples" and "Win" directories from phreeqc-@VERSION@ have been copied to
My Documents\xxx, and the examples can be run from My Documents\Win. Either
double click the test.bat file from Windows Explorer or cd to the directory in
a command-prompt window and type test.bat [start [stop [no_chart]]]

where:  start    is the number of the first test to perform, default = 1
        stop     is the number of the last test to perform, default = 22
        no_chart is any alphanumeric string, which causes no charts to be 
                 generated.

For example:

     command                            what happens
     ---------------------------------  --------------------------------
     test.bat                           runs all of the tests
     test.bat 1 1                       runs the first test
     test.bat 2 3                       runs tests 2 and 3
     test.bat 4                         runs test 4 through the last test
     test.bat 1 10 no                   runs tests 1 through 10 without charts


You will have to close chart windows after each chart has completed to proceed
to the remaining examples. After the tests are completed, the results are
compared to the expected results (found in the examples directory).  See the
file check.log; if all goes well, there should be few or no differences.
Differences in path names and run times are insignificant.

To clean up after the tests, double click on clean.bat in Windows Explorer or
type the command clean.bat from a command prompt. 

Note:  Sometimes different processors, or different compilers cause
       minor numerical differences in the results or differences in
       representation of exponents. In general, concentrations should
       differ by less than about 1e-14 (mol/kg water) between two sets
       of results. The pe may vary several units in some systems
       without redox buffering; however, all concentrations should
       still differ by only small amounts.

       Problem 9 generates a warning message that indicates negative 
       concentrations were generated in a kinetic run. The numerical
       method automatically reduces the step size until negative 
       concentrations are eliminated and an accurate kinetic integration
       is obtained.

       Problems 11, 12, 13, and 15 generate warning messages. The
       messages simply indicate a shorthand method for defining cell
       lengths and cell dispersivities was used in a transport 
       calculation.


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