EnhancedTemplateProcessor

EnhancedTemplateProcessor is a tool for tool for creating model input files from a model based on a template. EnhancedTemplateProcessor can replace a formula in the template with the value derived by evaluating that formula. It can also optionally replace parameter names with the values associated with those names or replace a reference to an array with a value from an array. The detailed format descriptions below are followed by an example. Viewing the example while reading the descriptions may help clarify the descriptions.

Usage:

EnhancedTemplateProcessor <template name> [<PVAL file name> [<Arrays file name>]]

Items between square brackets are optional. Items between angled brackets are user-supplied input values.

Run EnhancedTemplateProcessor from the command line followed by the name of a template file and (optionally) the name of a PVAL file containing the names and values of the parameters that should be substituted into the file and the name of an Arrays file containing the names of arrays, their dimensions, and the names of files containing their data. If the file names contain whitespace, the names must be enclosed in quotation marks. If the file names do not contain whitespace, quotation marks around the file names are optional. The template file name must contain an extension. The output of the program is a file with the same name as the template except that the extension will have been removed from the file name. The contents of the output file will be the contents of the input file after having been processed.

PVAL File Format:

The PVAL file format is the same as documented for MODFLOW-2005. However, if a line starts with “#--“, the remainder of the line will be treated as defining a parameter for the purposes of EnhancedTemplateProcessor. All such lines must follow the lines defining parameters for MODFLOW-2005 to ensure that the lines will be ignored by MODFLOW-2005. The number of parameters specified at the beginning of the PVAL file must be the number of MODFLOW-2005 parameters and does not include any of the additional parameters for EnhancedTemplateProcessor.

Arrays File Format:

The first line in the Arrays file must contain a single character that will be used to delineate array substitutions within the template. This is the array delimiter. It must not be the space character. It also must be different from the parameter delimiter and formula delimiter used in template files. If multiple arrays files are used in a single template, they must all use the same array delimiter.

Empty lines or lines that start with the character “#” in the arrays file will be skipped. All other lines define three-dimensional arrays of real numbers. Each such line has the name of an array immediately followed by an open bracket character “[“. The open bracket character is followed by three positive integers and then a close bracket character “]”. The integers represent the number of layers, rows, and columns in the array respectively. The array dimensions must be separated by commas and/or one or more spaces. Following the close bracket character are the names of one or more files containing the data for the array. If the file names contain spaces, they must be enclosed in double quotation marks. Each line of these files must contain one or more or more values for the array. The values in a line must be separated by commas and/or one or more space characters. When reading the array values, the column index will be incremented most frequently, and the layer index will be incremented least frequently. Array names are not case sensitive. Array names may consist only of the characters “A” through” Z”, “a” through “z”, “0” through”9” and “_”. Array names must not start with a digit.

Template file Format:

If parameter names are to be replaced by parameter values, the first line of the file must begin with either "ptf " or "jtf " followed by a single character. This character, known as the “parameter delimiter”, is used to specify locations in the file at which parameter names are replaced by parameter values. The parameter names must be surrounded by a pair of the parameter delimiters. Extra spaces are allowed and encouraged before and after the parameter name but within the pair of the parameter delimiters. When the parameter name is replaced, everything between the parameter delimiters and the delimiters themselves will be replaced by the parameter value. If the parameter value is too long to fit within the available space, it will be truncated to fit.

The next line of the template (or the first line if the parameter delimiter line is not included) must begin with "etf " followed by a single character. This character is the formula delimiter. It plays a role similar to the parameter delimiter. A formula should be included between a pair of formula delimiters. However, the width of the available space is indicated differently from how it is done with parameter delimiters. The available space extends from the first formula delimiter through the first character before the beginning of the formula.

The parameter delimiter must be different from the formula delimiter.

The parameter delimiter character cannot occur anywhere in the template except where it functions as a parameter delimiter.

The formula delimiter character cannot occur anywhere in the template except where it functions as a formula delimiter.

There is no restriction imposed by EnhancedTemplateProcessor on the length of lines in template or PVAL files.

There is no restriction imposed by EnhancedTemplateProcessor on the length of parameter names in PVAL files or template files.

Parameter names must not include whitespace.

Array Substitution:

Array used for substitution can be read in either of two ways. Either the name of an arrays file can be included on the command line after the PVAL file name, or it can be read using an ReadArrays command included in the template. ReadArrays commands must be in lines immediately following the formula delimiter (see above). The ReadArrays command has a pair of parentheses enclosing the name of an arrays file. An example is shown below in which % is the formula delimiter.

%ReadArrays(Drntest.drn.arrays)%

