Input Data

General Considerations

Techniques Control File or Terminal I/O Startup

The input/output (I/O) file information is provided to the code from an input control file or the terminal. The default control file name is fehmn.files. If a control file with the default name is present in the directory from which the code is being executed, no terminal input is required. If the default control file is not present, it is possible to supply the name of the control file on the command line, otherwise input prompts are written to the screen preceded by a short description of the I/O files used by FEHM. It should be noted that a control file name entered on the command line will take precedence over the default control file. The descriptions of the I/O files are elaborated on in Data Files. The initial prompt asks for the name of a control file. It is also If a control file name is entered for that prompt no further terminal input is required. If a control file is not used, the user is then prompted for I/O file names, the tty output flag, and user subroutine number. When the input file name is entered from the terminal the user has the option of letting the code generate the names for the remainder of the auxiliary files using the input file name prefix. The form of the input file name is filen or filen.* where filen is the prefix used by the code to name the auxiliary files and .* represents an arbitrary file extension.

Multiple Realization Simulations

The code has an option for performing multiple simulation realizations (calculations) where input (e.g., porosity, permeability, saturation, transport properties or particle distributions) is modified for each realization but the calculations are based on the same geometric model. Multiple realizations are initiated by including a file called fehmn.msim in the directory from which the code is being run. If invoked, a set number of simulations are performed sequentially, with pre- and post-processing steps carried out before and after each simulation. This capability allows multiple simulations to be performed in a streamlined fashion, with processing to change input files before each run and post-processing to obtain relevant results after each run.

Macro Control Structure

The finite element heat and mass transfer code (FEHM) contains a macro control structure for data input that offers added flexibility to the input process. The macro command structure makes use of a set of control statements recognized by the input module of the program. When a macro control statement is encountered in an input file, a certain set of data with a prescribed format is expected and read from the input file. In this way, the input is divided into separate, unordered blocks of data. The input file is therefore a collection of macro control statements, each followed by its associated data block. Blocks of data can be entered in any order, and any blocks unnecessary to a particular problem need not be entered. The macro control statements must appear in the first four columns of a line. The other entries are free format, which adds flexibility, but requires that values be entered for all input variables (no assumed null values).

As an aid to the user, the capabilities of FEHM summarized in Capabilities of FEHM with Macro Command References refer to applicable macro commands. Macro Control Statements for FEHM lists the macro control statements with a brief description of the data associated with each. A more detailed description of each macro control statement and its associated input are found in their respective pages. Macro control statements may be called more than once, if, for example, the user wishes to reset some property values after defining alternate zones. Some statements are required, as indicated in Macro Control Statements for FEHM, the others are optional.

Macro Control Statements for FEHM (Alphabetical List)

Comments may be entered in the input file by beginning a line with a # symbol (the # symbol must be found in the first column of the line). Comments may precede or follow macro blocks but may not be found within a block.

Optional input files may be used by substituting a keyword and file name in the main input file (described in detail in Optional Input Files). The normal macro input is then entered in the auxiliary file.

A macro may be disabled (turned off or omitted from a run) by adding keyword “off” on the macro line and terminating the macro with an end statement of the form end//macro// or end //macro// (see Option to disable a macro).

Input Parameters

Many input parameters such as porosity or permeability vary throughout the grid and need to have different values assigned at different nodes. This is accomplished in two ways. The first uses a nodal loop-type definition (which is the default):

JA, JB, JC, PROP1, PROP2, …

where

JA - first node to be assigned with the properties PROP1, PROP2, …

JB - last node to be assigned with the properties PROP1, PROP2, …

JC - loop increment for assigning properties PROP1, PROP2, ….

PROP1, PROP2, etc. - property values to be assigned to the indicated nodes.

In the input blocks using this structure, one or more properties are manually entered in the above structure. When a blank line is entered, that input block is terminated and the code proceeds to the next group or control statement. (Note that blank input lines are shaded in the examples shown in Individual Input Records or Parameters.) The nodal definition above is useful in simple geometries where the node numbers are easily found. Boundary nodes often come at regular node intervals and the increment counter JC can be adjusted so the boundary conditions are easily entered. To set the same property values at every node, the user may set JA and JC to 1 and JB to the total number of nodes, or alternatively set JA = 1, and JB = JC = 0.

