Groundwater TRANsport 3D (GTRAN3D) is an OpenGL-based integrated visualization software package for interactive 3D modeling of advective and diffusive contaminant transport in groundwater. The software is designed for visualizations of contaminant spreading caused by aquifer heterogeneities with applications both in teaching and in research. The visualization components of the package were developed by Vijay Kalivarapu and Eliot Winer of the Iowa State University, Ames, IA. The numerical engine is the groundwater solver Luka developed by Igor Jankovic of the University at Buffalo, Buffalo, NY. GTRAN3D is designed to be simple to use, while obeying platform independence for working with a multitude of operating systems.

The integrated software package models aquifer heterogeneities using non-intersecting inclusions (inhomogeneities) shaped as 3D rotational ellipsoids (prolate and oblate) and spheres, of varying hydraulic conductivity. These inhomogeneities are embedded in a homogeneous infinite background and subject to uniform flow in order to quantify and visualize contaminant spreading. The mathematical underpinnings of the solver Luka and numerous applications of this engine to modeling contaminant transport are described in a series of papers. Complete paper listing is available through Igor Jankovic’s web page at www.groundwater.buffalo.edu. The same web page houses the stand-alone version of the engine that can be used as a numerical laboratory for modeling transport.

Using GTRAN3D system, a user can:

- Define a “Virtual Porous Medium” (VPM) model by defining inclusions’ shapes, locations, sizes, orientations and conductivities, and other aquifer and model parameters (background conductivity, porosity, diffusion coefficient, uniform flow components).

- Trace particles through different VPM models.

- Interactively edit, view and save different VPM and particle models.

- Connect to the power wall or a cave system for full-fledged 3D immersive visualization of transport through different VPM models.

- Alter various viewing parameters for enhanced immersive viewing experience.

- View 3D transport simulations on a web browser.

2. Copyright and License

Eliot Winer, Iowa State University,

Igor Janković, University at Buffalo

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, June 1991, as published by the Free Software Foundation. For details see http://www.gnu.org/copyleft/gpl.html.

3. GTRAN3D Modules

The GTRAN3D package comes in three different flavors: a) Standalone Desktop Module, b) Immersive Module, and c) Web Module

3.1.Standalone Desktop Module

As the name suggests, the standalone desktop module is a typical PC application where a user can interactively build an aquifer, solve for particle flow paths, save and retrieve aquifer models. The desktop module is simple to use and is designed in a platform independent sense. That means the look and feel of the desktop module will remain the same on all operating systems (Windows, Linux, etc).

The source code and pre-compiled binaries for this module are available for download. Please refer to section 3 for details on how to obtain them.

3.2.Immersive Module

The immersive module leverages the availability of Virtual Reality (VR) technology and offers the capability of viewing life sized VPM models on systems ranging from a single power wall to six wall VR cave environments. Prospective researchers and groundwater enthusiasts can readily make use of this module to analyze transport on inclusions’ scale.

This module has two components – immersive client and the immersive server component. In addition to abstracting all the features from a standalone desktop module, the immersive client provides the convenience of connecting to the server to transmit VPM models with a few mouse clicks. The server, on the other hand, is the immersive viewing system (a power wall, six wall cave, etc) that waits for the commands from the immersive client to display life sized VPM models in 3D stereo vision.

With the help of virtual reality hardware such as a wand, active stereo glasses and a head tracking mechanism, a user is able to view, navigate and analyze the contaminant spreading patterns in groundwater.

The source code and pre-compiled binaries for this module (both client and the server) are available for download. Please refer to section 3 for details on how to obtain them.

3.3.Web Module

The web module is a handy way of viewing organizing and analyzing pre-built aquifer models. The usefulness of this module becomes especially apparent for groundwater researchers that are geographically distributed. A user can upload an input file using an ordinary web browser and have the web server compute particle flow paths. The user can then view the computed flow path off the browser with the click of a button. This eliminates the necessity to download and install software on the local machine.

Please refer to section 3 for details on how to access the web module.

4. Obtaining GTRAN3D

The source code and the pre-compiled binaries are available for download at www.groundwater.buffalo.edu. The following is the module hierarchy of GTRAN3D software available at this site:

- gwaterStandalone/

o gwaterWinStandalone/

§ gwaterBin/

§ gwaterSrc/

o gwaterLinuxStandalone/

§ gwaterBin/

§ gwaterSrc/

o gwaterIrixStandalone/

§ gwaterSrc/

- gwaterClient/

o gwaterLinuxImmersiveClient/

§ gwaterBin/

§ gwaterSrc/

o gwaterWinImmersiveClient/

§ gwaterBin/

§ gwaterSrc/

- gwaterServer/

o gwaterIrixImmersiveServer/

§ gwaterBin/

§ gwaterSrc/

o gwaterLinuxImmersiveServer/

§ gwaterBin/

§ gwaterSrc/

The directory names are quite self-explanatory. The source code for each module is the same for different platforms. However, the numerical engine ‘Luka’ and some of its dependency files (inverse and binverse) are platform dependent. To avoid confusion on the user’s end when downloading, the numerical engine Luka and its dependencies are bundled along with the gwaterSrc directories for each platform.

The details of pre-compiled binaries and the compile environments are listed in Table 1.

The ‘Operating System’ column indicates the platform on which the software was compiled. The listing under ‘Available Binaries’ indicate the pre-compiled binaries available for download. For example, pre-compiled standalone desktop module, immersive client module and the immersive server modules are available for Linux Operating System. The compiler details for the available pre-compiled binaries are indicated under the column ‘Compile Environment’.

