README

        IPhreeqc--Modules Based on the Geochemical Model PHREEQC for Use
                   in Scripting and Programming Languages
        
This file describes how to compile the IPhreeqc library and use
it in C++, C, and Fortran programs. The library may be compiled
after generating either a Visual Studio solution for Windows with 
CMake or a Makefile for Linux with configure. All source and 
compilation-related files are available at the following web site:

http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/index.html.

-----------------------------------------------------------------------------------
TABLE OF CONTENTS
-----------------------------------------------------------------------------------

	A. Distribution file
	B. Documentation
	C. Downloading and unzipping the distribution file
	D. Linux compiling, testing, and installing the IPhreeqc library
	E. Windows compiling, testing, and installing the IPhreeqc library
	F. Using the library
	G. Contacts

-----------------------------------------------------------------------------------
A. Distribution file
-----------------------------------------------------------------------------------

	The following distribution package (containing the software, 
	compilation-related files, and an advection example in
        C++, C, and Fortran) is available for Linux and Windows:

        iphreeqc-@VERSION@-@REVISION@.tar.gz      Linux
        iphreeqc-@VERSION@-@REVISION@.zip         Windows


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

	Descriptions and examples of IPhreeqc methods for C++, C, and Fortran
	are available in HTML format in the doc directory of the distribution. 

	Charlton, S.R., and Parkhurst, D.L., 2011, Modules based on the geochemical model 
	   PHREEQC for use in scripting and programming languages: Computers & Geosciences,
	   vol. 37, no. 10, p. 1653-1663.

	   *The following two user's guides are available in electronic format. Portable
	   Document Format (PDF) files are included in the doc subdirectory of all
	   PHREEQC program distributions.

	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. Downloading and unzipping the distribution file
-----------------------------------------------------------------------------------

	Follow the steps using gunzip, 7zip, or other compression program that can unzip a tar.gz/zip file:

	Steps in extracting files                   	Explanation
	----------------------------------------    	-----------------------------------
	gunzip iphreeqc-@VERSION@-@REVISION@.tar.gz	Uncompress the tar.gz file.
	tar -xvpof iphreeqc-@VERSION@-@REVISION@.tar	Extract files from the tar file.

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

	iphreeqc-@VERSION@-@REVISION@			Source code and configure/CMake files
	     ./config        				More configure files
	     ./database      				Database files for PHREEQC
	     ./doc           				Documentation files 
	     ./src           				Source code for IPhreeqc
	     ./tests         				Tests that check that C++, C, and Fortran(optional)
	     						are able to compile, link and run.

	Note:  A compiled executable is not included in the distribution.

-----------------------------------------------------------------------------------
D. Linux compiling, testing, and installing the IPhreeqc library
-----------------------------------------------------------------------------------

	In general, to compile the software, you will need:

		(a) a C++ compiler, and
		(b) a minimal level of knowledge of configure or CMake, Make, 
			the compiler, and the Linux operating system.

	A Makefile is generated by configure, and the Makefile is used to
	compile, test, and install the software.

  D.1.  Change directory to the directory that was extracted from the tar file.

        cd iphreeqc-@VERSION@-@REVISION@
        
  D.2.  Make a directory, for example, build.
	
	mkdir build
	
  D.3.  Change directory to build.
	
	cd build

  D.4.  Run configure

	Many of the options for configure can be seen by typing:
    
    	../configure --help
    
	Most common options:
    	--prefix=dir--specifies the directory for installation of the
    		library. Default is /usr/local, $HOME would install
    		to your home directory.
    	--disable-fortran--specifies that you do not want to include the Fortran test
    		files during "make check", which compiles, links, and runs programs that
    		use IPhreeqc.
    		
	Run configure as follows:	
    	
    	../configure [options] 

  D.5.  Compile the IPhreeqc library
	
	make [-j 4]
	
    	Optionally, use -j n--where n is the number of compilations make runs in parallel.
	
  D.6.  Compile and run the test cases. The files in the directory tests are compiled and linked
	to the IPhreeqc library. The Fortran files are optionally included (--enable-fortran 
	configure option).
	
	make check
	
  D.7.  Install the IPhreeqc library. By default the program is installed in /usr/local/bin
	and /usr/local/share/doc/iphreeqc-@VERSION@-@REVISION@. Alternatively, the directory defined
	by --prefix in the configure command is used. 
    
    	make install
    	
	The locations of various files are given for default installation (no
	--prefix definition). 
    
	Libraries:
		/usr/local/lib/libiphreeqc.a            (Static library)
		/usr/local/lib/libiphreeqc.so           (Shared object library)
		/usr/local/lib/libiphreeqc.la           (libtool library file)
		    
	Include files:
		C++ and C headers for user's code:
		/usr/local/include/IPhreeqc.h           (C header)
		/usr/local/include/IPhreeqc.hpp         (C++ header)
		
		Optionally, user's code may need one or more of the following:
		/usr/local/include/Var.h                (IPhreeqc VAR structure)
		/usr/local/include/IPhreeqcCallbacks.h  (IPhreeqc callbacks)
	
	Documentation (PDFs, IPhreeqc API(html)):
		/usr/local/share/doc/iphreeqc-@VERSION@-@REVISION@

	Databases: 
		/usr/local/share/doc/iphreeqc-@VERSION@-@REVISION@/database
		
	Fortran interfaces
		/usr/local/share/doc/iphreeqc-@VERSION@-@REVISION@/src
    