For dual porosity problems, which have three sets of parameter values at any nodal position, nodes 1 to N [where N is the total number of nodes in the grid (see macro coor)] represent the fracture nodes, nodes N + 1 to 2N are generated for the second set of nodes, the first matrix material, and nodes 2N + 1 to 3N for the third set of nodes, the second matrix material. For double porosity/double permeability problems, which have two sets of parameter values at any nodal position, nodes 1 to N represent the fracture nodes and nodes N + 1 to 2N are generated for the matrix material.

For more complicated geometries, such as 3-D grids, the node numbers are often difficult to determine. Here a geometric description is preferred. To enable the geometric description the zone control statement wgtu is used in the input file before the other property macro statements occur. The input macro zone requires the specification of the coordinates of 4-node parallelograms for 2-D problems or 8-node polyhedrons in 3-D. In one usage of the control statement zone all the nodes are placed in geometric zones and assigned an identifying number. This number is then addressed in the property input macro commands by specifying a JA < 0 in the definition of the loop parameters given above. For example if JA = -1, the properties defined on the input line would be assigned to the nodes defined as belonging to geometric Zone 1 (JB and JC must be input but are ignored in this case). The control statement zone may be called multiple times to redefine geometric groupings for subsequent input. The previous zone definitions are not retained between calls. Up to 1000 zones may be defined. For dual porosity problems, which have three sets of parameter values at any nodal position, Zone ZONE_DPADD + I is the default zone number for the second set of nodes defined by Zone I, and Zone 2*ZONE_DPADD + I is the default zone number for the third set of nodes defined by Zone I. For double porosity/double permeability problems, which have two sets of parameter values at any nodal position, Zone ZONE_DPADD + I is the default zone number for the second set of nodes defined by Zone I. The value of ZONE_DPADD is determined by the number of zones that have been defined for the problem. If less than 100 zones have been used ZONE_DPADD is set to 100, otherwise it is set to 1000. Zones of matrix nodes may also be defined independently if desired.

Alternatively, the zonn control statement may be used for geometric descriptions. Regions are defined the same as for control statement zone except that previous zone definitions are retained between calls unless specifically overwritten.

Interface

To interface with GoldSim, FEHM is compiled as a dynamic link library (DLL) subroutine that is called by the GoldSim code. When FEHM is called as a subroutine from GoldSim, the GoldSim software controls the time step of the simulation, and during each call, the transport step is carried out and the results passed back to GoldSim for processing and/or use as radionuclide mass input to another portion of the GoldSim system, such as a saturated zone transport submodel. The interface version of FEHM is set up only to perform particle tracking simulations of radionuclide transport, and is not intended to provide a comprehensive flow and transport simulation capability for GoldSim. Information concerning the GoldSim user interface may be found in the GoldSim documentation (Golder Associates, 2002).

Consecutive Cases

Consecutive cases can be run using the multiple realizations simulation option (see Multiple Realization Simulations). The program retains only the geometric information between runs (i.e., the grid and coefficient information). The values of all other variables are reinitialized with each run, either from the input files or a restart file when used.

Defaults

Default values are set during the initialization process if overriding input is not provided by the user.

Individual Input Records or Parameters

Other than the information provided through the control file or terminal I/O and the multiple realization simulations file, the main user input is provided using macro control statements in the input file, geometry data file, zone data file, and optional input files. Data provided in the input files is entered in free format with the exception of the macro control statements and keywords which must appear in the first four (or more) columns of a line. Data values may be separated with spaces, commas, or tabs. The primary input file differs from the others in that it begins with a title line (80 characters maximum) followed by input in the form of the macro commands. Each file containing multiple macro commands should be terminated with the stop control statement. In the examples provided in the following subsections, blank input lines are depicted with shading.

Control File or Terminal I/O Input

The file name parameters enumerated below [nmfil(2-13)], are entered in order one per line in the control file (excluding the control file name [nmfil(1)] and error file name [nmfil(14)]) or in response to a prompt during terminal input. If there is a control file with the name fehmn.files in your local space (current working directory), FEHM will execute using that control file and there will be no prompts. If another name is used for the control file, it can be entered on the command line or at the first prompt.

A blank line can be entered in the control file for any auxiliary files not required, for the “none” option for tty output, and for the “0” option for the user subroutine number.