Table 1. Available pre-compiled Binaries for GTRAN3D

Operating System	Available Binaries	Compile Environment
Windows (WinXP SP2)	- Standalone - Immersive Client	- Microsoft Visual Studio .NET 2003
Linux (Redhat Enterprise Linux – RHEL 4)	- Standalone - Immersive Client - Immersive Server	- Kernel version # 2.6.9 - gcc version # 3.4.5 - gmake version # 3.80
Irix (IRIX64)	- Immersive Server	- Kernel version # Irix 6.5 - gcc version # 3.3 - gmake version # 3.80

5. System Requirements

5.1.Standalone Desktop Module

Hardware requirements:

Since GTRAN3D is a 3D viewing system, graphics hardware acceleration is highly recommended although not necessary. Any video card 64MB or above can provide very decent visual output.

Software requirements for pre-compiled binaries:

- Windows Users: The only requirement for the standalone desktop windows application is glut32.dll, which is distributed along with the pre-compiled binaries. Therefore, the user does not need any additional software to be installed on his/her computer. The pre-compiled binaries were built on .NET 2003 compile environment. Users who do not have a .NET framework installed on their computer might encounter ‘MSVCRT.dll’ not found errors. Solutions to such problems include obtaining .NET framework from Microsoft’s website (www.microsoft.com) or compiling GTRAN3D from source on a compatible compile environment such as cygwin (www.cygwin.com). At this time, support for alternate means of source code compilation is not provided by GTRAN3D.

- Linux Users: The only requirement for the standalone desktop Linux application is GLUT (libglut.a – statically linked library or libglut.so – dynamically linked library). Most recent Linux OS distributions such as RedHat Enterprise, Fedora, Suse come with OpenGL pre-installed. Therefore, executing ‘GTRAN3D’ in the pre-compiled distribution should work right out of the box. Users should look for the dynamically linked library file libglut.so in directories /usr/lib/ or /usr/X11R6/lib/. If the library file does not exist in these directories, it is possible that GLUT is not pre-installed on the user’s computer. In such case, GLUT can be obtained from http://www.mesa3d.org. Instructions on installation can be obtained from this website as well.

Software requirements for compiling and executing the source code:

- Windows Users: Compiling the standalone desktop source code on windows requires two additional utilities – GLUT (an OpenGL Utility ToolKit) and GLUI (GLUT based User Interface). GTRAN3D source code distributes both GLUT and GLUI header files and libraries (glut.h, glui.h, glut32.lib and glui32.lib) that developers need to include these libraries in their software projects. If users choose to explicitly install a copy of GLUT instead of using the distribution that came along with GTRAN3D source, here is the link to go to: http://www.xmission.org/~nate/glut.hml. Similarly, GLUI can be obtained from: http://glui.sourceforge.net/. Again, since the libraries and headers are distributed in the source code, users do not need to install them separately.

- Linux Users: Compiling the standalone desktop source code on Linux requires two additional utilities – GLUT (an OpenGL Utility ToolKit) and GLUI (GLUT based User Interface). GTRAN3D source code distributes GLUI (glui.h and libglui.a) that developers need to include them at appropriate locations. For users interested in downloading and installing GLUI separately, the reference website is: http://glui.sourceforge.net/. A free version of GLUT can be obtained from http://www.mesa3d.org. Instructions on installation can be obtained from this website as well.

5.2.Immersive Module

Hardware requirements:

Since GTRAN3D is a 3D viewing system, graphics hardware acceleration is highly recommended although not necessary. Any video card 64MB or above can provide very decent visual output.

5.2.1. Client Side

Software requirements for pre-compiled binaries:

- Windows Users: The requirements for GTRAN3D client module for the Immersive version include glut32.dll and run-time omniORB libraries (dlls). omniORB is an open source CORBA implementation and consists of a set of libraries that help communicating data between the client and the server in a network environment. The GLUT requirements are the same as described in section 4.1. GLUT and omniORB libraries are distributed with the pre-compiled binaries of GTRAN3D. Hence, the user need not install any additional software. A few environment variables need to be set for the omniORB libraries to function. Please refer to section 5 (Installing GTRAN3D) for details.

- Linux Users: The requirements for executing GTRAN3D client module for the Immersive version include GLUT and omniORB. omniORB is an open source CORBA implementation and consists of a set of libraries that help communicating data between the client and the server in a network environment. The GLUT requirements are the same as described in section 4.1. omniORB libraries can be obtained from http://omniorb.sourceforge.net. Links to download pre-compiled libraries are also available at this website. An alternate means to obtain omniORB without the trouble of compiling from source is through installation of VRJuggler (http://www.vrjuggler.org) on the client machine. The server machine requires VR Juggler nevertheless. Through an additional step of installing VRJuggler on the client machine as well, the omniORB library files will be properly set up without the user having to hassle with compiling omniORB from source. A few environment variables need to be set for omniORB to be properly functional. Please refer to section 5 (Installing GTRAN3D) for details.

Software requirements for compiling and executing from source code:

