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 for use on
Apple Macintosh computers running OS X (10.4 or later).


                  PHREEQC - Version 2.18.0  April 18, 2011

Instructions for installation, execution, and testing are provided
below.  After installation, see the phreeqc.txt file in the doc directory
of the PHREEQC installation for summary information on PHREEQC.

For assistance, enhancement requests, or to report bugs, contact 
dlpark@usgs.gov.


                          TABLE OF CONTENTS

                          A. DISTRIBUTION FILES
                          B. DOCUMENTATION
                          C. EXTRACTING FILES
                          D  COMPILING
                          E. INSTALLING
                          F. RUNNING THE PROGRAM
                          G. TESTING
                          H. CONTACTS


A. DISTRIBUTION FILES

The following distribution package (containing the software, test data 
sets, and information files) is currently available for Mac OS X:

phreeqc-2.18.0-5314.dmg
	Compiled with Xcode 4.0.2 (gcc 4.21)

B. DOCUMENTATION

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.

   This user's guide is available in electronic format. Portable Document
   Format (PDF) files are included in the doc subdirectory of the
   PHREEQC program distribution. An online HTML version of the User's
   Guide can also be found at
   http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/.

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.

   This report documents the theory and implementation of isotopes 
   in PHREEQC. Portable Document Format (PDF) is included in the 
   doc subdirectory of the PHREEQC program distribution. 

C. EXTRACTING FILES

PHREEQC for Mac OS X is distributed as a compressed disk image file; the 
downloaded file may self expand or will expand to a disk image by double-
clicking it in the Finder. After the User Rights Notice is agreed to, the
image will mount and reveal the phreeqc-2.18.0 folder, which may be copied 
into any directory. Note that if you copy it to the /Applications folder,
users without admin privileges will not be able run phreeqc because it
writes files back into its own directory. On multi-user systems, it may
be desirable to move copies of the phreeqc-2.18.0 folder into each user's
home directory.

