User's Guide

This guide is organized in a manner which duplicates the normal approach to solving a subsurface flow and transport problem with the STOMP simulator. The STOMP simulator has been designed with a variable source code, where source code configurations are referred to as operational modes. Operational modes are classified according to the solved governing flow and transport equations and constitutive relation extensions. Therefore, prior to creating an input file or assembling the source code, the user must choose the appropriate operational mode for the particular subsurface system of interest. The selection of an operational mode requires that the user conceptualize the physical system as a computational system, which will always require making simplifying assumptions about the physical system. The complexity and execution speed of an operational mode is generally inversely related to the number of simplifying assumptions the user can justify about the physical system. Regardless of the operational mode complexity, the simulation of physical subsurface systems with the STOMP simulator always involves assumptions inherent to the founding governing equations and constitutive relations.

Having chosen an operational mode, the user should then set about creating an input file. Input files, simply stated, are translations of the physical system description into a computational system. The user communicates information about the physical system to the STOMP simulator through the input file. The input file, operational mode, and linear system solver determine the source code configuration and required dimension of the executable. Executable dimensions are controlled through parameters, which are communicated to the STOMP simulator through the "parameters" file. It is the user's responsibility to ensure that the parameters listed in the "parameters" file are sufficiently dimensioned for the input file, operational mode, and selected linear system solver. Having created "input" and "parameters" files that describe the physical system to be modeled, the next step in the simulation process involves assembling the source code, creating an executable, and executing the code.

The STOMP simulator offers the user considerable flexibility in executing and controlling the execution of simulations. The user can create numerous execution periods within a single simulation, which differ with respect to time step advancement and convergence control. Controls of this sort are beneficial for simulations involving complex time-varying boundary conditions or sources. Moreover, the user can produce intermediate "restart" files which are essentially "snapshots" of the primary variables. Simulations can be restarted from intermediate "restart" files using the altered or unaltered descriptions of the computational system. Various techniques and approaches for executing the simulator are also described in this document. Other examples of simulator applications and application techniques can be found in the STOMP Applications Guide.

The STOMP simulator generates results in a number of different formats, which can be controlled by the user. This guide describes these formats and the output capabilities of the simulator. Output formats include text files of simulation results and printing to the standard input/output device, which is typically a terminal or workstation screen. All input and output files generated by the simulator including "restart" files are ASCII text files, which can be read or modified by conventional text editors. Output data have been grouped in two basic formats, historic and snapshot. Historic data are records of selected variables over the simulation period. These data records are essential for creating graphs or plots showing the progression of variable values over simulation time. Snapshot data are records of selected variables at a particular moment in time over the computation domain. These data records are essential for generating images of variable values over the computational space. Snapshot data records can also be linked in a time sequence to show the evolution of variable values in both computational time and space.

Beyond providing operational type instructions, this document also contains useful information for executing the simulator with a debug utility or making modifications to the source code. The user may often be able to isolate input errors or convergence problems by tracing the execution of the simulator with a debug utility. To assist the user in performing debug executions or in making modifications to the code, critical information about the operational flow path, subroutine functions, and variable descriptions have been provided in this guide. The source coding for the STOMP simulator is suitably documented with comment statements; however, none of the variable or parameter names are defined nor is a general flow path for simulator outlined. Therefore, this guide provides essential information about subroutines and variables. Indexing of primary and secondary field variables and flux variables in the STOMP simulator is complex and depends on the operational mode. A description of the indexing patterns developed for the simulator are also provided in this guide.

Code Design

The primary design guides for the STOMP simulator have been modularity, computational efficiency, and readability. A modular code architecture is beneficial because of the ease of reading, maintaining, and modifying the algorithms and is essential to the variable configuration source code. Computational efficiency refers to both memory requirements and execution speed. The STOMP simulator has been designed with a variable configuration source code which allows the memory requirements and code algorithms to be partially customized to the computational problem. This approach offers considerable advantages with respect to achieving a computationally efficient code design. Within this source code framework, however, many design choices have been made that affect computational efficiency. Algorithm design often offers options between memory and speed. For example, to lessen memory requirements a code designer may opt to repeatedly compute commonly used variables. Conversely, execution speed may be increased at the cost of increased memory requirements, by storing commonly used variables after their initial computation. Generally, the approach in the STOMP simulator has been to favor increased memory requirements to gain computational speed. This design approach has been chosen because of the current state of computer architecture and capabilities. Because the STOMP simulator has been created as a scientific tool, algorithm readability has been a primary design guide. As a scientific tool, the simulator was never expected to remain unmodified, but rather a constantly changing package of software tools which could be applied to new or more complex problems. This design goal makes readability an essential feature of the code. Code readability has been achieved through an extensive use of comments, a modular design, a large group of common blocks, and minimal subroutine and function arguments.

