HydroGeoSphere/General Guidelines

Before presenting in detail the input data needed for the numerical simulations, some general information about the format and nature of the input data is first given.

Input/output procedure

There are two steps involved in solving a given problem. First, a data file is prepared for the preprocessor (called grok ) which is then run to generate the input data files for HydroGeoSphere. Second, HydroGeoSphere is run to solve the problem and generate output data files.

The grok input file name consists of a meaningful prefix of up to 40 characters to which the extension .grok is appended. This prefix will determine the input and output filenames. The grok listing file name will be the problem prefix to which the letter o and the file extension .eco are appended. For example, if the problem prefix specified by the user is test, the general input file to be created by the user will be test.grok and the output listing, or echo, file generated by the preprocessor will be testo.eco. Some simulations will require more than one input file (e.g. initial heads read from file) and will result in the generation of more than one output file. As a rule, all input files needed during a specific simulation will have the problem prefix plus a given extension as filename while all generated output files will have the problem prefix, the letter o, plus a given extension as filename.

Throughout the manual, we will adopt the convention of using italics to indicate problem-dependent, user-defined portions of filenames (e.g. prefix, species name etc.) and typewriter font to indicate invariant portions generated by HydroGeoSphere. For example, in the filename prefixo.conc.species.001 the prefix and species portions would be the user-defined prefix and name of a solute, or species, while the o.conc. and .001 portions would be generated by HydroGeoSphere automatically.

Preprocessor

After the preprocessor starts executing, it prompts the user to enter the prefix for the problem interactively from the keyboard. For cases in which the same input file is being used repeatedly, you can create a file called batch.pfx which consists of a single line which contains the problem prefix. If the file is present, the prefix will automatically be read from the file and you will not be prompted to enter it from the keyboard. This file should be placed in the same directory as the prefix.grok file.

Briefly, the preprocessor performs its tasks in the following order:

1. Read and allocate default array sizes
2. Read problem identification information
3. Read instructions for generating grid
4. Perform grid modifications if necessary
5. Generate default properties for all parameters
6. Read optional instructions for modifying the default parameters
7. Write the HydroGeoSphere-compatible data files

Tasks 3 and 6 are guided by instructions issued by the user in the prefix.grok file. The generation of a complete set of default data by Task 5 tends to minimize the amount of data which must be supplied by the user.

Here is an example instruction and some input data which illustrates some common conventions that will be used throughout the manual:

Example instruction text

1. xl, nbx Domain length and number of blocks in the x-direction
2. xi(i),i=1,nx x-coordinates of the nx nodes.
3. inode...end Node numbers.

• • •

Each preprocessor instruction is written as the heading of its own section, in order to make it easier to find in pages that have a table of contents. Instructions appearing elsewhere in the text are written in large sans serif font. An instruction must be typed in the prefix.grok file exactly as shown, with the exception that it is not case-sensitive, and blanks before and after the instruction are optional. Note that only one blank is allowed between any two words in an instruction.

If the instruction requires input data, there will follow a series of numbered lines, each containing bolded variable names and a description of what is to be read. Each numbered line will correspond to one or more FORTRAN read statements.

Usually, the number of items required in the data file are indicated by how many bolded variable names are present on the line. The default FORTRAN variable naming conventions are in effect. This means variables starting with the letters I--N inclusive require integer values, while all the rest require real values, unless stated otherwise in the case of string or logical variables. Numerical values are read in free-format so integers and reals do not need to be lined up in columns and they can be separated by blanks or commas. A descriptive comment can be included inline after the last data value has been read from the line, but should be avoided when reading character strings (e.g. file names).

In this example, 3 items of input are required. The first item xl, nbx requires that the user enter a real value (i.e. domain length) followed by an integer value (i.e. number of blocks)on the first non-blank or uncommented line following the instruction.

The second item xi(i),i=1,nx reads nx real values into the array xi. The size of nx is problem-dependent (e.g. number of nodes in x, number of species etc.) and it is up to the user to supply enough values to satisfy the read statement. The values may be entered on one line or spread out over multiple lines as desired. If they are entered on one line, they should be separated by spaces or commas.

Finally, the third item inode...end indicates a list, in this case of node numbers, that is to be read until an end card is encountered. The list values must be entered one per line.

The end of the documentation that pertains to a specific instruction is designated by 3 dots:

• • •

So for this example instruction, assuming that nx is equal to 5, the following statements in the prefix.grok file would satisfy the input requirements:

Example instruction text
10.0   100
0.0   2.0   4.0   6.0   8.0   10.0
1
2
3
5
6
end

Some instructions are controlled by input routines that have their own subset of input instructions, some or all of which may be optional. For example, the instruction Solute is used to define a new solute and in it’s simplest form appears as:

Solute
end

In this case, the End instruction immediately follows the Solute instruction, and no optional instructions have been issued. The End statement is required so that grok knows when to exit the solute definition routine. Such instructions will be indicated using the following convention:

Example instruction text...End

• • •

where the text ...End indicates that the instruction (e.g. Solute) will be followed by optional instructions or input and terminated by an End instruction.

Before grok processes instructions contained in a prefix.grok or a material properties file (see Section 5.8.1.6) it first makes a working copy of the file in which any line which is completely blank or which begins with an exclamation point(!) is removed and in which the contents of any included file are copied. This allows you to include blank lines and comments when and where required to improve the readability and clarity of the input.

Included files can be used to avoid having to cut and paste or comment and uncomment large sections of input instructions. Long lists (e.g. of node numbers or boundary condition data) and cases where various different grid generation approaches are being tried are good candidates for application of the include feature. For example, if we wanted to use include to supply data to the example given above, we could use the following instruction in prefix.grok:

Example instruction text
10.0   100
0.0   2.0   4.0   6.0   8.0   10.0
include my.node_list

and where the file my.node_list could contain, for example:

1
2
3
5
6
end

If you now wanted to substitute another node list you could, for example, supply different node numbers in the file my_other.node_list and then just change the file name given in the include instruction.

Included files can contain groups of instructions and input, or just bits of input for a single instruction. Only one level of include instruction is allowed, and so included files can not themselves contain include instructions.

Error messages

As grok reads and processes the copy of the prefix.grok file it also creates the prefixo.eco file. Results of the HydroGeoSphere data generation procedures are written to this file so if there are any problems reported by the preprocessor you should check this file first to determine their nature and how you might fix them. If an error occurs while reading the input data, then grok will halt execution and issue an error message (to the screen and the prefixo.eco file) of the form:

INSTRUCTION: 500
**************************************
*** INPUT ERROR, HALTING EXECUTION ***
**************************************
GRID GENERATION: Unrecognized instruction
Press any key to continue

In this case the last instruction (i.e. 500) has, for some reason, caused an error. You should now check the input files to further investigate the cause of the problem, starting with the prefix.grok and material properties files.