Any line containing the ReadArrays command will be processed for one arrays file. No other operations will be performed on that line and the line will not be included in the final output file.

In each line of a template file that does not include a ReadArrays command, the first operation to be performed is to replace references to arrays with the array values. Each array reference must be preceded and followed by the array delineator defined on the first line of the array file. The number of spaces between the initial array delineator and the beginning of the array name determines the number of characters used to print the array value. In the text between the array delineators, the array name must appear immediately followed by the open bracket character, the layer, row, and column indices and the closed bracket character. The layer, row, and column indices must be greater than or equal to 1 and less than or equal to the layer count, row count, or column count respectively. The corresponding value will be printed, right justified, in place of the text between the array delineators inclusive.

Parameter Substitution:

Formulas that are enclosed in formula delimiters will be replaced in the input file by the value to which the formula evaluates. Formulas typically enclose parameter names enclosed in parameter delimiters and/or array references enclosed by array delimiters. Unlike parameter substitution, the space reserved for the formula value is not determined by the distance between the formula delimiters. Instead, it is the number of space characters between the first formula delimiter and the beginning of the formula itself.

Formulas Substitution:

Formulas that are enclosed in formula delimiters will be replaced in the input file by the value to which the formula evaluates. Formulas typically enclose parameter names enclosed in parameter delimiters and/or array references enclosed by array delimiters. Unlike parameter substitution, the space reserved for the formula value is not determined by the distance between the formula delimiters. Instead, it is the number of space characters between the first formula delimiter and the beginning of the formula itself.

Formulas must evaluate to a real number. Note that while logical operations can be used, a formula that depends on parameter values should be a continuous function of the parameters. Failure to follow this rule can result in a failure of the parameter estimation process.

Operators:

The operators in the table below are available in formulas. For the >, <, >=, and <= operators, “True” is considered larger than “False” when applied to Booleans. For the same operators, applied to text, alphabetical order is used to decide which argument is larger.

Table 1. Operators in Formulas

The operator precedence rules are shown in the table below. Operators that are part of the same group have equal precedence. Operators of equal precedence are evaluated in order from left to right.

Table 2. Operator Precedence Rules

Functions:

The same logical, math, text, and trigonometric functions available in ModelMuse are also available in EnhancedTemplateProcessor.

Description of Operations:

EnhancedTemplateProcessor does not have equivalents of the PRECIS or DPOINT variables in PEST.

EnhancedTemplateProcessor processes a template file in the following sequence.

•EnhancedTemplateProcessor reads the names of the template file, PVAL file, and Array file from the command line. The PVAL and Array file are optional.

•It reads the PVAL file, if specified, and associates each parameter name with a real-number value.

•It reads the array file, if specified. If an arrays file is specified, a PVAL file must also be specified.

•It then opens the template file and reads the parameter delimiter (if specified) and formula delimiter.

•It then reads the following lines one by one.

•If the line contains a ReadArrays command, the array is read. This is a mechanism for including an arrays file if a PVAL file is not used.

•In each line, array references are replaced by array values.

•In each line, any parameter names enclosed within parameter delimiters are replaced by the associated values.

•In each line, any formulas in the line are evaluated and replaced with the evaluated values.

Template Example:

ptf @

etf !

this is a line with nothing to replace in it.

This is a line with a parameter value "@   HK1@"

This is a line with a formula "!     2/3*100000!"

This is a line with formula containing two parameters and a formula "!     @  HK2   @ + @   HK3  @!"

This is a line with two array substitutions "~            Kx[1,5,5]~", "~            Kx[2,5,5]~"

Array substitution and a parameter inside a formula "!~            Kx[1,5,5]~ + @  HK1   @ !"

PVAL File Example:

18

HK1        1

HK2        0.01

HK3        0.0001

HK4        1E-6

VKA12_1    0.25

VKA12_2    0.0025

VKA12_3    2.5E-5

VKA12_4    2.5E-7

VKA3_1     1

VKA3_2     0.01

VKA3_3     0.0001

VKA3_4     1E-6

KDEP_Par1  0.9

LVDA_Par1 1

GHB 1

DRAIN 1

RCH 0.00031

ETM 0.0004

Example Arrays File:

~

Kx[3, 10, 10] "Drn test.lpf.Kx_1.txt", "Drn test.lpf.Kx_2.txt" "Drn test.lpf.Kx_3.txt"

Example Output File:

This is a line with nothing to replace in it.

This is a line with a parameter value "       1"

This is a line with a formula "66666."

This is a line with formula containing two parameters and a formula "0.0101"

This is a line with two array substitutions "       0.044", "       0.144"

Array substitution and a parameter inside a formula "   1.044"