Input File

The STOMP simulator is controlled through a text file, which must be entitled "input" for proper execution. This input file has a structured format composed of cards, which contain associated groups of input data. Depending on the operational mode, input cards may be required, optional, or unused. Required cards must be present in an input file. Optional cards are not strictly required to execute the simulator, but may be required to execute a particular problem. Unused cards are treated as additional text that is unrecognized by the simulator, but will not hinder a proper execution. Cards may appear in any order within the input file; however, the data structure within a card is critical and must follow the formatting directives, shown in the Appendix. Data structures within cards vary with operational mode, which requires the user to follow a series of logic type statements to construct a readable input file. The simulator contains logic to capture and report some input errors. These capabilities are primarily limited to indicating syntax or formatting type errors and will generally not reveal errors such as those associated with ill-posed problems, atypical parameters, or inappropriate grid structures, for example. Because of their text format, STOMP input files may be generated with text editors, word processors, spread sheet programs, or graphical user interfaces and are portable between computing environments. The simulator's read routines are case insensitive (e.g., SAND and sand are equivalent) and allow considerable flexibility in specifying the simulation directives; however, close attention to the formatting instructions in this section will be necessary to prepare an executable input file.

Parameters File

This section describes the format and contents of the "parameters" file, which is required to compile and execute the STOMP simulator. Parameters are used by the FORTRAN programming language and compilers to allocate memory for storage of variables. The FORTRAN language is unable to allocate memory dynamically; therefore, all memory storage requirements must be defined at compilation time. No execution errors will occur if the memory allocated is greater that required by the simulation, unless the memory requirements exceed the computer's capabilities. Unless necessary, the user should avoid executing simulations which require the use of virtual memory. The time required to swap data between the virtual memory storage device and the active memory typically yields poor execution speeds. The STOMP simulator requires two types of parameters (declared and computed) to be defined, prior to compilation. The user is responsible for properly assigning all of the declared parameters. Declared parameters are assigned by modifying the "parameters" file supplied with the STOMP simulator using a text editor (word processor) or by creating a new "parameters" file. The equations for the computed parameters must be included in each "parameters" file after the declared parameters. The parameter definitions given in this manual represent minimum acceptable values. All declared parameters, except for "switch" type parameters, must have minimum values of 1. Undersized parameters will generally yield execution errors, which may or may not be detected by the system. Oversized parameters are permissible, but can result in excessive memory allocation.

Compilation & Execution

The STOMP simulator is written in the FORTRAN 77 language, following American National Standards Institute (ANSI 1978) standards, and was designed primarily for execution on computers with UNIX operating systems. An assembled source code, however, can be compiled and executed on any computer with an ANSI FORTRAN compiler, provided that the machine has sufficient memory. Although there is a general correspondence in computer design between memory size and execution speed, sufficient memory to compile and execute is not an assurance that the machine will have sufficient execution speeds to complete a simulation within a reasonable time period. The simulator should be thought of as a collection or library of source coding, where each operational mode requires a particular group of source codes modules from the library. The normal procedure for building an executable version for a particular operational mode involves compiling the required group of library source codes, using the declared and computed parameters in the "parameters" file to define memory requirements, and linking the compiled object files to create an executable. An alternative would be to assemble or concatenate all of the source code libraries required for a particular operational mode into a single file and then subsequently compile the assembled source code. Either procedure can be performed manually or automatically. The "make" utility, which generates a sequence of commands for execution by the UNIX shell, can be used to automatically compile and link the required source code libraries for a particular operational mode. A "makefile," which contains a "make" utility instruction set, has been built to generate an executable or assembly source code for the simulator.

Output Files

The STOMP simulator can generate, depending on the requested output and saturation function type, two data files for restarting a simulation and three simulation result files. Every execution produces an output file named "output." If the simulation concludes without a fatal error, then a "restart.n" and a "plot.n" file are also generated. Restart and plot file names include extensions (i.e., ".n" ) which correspond to the time step for which the file was written. For example, a restart file named "restart.39" would have been written at the conclusion of the 39th time step. A surface file named "surface" is generated whenever a Surface Flux Card is included in the "input" file. All output files generated by the simulator ("output," "restart.n," "plot.n," and "surface" files) are ASCII text files.