From ac5dba2c0f82d70d24e255c8b5be735bd835dad6 Mon Sep 17 00:00:00 2001 From: Scott R Charlton Date: Tue, 19 May 2015 21:17:15 +0000 Subject: [PATCH] Move http://internalbrr.cr.usgs.gov/svn_GW/IPhreeqc/trunk/README.IPhreeqc.TXT to http://internalbrr.cr.usgs.gov/svn_GW/phreeqc3/trunk/doc/README.IPhreeqc.TXT git-svn-id: svn://136.177.114.72/svn_GW/phreeqc3/trunk@9672 1feff8c3-07ed-0310-ac33-dd36852eb9cd --- README.IPhreeqc.TXT | 355 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 README.IPhreeqc.TXT diff --git a/README.IPhreeqc.TXT b/README.IPhreeqc.TXT new file mode 100644 index 00000000..3f24a09f --- /dev/null +++ b/README.IPhreeqc.TXT @@ -0,0 +1,355 @@ +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 +