- Windows Users: The requirements for GTRAN3D client module for the Immersive version include glut32.dll omniORB (static - *.lib and dynamic - *.dll). omniORB is an open source CORBA implementation and consists of a set of libraries that help communicating data between the client and the server in a network environment. The GLUT requirements are the same as described in section 4.1. The static libraries (*.lib) and header files (*.h) for omniORB are NOT distributed with the source code. The dynamic libraries (*.dll) are distributed though. The user would need to install omniORB through downloading from http://omniorb.sourceforge.net before compiling GTRAN3D source code. An alternate means to obtain omniORB without the trouble of compiling from source is through installation of VRJuggler (http://www.vrjuggler.org) on the client machine. The server machine requires VR Juggler nevertheless. Through an additional step of installing it on the client machine, the omniORB library files will be properly set up without the user having to hassle with compiling omniORB from source. A few environment variables need to be set for the omniORB libraries to function. Please refer to section 5 (Installing GTRAN3D) for details.

- Linux Users: The requirements for executing GTRAN3D client module for the Immersive version include GLUT (libglut.a or libglut.so) and omniORB (static - *.a and dynamic *.so). omniORB is an open source CORBA implementation and consists of a set of libraries that help communicating data between the client and the server in a network environment. The GLUT requirements are the same as described in section 4.1. omniORB libraries can be obtained from http://omniorb.sourceforge.net. Links to download pre-compiled libraries are also available at this website. An alternate means to obtain omniORB without the trouble of compiling from source is through installation of VRJuggler (http://www.vrjuggler.org) on the client machine. The server machine requires VR Juggler nevertheless. Through an additional step of installing it on the client machine, the omniORB library files will be properly set up without the user having to hassle with compiling omniORB from source. A few environment variables need to be set for omniORB to be properly functional. Please refer to section 5 (Installing GTRAN3D) for details.

5.2.2. Server Side

The primary requirement on the server side for immersive viewing is VR Juggler. VR Juggler is a collection of technologies which provide the tools necessary for VR application development. The API provides easy to use tools to port graphics applications (particularly OpenGL based) into immersive environments. The flexibility of VR Juggler allows it to be used on any VR environment (desktop inclusive).

The base VR Juggler distribution and its dependencies can be downloaded from http://www.vrjuggler.org. For novice users, the website provides tons of documentation on whats and hows. Since omniORB is a part of VRJuggler dependencies, a separate install of omniORB on the server is not necessary. This is true for both pre-compiled binary distribution as well as the source code distribution of GTRAN3D immersive server.

5.3.Web Module

There are no required installations necessary for accessing GTRAN3D system via web. However, only Firefox and Mozilla browsers currently are capable of showing 3D simulations on Windows and Linux platforms. For viewing text based simulation profiles, any browser (Internet Explorer, Opera, etc) would do on any platform. Please refer to section 6 for details on GTRAN3D usage through web.

6. Installing GTRAN3D

GTRAN3D is distributed in various zipped formats (.zip, .tar.gz, .tar.bzip2). A user can download any of them since their contents are identical. GTRAN3D does not come with a standard installation wizard. The directory hierarchy inside of the distribution is set and a pre-compiled distribution can be used as is, once un-zipped. The source distribution directory hierarchy looks similar to the pre-compiled binary directory but with a separate directory called ‘src’ and a .NET project file (windows) or a sample Makefile (Linux). The directory hierarchy for various GTRAN3D modules is explained in 5.1 and 5.2.

Note that for each module (desktop, immersive client and immersive server), the pre-compiled binaries are distributed as gwaterBin and the source is distributed as gwaterSrc.

6.1.Standalone Desktop Module

Installing Pre-Compiled Binaries:

The directory ‘gwaterBin’ inside the directory ‘gwaterWinStandalone’ or ‘gwaterLinuxStandalone’ consists of pre-compiled binaries and example simulations.

Table 2a. Contents of ‘gwaterBin’ directory

gwaterBin Directory (root):

Required

Optional

Files:

- GTRAN3D (GTRAN3D.exe)

- luka (luka.exe)

- inverse

- binverse

- glut32.dll (windows only)

Folders:

- 1oblate/

- 1prolate/

- 1sphere/

- 1bigProlate/

- 1bigSphere/

- 2ellipsoids/

- 4ellipsoids/

- 6ellipsoids/

- dummy/

Table 2a shows a list of files and folders in the gwaterBin root directory of the standalone module. The files listed in ‘Required’ column are required for the standalone module to be fully functional. GTRAN3D (GTRAN3D.exe in case of windows) is the groundwater visualization program that uses Luka as the particle flow path solver. Double clicking on GTRAN3D.exe (windows) or GTRAN3D (unix) will execute the program. Files inverse and binverse can be created first time software is run (if they are not present), but take considerable amount of time to be generated. Therefore, inverse and binverse files are included in gwaterBin and gwaterSrc directories so that the user does not need to re-generate them. Note that inverse and binverse files are platform dependent and cannot be interchangeable between operating systems, although the file names remain same.

The files and folders listed in ‘Optional’ column are not mandatory and their absence does not affect the performance of GTRAN3D. They are example simulation files created using GTRAN3D.

The standalone desktop module does not provide an interface to save an aquifer model at any arbitrary location chosen by the user. Any aquifer models are saved in the same directory as the GTRAN3D executable as a folder that the user specifies.

Compiling and Executing GTRAN3D Source:

The directory structure of GTRAN3D source code remains the same as pre-compiled binaries except that there is an additional folder called ‘src’ and a few additional files. The ‘src’ directory contains the source code. glut32.lib and glui32.lib are static window libraries required to be linked when compiling the source code, GTRAN3D.vcproj is the windows .NET project file, where the settings required for compiling the source code are stored. libglui.a is a static Linux GLUI library and is required to be linked for compiling the code on Linux. Also provided is an example Makefile for Linux. Table 2b shows the list of files and folders in the gwaterSrc root directory of the standalone module.