The following directory structure is assumed (the contents of each
directory are shown to the right):

   phreeqc-2.18.0      AppleScript applets
     `-----bin         compiled executable
     `-----database    database files required during execution
     `-----doc         documentation files 
     `-----examples    examples from user's guide--used in verification
                       tests
     `-----src         source code for AppleScript scripts

Notes:  (a) The PHREEQC source code is not included in the Mac
            distribution, but is available by downloading the Linux
            version.
        (b) The "run phreeqc" applet assumes that the phreeqc executable
            resides in the /bin directory relative to the path to the 
            "run phreeqc" application.

D. COMPILING

The Mac version is pre-compiled.

E. INSTALLING

No special installation is needed; if the software is run from a Terminal
window (by opening the file "/bin/phreeqc"), see the instructions 
available for the Linux version in order to resolve path problems.


F. RUNNING THE PROGRAM

By opening (double-clicking) the file "run phreeqc", the user is prompted
sequentially for the input, output and database files. These files can
reside in any directory; the database files are initially stored in
"/database/". Pressing the "Cancel" button in any file dialog
will halt execution of the script. Normally, no feedback is provided 
because the applet simply calls the phreeqc executable. Any errors
or warnings will be written to the output file. The log file "phreeqc.log"
may be checked if results are not what was expected. Note that selected
output files and phreeqc.log will be stored in the directory with
"run phreeqc". After the output file is created, the user is given the
option of opening the output file in an application of his/her choosing.
Just be sure to choose an application that can open text files. If
desired, the AppleScript script could be changed to always open the 
output file in the same application (i.e. TextEdit).

PHREEQC operates with generic text files; these files may be edited using
"TextEdit" or any program that can work with text files. An excellent text
editor is available from <http://www.barebones.com>. Because PHREEQC is 
a Unix program, it expects the end-of-line character to be a line-feed 
(ASCII 10). Many Mac programs generate text files using carriage-returns
(ASCII 13) as the end-of-line character.

A symptom of incorrect line-endings is that the output file will simply
echo the input with no calculations performed.

If you are using older input files from a Mac, or if your text editor 
uses the older end-of-line character, then simply drop your input file(s) 
onto the Mac2Unix droplet to convert them before using them as input to 
PHREEQC. A companion droplet called Unix2Mac is included in case one needs 
to reverse the process. Each time the file is converted a new file is 
created that ends with either "LF" or "CR" as appropriate.


G. TESTING

The Mac OS X version of PHREEQC has been tested and the results are 
comparable to the results on other Unix systems. The example files
are provided in the Examples directory.

Notes: The output data files were created on a Linux system. You may notice 
       slight numeric differences in the results. These are generally due 
       to different round-off algorithms and the different architecture of 
       the central processing unit. Slight differences in output 
       formats may occur on other computers, particularly for the value
       0.0.

       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.

The tests are described in the table below, where 'test' is the test
number and the 'usage' column indicates how a file is used, with i for
input and o for output.

test  description of test and files                  file name & usage
----  --------------------------------------------   -----------------
  1   Add uranium and speciate seawater

      PHREEQC input file                             ex1             i
      Printed results of calculation                 ex1.out         o
                                                                      
  2   Temperature dependence of solubility                            
      of gypsum and anhydrite                                         
                                                                      
      PHREEQC input file                             ex2             i
      Printed results of calculation                 ex2.out         o
      Results written to the selected-output file    ex2.sel         o

  3   A. Calcite equilibrium at log Pco2 = -2.0 and 25C
      B. Definition of seawater
      C. Mix 70% ground water, 30% seawater
      D. Equilibrate mixture with calcite and dolomite
      E. Equilibrate mixture with calcite only

      PHREEQC input file                             ex3             i
      Printed results of calculation                 ex3.out         o
                                                                      
  4   A. Rain water evaporation                                       
      B. Factor of 20 more solution                                   
                                                                      
      PHREEQC input file                             ex4             i
      Printed results of calculation                 ex4.out         o

  5   Add oxygen, equilibrate with pyrite, calcite, and goethite.

      PHREEQC input file                             ex5             i
      Printed results of calculation                 ex5.out         o
      Results written to the selected-output file    ex5.sel         o
                                                                      
  6   6A. React to phase boundaries                                    
      6A1.--Find amount of k-feldspar dissolved to                         
            reach gibbsite saturation                                  
      6A2.--Find amount of k-feldspar dissolved to                         
            reach kaolinite saturation                                 
      6A3.--Find amount of k-feldspar dissolved to                         
            reach K-mica saturation                                 
      6A4.--Find amount of k-feldspar dissolved to                         
            reach k-feldspar saturation                                    
      6A5.--Find point with kaolinite present,                         
            but no gibbsite                                            
      6A6.--Find point with K-mica present,                         
            but no kaolinite                                           
      6B. Path between phase boundaries                                
      6C. Kinetic calculation
                                                                      
      PHREEQC input file                             ex6             i
      Printed results of calculation                 ex6.out         o
      Results written to the selected-output file    ex6A-B.sel      o
      Results written to the selected-output file    ex6C.sel        o

  7   Organic decomposition with fixed-pressure and
      fixed-volume gas phases  

      PHREEQC input file                             ex7             i
      Printed results of calculation                 ex7.out         o
      Results written to the selected-output file    ex7.sel         o
                                                                      
  8   Sorption of zinc on hydrous iron oxides                         
                                                                      
      PHREEQC input file                             ex8             i
      Printed results of calculation                 ex8.out         o
      Results written to the selected-output file    ex8.sel         o
                                                                      
  9   Kinetically controlled oxidation of ferrous iron. 
      Decoupled valence states of iron.                                      
                                                                      
      PHREEQC input file                             ex9             i
      Printed results of calculation                 ex9.out         o
      Results written to the selected-output file    ex9.sel         o
                                                                      
 10   Solid solution of strontianite and aragonite.
                                                                      
      PHREEQC input file                             ex10            i
      Printed results of calculation                 ex10.out        o
      Results written to the selected-output file    ex10.sel        o
                                                                      
 11   Transport and ion exchange.
                                                                      
      PHREEQC input file                             ex11            i
      Printed results of calculation                 ex11.out        o
      Results written to the selected-output file    ex11adv.sel     o
      Results written to the selected-output file    ex11trn.sel     o

 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.

      PHREEQC input file                             ex12            i
      Printed results of calculation                 ex12.out        o
      Results written to the selected-output file    ex12.sel        o

 13   A. 1 mmol/l NaCl/NO3 enters column with stagnant zones. Implicit 
         definition of first-order exchange model.
      B. 1 mmol/l NaCl/NO3 enters column with stagnant zones. Explicit 
         definition of first-order exchange factors.
      C. 1 mmol/l NaCl/NO3 enters column with stagnant zones. 5 layer 
         stagnant zone with finite differences.

      PHREEQC input file                             ex13a           i
      Printed results of calculation                 ex13a.out       o
      Results written to the selected-output file    ex13a.sel       o
      PHREEQC input file                             ex13b           i
      Printed results of calculation                 ex13b.out       o
      Results written to the selected-output file    ex13b.sel       o
      PHREEQC input file                             ex13c           i
      Printed results of calculation                 ex13c.out       o
      Results written to the selected-output file    ex13c.sel       o

 14   Transport with equilibrium_phases, exchange, and surface reactions

      PHREEQC input file                             ex14            i
      Printed results of calculation                 ex14.out        o
      Results written to the selected-output file    ex14.sel        o

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

      PHREEQC input file                             ex15            i
      database file                                  ex15.dat        i
      Printed results of calculation                 ex15.out        o
      Results written to the selected-output file    ex15.sel        o

 16   Inverse modeling of Sierra springs

      PHREEQC input file                             ex16            i
      Printed results of calculation                 ex16.out        o

 17   Inverse modeling of Black Sea water evaporation

      PHREEQC input file                             ex17            i
      Printed results of calculation                 ex17.out        o

 18   Inverse modeling of Madison aquifer

      PHREEQC input file                             ex18            i
      Printed results of calculation                 ex18.out        o


H. CONTACTS

Inquiries about this software distribution should be directed to:

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

