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 compiled for Silicon Graphics Indigo and Sun SPARCstation Solaris Instructions for installation, execution, and recompilation (if necessary) 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 Runtime Environment (JRE) Version 1.1 and the Java Foundation Class Version 1.1 (JFC/Swing 1.0.3) are bundled with this software so that it can run as a standalone Java application. JRE and JFC are copyrighted by Sun Microsystems, Inc. Sun Microsystems has granted royalty-free distribution of JRE and 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 FILES B. DOCUMENTATION C. EXTRACTING FILES D. INSTALLING E. RUNNING THE SOFTWARE F. RECOMPILING G. TUTORIAL AND EXAMPLE PROBLEMS A. DISTRIBUTION FILES The following distribution files (containing the software, Java Runtime, example data, and information files) are currently available: vs2di1.1.SGI.tar.Z - Compiled for SGI Irix 6.3, 6.4, and 6.5 vs2di1.1.Solaris.tar.Z - Compiled for Sun Solaris 2.6 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.OS.tar.Z, contains all the files needed to install VS2DI on a computer with a particular operating system, where OS is a string indicating the intended operating system (SGI or Solaris). 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.OS.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.OS.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 `-----jre ; Java Runtime Environment `-----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. INSTALLING After the tar file has been uncompressed and extracted, the software should be usable from "bin" directory under the installation directory, for example, /usr/opt/usgs/vs2di1.1/bin. However, to make the software accessible from any directory, add the "bin" directory to the PATH environmental variable. E. 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. F. 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 libvs2dt(h)Jni.so. (The abbreviation "vs2dt(h)" means vs2dt or vs2dh.) This file is in the "lib" directory. This will also rebuild the executable vs2dt(h)3_0 in the "bin/vs2dt(h)" directory. The software used for rebuilding the shared libraries and executables are: - C compiler - Fortran 77 compiler - Java Development Kit 1.1 (JDK), version 1.1.6 or later. (Do not use version 1.2). Note that JDK is platform specific, so you must install the JDK for your platform. JDK for Silicon Graphics machines can be downloaded from http://www.sgi.com/developers/devtools/languages/java.html JDK for Sun machines can be downloaded from: http://java.sun.com/ Before you install JDK, check if any operating system patches are required, and install the necessary patches. 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 for the appropriate platform, following directions given in the comments. For SGI, edit the file Makefile.sgi. For Solaris, edit the file Makefile.sun. Note that Makefile is actually a soft link to makefile for the appropriate platform. In most instances, you only need to specify the location where JDK is installed. 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. G. 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.