There are many reasons for modifying a PEST control file.

Some modifications are small. For example, you may want to alter the values of one or two control variables. These changes are trivial and can be done with a text editor.

Some modifications are complex. For example, you may want to add regularisation to a PEST control file, or alter observation weights so that they are functions of observation values.

A number of programs that modify a PEST control file are supplied with the PEST suite and with the groundwater utility suite. This page draws your attention to these programs. See pertinent documentation for usage details.

PARREP

"PARREP" stands for "parameter replacement". This is one of the oldest PEST utilities.

PARREP reads a PEST control file and a parameter value file. (PEST records optimised parameter values in this type of file.) PARREP then writes a new PEST control file in which the "parameter data" section is altered. Initial parameter values that are recorded in this section are replaced by optimised parameter values.

A parameter value file is exemplified below.

OBSREP

OBSREP does for observations what PARREP does for parameters.

OBSREP reads a residuals file that is written by PEST. Among other things, this file contains the values of model-generated counterparts to observations as calculated by the calibrated model. It substitutes these for observation values that are recorded in a PEST control file.

PARAMFIX

PARAMFIX modifies a PEST control file by fixing user-nominated parameters. (When a parameter is fixed, it is not adjusted by PEST.) Optionally, it modifies prior information equations in which these parameters are featured.

ARRAYOBS

ARRAYOBS is supplied with the PEST groundwater utility suite. It automates the addition of "observations" to a PEST control file which are actually hydraulic property values pertaining to some or all cells of a finite difference grid. These observations can be used for regularisation purposes.

ADDREG1, ADDREG2 and ADDREG3

These three programs are particularly useful members of the PEST suite that get used all the time (particularly ADDREG1 and ADDREG2). In many inversion contexts, use of one of these programs is an indispensable component of PEST run preparation.

Suppose that you have prepared a PEST control file, and all of the template and instruction files that comprise the PEST-to-model interface. Where parameters and/or observation numbers are large, this can be a time-consuming task.

The next task is to build Tikhonov regularisation into the inversion process. The simplest type of Tikhonov regularisation is Bayesian regularisation. In implementing this type of regularisation, a prior information equation is created for each adjustable parameter. These equations suggest to PEST that all parameters retain their initial values unless the calibration dataset contains information to the contrary. Initial parameter values therefore become preferred parameter values. They therefore comprise the preferred parameter condition which Tikhonov regularisation expresses.

ADDREG1, ADDREG2 and ADDREG3 also add a "regularisation" section to a PEST control file. In the new PEST control file, PEST is instructed to run in "regularisation" mode.

The PEST control file which is written by ADDREG1, ADDREG2 or ADDREG3 may require further editing. In many groundwater model calibration contexts, a covariance matrix should be used instead of weights for groups of prior information equations. Where parameters pertain to pilot points, these covariance matrices can be created using programs PPCOV, PPCOV3D, PPCOV_SVA and PPCOV3D_SVA from the groundwater utility suite.

GENREG, PPKREG and PPKREG1

GENREG is a member of the groundwater utility suite. "GENREG" stands for "general regularisation". It adds prior information to a PEST control file that embodies many different types of Tikhonov regularisation. Regularisation can be of the preferred value type (such as introduced by the ADDREG family). Or it can specify that homogeneity, or more complex relationships between parameters, define parameter fall-back positions. Different regularisation strategies can be applied to different families of parameters.

PPKREG and PPKREG1 are older members of the PEST groundwater utility suite. They provide a subset of the functionality of GENREG.

ADDCOVMAT

It is an easy matter to inform PEST that it must use a covariance matrix instead of weights for observations that belong to a particular observation group. The name of the file that holds the covariance matrix must be written alongside the name of the observation group in the "observation groups" section of the PEST control file.

This can become a little tedious if there are many observation groups and many covariance matrix files. In this case, observation group to covariance matrix file linkages can be recorded in a separate file. These linkages can then be embedded in a PEST control file using ADDCOVMAT.

SUBREG1

As the name suggests, SUBREG1 performs the opposite task to ADDREG1. It removes observations and prior information equation which express Tikhonov regularisation constraints from a PEST control file. It also instructs PEST to run in "estimation" mode.

ADDPRED1

ADDPRED1 is similar to ADDREG1. It adds prior information to a PEST control file which suggests to PEST that parameters remain at their initial values. However it adds a "predictive analysis" section to the PEST control file instead of a "regularisation" section, and informs PEST that it must run in "predictive analysis" mode.

ADDPRED1 was designed for use with the surrogate model that is produced by data space inversion. Using this fast-running model, a prediction can be maximised or minimised subject to the constraint that model-to-measurement fit is maintained, and that parameter sensibility is maintained.

WTFACTOR

WTFACTOR is a very simple program. It reads one PEST control file and writes another in which all weights that belong to a user-specified observation group are multiplied by user-specified factors.

ADJOBS

ADJOBS is a member of the PEST groundwater utility suite. It calculates new weights for selected observations using a simple equation that involves the observation values themselves.

PWTADJ1

PWTADJ1 is one of the most commonly-used PEST utility programs. It balances contributions made to the objective function by different observation groups. This is an important component of PEST setup. Weighting for visibility ensures that information that is resident in observations of different types, and/or at different locations, gain entry to the inversion process.

Once PEST setup is complete, PEST should be run with the NOPTMAX variable in the "control data" section of the PEST control file set to 0. PEST then runs the model once, and ceases execution. But before it does this, it calculates the objective function, and contributions made to the objective function by different observation groups. These are recorded on its run record file. PWTADJ1 reads this file, together with the PEST control file. It then writes a new PEST control file in which weights are balanced.

PWTADJ2

This is another commonly-used utility. It is normally employed before undertaking linear uncertainty analysis. PEST utilities that perform linear analysis are easier to use if the weight that is assigned to each observation is equal to the inverse of the standard deviation of noise that is associated with that observation. If weights are "correct" in this fashion, then the measurement objective function should be roughly equal to the number of observations.

Like PWTADJ1, PWTADJ2 reads a PEST run record file in which the objective function is recorded. It then adjusts weights such that the objective function is equal to the number of observations. This can be done for all observations, or on an observation group by observation group basis.

PSTCLEAN

When reading a PEST control file, PEST and most other programs of the PEST suite ignore the following:

•blank lines;

•comments (these follow the "#" character);

•variables which govern the operation of PEST++ programs (these follow the "++" character sequence).

There are some older utilities which have not been programmed to do this. As the name suggests, PSTCLEAN removes all of the above items from a PEST control file so that these older utility programs can read it.