In version 2.30 an alternate format for the control file has been introduced that uses keywords to identify which input and output files will be used. Please note that the file name input styles may not be mixed.

Group 1: NMFIL(i) (a file name for each i = 2 to 13)

or

Group 1: KEYWORD: NMFIL

Group 2: TTY_FLAG

Group 3: USUB_NUM

Unlike previous versions of the code, if a file name is not entered for the output file, check file, or restart file, the file will not be generated. An error output file will still be generated for all runs (default name fehmn.err). However, with the keyword input style the user has the option of naming the error file. File names that do not include a directory or subdirectory name, will be located in the current working directory. With keyword input a root filename may be entered for output files that use file name generation (hist macro output, cont macro avs, surfer or tecplot output, etc.). The data files are described in more detail in Data Files.

The following are examples of the input control file. The first example (left) uses keyword style input, while the second and third examples (right) use the original style control file input form. In the first example, four files are explicitly named, the input file, geometry file, tracer history output file and output error file. A root file name is also provided for file name generation. The “all” keyword indicates that all information should be written to the terminal and the ending “0” indicates that the user subroutine will not be called. In the second example in the center, all input will be found in the current working directory and output files will also be written to that directory. The blank lines indicate that there is no restart initialization file or restart output file, a dual porosity contour plot file is not required, and the coefficient storage file is not used. The “some” keyword indicates that selected information is output to the terminal. The ending “0” indicates that the user subroutine will not be called. In the third example on the right, input will be found in the “groupdir” directory, while output will be written to the current working directory. The “none” keyword indicates that no information should be written to the terminal and the ending “0” indicates that the user subroutine will not be called.

Files fehmn.files:

Multiple Realization Simulations

The multiple realization simulations input file (fehmn.msim) contains the number of simulations to be performed and, on UNIX systems, instructions for pre- and post-processing input and output data during a multiple realization simulation. The file uses the following input format:

Line 1 nsim

Lines 2-N single_line

In the following (UNIX style) example, 100 simulations are performed with pre and post-processing steps carried out. File “fehmn.msim” contains the following:

echo This is run number $1 of $2
rm fehmn.filescurnum=`expr $1`
cp control.run fehmn.filesrm ptrk.inputcp ptrk.np$curnum ptrk.input
echo starting up the run
post
curnum=`expr $1`/home/robinson/fehm/chun_li/ptrk/process1_fujrm
np$curnum.outputmv results.output np$curnum.output
echo finishing the run again

The first line after the number of simulations demonstrates how the current and total number of simulations can be accessed in the fehmn.pre shell script. This line will write the following output for the first realization:

This is run number 1 of 100

The pre-processing steps in this example are to remove the fehmn.files file from the working directory, copy a control file to fehmn.files, copy a particle tracking macro input file to a commonly named file called ptrk.input, and write a message to the screen. The fehmn.files files should be used or else the code will require screen input of the control file name for every realization. One hundred particle tracking input files would have been generated previously, and would have the names ptrk.np1, ptrk.np2, …, ptrk.np100. Presumably, these files would all have different transport parameters, resulting in 100 different transport realizations. The post-processing steps involve executing a post-processor program for the results (process1_fuj). This post-processor code generates an output file called results.output, which the script changes to np1.output, np2.output, …, np100.output, for further processing after the simulation.

One other point to note is that the variable “curnum” in this example is defined twice, once in the pre-processor and again in the post-processor. This is necessary because fehmn.pre and fehmn.post are distinct shell scripts that do not communicate with one another.

Transfer function curve data input file

In the FEHM particle tracking models, diffusion of solute from primary porosity into the porous matrix is captured using an upscaling procedure designed to capture the small scale behavior within the field scale model. The method is to impart a delay to each particle relative to that of a nondiffusing solute. Each particle delay is computed probabilistically through the use of transfer functions. A transfer function represents the solution to the transport of an idealized system with matrix diffusion at the sub-grid-block scale. After setting up the idealized model geometry of the matrix diffusion system, a model curve for the cumulative distribution of travel times through the small-scale model is computed, either from an analytical or numerical solution. Then, this probability distribution is used to determine, for each particle passing through a given large-scale grid block, the travel time of a given particle. Sampling from the distribution computed from the small scale model ensures that when a large number of particles pass through a cell, the desired distribution of travel times through the model is reproduced. In FEHM, there are equivalent continuum and dual permeability formulations for the model, each of which call for a different set of sub-grid-block transfer function curves. These curves are numerical input to the FEHM, with a data structure described below. Optional input in macros mptr, ptrk, and sptr is used to tell the code when transfer function curves are required and whether 2 or 3 (numparams) parameter curves are to be used.

