PEST control file > Structure of PEST control file

There are two versions of the PEST control file.

PEST and its associated utility software read and write the older version of this file. Programs of the PEST++ suite can also read the older version of a PEST control file. However they can read and write the newer version of this file as well.

Old protocol

In the old version of the PEST control file, variables are recognised by location. That is, they are recognised by the line on which they are recorded, and by the order of their occurrence on that line. Variables can be separated by any number of spaces or tabs.

For this protocol to work, values must be provided for all variables, as a missing variable would change the sequence of those to the right of it. However PEST allows some variables to be optional. These are generally placed at the end of a line; in some cases they are recognised by the accompaniment of a keyword; or the variable can itself be a keyword. This allows a little more flexibility in their placement on a line. However the line to which any particular variable is assigned cannot be changed.

Nevertheless, certain flexibilities are allowed. Blank lines can appear anywhere in a PEST control file. Comments are also allowed. Comments are marked by a "#" character. All variables which follow the "#" character on any line are ignored.

The figure below shows part of the "control data" section of a PEST control file which adopts the old protocol. The comment lines and blank lines are not required, but are added for clarity.

* control data

# RSTFLE PESTMODE

restart regularisation

# NPAR NOBS NPARGP NPRIOR NOBSGP [MAXCOMPDIM][DERZEROLIM]

5639 3343 20 5639 50

# NTPLFLE NINSFLE PRECIS DPOINT [NUMCOM JACFILE MESSFILE] [OBSREREF]

4 4 single point 1 0 0

# RLAMBDA1 RLAMFAC PHIRATSUF PHIREDLAM NUMLAM [JACUPDATE] [LAMFORGIVE] [DERFORGIVE]

20 -3 0.3 0.01 7 0 lamforgive derforgive

# RELPARMAX FACPARMAX FACORIG [IBOUNDSTICK UPVECBEND] [ABSPARMAX]

10 10 0.001

# PHIREDSWH [NOPTSWITCH] [SPLITSWH] [DOAUI] [DOSENREUSE] [BOUNDSCALE]

0.1 2

New protocol

The new PEST control file protocol requires that the values of variables follow keywords. These are recorded one to a line. A user can omit variables from a PEST control file; default values are supplied for missing variables.

The new PEST control file requires fewer sections than the old PEST control file. Many variables are shifted to the "control data" section of the new file. Variables and sections in an old PEST control file that are not required by PEST++ are simply ignored.

The new PEST control file protocol is illustrated by the following figure. This shows part of the "control data" section of a new PEST control file. Notice that the string "keyword" follows the string "control data" in the header to this section. This indicates adoption of the new protocol. Notice also that blank and comment lines are supported, just as for the old PEST control file.

* control data keyword

pestmode estimation

maxsing 100

#Phimlim 1234 variable commented out

forecasts ar18,ar19

Parcov param.unc # the prior cov matrix in unc file format

lambdas 0.1, 1.0, 10,100 #some lambda values

n_iter_base -1

n_iter_super 4

base_jacobian pest.jcb

par_sigma_range 6

ies_par_en par.jcb

See the PEST++ manual for details.

For the remainder of this section we focus on the older version of the PEST control file, this being the version that is used by PEST and its utility support software.

Using PEST++ with an older PEST control file

Programs of the PEST++ suite will happily read a PEST control file which uses the older protocol. As stated above, they ignore variables and sections that do not concern them. Meanwhile, PEST++ control variables can be inserted anywhere in this file. Each of these variables must be provided on a line of its own; this line must begin with "++".

The figure below shows the last few lines of an old-protocol PEST control file to which PESTPP-IES control variables have been added. Lines which contain PESTPP-IES control variables are in bold.

...

* model command line

run_new_model.bat

* model input/output

mean.tpl mean.dat

zfac.tpl zfac.dat

z_aa.tpl z_aa.dat

hyperparameter_specs.tpl hyperparameter_specs.dat

concsim_.ins concsim_.dat

p_concsim_.ins p_concsim_.dat

++ies_num_reals(300)