Table 2b. Contents of ‘gwaterSrc’ directory

gwaterSrc Directory (root):

Required

Optional

Files:

- GTRAN3D (GTRAN3D.exe)

- luka (luka.exe)

- inverse

- binverse

- glut32.dll (Windows only)

- glut32.lib (Windows only)

- glui32.lib (Windows only)

- GTRAN3D.vcproj (Windows)

- libglui.a (Linux only)

- Makefile (Linux)

Folders:

- src/

Folders:

- 1oblate/

- 1prolate/

- 1sphere/

- 1bigProlate/

- 1bigSphere/

- 2ellipsoids/

- 4ellipsoids/

- 6ellipsoids/

- dummy/

6.2.Immersive Module

Neither the client side application nor the server side application requires root or admin privileges for installation.

6.2.1. Client Side

Installing Pre-Compiled Binaries:

The directory ‘gwaterBin’ inside the directory ‘gwaterWinImmersiveClient’ or ‘gwaterLinuxImmersiveClient’ consists of precompiled binaries, dlls (in case of windows) and example simulations.

Table 3a. Contents of ‘gwaterBin’ directory

gwaterBin Directory (root):

Required

Optional

Files:

- GTRAN3DCLIENT.EXE

- luka (luka.exe)

- inverse

- binverse

- glut32.dll (windows only)

DLLs (windows only):

- COS406_rt.dll

- COSDynamic406_rt.dll

- omniCodeSets406_rt.dll

- omniDynamic406_rt.dll

- omniORB406_rt.dll

- omnithread31_rt.dll

- python15.dll

Configuration Files:

- gwater.cfg

Folders:

- 1oblate/

- 1prolate/

- 1sphere/

- 1bigProlate/

- 1bigSphere/

- 2ellipsoids/

- 4ellipsoids/

- 6ellipsoids/

- dummy/

Table 3a shows a list of required and optional files and folders for executing the immersive client application. The DLLs in the listing are required by GTRAN3D to be fully functional. They aid in the communication of data throughput between the client and the servers. Although not necessary, these DLL files can be placed in any directory on the user’s machine provided the path variable is set (PATH in windows and LD_LIBRARY_PATH in Linux). The rest of the folder structure is similar to the standalone desktop module as explained in section 5.1.

omniORB, needs to be installed for facilitating the communication of data from the client to the server. Setting up omniORB on a windows desktop/laptop/tablet PC is described below, and for illustration purpose the version of omniORB being set up is 4.0.6:

- Copy/FTP omniORB-4.0.6_win32.zip located at /home/<username>/groundwater/OmniRelated/ to a windows machine.

- Unzip and extract it so say, C:\OmniORB-4.0.6\

- Set the following environment variables for windows

- OMNIORB_HOME = C:\OmniORB-4.0.6

- OMNIORB_CONFIG = %OMNIORB_HOME%\omniORB.cfg

- OMNINAMES_LOGDIR = %OMNIORB_HOME%\<specify_a_writable_directory_for_omniNames_log_files >

- Path = %Path%;%OMNIORB_HOME%\bin\x86_win32

- Change line 254 in omniORB.cfg: InitRef = NameService=corbaname::localhost to InitRef = NameService=corbaname::serverName.buffalo.edu

Compiling and executing immersive client:

The directory structure of GTRAN3D source code remains the same as pre-compiled binaries except that there is an additional folder called ‘src’ and a few additional files. The ‘src’ directory contains the source code. Table 3b lists out the directory structure of the immersive client source directory (gwaterSrc). The listings under ‘Required’ column show the files and folders mandatory for GTRAN3D immersive client to be fully functional. The listings under ‘Optional’ column show example simulation directories.

Table 3b. Contents of ‘gwaterSrc’ directory

gwaterSrc Directory (root):

Required

Optional

Files:

- GTRAN3DCLIENT.EXE

- luka (luka.exe)

- inverse

- binverse

- glut32.dll (windows only)

- glut32.lib (windows only)

- glui32.lib (windows only)

- GTRAN3D.vcproj (windows)

- libglui.a (Linux)

- Makefile (Linux)

DLLs (windows only):

- COS406_rt.dll

- COSDynamic406_rt.dll

- omniCodeSets406_rt.dll

- omniDynamic406_rt.dll

- omniORB406_rt.dll

- omnithread31_rt.dll

- python15.dll

Configuration Files:

- gwater.cfg

Folders:

- src/

Folders:

- 1oblate/

- 1prolate/

- 1sphere/

- 1bigProlate/

- 1bigSphere/

- 2ellipsoids/

- 4ellipsoids/

- 6ellipsoids/

- dummy/

Make sure the required files and folders are in place in a directory as illustrated in Table 3b. Here are a few tips on compiling the immersive client on windows.

- The VC7.1 (.NET 2003) project files contain the essential information required to compile the source. However, make sure that the source is compiled as a 'Release' version and not as a 'debug' version unless you have debug binaries of omniORB distribution installed. Change omniORB settings if you really know what you are doing.