The transfer function curve data file uses the following format if a regular grid of parameters is input. Please note that parameter values for this format should be input from smallest to largest value:

nump1

param1 (i), i = 1 to nump1

nump2

param2 (j), j = 1 to nump2

If 2 parameter curves are being input

nump_max

For each i, j (nump3 =1, d4 = 1)

nump(i, j, 1, 1), param1(i), param2(j)

followed by for each nump(i, j, 1, 1)

time(i, j, 1, 1, nump), conc(i, j, 1, 1, nump)

Or if 3 parameter curves are being input

nump3

param3(k), k = 1 to nump3

nump_max

For each d4, i, j, k

nump(i, j, k, d4), param1(i), param2(j), param3(k), d4

followed by for each nump(i, j, k, d4)

time(i, j, k, d4, nump), conc(i, j, k, d4, nump)

out_flag (optional) - keyword "out"

The transfer function curve data file uses the following format for the case in which the transfer functions are input without a regular grid of parameters:

dummy_flag - keyword "free"

log_flag(i), i = 1 to numparams

normal_param(i), i = 1 to numparams

curve_structure, weight_factor (optional)

ncurves

nump_max

For “free” form input of transfer function curves (nump1 = ncurves, nump2 = 1, and nump3 = 1)

If 2 parameter curves are being input

For each i = 1to ncurve (d4 = 1)

nump(i, 1, 1, 1), param1(i), param2(i)

followed by for each nump(i, 1, 1, 1)

time(i, 1, 1, 1, nump), conc(i, 1, 1, 1, nump)

Or if 3 parameter curves are being input

For each d4 = 1 to 4, i = 1 to ncurve

nump(i, 1, 1, d4), param1(i), param2(i), param3(i), d4

followed by for each nump(i, 1, 1, d4)

time(i, 1, 1, d4, nump), conc(i, 1, 1, d4, nump)

out_flag (optional) - keyword "out"

Please note that all fracture-fracture curves are input followed by fracture-matrix curves, followed by matrix-fracture curves, followed by matrix-matrix curves.

Optional Input Files

The data for any of the FEHM macros (with the exception of coor and elem, where use of a separate geometry input file is handled through control file input) may be entered in an alternate input file. To use this option the keyword ‘file’ must appear on the input line immediately following the control statement (macro name). The line immediately following this keyword will contain the name of the alternate input file. The contents of the alternate input file consist of the regular full macro description: the macro name followed by the data. Note that data from only one macro may be entered per auxilliary file. The entries in the optional input file may be preceded or followed by comments using the “#” designator (see discussion on `Comments`_ may be entered in the input file by beginning a line with a ‘#’ symbol (the ‘#’ symbol must be found in the first column of the line). Comments may precede or follow macro blocks but may not be found within a block.). As with regular macro input, comments may not be embedded within the data block.

Group 1 - LOCKEYWORD

Group 2 - LOCFILENAME

The following illustrate the use of an optional input file and its contents. In this example, optional file “rockfile” is located in the current working directory. Input for macro “rock” is described in Control statement rock (required).

rock
file
rockfile

File “rockfile”:

# Auxiliary file used for rock macro input
rock
 1   140     1       2563.   1010.   0.3500

# End of rock macro input

Option to disable a macro

The data from any input macro may be omitted from a simulation by including the “off” keyword on the macro line and terminating the macro with an end macro statement. This also allows the inclusion of an end macro statement for any input macro. The end macro will follow the last specified line of input. If a macro is normally terminated with an end keyword, the macro id is appended to that keyword (an additional end macro line is not added). This facilitates experimentation with input options without the need to comment out or remove unwanted macros from the input file.

In the following example the perm macro is turned off and the hyco macro is used in its place.

perm off
     1       0       0       1.e-12  1.e-12  1.e-12
end perm
hyco
     1       0       0       3.8e-3  3.8e-3  3.8e-3
end hyco