++ies_subset_size(5)

++ies_include_base(true)

++ies_use_approx(false)

++ies_autoadaloc(true)

++ies_parcov(param.unc)

A PEST control file is subdivided into sections. Some of them are mandatory and some of them are optional. Some are used by PEST but not by PEST_HP, and vice versa. Sections that are not used by a particular version of PEST are ignored when that version is run.

Each section in a PEST control file begins with "*" followed by a space followed by the name of the section - for example "* control data".

The purpose and status of different sections of a PEST control file are listed in the following table.

Section	Status	Contents
control data	mandatory	Problem dimensions, mode of PEST operation, termination criteria, change limits and other control variables.
automatic user intervention	optional	Variables which control PEST's "automatic user intervention" functionality. This is not read by PEST_HP. It is generally not required in modern parameter estimation as its functionality is superseded by singular value decomposition.
singular value decomposition	optional	Variables which govern operation of singular value decomposition. It is wise to include this section (or an lsqr section) in a PEST control file.
lsqr	optional	Use LSQR instead of SVD where parameter numbers are very high. It accomplishes nearly the same thing.
sensitivity reuse	optional	Variables in this section can increase the efficiency of sensitivity calculation by telling PEST to omit re-calculation of some parameter sensitivities on subsequent iterations.
svd assist	optional	This section is normally written by the SVDAPREP program. It controls PEST operations when undertaking svd-assisted inversion.
randomised jacobian	optional	This section is read only by PEST_HP. It controls the operation of its randomised Jacobian functionality.
rsi	optional	Used by RSI_HP to govern the operation of realisation space inversion (a type of ensemble method for exploration of posterior parameter uncertainty).
simultaneous parameter increments	optional	Used by PEST_HP only. If the structure of the Jacobian matrix permits, then two or more parameters are incrementally varied at the same time when calculating finite-difference derivatives. This can result in a considerable saving in model runs.
parameter groups	mandatory	Variables in this section control the way in which finite-difference derivatives are calculated. Parameter groups are also used by programs such as ADDREG1 when adding regularisation to a PEST control file.
parameter data	mandatory	Parameter initial values, transformation status, bounds, groups, scales and offsets.
observation groups	mandatory	Lists observation and prior information groups, and (optionally) the names of files that contain covariance matrices for these groups.
observation data	mandatory	Lists observation names, values, weights and the names of groups to which observations belong.
derivatives command line	optional	This is not read by PEST_HP. This section provides data that enables PEST to obtain external derivatives from a model instead of having to calculate them itself using finite differences.
model command line	mandatory	Provides the system command which PEST must use to run the model.
model input/output	mandatory	Lists the names of template files and corresponding model input files, and then instruction files and corresponding model output files. Optionally, this section can be replaced by separate "model input" and "model output" sections.
prior information	optional	Provides "observed" linear relationships between parameters that can be used to constrain the inversion process.
predictive analysis	optional	This is not used by PEST_HP as PEST_HP does not provide constrained predictive maximisation/minimisation functionality that is provided by PEST and BEOPEST.
regularisation	optional	Contains variables that govern the operation of PEST when run in "regularisation" mode.
pareto	optional	Contains variables that govern the operation of PEST when run in "pareto" mode.
distribution files	optional	This section is used only by PEST_HP. The variables in this section govern the action of its file re-distribution functionality.

It is easy to make a mistake when building or modifying a PEST control file. Control variables must be consistent with each other, and with the values and types of parameters and observations. All parameters which are listed in a PEST control file must feature in template files that it cites. All observations which are listed in a PEST control file must feature in instruction files that it cites.

When you run PEST it will detect and report any errors or inconsistencies that it finds in a PEST control file. However it is better to run PESTCHEK before you run PEST. PESTCHEK's error-checking is comprehensive and well-explained. PESTCHEK reads a PEST control file, as well as all of the template and instruction files that are cited in the PEST control file. When reading the latter file types, PESTCHEK replicates some of the checking functionality provided by TEMPCHEK and INSCHEK. Any and all errors and inconsistencies are reported to the screen.