On this page we examine a few variables that are located in the "control data" section of a PEST control file. Some of them affect what PEST does. Others are candidates for adjustment if PEST performance is not good.

The layout of variables in the "control data" section of a PEST control file is shown below. (There are a few other variables which are specific to PEST_HP which are not cited in this figure, but are discussed below. See PEST_HP documentation for further details.)

NOPTMAX is one of the most important variables in a PEST control file. It informs PEST of the maximum number of iterations that it should undertake. Regardless of other termination criteria, PEST will cease execution after NOPTMAX iterations have elapsed. However some values of NOPTMAX have special significance.

If NOPTMAX is set to zero, PEST runs the model once and then ceases execution. But before doing this it writes a number of output files, including the run record file and the residuals file. The first of these files records (among other things), the objective function, as well as the objective function corresponding to each observation group. All model outputs and residuals are recorded in the residuals file. The parameters on which these are based are those that are recorded in the "parameter data" section of the PEST control file as initial parameter values.

If NOPTMAX is set to -2, then PEST calculates a Jacobian matrix, records this matrix in a JCO file (i.e. a file with the same filename base as the PEST control file but with an extension of ".jco"), and then ceases execution. If NOPTMAX is set to -1, then PEST does the same thing; however it calculates a few statistics and records these on its run record file before shutting down. The number of model runs that is required to fill a Jacobian matrix is equal to the number of adjustable parameters (or perhaps more than this, depending on settings in the "parameter groups" section of the PEST control file).

Jacobian matrices have many uses. They are the cornerstone on which all forms of linear analysis rest. Also, PEST requires that a Jacobian matrix be calculated before it can commence SVD-assisted inversion.

In circumstances where termination of a PEST run is not set by the value of NOPTMAX, it is determined by values assigned to variables that follow NOPTMAX on the same line of the PEST control file. Put simply, PEST will cease execution when alterations to parameters between subsequent iterations are small, or when the fall in the objective function between subsequent iterations is small. You get to set "small" through values that you provide to these variables.

In practice, it is generally best to set tight termination criteria, and then stop PEST yourself when you sense that the inversion process is nearing completion. You can stop PEST by pressing <Ctl-C> when focussed on the PEST window. (You may need to do this a number of times so that the model that PEST is running gets the message as well.) You can also stop PEST using the PSTOP and PSTOPST utilities that are supplied with PEST. Meanwhile, the best parameters that PEST has calculated so far can be found in the PAR file that PEST updates during every iteration of the inversion process. This is otherwise known as a "parameter value file". It has the same filename base as the PEST control file, but has an extension of ".par". The PARREP utility can be used to place optimised parameter values that are recorded in this file into a new PEST control file.

The PESTMODE variable has four settings. These determine PEST's mode of operation.

estimation

When run in "estimation" mode, PEST minimises the total objective function. It is presumed that the inverse problem is well-posed so that the objective function has a discrete minimum. (If an inverse problem is ill-posed, the objective function minimum is a multi-dimensional valley in parameter space; the objective function is then minimised by many parameter sets.)

It is a good idea to include a "singular value decomposition" section in any PEST control file, just in case an inverse problem is not well-posed. (An LSQR section will do the same thing.) This allows PEST to undertake approximate inversion of non-invertible matrices that are formulated under these circumstances. Without use of singular value decomposition, PEST may not be able to lower the objective function at all if an inverse problem is ill-posed and PEST is run in "estimation" mode.

If you are sure that the inverse problem is well-posed, then you can turn singular value decomposition off. PEST will then calculate and record a number of matrices at the end of its run record file (provided the ICOV, ICOR and IEIG control variables are set to 1.) These matrices are:

•the posterior covariance matrix;

•the posterior parameter correlation coefficient matrix;

•eigenvalues and eigenvectors of the posterior covariance matrix.

These matrices are only meaningful if an inversion problem is well posed. If it is not well posed, linear analysis utilities such as PREDUNC7 must be used to calculate the posterior parameter covariance matrix.