- If compiling as a release version (the VC7.1 project's default settings) the Run-time library should be set as 'Multi-threaded DLL (/MD)'. When you open the project in .NET 2003, you can find this option under: Project → <project name> Properties → C/C++ → Code Generation → Runtime Library.

- Double click on GTRAN3DCLIENT.exe (or) execute it through visual studio .net 2003

- When compiling the source on a Linux platform, the Makefile provided in the distribution can be used as a template for creating a user’s own Makefile. The compiled code can be executed through running GTRAN3DCLIENT.

6.2.2. Server Side

The immersive system (power wall or a cave) is the server that listens to data from the client application. VR Juggler contains a slew of tools required for running immersive applications, which includes omniORB for communicating with the client. Refer to the documentation of VR Juggler for the installation at http://www.vrjuggler.org.

The following environment variables need to be set on the immersive system assuming that the shell type is tcsh:

#Base environment variables

setenv VJ_BASE_DIR /home/vr/Juggler/2.0/vrjuggler-2.0.1-irix-n32-posix

setenv VJ_DEPS_DIR /home/vr/Juggler/2.0/vrjuggler-2.0.1-irix-n32-posix-deps

setenv VJ_CFG_PATH $VJ_BASE_DIR/share/vrjuggler/data/configFiles

setenv JDK_HOME /usr/java

setenv LD_LIBRARY_PATH /usr/lib32

#Required VR Juggler environment variables

setenv LD_LIBRARYN32_PATH "${VJ_BASE_DIR}/lib32:${VJ_DEPS_DIR}/lib32"

set path=( ${VJ_BASE_DIR}/lib32 ${VJ_BASE_DIR}/bin $path )

alias vjcontrol ${VJ_BASE_DIR}/bin/vjcontrol

#example power wall configuration

setenv powerWallConf $VJ_CFG_PATH/c6/C6.lego.1con.1pack.jconf

#OmniORB Settings

setenv OMNIORB_HOME $VJ_DEPS_DIR

setenv OMNIORB_CONFIG /home/<username>/omni4.0.6/omniORB.cfg

set path=( ${OMNIORB_HOME}/bin $path )

setenv OMNINAMES_LOGDIR /home/<username>omni4.0.6/omniNamesData

The paths to the base environment variables are to be appropriately specified so that the remaining variables are automatically set.

The immersive server application is built on Irix and Linux platforms only. The user is free to download the source code for GTRAN3D immersive and compile it on a windows platform but the chances of an immersive six wall cave or a power wall using a windows environment are quite slim.

Installing Pre-Compiled Binaries:

The directory ‘gwaterBin’ inside the directory ‘gwaterLinuxImmersiveServer’ or ‘gwaterIrixImmersiveServer’ consists of pre-compiled binaries as shown in Table 4a.

Table 4a. Contents of ‘gwaterBin’ directory

gwaterBin Directory (root):

Required

Optional

Files:

- GTRAN3DSERVER

Configuration Files:

- gwater.cfg

Files:

- visualization_ellipsoid.viz

- visualization_location.viz

- visualization_parameters.viz

- visualization_particle.viz

- visualization_timestep.viz

In a very minimal configuration, the gwaterBin directory for the immersive server does not need any thing other than GTRAN3DSERVER and gwater.cfg, as listed as ‘Required’ in Table 4a. The installed VRJuggler on the server and the set environment variables take care of communication component between the server and the client. Therefore, additional files and folders are not needed for GTRAN3DSERVER to be functional. Executing GTRAN3DSERVER requires one or more arguments and is described in section 6.2.2.

Compiling and executing immersive server:

The directory ‘gwaterSrc’ inside of ‘gwaterLinuxImmersiveServer’ or ‘gwaterIrixImmersiveServer’ consists of the following files and folders as listed in Table 4b.

Table 4b. Contents of ‘gwaterSrc’ directory

gwaterSrc Directory (root):

Required

Optional

Files:

- GTRAN3DSERVER

Configuration Files:

- gwater.cfg

Folders:

- src/

Files:

- visualization_ellipsoid.viz

- visualization_location.viz

- visualization_parameters.viz

- visualization_particle.viz

- visualization_timestep.viz

The contents of the gwaterSrc directory are similar to that of Table 4a except that there is an additional file (Makefile) and a folder (src) for compiling the source code. GTRAN3DSERVER is built through compiling the code using the example Makefile provided. Executing GTRAN3DSERVER requires one or more arguments and is described in section 6.2.2.

7. Usage

Notes:

- The software package is designed so that simulations saved on a standalone desktop application or an immersive client on one platform (e.g., Windows) can be opened directly on another platform (e.g., Linux) without any alterations.

- The Luka input file (input.dat) and the output file (location.dat) do not contain any headers when files are created by GTRAN3D. Therefore, input.dat and location.dat that are created directly by the user (e.g. when using Luka as stand-alone application) can be opened by GTRAN3D provided that files are in the appropriate format.

- GTRAN3D and its dependencies (files and folders listed as ‘required’ in Tables 2 and 3) MUST be located in the same directory. GTRAN3D saves any new aquifer models created by the user as additional directories, in this directory, as specified by the user.

7.1.Standalone Desktop Module

7.1.1. General

The use of cross platform compatible graphics tools – OpenGL, GLUT and GLUI allows GTRAN3D to maintain an identical look and feel of the standalone desktop on various platforms. While GLUT provides improved utilities in 3D viewing, GLUI provides a simple yet extensive graphical user interface features. Figure 1 shows a screen capture of a blank simulation just after executing GTRAN3D.exe.

The black part of the screen shows an orange cubical bounding box with capped red, green and blue lines indicating X, Y and Z axes. To the left of the screen are several options through which the user initializes the aquifer model and viewing parameters.

7.1.2. Navigation and Viewing Options

Navigating through the 3D domain on a desktop is made using mouse. The following are the functions provided:

- Left Button: Rotate

- Middle Button: Zoom

- Right Button: Pan

Figure 2 shows the viewing options interface in detail. The checkboxes are toggle boxes that switch on and off various view features. Culling is a feature used to improve the performance of the visualization system. When the number of ellipsoids and particles are considerably large, the real-time interactivity of the simulation decreases due to saturated video memory. Turning culling on will cull that part of 3D simulation that is outside of the view frustum, thereby increasing the performance.

In certain situations where three button mouse is not available (e.g., Apple mouse, 2 button mouse), the feature Navigation Emulation as shown in Figure 2 complements the navigation in the interface.

7.1.3. Aquifer and Model Parameters

Figure 3 shows various aquifer and model parameters that a user can set when modeling contaminant transport through a VPM model. The control parameters Solve and Transport control numerical engine Luka execution: first time VPM model is created and particles are transported both parameters need to be checked on. In subsequent simulations of particle tracking (e.g. if particle tracking time is increased or new particles are added), the Solve parameter can be turned off, as long as no changes to the VPM model are made.

Model precision is a selectable number between 3 and 19. It corresponds to the order of mathematical functions used to describe influence of each in-homogeneity. Higher orders imply higher precisions in flow solution (that is behind particle tracking simulations), and longer execution times.

Each inhomogeneity contains (order+1)² coefficients. These coefficients are computed using an iterative algorithm which is terminated once relative change in coefficients between two subsequent iterations is less than Tolerance. The default Tolerance value should be sufficient for most simulations.

The GTRAN3D does not use any particular set of units. The user must hence use a consistent set of units throughout the software. For example, background hydraulic conductivity [L/T] (specified here) must be specified in same units as conductivity of inclusions (specified later). Same units must be used to set components of uniform flow [L/T] and molecular diffusion coefficient [L²/T].

A default bounding box size[L] of 15[L] is used. The box size can be made larger depending upon the model. This box is used only for visualization purposes: it does not affect particle tracks in any way. The aquifer and model parameters must be saved once they are set.

7.1.4. Adding ellipsoids and particles to the aquifer model

The user is now ready to add spheroidal inhomogeneities (ellipsoids) to the aquifer background. Figure 4 shows the interface for adding ellipsoids and particles. A user can choose to add inhomogeneities of 3 types – prolate and oblate ellipsoids and spheres. A prolate ellipsoid is created by rotation of an ellipse about its long axis. An oblate ellipsoid is created by rotation of an ellipse about its short axis. A sphere has a uniform diameter through out.

Figure 4a shows various characteristic attributes of the ellipsoids. x-, y- and z- rotational components determine the orientation of the rotational axis of each inhomogeneity (long axis for prolate and short axis for oblate ellipsoid). Long and short semi-axes [L] determine the size, while coordinates of the center [L] determine the location. Ellipsoids can be added and deleted. The ellipsoids are indexed so that deleting them is made easy. Added ellipsoids are red in color while a selected ellipsoid for deletion is displayed in green color. The yellow colored ellipsoid specifies what type of ellipsoid is currently being created, and is called the ellipsoid creator. Once the ellipsoid is added, this ellipsoid turns red indicating that it is added to the ellipsoid database in the aquifer model. Figure 5 illustrates these colors.

Particle addition and deletion is shown in figure 4(b). Although displayed as small spheres, particles in the simulations are infinitesimally small – they do not have a specific shape. They are denoted by cyan colored spheres for the visualization. The number of steps when particle positions are saved and the total tracking time are user-defined parameters. Particle tracking is performed using variable time step that is automatically selected by the numerical engine. Particles can be added individually or as a grid. The grid addition of particles facilitates a 2D matrix of particles in one single step. Similar to ellipsoid deletion, particles can be deleted as well. A selected particle for deletion is shown in red. Figure 6 illustrates these colors.

7.1.5. Computing particle flow path

With the addition of ellipsoids and particles, the GTRAN3D system is ready to compute the particle flow paths. Hitting the compute button performs this task. During the computation, the groundwater solver Luka is executed and flow paths are computed. Please note that the application might seem to be doing nothing during flow path computation. A child process (Luka) is spawned from the desktop application that causes GTRAN3D to freeze. Once the particle flow path computation is complete, the interaction returns to normal. In addition, a ‘Transport Animation’ sub-window opens at the bottom of the screen. Figure 6 shows an example output.

7.1.6. Viewing particle flow path

When the particle flow paths are computed, a Transport Animation sub-window is created at the bottom of the screen that contains VCR type controls. These controls facilitate animation of particles along the computed flow path. The animation can be stopped, rewound or can proceed forward and backward in steps with a press of a button to facilitate a better understanding.

In addition, a Lagrangian view option is provided which allows the view point to be placed on a selected particle for fly-through viewing. The yellow lines in figure 6 indicate the computed particle flow path.

7.1.7. Saving/Opening aquifer models

The models created through GTRAN3D can be saved and re-opened. The flexibility of GTRAN3D lies in that models created on an operating system (e.g., Windows) can be retrieved on another operating system (e.g., Linux) without any modification to the aquifer model files. Figure 7 shows a simulation panel that allows saving and retrieval of aquifer models.

When saving VPM and particle model, GTRAN3D application creates a directory that the user specifies in ‘Save Simulations’. A space between two different words when saving a file is automatically converted to an underscore. For example, if a user saves an aquifer model with the name ‘run 1’, GTRAN3D saves it as ‘run_1’. Similarly, if a user tries to open a model ‘run 1’, GTRAN3D expects to find the model ‘run_1’ in the root directory.

A user can choose to open: a) input.dat (Luka input file that contains VPM and initial particle positions) b) location.dat (Luka output file that contains particle trajectories) or c) simulation directory previously created using GTRAN3D. The checkboxes facilitate selecting a), b) or c). File paths and file extension is required to be typed in when opening input.dat and location.dat. Opening a simulation directory however requires directory name only (Note: the directory must be placed under Root directory). A user can open either input.dat or location.dat or both. When opening a simulation directory, checkboxes for input.dat and location.dat get disabled.

