README February 9, 2000 VS2DI A Graphical Software Package for Simulating Fluid Flow and Solute or Energy Transport in Variably Saturated Porous Media VS2DI - Version 1.1 2000/02/09 for Unix (Requires compilation and Java Development Kit) If your Unix machine is a Sun SPARCstation running Solaris 2.6 or Silicon Graphics computer running Irix 6.3/4/5, please install the software compiled for these systems. For all other Unix machines, VS2DI can be installed only if a Java Development Kit is available for the machine. Instructions for compilation, installation, and execution are provided below. After installation, see the vs2di.txt file in the "doc" subdirectory of the VS2DI installation directory for summary information on VS2DI. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. A component of this software uses the program triangle.c version 1.3, written and copyrighted by Jonathan Richard Shewchuk (jrs@cs.berkeley.edu), Computer Science Division, University of California, Berkeley. Triangle.c is freely available on the World Wide Web at http://www.cs.cmu.edu/~quake/triangle.html The author of triangle.c has granted free distribution of that program for noncommercial use. Distribution of triangle.c as part of a commercial system is permissible only by direct arrangement with the author of that program. The Java Foundation Class Version 1.1 (JFC/Swing 1.0.3) is bundled with this software. JFC is copyrighted by Sun Microsystems, Inc. Sun Microsystems has granted royalty-free distribution of JFC for the purpose of running Java applications. References to commercial vendors of software products or services are for informational purposes only and does not imply endorsement by the U.S. Government. TABLE OF CONTENTS A. DISTRIBUTION FILE B. DOCUMENTATION C. EXTRACTING FILES D. COMPILING - Overview - Software requirements - Java Development Kit - Editing the source codes - Compiling Shared Libraries and Executables E. INSTALLING F. RUNNING THE SOFTWARE G. RECOMPILING H. TUTORIAL AND EXAMPLE PROBLEMS A. DISTRIBUTION FILE The following distribution file is currently available for UNIX systems: vs2di1.1.unix.tar.Z - Requires compilation and Java Development Kit B. DOCUMENTATION This software package includes on-line help manuals that provide detailed information on how to set up and run a simulation. To access the on-line help manual, run the software and select "Contents" from the "Help" menu. In addition, the following reports are available: Hsieh, P.A., Wingle, William, and Healy, R.W., 1999, VS2DI--a graphical software package for simulating fluid flow and solute or energy transport in variably saturated porous media: U.S. Geological Survey Water-Resources Investigations Report 99-4130, 16 p. This document is available in electronic format. A Portable Document Format (PDF) version is included in the "doc" subdirectory of the VS2DI installation directory. This and other formats can also be found at http://water.usgs.gov/software/vs2di.html. Healy, R.W., and Ronan, A.D., 1996, Documentation of computer program VS2DH for simulation of energy transport in variably saturated porous media--modification of the U.S. Geological Survey's computer program VS2DT: U.S. Geological Survey Water-Resources Investigations Report 96-4230, 36 p. Healy, R.W., 1990, Simulation of solute transport in variably saturated porous media with supplemental information on modifications to the U.S. Geological Survey's Computer Program VS2D: U.S. Geological Survey Water-Resources Investigations Report 90-4025, 125 p. Lappala, E.G., Healy, R.W., and Weeks, E.P., 1987, Documentation of computer program VS2D to solve the equations of fluid flow in variably saturated porous media: U.S. Geological Survey Water-Resources Investigations Report 83-4099, 184 p. See http://water.usgs.gov/software/ordering_documentation.html for information on ordering printed copies of USGS publications. C. EXTRACTING FILES The compressed tar file (distribution file), vs2di1.1.unix.tar.Z, contains all the files needed to compile and install VS2DI on a Unix system. The directory vs2di1.1 is created (or overwritten) when the files are extracted from the distribution file. If the vs2di1.1 directory already exists, you may want to delete or rename it before extracting the files. The following are the steps to extract the files from a distribution file. 1. If the distribution file is not already in the directory under which you want the software installed, move it there. For example: mv vs2di1.1.unix.tar.Z /usr/opt/usgs 2. If you are not in the directory where the distribution file is located, go there. For example: cd /usr/opt/usgs 3. Uncompress and extract the distribution file. For example: zcat vs2di1.1.unix.tar.Z | tar xvf - This creates the following directory structure (the contents of each directory are shown to the right): vs2di1.1 ; files NOTICE, this README `-----bin ; executables `-----doc ; documentation files `-----examples ; example files (including tutorial) `-----help ; help manuals, accessible from within the software `-----images ; image files used by the software `-----lib ; supporting files, Java Foundation Class - Swing `-----src ; source codes Notes: a) The Fortran source codes for VS2DT and VS2DH are provided for users whose simulations require array dimensions exceeding those provided in the current release. To recompile with larger arrays, see section E ("Recompiling") below. b) The Java source code that implements the graphical interface is not included in this distribution. c) The beginning portion of the source code for triangle.c contains copyright notice and conditions on use and distribution of that program. Recompilation of triangle.c should not be necessary. d) It is recommended that no user files are kept in the VS2DI directory structure. If you plan to put files in the VS2DI directory structure, do so only by creating subdirectories. D. COMPILING Overview -------- Compilation involves building the shared libraries libtrimesh.so and and libvs2dt(h)Jni.so, and the executable vs2dt(h)3_0. (The abbreviation "vs2dt(h)" means vs2dt or vs2dh.) Compilation is accomplished by executing the Makefile in the src directory. Software requirements --------------------- The software needed for compiling the source codes distributed with this release are: - C compiler - Fortran 77 compiler - Java Development Kit 1.1 (JDK), version 1.1.6 or later. (Do not use version 1.2). Java Development Kit -------------------- To determine whether a JDK is available for your system, check with your system manufacturer. Listed below are various sources for JDK. (These have not all been tested by the authors.) Data General http://www.dg.com/products/html/jdk.html Hewlett-Packard http://www.datacentersolutions.hp.com/java/ IBM http://www.ibm.com/java/jdk/download/ Linux http://www.blackdown.org/java-linux.html Silicone Graphics http://www.sgi.com/developers/devtools/languages/java.html Sun http://java.sun.com/ If your manufacturer is not listed here, go to their homepage, and perform a search for "Java", "products", "software", and/or "development tools". You may be able to find whether or not a JDK is available. Before you install JDK, check if any operating system patches are required, and install the necessary patches. Editing the Source Codes ------------------------ Depending on your Unix system, you might have to edit the source codes vs2dt(h).h and vs2dt(h)Jni.c. These 2 files are in the directory src/vs2dt(h). The purpose of these C source codes is to establish communication between the graphical user interface (written in Java) and the numerical model (written in Fortran). The manner in which a C program calls a Fortran subroutine is platform dependent. For Unix systems, we have assumed the C-calling-Fortran naming convention to consist of the Fortran subroutine name, in lower case, followed by an underscore ("_"). For example, the Fortran subroutine SETUP will be called in the C program as setup_(). However, if the C-calling-Fortran naming convention on your system does not use an underscore, then you will have to edit the files vs2dt(h).h and vs2dt(h)Jni.c to remove the underscore. Alternatively, there might be a compiler flag that can be turned on to recognize the underscore. Compiling Shared Libraries and Executables ------------------------------------------ The Makefile in the src directory is actually a soft link to Makefile.sun (for Sun Solaris platform) or Makefile.sgi (Silicon Graphics Irix platform). Use these as guides to creating the Makefile for your own unix platform (by following the directions given in the comments.) The Makefile can be executed by using the command: make. If the make is successful, the shared libraries libvs2dt(h)Jni.so and libtrimesh.so will be generated in the lib directory, and the executable vs2dt(h)3_0 will be generated in the "bin" directory. In addition, object files (having filenames ending with ".o") will also be generated. These object files are not need to run the software, and can be removed using the command: make rmobj. E. INSTALLING After the Fortran and C source codes are compiled, edit the scripts vs2dti.jdk, vs2dhi.jdk and vs2post.jdk in the "bin" directory according to the comments in the scripts. In most cases, you only need to specify the location where JDK is installed. Also make sure that the following soft links are established: vs2dti -> vs2dti.jdk vs2dhi -> vs2dhi.jdk vs2post -> vs2post.jdk The software should now be usable from the "bin" directory, for example, /usr/opt/usgs/vs2di1.1/bin. However, to make the software accessable from any directory, add the bin directory to the PATH environmental varible. Note that the scripts vs2dti.jre, vs2dhi.jre, and vs2post.jre are not used when the software is launched using JDK. F. RUNNING THE SOFTWARE After VS2DI is properly installed, and the "bin" directory is included in your PATH, the software can be run by typing the command: vs2dti -- to simulate fluid flow and solute transport vs2dhi -- to simulate fluid flow and energy transport vs2post -- to run the postprocessor in standalone mode It is anticipated that most user will not need to run the numerical models VS2DT and VS2DH independently from the graphical user interface. However, if you need to run these models separately, see the readme file in the "bin" directory. G. RECOMPILING Recompiling is not necessary unless the user's simulation requires array dimensions exceeding those provided in the current release. In the current release, the numerical models VS2DT and VS2DH are compiled to accommodate the following: - Up to 36000 grid cells and a maximum of 6000 rows or columns. - Up to 25 textural classes, with up to a total of 64 rows of tabular data. (One row of tabular data contains 3 entries: pressure head, relative conductivity, and moisture content.) - Up to 100 boundary segments may be designated as "possible seepage face." Each boundary segment may be represented by up to 100 cells. - Up to 200 iterations per time step. - Up to 50 observation points. - Up to 365 evapotranspiration periods. - Up to 150 output times to File 8. If the user's simulation requires larger array dimensions, then it is necessary to rebuild the shared library vs2dt(h)Jni.so (in the "lib" directory). This will also rebuild the executable vs2dt(h)3_0 in the "batch/vs2dt(h)" directory. Steps to rebuild libvs2dt(h)Jni.so and vs2dt(h)3_0 are as follows: 1. Edit the Fortran source code vs2dt(h)3_0.f by modifying array dimensions to appropriate sizes. These files are located in the directory "src/vs2dt(h)". 2. Go to the src directory and edit the Makefile, following the directions given in the comments. (In most instances, no change will be needed.) 3. Execute the Makefile using the command: make. 4. To remove object files generated by make, use the command: make rmobj. The object files are not needed to run the software. H. TUTORIALS AND EXAMPLE PROBLEMS A tutorial and several example problems are included for both VS2DTI and VS2DHI. These are designed help the user learn how to use the software, and to allow testing of the software after installation. A working directory is created for each tutorial or example. The file terminating with ".vs2" is the document file. For the example problems, the main output files are included (renamed as exampleN.out) for users to verify that the software is running correctly. For VS2DTI, the following tutorial and example problems are included in the "examples\solute" directory: tutorial1 -- tutorial for VS2DTI example1 -- Example problem in Water-Resources Investigations Report (WRIR) 90-4025, p. 45. Infiltration of water containing a solute concentration of 1.0 into a partially saturated one-dimensional soil column containing solute free water. example2 -- Verification Problem 1 WRIR 90-4025, p. 36-37. Advection and dispersion in a steady, radial flow field under fully saturated conditions. example3 -- 2-D example that involves solute transport, evaporation, and plant transpiration. For VS2DHI, the following tutorial and example problems are included in the "examples\energy" directory: tutorial1 -- tutorial for VS2DHI example1 -- Example problem in WRIR 96-4230, p. 26. Ponded infiltration of water at 17.48 degrees C into a partially saturated soil column with an initial temperature of 21.3 degrees C. example2 -- Verification Problem 1 in WRIR 96-4230, p.5. Water at 21 degrees C flowing into a one-dimensional saturated column with an initial temperature of 20 degrees C. example3 -- Injection of heated water into a water-table aquifer with initial saturated thickness of 10 m. Axisymmetric flow field. In addition, two seepage problems (no transport) are included in the "example\flow" directory. These examples may be run using either VS2DTI or VS2DHI: example1 -- Transient seepage across an earthen dam. example2 -- Development of seepage face on a slope with layered soils.