doc

Author: jtwhite79

documentation/pestpp_users_guide_v5.2.19.docx

@@ -3806,6 +3806,8 @@ Note that, as described above, PESTPP-IES also ceases execution if, during any p
 
 Special values of NOPTMAX can instigate special PESTPP-IES behaviour. If NOPTMAX is set to -1, PESTPP-IES does not upgrade random parameter sets which comprise an ensemble. It simply runs the model once for each parameter set, records model output values, and then ceases execution, thereby effective undertaking unconstrained Monte Carlo analysis. If NOPTMAX is set to zero, execution of PESTPP-IES is even shorter. It evaluates only the parameter values listed in the control file­ – replicating the behaviour of PESTPP-GLM and PEST. If NOPTMAX is supplied as -2, then PESTPP-IES will calculate the mean value of the initial parameter ensemble, evaluate it (by running the model once) and record the results.
 
+In many cases, users may want to run a single realization from an existing parameter ensemble file to have access to the underlying model input and output files. Historically, this involved several steps, including extracting the realization, setting the PARVAL1 quantity in the control file to the realization values, setting NOPTMAX = 0, saving the control file, and then running the PESTPP-IES. Clearly, this workflow provides many opportunities for hardship. To make this common set of steps easier and less prone to error, users can *ies_run_realname* to the name of a realization in the user-supplied parameter ensemble (through the *ies_parameter_ensemble* option), and set NOPTMAX = -2. When PESTPP-IES is run, it will extract the named realization and execute the model run process using this realization, record results and quit.
+
 PESTPP-IES reports several different objective functions, namely “composite”, “measurement”, “regularization”, and “actual”, depending on the mode of operation. The “measurement” objective function is calculated using the current simulated outputs and the observations values in the pest control combined with realizations of additive measurement noise (described elsewhere in this manual). The measurement objective function is calculated using the weights in the pest control file (unless an *obscov* is supplied, described elsewhere, or unless a user-generated observations plus noise ensemble is supplied, described elsewhere). Note that if the *ies_no_noise* option is activated, the “measurement” and “actual” objective functions are the same and only the “actual” is reported to the screen and record file.
 
 The “regularization” objective function is calculated as parameter value deviations from the initial (stochastic) realized values–this objective function is scaled by the diagonal of the prior parameter covariance matrix. Note the “regularization” objective function is only used and reported if the value of *ies_reg_factor* is supplied with a value greater than 0.0.
@@ -4193,6 +4195,11 @@ Note also that the number of control variables may change with time. Refer to th
 <td>bool</td>
 <td>Flag to save ensembles in a “dense” binary format, which in constrast to the sparse binary format of jcb/jco. Ensemble files will be given a “.bin” extension. These files can be read by PESTPP-IES (for restarting) and by pyEMU. This option only applies of <em>save_</em>binary is True. Default is False</td>
 </tr>
+<tr class="even">
+<td><em>ies_run_realname</em></td>
+<td>Text</td>
+<td>The name of a parameter realization in an external parameter ensemble file to run. Only used if noptmax = -2.</td>
+</tr>
 </tbody>
 </table>