prediction

If PESTMODE is set to "prediction", PEST runs in "predictive analysis" mode. When run in this mode, PEST maximises or minimises a user-identified prediction subject to the constraint that the objective function rises no higher than a specified value. Singular value decomposition cannot be used if PEST is run in this mode. The prediction that must be maximised or minimised must be featured in the "observation data" section of the PEST control file. The PEST control file must also include a "predictive analysis" section.

Predictive analysis is discussed in greater detail in other pages of this series.

regularisation

When run in "regularisation" mode, PEST uses Tikhonov regularisation to solve an ill-posed inverse problem.

Actually, PEST solves a constrained optimisation problem. Two objective functions are defined. One is called the "measurement objective function" whereas the other is referred to as the "regularisation objective function". A modeller must provide a target measurement objective function in the "regularisation" section of the PEST control file.

PEST minimises the regularisation objective function subject to the constraint that the measurement objective function is equal to its target value. If the measurement objective function cannot be lowered to its target value, then PEST does the best that it can, while keeping the regularisation objective function as low as it can.

pareto

When run in "pareto" mode, PEST trades two objective functions against each other. The observations that are used to compute one of these objective functions are awarded greater and greater weights as the iteration count progresses. The cost of misfitting one set of observations that is incurred by fitting another set of observations can therefore be judged.

In some decision-support circumstances, one of these objective functions may be calculated using just one observation. This can be a "predictive observation". A modeller can therefore ask PEST to investigate whether the occurrence of a certain prediction is compatible or incompatible with:

•fitting observations of past system behaviour; and

•sensibility of parameter values.

Variables which govern the operation of the Marquardt lambda appear on the fifth line of the "control data" section of the PEST control file. This is the line that begins with the RLAMBDA1 variable. (The Marquardt lambda helps PEST to accommodate inverse problem nonlinearity; see the PEST book for more details.)

When using PEST_HP you don't need to worry about the values that you give to RLAMBDA1, RLAMFAC, PHIRATSUF, PHIREDLAM and NUMLAM. PEST_HP works out the best values for these variables itself.

The UPTESTMIN and UPTESTLIM variables that can appear on this line of the PEST control file are specific to PEST_HP. These specifiy the minimum and maximum number of model runs that PEST_HP will devote to testing parameter upgrades that are calculated using different Marquardt lambdas, and different lambda line search factors. PEST_HP can devote as many model runs to this activity as there are parallelisation agents at its disposal. However it is a good idea to limit these runs to a maximum of about 30 using UPTESTLIM. Sometimes the use of extreme lambda values can result in extreme parameter values. The model may object to these.

Setting JACUPDATE to 999 activates Broyden Jacobian updating. Hence, if using PEST_HP, two rounds of Marquardt lambda testing are undertaken, the second using a Jacobian matrix that has been improved based on the results of the first round of lambda testing. To get the most out of this process it is a good idea to set UPTESTMIN to 20 or 25. (The best value depends on the number of parallel run agents that PEST_HP has at its disposal.) If you do not do this, PEST_HP will limit the number of model runs that are devoted to Marquardt lambda testing to the number of available agents. If there are only a few agents, then not enough Marquardt lambdas are tested to result in Broyden improvements to the Jacobian matrix.

Actually, regardless of the JACUPDATE setting, it is a good idea to set UPTESTMIN to at least 10. But be attentive to the number of agents at your disposal when you do this. If you have 9 agents and set UPTESTMIN to 10, then 8 agents do nothing while the final lambda-based parameter upgrade is being tested.

Two optional variables control PEST's reactions to model run failure. These are DERFORGIVE and LAMFORGIVE.  

DERFORGIVE determines how PEST reacts to model run failure as parameters are varied incrementally when calculating finite-difference derivatives. DERFORGIVE can be set to "derforgive" or "noderforgive". The default value is "noderforgive". Therefore, if model run failure is encountered during filling of the Jacobian matrix, PEST will cease execution with an appropriate error message. Alternatively, if DERFORGIVE is set to "derforgive", then PEST forgives model run failure. The derivative of all model outputs with respect to the incrementally varied parameter is set to zero.