File structure of a saved aquifer model using GTRAN3D:

It is not necessary to know the details of how aquifer model files are managed by the GTRAN3D system, but is explained below if it interests anyone.

Luka, the particle flow path solver requires an input file ‘input.dat’. This input file is interactively created through the GTRAN3D system. Upon execution of ‘luka’, an output file ‘location.dat’ is created. The following is a list of files created in a saved aquifer model using GTRAN3D. (Assume that the name of the saved simulation is ‘test1’).

test1/

- test1.sim (contains a list of *.viz and *.dat files)

- first_10_lines_of_input.viz (contains header extracted from input.dat)

- input.dat (input to luka)

- location.dat (output from luka execution)

- visualization_ellipsoid.viz (contains ellipsoid information)

- visualization_location.viz (contains particle flow path information)

- visualization_parameters.viz (contains aquifer parameter information)

- visualization_particle.viz (contains particle information)

- visualization_timestep.viz (contains particle animation information)

*.viz are working ASCII visualization files required for GTRAN3D to display anything on screen. File management in GTRAN3D is made through *.viz. *.dat files are touched only when ‘luka’ is executed.

7.2.Immersive Module

The desktop application allows a user to interact with a program through a traditional keyboard and mouse interface. This interface in an immersive environment however, restricts a user from navigating in 3D space. To facilitate interactive groundwater modeling and viewing, the GTRAN3D system is split into two parts – building an aquifer model through a client program (on a desktop/laptop/table interface), and navigation in the immersive system through a server program (using wand and head tracking system).