-----------------------------------------------------------------------------------
E. Windows compiling, testing, and installing the IPhreeqc library
-----------------------------------------------------------------------------------

	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.
   
  E.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.

  E.2  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:/iphreeqc-@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, 32/64 bit, dll/lib.
			for example, vs2012_64_dll.
	
	Click Configure. From the pulldown menu 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) BUILD_SHARED_LIBS--If checked, .dll files will be
		created. If not checked, a .lib file will be created.
		Note that .dll files have a .lib file associated with them,
		but it is not the same .lib generated when
		BUILD_SHARED_LIBS is not checked.
	(2) 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.
	(4) IPHREEQC_FORTRAN_TESTING--Sets whether the test calculations
		(tests directory) will include Fortran test files. A Fortran
		compiler is required. 
	
	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.
	
  E.3. Compile and install IPhreeqc

	Open the Visual Studio solution in the build directory defined in CMake.

	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 libraries, header files, Fortran module source
	files, phreeqc database files, and documentation are installed in the
	install directory selected in CMake.

		Libraries that can be installed:
			IPhreeqc.lib
			IPhreeqcd.lib
			IPhreeqc.dll
			IPhreeqcd.dll

		Include files:
			C++ and C headers for user's code:	
				IPhreeqc.hpp        (C++ header)
				IPhreeqc.h          (C header)

			Optionally, may need one or more of the following:
				Var.h                (IPhreeqc VAR structure)
				IPhreeqcCallbacks.h  (IPhreeqc callbacks)
			
		Src files:
			To use IPhreeqc in Fortran:
				IPhreeqc_interface.F90

		Database files:
			Amm.dat
			frezchem.dat
			iso.dat
			llnl.dat
			minteq.dat
			minteq.v4.dat
			phreeqc.dat
			pitzer.dat
			sit.dat
			wateq4f.dat

		Documentation files:
			html/index.html       (IPhreeqc API documentation)

-----------------------------------------------------------------------------------        			
F. Using the library
-----------------------------------------------------------------------------------

  F.1. C++
     
     In C++, you will include the IPhreeqc.hpp header file and 
     create an IPhreeqc instance:

     #include "IPhreeqc.hpp"
     IPhreeqc iphreeqc;

     or

     IPhreeqc *iphreeqc = new IPhreeqc();

     You will need to link to the IPhreeqc.lib that you installed.

  F.2. C

     In C, you will include the C interface header, IPhreeqc.h, and
     create an IPhreeqc instance.

     #include "IPhreeqc.h"
     int id;
     id = CreateIPhreeqc();

     You will need to link to the IPhreeqc.lib that you installed.

  F.3. Fortran

     In Fortran, you will need to include the source file IPhreeqc_interface.F90
     in your project files. This file defines the IPhreeqc Fortran module.

     USE IPhreeqc
     INTEGER(KIND=4) id
     id = CreateIPhreeqc()

     You will need to link to the IPhreeqc.lib that you installed.

-----------------------------------------------------------------------------------
G. CONTACTS
-----------------------------------------------------------------------------------

Inquiries about this software distribution should be directed to:

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