PEST++
Version 4
Jeremy White, David Welter, John Doherty
Acknowledgements
Acknowledgements
Initial funding for the development of PEST++ was provided by the United States Geological
Survey (USGS). Further support for development of programs comprising the PEST++ suite
was provided by the USGS and by GNS Science, New Zealand while Jeremy White was
employed by these institutions.
The writing of this manual, and improvements to the PEST++ parallel run manager, were
funded by the Queensland Water Modelling Network. A little funding was also provided by
the CAELUM project overseen by National Centre for Groundwater Research and Training,
and sponsored by BHP-Billiton and Rio Tinto.
On a personal note, thanks are also due to the following people who have contributed in the
distant or more recent past to the development of the PEST++ suite, and to modelling education
based on the PEST++ suite:
Chas Egan (Queensland Department of Environment and Science)
Mike Toews (GNS Science)
Mike Fienen (USGS)
Randy Hunt (USGS)
Wes Kitlasten (USGS)
Matt Knowling (GNS Science)
Brioch Hemmings (GNS Science)
Chris Muffels (SS Papadopoulos and Associates)
Preface
Preface
The release of version 4 of PEST++ coincides with the release of version 15 of PEST. The
relationship between these two suites is described in a companion to this manual; see Doherty
et al (2018c).
Interoperability between programs of the PEST++ suite and those of the PEST suite has been
greatly improved with the release of version 15 of PEST. This, it is hoped, will promulgate
conjunctive use of these two suites. In particular, many of the utility programs that comprise
the PEST suite (including its ground and surface water utilities) can perform the same support
roles for programs of the PEST++ suite that they do for PEST itself. At the same time, the ever-
expanding functionality of the PyEMU suite (White et al, 2016) can facilitate use of PEST as
it does the same for PEST++.
The present document replaces two USGS reports that served as manuals for previous versions
of PEST++. These are Welter et al (2012) and Welter et al (2015).
The term “PEST++” describes a suite of programs which have certain things in common. Chief
among these is their ability to conduct many model runs in parallel on a single computer, over
an office network, on a high performance cluster and on the computing cloud. Members of the
PEST++ suite employ the same protocol for communicating with a model as PEST does. They
all employ a modular, parallel run manager named PANTHER, an upgrade from the YAMR
run manager used by previous versions of PEST++. PANTHER is freely available to other
programmers. Its sophisticated run management functionality is accessible through functions
calls that can be issued from a number of programming languages. See the PANTHER manual
(Welter et al; 2019) for details.
A theme that runs through all members of the PEST++ suite is that of adding value to
environmental modelling as it is conducted in the decision-making context. Programs which
comprise the PEST++ suite apply state-of-the-art methods to model calibration and exploration
of post-calibration parameter and predictive uncertainty. Their algorithms are capable of
handling large numbers of parameters, of deploying advanced regularisation devices, and of
exploring parameter and predictive uncertainty. One member of the suite optimizes
environmental system management in a modelling context that respects the (sometimes high)
levels of uncertainty that accompany all model predictions.
The PEST++ suite is still under active development. The theme of enhancing model-based
decision-support is being maintained. The free availability of the PANTHER run manager
constitutes an invitation for others to join us in this important work.
Jeremy White
Dave Welter
John Doherty
Preface
License
Programs of the PEST++ suite are distributed under the following license. This is the so-called
“MIT license”. It is explained at the following site.
https://opensource.org/licenses/MIT
Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Table of Contents
Table of Contents
1. Introduction ............................................................................................................................ 1
1.1 PEST++ and PEST .......................................................................................................... 1
1.2 Software Installation ....................................................................................................... 3
1.3 This Document ................................................................................................................ 3
1.4 A Model: Some Considerations ...................................................................................... 3
1.4.1 Running a Model ..................................................................................................... 3
1.4.2 Model Input and Output Files ................................................................................. 4
1.4.3 Differentiability of Model Outputs ......................................................................... 5
1.4.4 Observations and Predictions .................................................................................. 6
2. The PEST(++) Model Interface ............................................................................................ 7
2.1 Introduction ..................................................................................................................... 7
2.2 PEST++ Input Files ......................................................................................................... 7
2.3 Template Files ................................................................................................................. 7
2.3.1 Model Input Files .................................................................................................... 7
2.3.2 An Example ............................................................................................................. 8
2.3.3 The Parameter Delimiter ......................................................................................... 9
2.3.4 Parameter Names ..................................................................................................... 9
2.3.5 Setting the Parameter Space Width ....................................................................... 10
2.3.6 How a Parameter Space is Filled with a Number .................................................. 11
2.3.7 Multiple Occurrences of the Same Parameter ....................................................... 12
2.3.8 Preparing a Template File ..................................................................................... 12
2.4 Instruction Files ............................................................................................................. 12
2.4.1 Precision in Model Output Files ............................................................................ 13
2.4.2 How Model Output Files are Read ........................................................................ 13
2.4.3 An Example Instruction File ................................................................................. 14
2.4.4 The Marker Delimiter ............................................................................................ 15
2.4.5 Observation Names ............................................................................................... 15
2.4.6 The Instruction Set ................................................................................................ 15
2.4.7 Making an Instruction File .................................................................................... 26
3. Some Important PEST++ Features ...................................................................................... 27
3.1 General .......................................................................................................................... 27
3.2 Parameter Adjustment ................................................................................................... 27
3.2.1 Parameter Transformation ..................................................................................... 27
3.2.2 Fixed and Tied Parameters .................................................................................... 27
3.2.3 Upper and Lower Parameter Bounds .................................................................... 28
3.2.4 Scale and Offset .................................................................................................... 28
3.2.5 Parameter Change Limits ...................................................................................... 29
3.3 Calculation of Derivatives............................................................................................. 31
3.3.1 General .................................................................................................................. 31
3.3.2 Forward or Central Differences ............................................................................. 31
3.3.3 Parameter Increments for Two and Three-Point Derivatives ................................ 32
3.3.4 Settings for Three-Point Derivatives ..................................................................... 34
3.3.5 How to Obtain Derivatives You Can Trust ........................................................... 34
3.3.6 Looking at Model Outputs under the Magnifying Glass ....................................... 35