7.2.1. Client Side

The client program for immersive viewing has a similar look and feel set up as the standalone desktop application except that it has additional widgets for communicating information from the client to the server (immersive system).

A user is given 4 different options for sending data from the client to the server, as seen in figure 8 under ‘Immersive Connect’ panel. As the name indicates, ‘ellipsoids only’ will update the immersive with only ellipsoids and ‘particles init position’ will update the immersive with only the particles’ initial position. This information is relatively less and sending it to the server will not take long time depending upon the Internet connection speeds. Sending ‘particle paths only’ updates the immersive with the entire flow path information and could take quite long because the amount of information is quite large. Sending ‘Entire Simulation’, as expected, will take quite long because ellipsoids information, particle information, and particle paths will be sent.

The viewing options are designed to work for both the client and the immersive server. That means, checking on ‘Wireframe mode’ will put both the client and the immersive display in wireframe mode. These viewing options are updated on the immersive display through a configuration file called ‘gwater.cfg’, locatable in the working directory as other binaries/source code.

Options -

- Show Ellipsoids

- Wireframe mode

- Show Particles

- Bounding box

- Show Axes

will work for both the client and the immersive server.

Figure 9 shows other immersive update options from the client.

The ‘Update Immersive’ button updates the following views in the immersive environment:

- Eulerian and Lagrangian view

- Lagrangian view on a selected particle

- Toggle between ‘Position only’ and ‘Entire Path’

Please note that the ‘Navigation Emulation’ in figure 8 and the VCR control buttons – Play, Stop, etc buttons in figure 9 will work only on the client machine and not on the immersive server. Navigation in the server is completely managed by the head tracker and wand as explained in section 5.2.2.

7.2.2. Server Side

The server is assumed to be SGI Irix and it needs to be started first. The following is a list of to-dos before interacting with the application.

- Start omniNames service by running ‘omniNames’ at the command prompt in a terminal/console.

- If this is a first time operation of omniORB on the machine containing the GTRAN3D server, the command ‘omniNames –start’ needs to be given so that an omniORB profile for the server is created.

- GTRAN3D server application will fail if omniNames service is not initated.

- At the command prompt in a separate terminal, type in gwaterServer $powerwallconf in the path where the immersive GTRAN3D binaries are located.

- For a standalone simulation (i.e., if running on a desktop in sim. mode), type in gwaterServer standalone.jconf at the command prompt.

The immersive Juggler application should be running now and any aquifer models created or opened should be looking life sized. The interaction with the immersive version is through wand, goggles and a head tracking system. The head tracking system changes the perspective of the display according to the user’s position. Stereo viewing is made possible through the use of active stereo goggles, sometimes also called as shutter glasses (figure 10).

Navigation is made using a wand that has more than 2 or 3 buttons and a little joystick interface to facilitate rotation or movement. These devices are not unique and each VR system could have a different wand device.