An incremental variation of a parameter should not precipitate model run failure. If it does, then there may be little point in continuing the inversion process because PEST is walking on thin numerical ice. So it seems reasonable to accept PEST's default setting of "noderforgive". However, if you consider model run failure to be an aberration, then turning on model run forgiveness during finite-difference derivatives calculation is a good idea.

Model run failure is more likely to occur during testing of parameter upgrades. It is under these circumstances that the model is likely to receive a set of parameters that are significantly different from any that it has received before. It is a good idea to forgive model run failure under these circumstances. Activate this alternative by setting LAMFORGIVE to "lamforgive". In fact, this is the default setting for PEST_HP. If a certain set of parameters results in model run failure during Marquardt lambda testing, then these parameters are simply forgotten by PEST. However, if all upgraded parameter sets result in model run failure, then PEST ceases execution with an appropriate error message.

PEST and PEST_HP require that values be provided for the FACPARMAX, RELPARMAX and FACORIG control variables. Supplying a value for ABSPARMAX is optional, but sometimes important.

In the "parameter data" section of a PEST control file, each parameter is designated as factor-limited, relative-limited or absolute-limited. In the latter case, an integer is associated with the absolute limit. This allows different absolute limits to apply to different parameters.

If a parameter is designated as log-transformed in the "parameter data" section of a PEST control file, then it must be factor-limited. Hence when it is upgraded, the parameter's value will not change by more than a certain factor. This factor is the same for all parameters; it is the value assigned to the FACPARMAX control variable. The entire parameter upgrade vector is shortened so that this factor is not violated for any parameter. This can protect the inversion process from aberrant parameter upgrades when the relationship between model outputs and parameters is nonlinear. A FACPARMAX setting of 10 is fine in most circumstances.

Parameters that are not log transformed can be designated as either relative-limited or factor-limited. However if a parameter can change sign during the inversion process, then it must be designated as relative-limited. In this case, an upgrade limit is placed on the change in the value of the parameter relative to its current value. This limit is the same for all parameters; it is the value of the RELPARMAX control variable. However a parameter's "effective" value in calculating this limit is raised to FACORIG times its initial value if the current value of the parameter approaches zero. This prevents the imposition of excessively small change limits. A RELPARMAX setting of 10 is fine in most circumstances.

Calculation of a suitable change limit can be difficult for parameters that can adopt both positive and negative values. This is especially the case for parameters whose initial values are zero. It is more useful to impose absolute change limits than relative change limits on parameters of this type. The limit is thus imposed on the absolute value of the parameter's change. This limit must be different for different types of parameter. PEST's absolute change limit functionality allows this. See the PEST manual for more details.

If asked to do so, PEST records a number of iteration-specific files. These are in addition to files that are updated during every iteration of the inversion process, and that are calculated using the best parameters that have been achieved so far. The names of iteration specific files include the iteration number to which they pertain, this allowing their easy recognition. These iteration-specific files can be:

•the JCO (Jacobian matrix) file;

•the REI (residuals) file;

•the PAR (parameter value) file.

Iteration-specific recording of these files is activated using the optional JCOSAVEITN, REISAVEITN and PARSAVEITN control variables. The default in all cases is to not write these files.

It is often a good idea to set PARSAVEITN to "parsaveitn". Sometimes, especially when undertaking regularised inversion, PEST may over-fit model outputs to field measurements after a certain stage of the inversion process. On the other hand, parameters which provide a satisfactory level of model-to-measurement fit while still remaining sensible (thanks to the benefits of regularisation) may have been calculated during previous iterations. The trail of iteration-specific parameter value files thus provides a rudimentary traversal of an L-curve in which the measurement objective function is traded off against the regularisation objective function. Parameter values from any of these iteration-specific parameter value files can be placed into a new PEST control file using the PARREP utility.