The immersive version of GTRAN3D leverages the VRJuggler’s ability to use any generic wand for groundwater visualization. However, a user will have to play around with the buttons a little before being able to smoothly navigate within a 3D groundwater aquifer.

Figure 11 shows some of such commonly used navigating/pointing devices.

Figure 12 shows a GTRAN3D user in a six wall immersive system with wireless head tracking and navigation system at the Virtual Reality Applications Center, Iowa State University.

7.3.Web Module

The GTRAN3D system allows accessing and performing simulations via web using a web browser, thereby increasing the portability of GTRAN3D. This tool becomes especially handy when a local install of GTRAN3D software is not possible and when the user has input files (input.dat) already available. The groundwater particle flow path solver ‘Luka’ resides on the web server along with the files ‘inverse’ and ‘binverse’. When the user uploads an appropriate input file (input.dat), Luka can be triggered and particle flow path can be computed using the web server. The results can then be displayed on the web browser either as customized text output for ellipsoids and particles or viewed as a 3D display of particle flow paths similar to the GTRAN3D standalone module. All simulations computed off the web server are saved on a MySQL database thereby providing access to past simulations the user has uploaded and computed.

The only requirement for using the web module is to have an appropriate input file (input.dat), a web browser that can accept cookies and an Internet connection.

For viewing text based output, any web browser on Windows, Linux and SGI Irix Operating Systems is sufficient. For viewing 3D simulations, the web browser installs the web version of GTRAN3D and scripts required for its automatic execution. Currently, Firefox and Mozilla browsers are the only ones compatible for viewing the 3D simulations via the browser. The web scripts are written using PHP (Hyper Text Pre-Processor) language and executed on an Apache Web server. The database management is made using MySQL relational database management system.

The URL of the GTRAN3D web module is available at:

http://grierson.nyscedii.buffalo.edu/GTRAN3D/

The following paragraphs explain how to use the web Application.

User authentication

The web scripts use a basic cookie based user authentication scheme. The user has to make sure that the browser is capable of accepting cookies before using the GTRAN3D Web Application. The web module has a tabbed interface and figure 13 shows the homepage of the web application. The wordings in the screenshots might differ a little bit from the actual website due to enhancements made from time to time. However the layout, appearance and the functioning of the site remains the same. The tabs ‘View Results’ or ‘Upload Input File’ requires user to provide a valid username and a password.

Uploading input file

Figure 14 shows the interface to upload an input file to the web server. This option can be selected from one of the tabs on the top of the simulation home page. Select the input file from the local machine using the Browse button as shown in Figure 14 and hit ‘Submit’.

Once the submit button is hit, the input file is uploaded to the web server and is ready for the particle paths to be computed. This is shown in figure 15. When the input file is received by the web server, this page confirms it and waits for the user to click the link ‘Proceed’ to compute the particle flow path.

The particle flow path computation could take time depending upon the number of ellipsoids to be solved in the aquifer and the number of particles to be tracked. The web page refreshes itself once particle solving is complete and will prompt the user to view the results. This is shown in figure 16.

An important note:

The input file is an ASCII text file that does not have any header indicating that it is readable by groundwater solver Luka. The results are unpredictable if the user uploaded an incorrect input file.

Viewing Results

A user can view the results either in text mode or as 3D simulations. Once the ellipsoid coefficients are solved and particle tracking is completed, the results from the output files are saved into a MySQL database. Figure 17 shows the view results page where a record of all the web simulations was previously performed. A user can choose to view ellipsoid properties or particle properties of a selected simulation performed previously. Alternately, a 3D simulation of the selected simulation can be viewed as well.

Individual viewing of ellipsoid and particle profiles are quite straight forward.

In the text-based ellipsoid analysis of a selected simulation, a user can choose to:

View all ellipsoid properties
View only Prolate properties, if existing
View only Oblate properties, if existing
View only Sphere properties, if existing
View a selected ellipsoid, from a drop down list of ellipsoid properties

In each of these options, a user can view information on: a) the spatial location, b) the orientation, c) the long & short axes lengths of ellipsoids and d) hydraulic conductivity.

In the text-based particle analysis of a selected simulation, a user can choose to:

View all particle properties
View all particles for a specific timestep
View a specific particle for all timesteps
View specific particle in a specific timestep

In each of these options, a user can get the ID, spatial location and the velocity component of the particle(s).

When a user selects to view 3D simulations, the web script detects the browser type and the operating system. For a compatible browser and the operating system, as explained at the start of this section, a user can click on the link ‘Display Visual Output’ to view 3D output. Upon clicking this link, a pop up window opens up requesting for the user’s permission to install software on the user’s computer. The software is installed on a temporary directory on the user’s computer (C:\Documents and Settings\<username>\Local Settings\Temp\ on a windows machine or \tmp\ or \var\tmp\ on a unix machine) and hence root/admin privileges to install this software are not required. Request to install the software window comes up every time a user chooses to view a 3D simulation for a selected simulation profile. Figure 18 shows a sample visual output.

Important Note for web module users:

The web server is not capable of handling and solving input files containing a large number of ellipsoids and particles. Please make sure the number of ellipsoids and particles in the input file are reasonable (say, 5 – 10 ellipsoids and 50-60 particles). Computation time for the particle flow path would very much depend upon the user load on the web server. Flow path computation processes that take more than 15 minutes on the web server are likely to be killed.

8. Acknowledgments

This software is based upon work supported by the National Science Foundation under Grant EAR-0218914.