+ 
-# 
+
PEST++ Development Team
-October 2021
+Decemeber 2021
# | ~ decision_variable coefficient pump_rate1 3.345 pump_rate2 3.034 inj_rate1 4.321 inj_rate2 4.287 etc. |
| ~ decision_variable coefficient pump_rate1 3.345 pump_rate2 3.034 inj_rate1 4.321 inj_rate2 4.287 etc. |
|---|
| 4 5 2 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 * row names c001cr03c10_19700102 c001cr03c16_19700102 c001cr04c09_19700102 flx_river * column names hk r0 r1 w0 w1 |
| 4 5 2 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 0.0 * row names c001cr03c10_19700102 c001cr03c16_19700102 c001cr04c09_19700102 flx_river * column names hk r0 r1 w0 w1 |
|---|
+
Figure 9.1 – A demonstration of the multi-modal upgrade process (B) using the example problem from Zhang and others (2018) compared to the standard solution (A). During the first iteration upgrade process, the upgrade for red-dot realization uses only realizations in the local parameter space/low objective function neighborhood (cyan dots) out of the entire ensemble (grey dots). This upgrade yields the magenta location, very near the target circle, compared to the nearly no movement from the standard solution (A).
-It is important to note that more realizations will be required in the PESTPP-IES solution process when using multi-modal upgrades. This is so an effectively local group of realizations can be found for each realizations upgrade that a) capture the local objective function behavior and b) the local group has enough realizations to resolve the important relations between pars and obs. The size of the local group of realizations is controlled by the *ies\_multimodal\_alpha* argument, which ranges between 0 and 1 and is the fraction of the total ensemble to use for the local group of realizations. Smaller values of *ies\_multimodal\_alpha* will result in more local groups of realizations but at the expense of these groups being smaller in number. A value between 0.1 and0.25 seems to work well for a limited number of test cases.
+It is important to note that more realizations will be required in the PESTPP-IES solution process when using multi-modal upgrades. This is so an effectively local group of realizations can be found for each realizations upgrade that a) capture the local objective function behavior and b) the local group has enough realizations to resolve the important relations between pars and obs. The size of the local group of realizations is controlled by the *ies_multimodal_alpha* argument, which ranges between 0 and 1 and is the fraction of the total ensemble to use for the local group of realizations. Smaller values of *ies_multimodal_alpha* will result in more local groups of realizations but at the expense of these groups being smaller in number. A value between 0.1 and0.25 seems to work well for a limited number of test cases.
-Closely related to the multimodal solution process is the use of a “weights” ensemble with PESTPP-IES. Through the *ies\_weight\_ensemble* argument, users can specify unique weight vectors for each realization. This argument can only be used with the multimodal solution process and allows the upgrade of each realization use a unique weighting scheme. In this way, PESTP-IES can be used to explore how different weighting scheme impact the posterior results. This functionality is demonstrated on the ZDT1 bi-objective optimization benchmark in Figure 9.2
+Closely related to the multimodal solution process is the use of a “weights” ensemble with PESTPP-IES. Through the *ies_weight_ensemble* argument, users can specify unique weight vectors for each realization. This argument can only be used with the multimodal solution process and allows the upgrade of each realization use a unique weighting scheme. In this way, PESTP-IES can be used to explore how different weighting scheme impact the posterior results. This functionality is demonstrated on the ZDT1 bi-objective optimization benchmark in Figure 9.2
-
+
Figure 9.2 – A demonstration of the multi-modal solution process using a weight ensemble on the ZDT1 benchmark problem. The standard solution process using single weight vector drives the posterior towards a single point, while the multi-modal upgrade process uses unique weights on each of the two objectives (observations in the control file) such that each realization targets a different point on the trade-off between the two objectives.
-## 9.2 Using PESTPP-IES
-
+## 9.2 Using PESTPP-IES
-### 9.2.1 General
+### 9.2.1 General
The parameter adjust algorithm implemented by PESTPP-IES is described in detail by Chen and Oliver (2013). The reader is referred to that publication for a complete mathematical description of that algorithm; see also the description presented by White (2018). We now focus on PESTPP-IES implementation details, and on control variables that are available for tuning the Chen and Oliver algorithm implemented by PESTPP-IES to particular history-matching contexts.
@@ -2845,10 +2771,10 @@ As is the usual protocol for members of the PEST++ suite, values of control vari
Like most programs of the PEST++ suite, PESTPP-IES can be run without any PEST++ control variables. PESTPP-IES then provides default values for all of these variables. For example, the default position of PESTPP-IES is to assume that the prior parameter covariance matrix is diagonal, and that parameter bounds span four standard deviations of the prior probability distribution of each parameter. Nevertheless, users are encouraged to use PESTPP-IES control variables in order to ensure that its performance is optimized for their particular modelling context.
-### 9.2.2 Initial Realizations
+### 9.2.2 Initial Realizations
**Realizations**
-Initial parameter realizations can be generated by PESTPP-IES (the default), or they can be supplied by the user. The number of realizations that PESTPP-IES generates is set by the *ies\_num\_reals()* control variable; the default value is 50.
+Initial parameter realizations can be generated by PESTPP-IES (the default), or they can be supplied by the user. The number of realizations that PESTPP-IES generates is set by the *ies_num_reals()* control variable; the default value is 50.
If you do not provide specifications for prior parameter uncertainty, then PESTPP-IES will make the following assumptions when generating initial parameter realizations.
@@ -2856,40 +2782,40 @@ If you do not provide specifications for prior parameter uncertainty, then PESTP
2. Every parameter is statistically independent of every other parameter.
-3. The difference between the upper and lower bound of each parameter is equal to *par\_sigma\_range()* standard deviations of its prior probability distribution. If *par\_sigma\_range(4)* is passed to PESTPP-IES, this indicates that the parameter bounds are set to approximately the 95% confidence interval of the parameter if it is normally distributed (i.e., four standard deviations). PESTPP-IES adopts this protocol even if the initial value of a parameter is not centrally located with respect to these bounds. Where a parameter is log transformed, the difference between the logarithms of the parameter’s upper and lower bounds is equated to *par\_sigma\_range()* standard deviations of the prior probability distribution of the log of the parameter.
+3. The difference between the upper and lower bound of each parameter is equal to *par_sigma_range()* standard deviations of its prior probability distribution. If *par_sigma_range(4)* is passed to PESTPP-IES, this indicates that the parameter bounds are set to approximately the 95% confidence interval of the parameter if it is normally distributed (i.e., four standard deviations). PESTPP-IES adopts this protocol even if the initial value of a parameter is not centrally located with respect to these bounds. Where a parameter is log transformed, the difference between the logarithms of the parameter’s upper and lower bounds is equated to *par_sigma_range()* standard deviations of the prior probability distribution of the log of the parameter.
-In generating prior parameter realizations, and in adjusting these realizations through the ensemble smoother process, PESTPP-IES ensures that a parameter’s bounds are not violated if the *ies\_enforce\_bounds()* control variable is set to *true* (it is *true* by default). The parameter’s probability density function is therefore effectively truncated by these bounds. In some situations, truncation may affect the performance of PESTPP-IES. Incidences of this occurrence may be reduced by ensuring that bounds are symmetrical with respect to initial parameter values cited in the “parameter data” section of the PEST control file (taking log transformation into account). Alternatively, the *par\_sigma\_range()* control variable may be used to increase the number of standard deviations implied by the parameter bounds so that bounds are less likely to be encountered.
+In generating prior parameter realizations, and in adjusting these realizations through the ensemble smoother process, PESTPP-IES ensures that a parameter’s bounds are not violated if the *ies_enforce_bounds()* control variable is set to *true* (it is *true* by default). The parameter’s probability density function is therefore effectively truncated by these bounds. In some situations, truncation may affect the performance of PESTPP-IES. Incidences of this occurrence may be reduced by ensuring that bounds are symmetrical with respect to initial parameter values cited in the “parameter data” section of the PEST control file (taking log transformation into account). Alternatively, the *par_sigma_range()* control variable may be used to increase the number of standard deviations implied by the parameter bounds so that bounds are less likely to be encountered.
-PESTPP-IES allows you to specify the properties of an assumed multi-Gaussian prior parameter probability distribution yourself; this distribution can include correlation between parameters. This is done using the *parcov()* control variable – the same variable that is available to users of PESTPP-GLM and PESTPP-OPT. As for other programs of the PEST++ suite, the filename that is supplied as the argument for this control variable can be a parameter uncertainty file (recognized by an extension of *.unc*), a covariance matrix file (recognized by an extension of *.cov*), or a binary, matrix-holding file (recognized by an extension of *.jco* or *.jcb*); see appendix B of this manual for specifications of these file types. In generating random parameter realizations comprising the initial ensemble, parameter values listed in the “parameter data” section of the PEST control file are taken as prior mean parameter values. If the *ies\_enforce\_bounds()* control variable is set to *true*, then parameter realizations are truncated at their bounds; nor are these bounds transgressed during subsequent parameter adjustment.
+PESTPP-IES allows you to specify the properties of an assumed multi-Gaussian prior parameter probability distribution yourself; this distribution can include correlation between parameters. This is done using the *parcov()* control variable – the same variable that is available to users of PESTPP-GLM and PESTPP-OPT. As for other programs of the PEST++ suite, the filename that is supplied as the argument for this control variable can be a parameter uncertainty file (recognized by an extension of *.unc*), a covariance matrix file (recognized by an extension of *.cov*), or a binary, matrix-holding file (recognized by an extension of *.jco* or *.jcb*); see appendix B of this manual for specifications of these file types. In generating random parameter realizations comprising the initial ensemble, parameter values listed in the “parameter data” section of the PEST control file are taken as prior mean parameter values. If the *ies_enforce_bounds()* control variable is set to *true*, then parameter realizations are truncated at their bounds; nor are these bounds transgressed during subsequent parameter adjustment.
-Unless PESTPP-IES is advised to the contrary (through the *ies\_no\_noise* option), realizations of measurement noise that are added to the values of observations provided in the “observation data” section of a PEST control file are generated in the manner already stated. That is, the noise associated with any observation is assumed to be statistically independent of the noise associated with all other observations. The standard deviation of noise associated with each observation is assumed to be the inverse of the weight associated with that observation (unless the optional “standard\_deviation” column is found in the version 2 control file external observation data files). However, if an observation is given a weight of zero, it plays no part in the history-matching process; nevertheless, these observations are “carried” through the PESTPP-IES reporting process.
+Unless PESTPP-IES is advised to the contrary (through the *ies_no_noise* option), realizations of measurement noise that are added to the values of observations provided in the “observation data” section of a PEST control file are generated in the manner already stated. That is, the noise associated with any observation is assumed to be statistically independent of the noise associated with all other observations. The standard deviation of noise associated with each observation is assumed to be the inverse of the weight associated with that observation (unless the optional “standard_deviation” column is found in the version 2 control file external observation data files). However, if an observation is given a weight of zero, it plays no part in the history-matching process; nevertheless, these observations are “carried” through the PESTPP-IES reporting process.
“Greater than” and “less than” observations are treated differently from ordinary observations. PESTPP-IES adds no noise to values for these observations provided in the “observation data” section of the PEST control file when formulating observation realizations. This reflects the fact that, on most occasions of their use, observations of this type reflect something that is known about a system rather than something that is measured. At the same time, the penalty for transgressing an observation of this type that is encapsulated in its associated weight should reflect a modeller’s capacity to tolerate this transgression in pursuit of fitting other data. If you are unhappy with this approach, you are free to generate your own observation realizations in which noise is added to these one-way observations; see below.
-If the *ies\_add\_base()* control variable is suppled as *true* (which is the default), then PESTPP-IES adds an extra realization to each of the parameter and observation ensembles. For parameters, this “realization” is comprised of parameter values listed in the “parameter data” section of the PEST control file. For observations, this “realization” is comprised of measurements read from the “observation data” section of the PEST control file. Given the importance of the “base” realization, users can also give this realization added importance during parameter upgrade calculations through the use of the *ies\_center\_on()* option. This option instructs PESTPP-IES to use a specific realization as the “center” of the ensemble. In the standard form of the upgrade equations, the mean vector is used as the “center” of the ensemble. By setting *ies\_center\_on(base)*, PESTPP-IES will treat the base realization (comprised on control file parameter values) as the center of the ensemble. Limited testing has shown this can improve the resulting phi associated with the base realization.
+If the *ies_add_base()* control variable is suppled as *true* (which is the default), then PESTPP-IES adds an extra realization to each of the parameter and observation ensembles. For parameters, this “realization” is comprised of parameter values listed in the “parameter data” section of the PEST control file. For observations, this “realization” is comprised of measurements read from the “observation data” section of the PEST control file. Given the importance of the “base” realization, users can also give this realization added importance during parameter upgrade calculations through the use of the *ies_center_on()* option. This option instructs PESTPP-IES to use a specific realization as the “center” of the ensemble. In the standard form of the upgrade equations, the mean vector is used as the “center” of the ensemble. By setting *ies_center_on(base)*, PESTPP-IES will treat the base realization (comprised on control file parameter values) as the center of the ensemble. Limited testing has shown this can improve the resulting phi associated with the base realization.
**User-Supplied**
Realizations of parameters and/or observations can be prepared by the user and provided to PESTPP-IES in comma-delimited files (i.e., CSV files), and in binary files which adopt the PEST Jacobian matrix file protocol or the PEST++ enhanced Jacobian matrix file protocol. PESTPP-IES recognizes the former through an extension of *.csv* and the latter through extensions of *.jco* and *.jcb*. Actually, as CSV and JCB files containing parameter and observation ensembles comprise part of PESTPP-IES’s output dataset, initial realizations can also be prepared by PESTPP-IES itself.
-The value of the optional *ies\_parameter\_ensemble()* control variable is the name of a file containing a suite of parameter realizations which collectively comprise an ensemble. If this is a CSV file, it should contain *m*+1 columns, where *m* is the number of parameters featured in the “parameter data” section of the PEST control file. The first column must be comprised of text strings which endow each realization of the ensemble with a unique identifier. Each of the subsequent *m* columns must pertain to a single parameter; parameter names must occupy the first row of the CSV file as column headers. It is not necessary that these names be supplied in the same order as in the “parameter data” section of the PEST control file.
+The value of the optional *ies_parameter_ensemble()* control variable is the name of a file containing a suite of parameter realizations which collectively comprise an ensemble. If this is a CSV file, it should contain *m*+1 columns, where *m* is the number of parameters featured in the “parameter data” section of the PEST control file. The first column must be comprised of text strings which endow each realization of the ensemble with a unique identifier. Each of the subsequent *m* columns must pertain to a single parameter; parameter names must occupy the first row of the CSV file as column headers. It is not necessary that these names be supplied in the same order as in the “parameter data” section of the PEST control file.
-PESTPP-IES reads as many rows of the CSV as this file contains, unless a value has been provided for the *ies\_num\_reals()* control variable in the PEST control file. If this is the case, PESTPP-IES reads no more than *ies\_num\_reals()* rows (after the header row) of the CSV file. If *ies\_num\_reals()* exceeds the number of data rows that are present in the CSV file, then the number of realizations comprising the PESTPP-IES parameter ensemble is reduced in accordance with the contents of this file.
+PESTPP-IES reads as many rows of the CSV as this file contains, unless a value has been provided for the *ies_num_reals()* control variable in the PEST control file. If this is the case, PESTPP-IES reads no more than *ies_num_reals()* rows (after the header row) of the CSV file. If *ies_num_reals()* exceeds the number of data rows that are present in the CSV file, then the number of realizations comprising the PESTPP-IES parameter ensemble is reduced in accordance with the contents of this file.
-Through the *ies\_csv\_by\_reals()* control variable a user can transpose rows and columns in CSV files that PESTPP-IES reads and writes. If *ies\_csv\_by\_reals()* is set to *false*, then in all CSV files provided to PESTPP-IES or written by PESTPP-IES, parameters/observations are assigned to rows while realizations are assigned to columns. This option can be useful where CSV files are pre/postprocessed in Microsoft EXCEL and parameter/observation numbers are large.
+Through the *ies_csv_by_reals()* control variable a user can transpose rows and columns in CSV files that PESTPP-IES reads and writes. If *ies_csv_by_reals()* is set to *false*, then in all CSV files provided to PESTPP-IES or written by PESTPP-IES, parameters/observations are assigned to rows while realizations are assigned to columns. This option can be useful where CSV files are pre/postprocessed in Microsoft EXCEL and parameter/observation numbers are large.
Parameters that are declared as tied and fixed in a PEST control file can be included in a user-prepared parameter ensemble CSV of JCO/JCB file. As has already been discussed, a user can decide for him/herself whether the values of fixed parameters are invariant from ensemble to ensemble, or whether they are the same as the values provided for these parameters in the PEST control file. However, it is the user’s responsibility to ensure that tied parameters maintain the correct ratios to their parent parameters in all realizations. If the user fails in his/her responsibility, PESTPP-IES will detect this; values attributed to tied parameters will then be altered so that correct tied-to-parent parameter ratios are maintained. Furthermore, if omitted from user-supplied parameter realizations, values for fixed and tied parameters will be provided by PESTPP-IES in accordance with ratios supplied in the “parameter data” section of the PEST control file.
-Optionally, one of the realizations provided in a user-supplied parameter ensemble can be named “base”. The significance of the base realization has already been explained. If a realization named “base” is provided in a CSV file, and if the *ies\_add\_base()* control variable has been set to *true* (which is the default) then PESTPP-IES assumes that the base realization has been provided by the user; it will not create one itself. However, if a base realization is not provided in a CSV file, and *ies\_add\_base()* has been set to *true*, then PESTPP-IES creates the base realization. As has already been discussed, parameter values comprising a PESTPP-IES-generated base realization are read from the “parameter data” section of the PEST control file.
+Optionally, one of the realizations provided in a user-supplied parameter ensemble can be named “base”. The significance of the base realization has already been explained. If a realization named “base” is provided in a CSV file, and if the *ies_add_base()* control variable has been set to *true* (which is the default) then PESTPP-IES assumes that the base realization has been provided by the user; it will not create one itself. However, if a base realization is not provided in a CSV file, and *ies_add_base()* has been set to *true*, then PESTPP-IES creates the base realization. As has already been discussed, parameter values comprising a PESTPP-IES-generated base realization are read from the “parameter data” section of the PEST control file.
-If the *ies\_enforce\_bounds()* control variable has been set to *true*, and if the values of any parameters supplied in a CSV file violate bounds provided in a PEST control file, PESTPP-IES alters parameter values to respect them. Note this form of parameter bound enforcement does not scale the entire realization to bring it within bounds, instead, individually bound-offending parameters values are simply changed to bring them to their respective bound values. In high dimensions with stochastic realizations, this “shrinking” type of enforcement almost guarantees that all realizations will be shrunk by varying degrees. Therefore, this type bound enforcement is not used in PESTPP-IES. However, PESTPP-IES does implement parameter change limit enforcement (in the same style as PEST and PESTPP-GLM with the variables FACPARMAX and RELPARMAX) via the *ies\_enforce\_chglim* option. Also note that if a restart observation ensemble is passed to PESTPP-IES, bounds enforcement on the initial parameter ensemble is foregone to avoid corrupting the first iteration upgrade calculation process.
+If the *ies_enforce_bounds()* control variable has been set to *true*, and if the values of any parameters supplied in a CSV file violate bounds provided in a PEST control file, PESTPP-IES alters parameter values to respect them. Note this form of parameter bound enforcement does not scale the entire realization to bring it within bounds, instead, individually bound-offending parameters values are simply changed to bring them to their respective bound values. In high dimensions with stochastic realizations, this “shrinking” type of enforcement almost guarantees that all realizations will be shrunk by varying degrees. Therefore, this type bound enforcement is not used in PESTPP-IES. However, PESTPP-IES does implement parameter change limit enforcement (in the same style as PEST and PESTPP-GLM with the variables FACPARMAX and RELPARMAX) via the *ies_enforce_chglim* option. Also note that if a restart observation ensemble is passed to PESTPP-IES, bounds enforcement on the initial parameter ensemble is foregone to avoid corrupting the first iteration upgrade calculation process.
-The optional *ies\_observation\_ensemble()* keyword provides the name of a CSV or JCO/JCB file containing realizations which comprise an observation plus noise ensemble. Similar protocols apply to this file as those that apply to user-supplied parameter ensemble files. If a user-provides both parameter and observation ensemble input files, then PESTPP-IES links realizations in these files according to the order in which they are supplied, regardless of realization names. If a base realization is supplied in each of these files, it is the user’s responsibility to ensure that these occupy the same row of their respective files.
+The optional *ies_observation_ensemble()* keyword provides the name of a CSV or JCO/JCB file containing realizations which comprise an observation plus noise ensemble. Similar protocols apply to this file as those that apply to user-supplied parameter ensemble files. If a user-provides both parameter and observation ensemble input files, then PESTPP-IES links realizations in these files according to the order in which they are supplied, regardless of realization names. If a base realization is supplied in each of these files, it is the user’s responsibility to ensure that these occupy the same row of their respective files.
That is worth saying again: it is important to note that PESTPP-IES does not require that user-supplied parameter and observation ensembles share realization names. If a user supplies either a parameter or observation ensemble, PESTPP-IES will check for realization name commonality between the initial parameter and observation ensemble, and if they share all realization names but are not aligned, PESTPP-IES will reorder the observation ensemble. If the realization names are not common between these two ensembles, but there are some shared names, PESTPP-IES will warn the user and continue.
-### 9.2.3 “Regularization”
+### 9.2.3 “Regularization”
-Chen and Oliver (2013) provide two equations through which parameters comprising a particular realization within an ensemble are adjusted to provide a better fit with the calibration dataset. These are equations 18 and 19 in their paper. Equation 18 is expensive to compute. It incorporates a term that penalizes adjusted parameter fields whose statistical properties depart too far from those which characterize the prior parameter distribution. Equation 19 is simpler, and less expensive to compute. It adjusts parameters on the basis of current model-to-measurement misfit only. A user can inform PESTPP-IES to use the simpler and less expensive equation by providing the value *true* to the *ies\_use\_approx()* control variable. Despite the fact that the default value for this variable is *false*, *true* works well on most occasions. When *ies\_use\_approx* is set to *false*, a penalty for changing parameter values is enforced within the upgrade calculation process.
+Chen and Oliver (2013) provide two equations through which parameters comprising a particular realization within an ensemble are adjusted to provide a better fit with the calibration dataset. These are equations 18 and 19 in their paper. Equation 18 is expensive to compute. It incorporates a term that penalizes adjusted parameter fields whose statistical properties depart too far from those which characterize the prior parameter distribution. Equation 19 is simpler, and less expensive to compute. It adjusts parameters on the basis of current model-to-measurement misfit only. A user can inform PESTPP-IES to use the simpler and less expensive equation by providing the value *true* to the *ies_use_approx()* control variable. Despite the fact that the default value for this variable is *false*, *true* works well on most occasions. When *ies_use_approx* is set to *false*, a penalty for changing parameter values is enforced within the upgrade calculation process.
A phenomenon that is sometimes encountered in using an ensemble smoother is a collapse in diversity of parameter realizations as the iterative adjustment process progresses. Sometimes this collapse can invalidate the integrity of posterior parameter and predictive probability distributions that the ensemble attempts to characterize.
@@ -2899,108 +2825,107 @@ PESTPP-IES also supports preferred-value Tikhonov regularization in which it is
PEST and PESTPP-GLM calculate regularization weights using a numerical procedure that depends on the value of a user-supplied “measurement objective function”. This defines the level of model-to-measurement fit that a modeller is not prepared to exceed. Unfortunately, numerical calculation of a regularization weight factor through this means is an expensive undertaking. PESTPP-IES uses a simpler option, but with less intuitive appeal.
-Optionally, a user can supply a value for the *ies\_reg\_factor()* control variable. If this variable is given a value greater than zero, then preferred value regularization is implemented. That is, an objective function penalty is incurred to the extent that the values of individual parameters that comprise a particular parameter realization depart from their initial values that were generated on the basis of the prior parameter probability distribution. A “regularization” objective function is computed which quantifies this departure. The weight assigned to each individual parameter departure is proportional to the inverse of the prior standard deviation of the respective parameter. (At the time of writing, a covariance matrix cannot be employed in formulation of the regularization objective function because of the computational requirements to invert a covariance matrix of greater than 30,000 entries per dimension, so that each parameter departure is assumed to be statistically independent of every other parameter departure). During every iteration of the parameter adjustment process, PESTPP-IES calculates a penalty function for each realization that is a function of the deviations from the initial value for each realization and the variance of each parameter. The value assigned to the *ies\_reg\_factor()* control variable is then a scaling factor to increase or decrease the penalty functions presence in the composite objective function .
+Optionally, a user can supply a value for the *ies_reg_factor()* control variable. If this variable is given a value greater than zero, then preferred value regularization is implemented. That is, an objective function penalty is incurred to the extent that the values of individual parameters that comprise a particular parameter realization depart from their initial values that were generated on the basis of the prior parameter probability distribution. A “regularization” objective function is computed which quantifies this departure. The weight assigned to each individual parameter departure is proportional to the inverse of the prior standard deviation of the respective parameter. (At the time of writing, a covariance matrix cannot be employed in formulation of the regularization objective function because of the computational requirements to invert a covariance matrix of greater than 30,000 entries per dimension, so that each parameter departure is assumed to be statistically independent of every other parameter departure). During every iteration of the parameter adjustment process, PESTPP-IES calculates a penalty function for each realization that is a function of the deviations from the initial value for each realization and the variance of each parameter. The value assigned to the *ies_reg_factor()* control variable is then a scaling factor to increase or decrease the penalty functions presence in the composite objective function .
-The PESTPP-IES default value for *ies\_reg\_factor()* is zero; that is, no “after the fact regularization” is applied (if *ies\_use\_approx* is false, then regularization penalties are baked into the upgrade calculation process in Bayesian proportions). Under these circumstances, PESTPP-IES seeks to minimize model-to-measurement misfit for all parameter realizations. Where regularization is applied, determination of a suitable value for *ies\_reg\_factor()* can be difficult. Its value depends on the nature of the inverse problem, on the number of parameters comprising a realization, and on the desired level of model-to-measurement misfit. Despite its dependence on all of these variables, a value in the vicinity of 0.25 often works well. Just as for specification of the PHIMILIM control variable in PEST and PESTPP-GLM, a little trial and error may be warranted in choosing a suitable value for *ies\_reg\_factor()*. Assignment of too high a value slows the progress of PESTPP-IES in reducing the objective function. Assignment of too low a value may provide insufficient insurance against parameter field collapse.
+The PESTPP-IES default value for *ies_reg_factor()* is zero; that is, no “after the fact regularization” is applied (if *ies_use_approx* is false, then regularization penalties are baked into the upgrade calculation process in Bayesian proportions). Under these circumstances, PESTPP-IES seeks to minimize model-to-measurement misfit for all parameter realizations. Where regularization is applied, determination of a suitable value for *ies_reg_factor()* can be difficult. Its value depends on the nature of the inverse problem, on the number of parameters comprising a realization, and on the desired level of model-to-measurement misfit. Despite its dependence on all of these variables, a value in the vicinity of 0.25 often works well. Just as for specification of the PHIMILIM control variable in PEST and PESTPP-GLM, a little trial and error may be warranted in choosing a suitable value for *ies_reg_factor()*. Assignment of too high a value slows the progress of PESTPP-IES in reducing the objective function. Assignment of too low a value may provide insufficient insurance against parameter field collapse.
-In some contexts, a more heuristic approach may be taken to balancing goodness of fit against ensemble diversity. A user may ascribe a low value to *ies\_reg\_factor()* so that, after a number of iterations have elapsed, a very good fit is attained between model outputs and the calibration dataset. He/she can then select an ensemble from a previous iteration that, in his/her opinion, best balances fit with the calibration dataset against parameter field diversity.
+In some contexts, a more heuristic approach may be taken to balancing goodness of fit against ensemble diversity. A user may ascribe a low value to *ies_reg_factor()* so that, after a number of iterations have elapsed, a very good fit is attained between model outputs and the calibration dataset. He/she can then select an ensemble from a previous iteration that, in his/her opinion, best balances fit with the calibration dataset against parameter field diversity.
In addition to its role in generating initial parameter realizations, the prior parameter probability distribution supports the following aspects of PESTPP-IES calculations.
-1. It features in equation 18 of Chen and Oliver (2013). This term of the equation is omitted if equation 19 is used for parameter field adjustment in its stead; as stated above, this occurs if *ies\_use\_approx()* is set to *true*.
+1. It features in equation 18 of Chen and Oliver (2013). This term of the equation is omitted if equation 19 is used for parameter field adjustment in its stead; as stated above, this occurs if *ies_use_approx()* is set to *true*.
-2. It provides weights to individual “regularization observations” that measure departures of adjusted parameter fields from initial parameter fields. This occurs if *ies\_reg\_factor()* is set to a value greater than zero.
+2. It provides weights to individual “regularization observations” that measure departures of adjusted parameter fields from initial parameter fields. This occurs if *ies_reg_factor()* is set to a value greater than zero.
3. It is used in prior parameter scaling; see below.
-Where a user-supplied CSV or JCO/JCB file provides initial parameter realizations, the prior covariance matrix that is used for the above purposes can be calculated empirically from these realizations. Alternatively, a prior parameter covariance matrix can be read from a file whose name is supplied with the *parcov()* control variable. Regardless of whether the *parcov()* control variable has been supplied, PESTPP-IES calculates prior parameter variances empirically for the second and third of the above tasks from user-supplied initial parameter realizations (if the latter are available) if a value of *true* is supplied for the *ies\_use\_empirical\_prior()* control variable. If this is done, off-diagonal elements of the prior parameter covariance matrix are assigned values of zero for use in the above calculations, this expediting their implementation.
+Where a user-supplied CSV or JCO/JCB file provides initial parameter realizations, the prior covariance matrix that is used for the above purposes can be calculated empirically from these realizations. Alternatively, a prior parameter covariance matrix can be read from a file whose name is supplied with the *parcov()* control variable. Regardless of whether the *parcov()* control variable has been supplied, PESTPP-IES calculates prior parameter variances empirically for the second and third of the above tasks from user-supplied initial parameter realizations (if the latter are available) if a value of *true* is supplied for the *ies_use_empirical_prior()* control variable. If this is done, off-diagonal elements of the prior parameter covariance matrix are assigned values of zero for use in the above calculations, this expediting their implementation.
-Note that the default value for *ies\_use\_empirical\_prior()* is *false*. Hence PESTPP-IES employs a user-supplied covariance matrix for the above roles if one is available. Note also that, even if *ies\_use\_empirical\_prior()* is set to *true*, a user-supplied covariance matrix is always used in the first of the above roles if it can be accessed through a *parcov()* file. If this file is not available so that an empirical covariance matrix is used for this task, off-diagonal elements of this matrix are not automatically set to zero.
+Note that the default value for *ies_use_empirical_prior()* is *false*. Hence PESTPP-IES employs a user-supplied covariance matrix for the above roles if one is available. Note also that, even if *ies_use_empirical_prior()* is set to *true*, a user-supplied covariance matrix is always used in the first of the above roles if it can be accessed through a *parcov()* file. If this file is not available so that an empirical covariance matrix is used for this task, off-diagonal elements of this matrix are not automatically set to zero.
-### 9.2.4 Prior Parameter Scaling
+### 9.2.4 Prior Parameter Scaling
Like PESTPP-GLM and PEST, PESTPP-IES uses a Jacobian matrix as a basis for parameter adjustment. The mathematics of parameter adjustment which all of these programs implement is very similar, differing only in some of the details of how to handle problem ill-posedness. The major difference between PESTPP-IES on the one hand and PESTPP/PEST on the other hand is in how the Jacobian matrix is calculated. PESTPP-IES does not use finite parameter differences. Instead, it runs the model using the suite of random parameter fields that comprise an ensemble. It then inspects model outputs that correspond to members of the calibration dataset and calculates cross-covariances between these and individual parameters. From these covariances, with some matrix manipulation, it calculates an approximation to the Jacobian matrix. Where the number of realizations that comprise an ensemble is less than the number of adjustable parameters featured in the PEST control file, this Jacobian matrix is column-rank-deficient. Nevertheless, provided its rank is higher than the dimensionality of the calibration solution space, it can support attainment of parameter values which provide a good fit between model outputs and members of the calibration dataset.
-In calculating model-output-to-parameter cross-covariances, certain numerical advantages can be gained if differences between individual parameter realizations and the mean parameter field are scaled. This is done by dividing the difference between each parameter and its mean by the prior standard deviation of that parameter. PESTPP-IES performs this scaling if the *ies\_use\_prior\_scaling()* control variable is set to *true*. Experience has demonstrated that prior scaling can be beneficial for problems that involve a very high number of parameters (over three hundred thousand), but that it is not so effective for problems that involve fewer parameters. The default value for *ies\_use\_prior\_scaling()* is *false*.
+In calculating model-output-to-parameter cross-covariances, certain numerical advantages can be gained if differences between individual parameter realizations and the mean parameter field are scaled. This is done by dividing the difference between each parameter and its mean by the prior standard deviation of that parameter. PESTPP-IES performs this scaling if the *ies_use_prior_scaling()* control variable is set to *true*. Experience has demonstrated that prior scaling can be beneficial for problems that involve a very high number of parameters (over three hundred thousand), but that it is not so effective for problems that involve fewer parameters. The default value for *ies_use_prior_scaling()* is *false*.
-### 9.2.5 The Marquardt Lambda
+### 9.2.5 The Marquardt Lambda
The Marquardt lambda plays a pivotal role in gradient based inversion. Use of a high lambda value in early iterations of an inversion process, and a low lambda value later in that process, can have a large impact on the rate at which a good fit with the calibration dataset is attained. However, the best value of the Marquardt lambda to use during any particular iteration must often be determined by trial and error. PESTPP-GLM and PEST test a number of parameter upgrades, calculated using different values of the Marquardt lambda; the cost is one model run for each tested lambda. Optionally, upgrades calculated using fractional lengths along these parameter upgrade vectors can also be tested. The parameter set that leads to the lowest objective function is selected as the upgraded parameter set.
Where a single parameter field is being estimated in a standard model calibration process, this procedure constitutes a good investment in model runs. (In parallel computing environments the cost may actually be very small, as computing cores that would otherwise be idle while waiting to fill the next Jacobian matrix are given something to do.) This investment in finding the best parameter upgrade vector provides the best return on the previously much larger investment of filling a Jacobian matrix.
-The situation is different, however, when many parameter fields comprising an ensemble are adjusted, such as is done by PESTPP-IES. For an ensemble smoother, the testing of parameter upgrades and the filling of a Jacobian matrix are the same operation. The cost of this operation would become prohibitive if a trial-and-error lambda search procedure accompanied the adjustment of each parameter realization comprising an ensemble. Hence a different strategy must be adopted. This strategy is to undertake lambda testing for only a limited number of parameter fields, and to then use the best lambda that emerges from that testing process when upgrading the rest of them. This limited number of realizations used to evaluate objective function values during upgrade testing is referred to as the “subset”. Options for how to pick the subset are available through the *ies\_subset\_how()* argument; valid choices for *ies\_subset\_how()* are “first” (the first *ies\_subset\_size()* realizations), “last” (the last *ies\_subset\_size()* realizations), “random” (randomly select *ies\_subset\_size()* realizations for each iteration), or “phi\_based” (select *ies\_subset\_size()* realizations across the previous composite objective function distribution). Note that if the “base” parameter realization is present, it is always included in the selected subset as the objective function calculated for this realization has special significance.
+The situation is different, however, when many parameter fields comprising an ensemble are adjusted, such as is done by PESTPP-IES. For an ensemble smoother, the testing of parameter upgrades and the filling of a Jacobian matrix are the same operation. The cost of this operation would become prohibitive if a trial-and-error lambda search procedure accompanied the adjustment of each parameter realization comprising an ensemble. Hence a different strategy must be adopted. This strategy is to undertake lambda testing for only a limited number of parameter fields, and to then use the best lambda that emerges from that testing process when upgrading the rest of them. This limited number of realizations used to evaluate objective function values during upgrade testing is referred to as the “subset”. Options for how to pick the subset are available through the *ies_subset_how()* argument; valid choices for *ies_subset_how()* are “first” (the first *ies_subset_size()* realizations), “last” (the last *ies_subset_size()* realizations), “random” (randomly select *ies_subset_size()* realizations for each iteration), or “phi_based” (select *ies_subset_size()* realizations across the previous composite objective function distribution). Note that if the “base” parameter realization is present, it is always included in the selected subset as the objective function calculated for this realization has special significance.
-The number of realizations that comprise the ensemble subset used for lambda testing is set by the value of the *ies\_subset\_size()* control variable. During each iteration of the ensemble smoother process, values of the Marquardt lambda used for testing realization upgrades are determined by applying a set of multipliers to the best lambda found during the previous iteration. These multipliers are provided through the *ies\_lambda\_mults()* control variable. A comma separated list of multipliers should be supplied by the user as arguments to this keyword; at least one of these multipliers should be less than 1.0 while, or course, one of them should be greater than 1.0. Line search factors (otherwise known as scale factors) that are applied to each of these lambdas can also be supplied. If so, this is done through the *lambda\_scale\_fac()* control variable, the same variable that is used by PESTPP-GLM. As for *ies\_lambda\_mults()*, scale factors should be supplied as a comma-separated list of numbers spanning a range from below 1.0 to greater than 1.0. The total number of model runs required to test parameter upgrades during a given iteration is thus *ies\_subset\_size()* times the number of multipliers supplied with the *ies\_lambda\_mults()* control variable times the number of factors supplied with the *lambda\_scale\_fac()* control variable.
+The number of realizations that comprise the ensemble subset used for lambda testing is set by the value of the *ies_subset_size()* control variable. During each iteration of the ensemble smoother process, values of the Marquardt lambda used for testing realization upgrades are determined by applying a set of multipliers to the best lambda found during the previous iteration. These multipliers are provided through the *ies_lambda_mults()* control variable. A comma separated list of multipliers should be supplied by the user as arguments to this keyword; at least one of these multipliers should be less than 1.0 while, or course, one of them should be greater than 1.0. Line search factors (otherwise known as scale factors) that are applied to each of these lambdas can also be supplied. If so, this is done through the *lambda_scale_fac()* control variable, the same variable that is used by PESTPP-GLM. As for *ies_lambda_mults()*, scale factors should be supplied as a comma-separated list of numbers spanning a range from below 1.0 to greater than 1.0. The total number of model runs required to test parameter upgrades during a given iteration is thus *ies_subset_size()* times the number of multipliers supplied with the *ies_lambda_mults()* control variable times the number of factors supplied with the *lambda_scale_fac()* control variable.
-The value of the Marquardt lambda to use during the first iteration of the ensemble smoother process can be supplied through the *ies\_initial\_lambda()* control variable. Lambda multipliers supplied through *ies\_lambda\_mults()* are applied to this value during the first iteration of this process. The PESTPP-IES default value for *ies\_initial\_lambda()* is $10^{\\text{floor}\\left( \\log\_{10}\\frac{\\mu\_{Փ}}{2n} \\right)}$ where *μ*Փ is the mean of objective functions achieved using realizations comprising the initial ensemble, and *n* is the number of non-zero-weighted observations featured in the “observation data” section of the PEST control file.
+The value of the Marquardt lambda to use during the first iteration of the ensemble smoother process can be supplied through the *ies_initial_lambda()* control variable. Lambda multipliers supplied through *ies_lambda_mults()* are applied to this value during the first iteration of this process. The PESTPP-IES default value for *ies_initial_lambda()* is $10^{\\text{floor}\\left( \\log\_{10}\\frac{\\mu\_{Փ}}{2n} \\right)}$ where *μ*Փ is the mean of objective functions achieved using realizations comprising the initial ensemble, and *n* is the number of non-zero-weighted observations featured in the “observation data” section of the PEST control file.
Suppose for example that the following lines appear in a PESTPP-IES control file.
-| ++ ies_initial_lambda(100) ++ ies_subset_size(4) ++ ies_lambda_mults(0.1,1.0,10.0) ++ ies_lambda_scale_fac(0.9,1.0,1.1) |
| ++ ies_initial_lambda(100) ++ ies_subset_size(4) ++ ies_lambda_mults(0.1,1.0,10.0) ++ ies_lambda_scale_fac(0.9,1.0,1.1) |
|---|
| Variable | Type | Role |
|---|---|---|
| ies_num_reals(50) | integer | The number of realizations to draw in order to form parameter and observation ensembles. |
| parcov() | text | The name of a file containing the prior parameter covariance matrix. This can be a parameter uncertainty file (extension .unc), a covariance matrix file (extension .cov) or a binary JCO or JCB file (extension .jco or .jcb). |
| par_sigma_range(4.0) | real | The difference between a parameter’s upper and lower bounds expressed as standard deviations. |
| ies_parameter_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied parameter realizations comprising the initial (prior) parameter ensemble. If this keyword is omitted, PESTPP-IES generates the initial parameter ensemble itself. |
| ies_observation_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied observation plus noise realizations comprising the observation plus noise ensemble. If this keyword is omitted, PESTPP-IES generates the observation plus noise ensemble itself. |
| ies_add_base(true) | Boolean | If set to true, instructs PESTPP-IES to include a “realization” in the initial parameter ensemble comprised of parameter values read from the “parameter data” section of the PEST control file. The corresponding observation ensemble is comprised of measurements read from the “observation data” section of the PEST control file. |
| ies_restart_observation_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing model outputs calculated using a parameter ensemble. If it reads this file, PESTPP-IES does not calculate these itself, proceeding to upgrade calculations instead. |
| ies_restart_parameter_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing a parameter ensemble that corresponds to the ies_restart_observation_ensemble(). This option requires that the ies_restart_observation_ensemble() control variable also be supplied. This ensemble is only used in the calculation of the regularization component of the objective function for a restarted PESTPP-IES analysis. |
| ies_enforce_bounds(true) | Boolean | If set to true PESTPP-IES will not transgress bounds supplied in the PEST control file when generating or accepting parameter realizations, and when adjusting these realizations. |
| ies_initial_lambda() | real | The initial Marquardt lambda. The default value is \(10^{\text{floor}\left( \log_{10}\frac{\mu_{Փ}}{2n} \right)}\text{.\ \ }\)If supplied as a negative value, then the abs(ies_initial_lambda) is used as multiplier of the default initial-phi-based value. |
| ies_lambda_mults(0.1,1.0,10.0) | comma-separated reals | Factors by which to multiply the best lambda from the previous iteration to yield values for testing parameter upgrades during the current iteration. |
| lambda_scale_fac(0.75,1.0,1.1) | comma-separated reals | Line search factors along parameter upgrade directions computed using different Marquardt lambdas. |
| ies_subset_size(4) | integer | Number of realizations used in testing and evaluation of different Marquardt lambdas. If supplied as a negative value, then abs(ies_subset_size) is treated as a percentage of the current ensemble size – this allows the subset size to fluctuate with the size of the ensemble |
| ies_use_approx(true) | Boolean | Use complex or simple formula provided by Chen and Oliver (2013) for calculation of parameter upgrades. The more complex formula includes a function which constrains parameter realizations to respect prior means and probabilities. |
| ies_reg_factor(0.0) | real | Regularization objective function as a fraction of measurement objective function when constraining parameter realizations to respect initial values. |
| ies_bad_phi(1.0E300) | real | If the objective function calculated as an outcome of a model run is greater than this value, the model run is deemed to have failed. |
| ies_bad_phi_sigma(1.0E300) | real | If the objective function calculated for a given realization is greater than the current mean objective function of the ensemble plus the objective function standard deviation of the ensemble times ies_bad_phi_sigma(), that realization is treated as failed. |
| ies_use_prior_scaling(false) | Boolean | Use a scaling factor based on the prior parameter distribution when evaluating parameter-to-model-output covariance used in calculation of the randomized Jacobian matrix. |
| ies_use_empirical_prior(false) | Boolean | Use an empirical, diagonal parameter covariance matrix for certain calculations. This matrix is contained in a file whose name is provided with the ies_parameter_ensemble() keyword. |
| Ies_save_lambda_ensembles(false) | Boolean | Save a set of CSV or JCB files that record parameter realizations used when testing different Marquardt lambdas. |
| ies_verbose_level(1) | 0, 1 or 2 | The level of diagnostic output provided by PESTPP-IES. If set to 2, all intermediate matrices are saved to ASCII files. This can require a considerable amount of storage. |
| ies_accept_phi_fac(1.05) | real > 1.0 | The factor applied to the previous best mean objective function to determine if the current mean objective function is acceptable. |
| ies_lambda_dec_fac(0.75) | real < 1.0 | The factor by which to decrease the value of the Marquardt lambda during the next IES iteration if the current iteration of the ensemble smoother process was successful in lowering the mean objective function. |
| ies_lambda_inc_fac(10.0) | real > 1.0 | The factor by which to increase the current value of the Marquardt lambda for further lambda testing if the current lambda testing cycle was unsuccessful. |
| ies_subset_how(random) | “first”,”last”, ”random”, ”phi_based | How to select the subset of realizations for objective function evaluation during upgrade testing. Default is “random”. |
| ies_num_threads(-1) | integer > 1 | The number of threads to use during the localized upgrade solution process, the automatic adaptive localization process. If the localizer contains many (>10K) rows, then multithreading can substantially speed up the upgrade calculation process. ies_num_threads() should not be greater than the number of physical cores on the host machine. |
| ies_localizer() | text | The name of a matrix to use for localization. The extension of the file is used to determine the type: .mat is an ASCII matrix file, .jcb/.jco signifies use of (enhanced) Jacobian matrix format (a binary format), while .csv signifies a comma-delimited file. Note that adjustable parameters not listed in localization matrix columns are implicitly treated as “fixed” while non-zero weighted observations not listed in rows of this matrix are implicitly treated as zero-weighted. |
| ies_group_draws(true) | Boolean | A flag to draw from the (multivariate) Gaussian prior by parameter/observation groups. This is usually a good idea since groups of parameters/observations are likely to have prior correlation. |
| ies_save_binary(false) | Boolean | A flag to save parameter and observation ensembles in binary (i.e., JCB) format instead of CSV format. |
| ies_csv_by_reals(true) | Boolean | A flag to save parameter and observation ensemble CSV files by realization instead of by variable name. If true, each row of the CSV file is a realization. If false, each column of the CSV file is a realization. |
| ies_autoadaloc(false) | Boolean | Flag to activate automatic adaptive localization. |
| ies_autoadaloc_sigma_dist(1.0) | Real | Real number representing the factor by which a correlation coefficient must exceed the standard deviation of background correlation coefficients to be considered significant. Default is 1.0 |
| tie_by_group(false) | Boolean | Flag to tie all adjustable parameters together within each parameter group. Initial parameter ratios are maintained as parameters are adjusted. Parameters that are designated as already tied, or that have parameters tied to them, are not affected. |
| ies_enforce_chglim(false) | Boolean | Flag to enforce parameter change limits (via FACPARMAX and RELPARMAX) in a way similar to PEST and PESTPP-GLM (by scaling the entire realization). Default is false. |
| ies_center_on() | String | A realization name that should be used for the ensemble center in calculating the approximate Jacobian matrix. The realization name must be in both the parameter and observation ensembles. If not passed, the mean vector is used as the center. The value “_MEDIAN_” can also be used, which instructs PESTPP-IES to use the median vector for calculating anomalies. |
| enforce_tied_bounds(false) | Boolean | Flag to enforce parameter bounds on any tied parameters. Depending on the ration between the tied and free parameters, this option can greatly limit parameter changes. |
| ies_no_noise(false) | Boolean | Flag to not generate and use realizations of measurement noise. Default is False (that is, to use measurement noise). |
| ies_drop_conflicts(false) | Boolean | Flag to remove non-zero weighted observations that are in a prior-data conflict state from the upgrade calculations. Default is False. |
| ies_pdc_sigma_distance() | Real > 0.0 | The number of standard deviations from the mean used in checking for prior-data conflict. |
| ies_save_rescov(False) | Boolean | Flag to save the iteration-level residual covariance matrix. If ies_save_binary is True, then a binary format file is written, otherwise an ASCII format (.cov) file is written. The file name is case.N.res.cov/.jcb. Note that this functionality does not scale beyond about 20,000 non-zero-weighted observations |
| obscov() | text | The name of a file containing the observation noise covariance matrix. This can be a parameter uncertainty file (extension .unc), a covariance matrix file (extension .cov) or a binary JCO or JCB file (extension .jco or .jcb). Please see the section on this matrix above to understand the implications of using this matrix |
| rand_seed(358183147) | unsigned integer | Seed for the random number generator. |
| Ies_use_mda(false) | Boolean | Flag to use the (optionally iterative) Kalman update equation – the number of data assimilation iterations is controlled by NOPTMAX; NOPTMAX = 1 and ies_use_mda(true) results in the standard ensemble smoother Kalman update. If False, the GLM iterative ensemble smoother equation is used. Default is False |
| Ies_mda_init_fac(10.0) | double | The initial MDA covariance inflation factor. Only used if ies_use_mda is true. Default is 10.0 |
| Ies_mda_decl_fac(0.5) | double | The final MDA covariance inflation factor. Only used in ies_use_mda is true. Default is 0.5 |
| Ies_localization_type(local) | text | Can be either “local” for local analysis or “covariance” for covariance-only localization. Default is “local” |
| Ies_upgrades_in_memory(true) | Boolean | Flag to hold parameter upgrade ensembles in memory during testing. If False, parameter ensembles are saved to disk during testing and the best-phi ensemble is loaded from disk after testing – this can reduce memory pressure for very high dimensional problems. Default is True but is only activated if number of parameters > 100K. |
| Ies_ordered_binary(true) | Boolean | Flag to write control-file-ordered binary ensemble files. Only used if save_binary is true. If false, hash-ordered binary files are written – for very high dimensional problems, writing unordered binary can save lots of time. If not passed and number of parameters > 100K, then ies_ordered_binary is set to false. |
| ensemble_output_precision(6) | int | Number of significant digits to use in ASCII format ensemble files. Default is 6 |
| ies_multimodal_alpha(1.0) | double | The fraction of the total ensemble size to use as the local neighborhood realizations in the multimodal solution process. Must be greater than zero and less than 1. Values of 0.1 to 0.25 seem to work well. Default is 1.0 (disable multi-modal solution process) |
| ies_weight_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied weight vectors for each realization. If this keyword is omitted, PESTPP-IES uses the weight vector in the control file for all realizations. Only used with ies_multimodal_alpha |
| Variable | Type | Role |
|---|---|---|
| ies_num_reals(50) | integer | The number of realizations to draw in order to form parameter and observation ensembles. |
| parcov() | text | The name of a file containing the prior parameter covariance matrix. This can be a parameter uncertainty file (extension .unc), a covariance matrix file (extension .cov) or a binary JCO or JCB file (extension .jco or .jcb). |
| par_sigma_range(4.0) | real | The difference between a parameter’s upper and lower bounds expressed as standard deviations. |
| ies_parameter_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied parameter realizations comprising the initial (prior) parameter ensemble. If this keyword is omitted, PESTPP-IES generates the initial parameter ensemble itself. |
| ies_observation_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied observation plus noise realizations comprising the observation plus noise ensemble. If this keyword is omitted, PESTPP-IES generates the observation plus noise ensemble itself. |
| ies_add_base(true) | Boolean | If set to true, instructs PESTPP-IES to include a “realization” in the initial parameter ensemble comprised of parameter values read from the “parameter data” section of the PEST control file. The corresponding observation ensemble is comprised of measurements read from the “observation data” section of the PEST control file. |
| ies_restart_observation_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing model outputs calculated using a parameter ensemble. If it reads this file, PESTPP-IES does not calculate these itself, proceeding to upgrade calculations instead. |
| ies_restart_parameter_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing a parameter ensemble that corresponds to the ies_restart_observation_ensemble(). This option requires that the ies_restart_observation_ensemble() control variable also be supplied. This ensemble is only used in the calculation of the regularization component of the objective function for a restarted PESTPP-IES analysis. |
| ies_enforce_bounds(true) | Boolean | If set to true PESTPP-IES will not transgress bounds supplied in the PEST control file when generating or accepting parameter realizations, and when adjusting these realizations. |
| ies_initial_lambda() | real | The initial Marquardt lambda. The default value is \(10^{\text{floor}\left( \log_{10}\frac{\mu_{Փ}}{2n} \right)}\text{.\ \ }\)If supplied as a negative value, then the abs(ies_initial_lambda) is used as multiplier of the default initial-phi-based value. |
| ies_lambda_mults(0.1,1.0,10.0) | comma-separated reals | Factors by which to multiply the best lambda from the previous iteration to yield values for testing parameter upgrades during the current iteration. |
| lambda_scale_fac(0.75,1.0,1.1) | comma-separated reals | Line search factors along parameter upgrade directions computed using different Marquardt lambdas. |
| ies_subset_size(4) | integer | Number of realizations used in testing and evaluation of different Marquardt lambdas. If supplied as a negative value, then abs(ies_subset_size) is treated as a percentage of the current ensemble size – this allows the subset size to fluctuate with the size of the ensemble |
| ies_use_approx(true) | Boolean | Use complex or simple formula provided by Chen and Oliver (2013) for calculation of parameter upgrades. The more complex formula includes a function which constrains parameter realizations to respect prior means and probabilities. |
| ies_reg_factor(0.0) | real | Regularization objective function as a fraction of measurement objective function when constraining parameter realizations to respect initial values. |
| ies_bad_phi(1.0E300) | real | If the objective function calculated as an outcome of a model run is greater than this value, the model run is deemed to have failed. |
| ies_bad_phi_sigma(1.0E300) | real | If the objective function calculated for a given realization is greater than the current mean objective function of the ensemble plus the objective function standard deviation of the ensemble times ies_bad_phi_sigma(), that realization is treated as failed. |
| ies_use_prior_scaling(false) | Boolean | Use a scaling factor based on the prior parameter distribution when evaluating parameter-to-model-output covariance used in calculation of the randomized Jacobian matrix. |
| ies_use_empirical_prior(false) | Boolean | Use an empirical, diagonal parameter covariance matrix for certain calculations. This matrix is contained in a file whose name is provided with the ies_parameter_ensemble() keyword. |
| Ies_save_lambda_ensembles(false) | Boolean | Save a set of CSV or JCB files that record parameter realizations used when testing different Marquardt lambdas. |
| ies_verbose_level(1) | 0, 1 or 2 | The level of diagnostic output provided by PESTPP-IES. If set to 2, all intermediate matrices are saved to ASCII files. This can require a considerable amount of storage. |
| ies_accept_phi_fac(1.05) | real > 1.0 | The factor applied to the previous best mean objective function to determine if the current mean objective function is acceptable. |
| ies_lambda_dec_fac(0.75) | real < 1.0 | The factor by which to decrease the value of the Marquardt lambda during the next IES iteration if the current iteration of the ensemble smoother process was successful in lowering the mean objective function. |
| ies_lambda_inc_fac(10.0) | real > 1.0 | The factor by which to increase the current value of the Marquardt lambda for further lambda testing if the current lambda testing cycle was unsuccessful. |
| ies_subset_how(random) | “first”,”last”, ”random”, ”phi_based | How to select the subset of realizations for objective function evaluation during upgrade testing. Default is “random”. |
| ies_num_threads(-1) | integer > 1 | The number of threads to use during the localized upgrade solution process, the automatic adaptive localization process. If the localizer contains many (>10K) rows, then multithreading can substantially speed up the upgrade calculation process. ies_num_threads() should not be greater than the number of physical cores on the host machine. |
| ies_localizer() | text | The name of a matrix to use for localization. The extension of the file is used to determine the type: .mat is an ASCII matrix file, .jcb/.jco signifies use of (enhanced) Jacobian matrix format (a binary format), while .csv signifies a comma-delimited file. Note that adjustable parameters not listed in localization matrix columns are implicitly treated as “fixed” while non-zero weighted observations not listed in rows of this matrix are implicitly treated as zero-weighted. |
| ies_group_draws(true) | Boolean | A flag to draw from the (multivariate) Gaussian prior by parameter/observation groups. This is usually a good idea since groups of parameters/observations are likely to have prior correlation. |
| ies_save_binary(false) | Boolean | A flag to save parameter and observation ensembles in binary (i.e., JCB) format instead of CSV format. |
| ies_csv_by_reals(true) | Boolean | A flag to save parameter and observation ensemble CSV files by realization instead of by variable name. If true, each row of the CSV file is a realization. If false, each column of the CSV file is a realization. |
| ies_autoadaloc(false) | Boolean | Flag to activate automatic adaptive localization. |
| ies_autoadaloc_sigma_dist(1.0) | Real | Real number representing the factor by which a correlation coefficient must exceed the standard deviation of background correlation coefficients to be considered significant. Default is 1.0 |
| tie_by_group(false) | Boolean | Flag to tie all adjustable parameters together within each parameter group. Initial parameter ratios are maintained as parameters are adjusted. Parameters that are designated as already tied, or that have parameters tied to them, are not affected. |
| ies_enforce_chglim(false) | Boolean | Flag to enforce parameter change limits (via FACPARMAX and RELPARMAX) in a way similar to PEST and PESTPP-GLM (by scaling the entire realization). Default is false. |
| ies_center_on() | String | A realization name that should be used for the ensemble center in calculating the approximate Jacobian matrix. The realization name must be in both the parameter and observation ensembles. If not passed, the mean vector is used as the center. The value “_MEDIAN_” can also be used, which instructs PESTPP-IES to use the median vector for calculating anomalies. |
| enforce_tied_bounds(false) | Boolean | Flag to enforce parameter bounds on any tied parameters. Depending on the ration between the tied and free parameters, this option can greatly limit parameter changes. |
| ies_no_noise(false) | Boolean | Flag to not generate and use realizations of measurement noise. Default is False (that is, to use measurement noise). |
| ies_drop_conflicts(false) | Boolean | Flag to remove non-zero weighted observations that are in a prior-data conflict state from the upgrade calculations. Default is False. |
| ies_pdc_sigma_distance() | Real > 0.0 | The number of standard deviations from the mean used in checking for prior-data conflict. |
| ies_save_rescov(False) | Boolean | Flag to save the iteration-level residual covariance matrix. If ies_save_binary is True, then a binary format file is written, otherwise an ASCII format (.cov) file is written. The file name is case.N.res.cov/.jcb. Note that this functionality does not scale beyond about 20,000 non-zero-weighted observations |
| obscov() | text | The name of a file containing the observation noise covariance matrix. This can be a parameter uncertainty file (extension .unc), a covariance matrix file (extension .cov) or a binary JCO or JCB file (extension .jco or .jcb). Please see the section on this matrix above to understand the implications of using this matrix |
| rand_seed(358183147) | unsigned integer | Seed for the random number generator. |
| Ies_use_mda(false) | Boolean | Flag to use the (optionally iterative) Kalman update equation – the number of data assimilation iterations is controlled by NOPTMAX; NOPTMAX = 1 and ies_use_mda(true) results in the standard ensemble smoother Kalman update. If False, the GLM iterative ensemble smoother equation is used. Default is False |
| Ies_mda_init_fac(10.0) | double | The initial MDA covariance inflation factor. Only used if ies_use_mda is true. Default is 10.0 |
| Ies_mda_decl_fac(0.5) | double | The final MDA covariance inflation factor. Only used in ies_use_mda is true. Default is 0.5 |
| Ies_localization_type(local) | text | Can be either “local” for local analysis or “covariance” for covariance-only localization. Default is “local” |
| Ies_upgrades_in_memory(true) | Boolean | Flag to hold parameter upgrade ensembles in memory during testing. If False, parameter ensembles are saved to disk during testing and the best-phi ensemble is loaded from disk after testing – this can reduce memory pressure for very high dimensional problems. Default is True but is only activated if number of parameters > 100K. |
| Ies_ordered_binary(true) | Boolean | Flag to write control-file-ordered binary ensemble files. Only used if save_binary is true. If false, hash-ordered binary files are written – for very high dimensional problems, writing unordered binary can save lots of time. If not passed and number of parameters > 100K, then ies_ordered_binary is set to false. |
| ensemble_output_precision(6) | int | Number of significant digits to use in ASCII format ensemble files. Default is 6 |
| ies_multimodal_alpha(1.0) | double | The fraction of the total ensemble size to use as the local neighborhood realizations in the multimodal solution process. Must be greater than zero and less than 1. Values of 0.1 to 0.25 seem to work well. Default is 1.0 (disable multi-modal solution process) |
| ies_weight_ensemble() | text | The name of a CSV or JCO/JCB file (recognized by its extension) containing user-supplied weight vectors for each realization. If this keyword is omitted, PESTPP-IES uses the weight vector in the control file for all realizations. Only used with ies_multimodal_alpha |
| pcf * control data RSTFLE PESTMODE NPAR NOBS NPARGP NPRIOR NOBSGP NTPLFLE NINSFLE PRECIS DPOINT RLAMBDA1 RLAMFAC PHIRATSUF PHIREDLAM NUMLAM RELPARMAX FACPARMAX FACORIG PHIREDSWH NOPTMAX PHIREDSTP NPHISTP NPHINORED RELPARSTP NRELPAR ICOV ICOR IEIG * singular value decomposition SVDMODE MAXSING EIGTHRESH EIGWRITE * parameter groups PARGPNME INCTYP DERINC DERINCLB FORCEN DERINCMUL DERMTHD (one such line for each parameter group) * parameter data PARNME PARTRANS PARCHGLIM PARVAL1 PARLBND PARUBND PARGP SCALE OFFSET DERCOM (one such line for each parameter) PARNME PARTIED (one such line for each tied parameter) * observation groups OBGNME (one such line for each observation group) * observation data OBSNME OBSVAL WEIGHT OBGNME (one such line for each observation) * model command line COMLINE (one such line for each model command line) * model input TEMPFLE INFLE (one such line for each template file) * model output INSFLE OUTFLE (one such line for each instruction file) * prior information PILBL PIFAC * PARNME + PIFAC * log(PARNME) ... = PIVAL WEIGHT OBGNME (one such line for each article of prior information) * regularization PHIMLIM PHIMACCEPT [FRACPHIM] WFINIT WFMIN WFMAX WFFAC WFTOL [IREGADJ] ++ ++PSO(case.pst) |
| pcf * control data RSTFLE PESTMODE NPAR NOBS NPARGP NPRIOR NOBSGP NTPLFLE NINSFLE PRECIS DPOINT RLAMBDA1 RLAMFAC PHIRATSUF PHIREDLAM NUMLAM RELPARMAX FACPARMAX FACORIG PHIREDSWH NOPTMAX PHIREDSTP NPHISTP NPHINORED RELPARSTP NRELPAR ICOV ICOR IEIG * singular value decomposition SVDMODE MAXSING EIGTHRESH EIGWRITE * parameter groups PARGPNME INCTYP DERINC DERINCLB FORCEN DERINCMUL DERMTHD (one such line for each parameter group) * parameter data PARNME PARTRANS PARCHGLIM PARVAL1 PARLBND PARUBND PARGP SCALE OFFSET DERCOM (one such line for each parameter) PARNME PARTIED (one such line for each tied parameter) * observation groups OBGNME (one such line for each observation group) * observation data OBSNME OBSVAL WEIGHT OBGNME (one such line for each observation) * model command line COMLINE (one such line for each model command line) * model input TEMPFLE INFLE (one such line for each template file) * model output INSFLE OUTFLE (one such line for each instruction file) * prior information PILBL PIFAC * PARNME + PIFAC * log(PARNME) ... = PIVAL WEIGHT OBGNME (one such line for each article of prior information) * regularization PHIMLIM PHIMACCEPT [FRACPHIM] WFINIT WFMIN WFMAX WFFAC WFTOL [IREGADJ] ++ ++PSO(case.pst) |
|---|
| * control data RSTPSO NOBJGP NCON NFORG VERBOSE NPOP C1 C2 ISEED INITP VMAX IINERT FINERT INITER NEIBR NNEIBR * objective data OBJNME OBJMETH * constraint data CONNME CONMETH UPLIM (one such line for each constraint function) |
| * control data RSTPSO NOBJGP NCON NFORG VERBOSE NPOP C1 C2 ISEED INITP VMAX IINERT FINERT INITER NEIBR NNEIBR * objective data OBJNME OBJMETH * constraint data CONNME CONMETH UPLIM (one such line for each constraint function) |
|---|
| * control data RSTPSO NOBJGP NCON NFORG VERBOSE NPOP C1 C2 ISEED INITP VMAX IINERT FINERT INITER NREP REPMODE RFIT RRAMP * pareto groups PTONME PTOLIM (one such line for each pareto group) * objective data OBJNME OBJMETH PTOGPNME PTOW (one such line for each objective function) * constraint data CONNME CONMETH UPLIM (one such line for each constraint function) |
| * control data RSTPSO NOBJGP NCON NFORG VERBOSE NPOP C1 C2 ISEED INITP VMAX IINERT FINERT INITER NREP REPMODE RFIT RRAMP * pareto groups PTONME PTOLIM (one such line for each pareto group) * objective data OBJNME OBJMETH PTOGPNME PTOW (one such line for each objective function) * constraint data CONNME CONMETH UPLIM (one such line for each constraint function) |
|---|
+
where, *p*full is the percentage of the repository that is full. When the repository only has three positions, all fitness values are 1, so the value of *α* has no effect. Once the repository size becomes four or greater, the value for *α* begins to increase as a function of how full the repository is. The base value for *α* is 1.0, and then increases toward RFIT until the repository is full, in which case *α* equals RFIT. The value for RRAMP affects how quickly RFIT is reached. RRAMP cannot be 0.0; however, values close to 0.0 will yield an approximately linear increase in *α*. Negative values for RRAMP will cause *α* to approach RFIT more quickly, and the opposite applies to positive values. If you wish to have a constant value for *α* simply set RRAMP to a very large negative number, such as -5.0E+02; this will cause RFIT to be reached immediately. The converse is true for large positive values, i.e., *α* will remain at 1.0 and then suddenly jump to RFIT when the repository is full. The absolute value for RRAMP should not exceed 5.0E+02. *PTONME* and *PTOLIM* @@ -3305,40 +3220,41 @@ When using PESTPP-PSO, in either *estimation* or *pareto* mode, the initial swar To supply PESTPP-PSO with user-defined set of initial swarm positions, the user must supply a value of 2 for the control variable INITP (see Section 11.2.2), along with the path to an external text file containing these initial values. An example of a PSO control file for doing this is shown in Figure 11.4 (this is taken from the *Kursawe* (1991) benchmark problem), -
| * control data 0 2 0 10 2 100 1.00E+00 1.00E+00 171 2 9.00E-01 4.00E-01 4.00E-01 1 lhs-initial-swarm.txt 100 2 5.0 3.0 0 2 -1 * pareto groups obj01 0.00E+00 obj02 1.00E+03 * objective data objfun01 2 obj01 1.00 objfun02 2 obj02 1.00 |
| * control data 0 2 0 10 2 100 1.00E+00 1.00E+00 171 2 9.00E-01 4.00E-01 4.00E-01 1 lhs-initial-swarm.txt 100 2 5.0 3.0 0 2 -1 * pareto groups obj01 0.00E+00 obj02 1.00E+03 * objective data objfun01 2 obj01 1.00 objfun02 2 obj02 1.00 |
|---|
| NPOP PARNME PARVAL-1 PARVAL-2 … PARVAL-NPOP (one such line for each decision variable (or parameter)) |
| NPOP PARNME PARVAL-1 PARVAL-2 … PARVAL-NPOP (one such line for each decision variable (or parameter)) |
|---|
+
Figure 12.XXX. Results of a direct predictive hypothesis testing analysis where the relation between fitting historic observations and a desire to make surface-water/groundwater exchange (SGE) zero is evaluated. The ensemble-based pareto trade-off between these two quantities shows that simulating an SGE of zero is not compatible with the historic observations.
-### 12.2.14 PESTPP-DA Output Files
+### 12.2.14 PESTPP-DA Output Files
The following table summarizes the contents of files that are recorded by PESTPP-DA when it is asked to undertake highly-parameterized inversion. Most of these have been discussed above. It is assumed that the PEST control file on which the inversion process is based is named *case.pst*.
Since the parameters and observations being used can change across cycles, the PESTPP-DA output files for a given cycle may not contain all of the parameters and observations listed in the control file. However, any file tagged with “global” in the name will contain all parameters and observations listed in the control file.
-| File | Contents |
|---|---|
| case.rec | Run record file. This file records a complete history of the inversion process. It is available for user-inspection at any time during that process. |
| case.rmr | Parallel run management record file. |
| case.log | performance record. This file records the times commenced and completed various processing tasks. |
| case.global.<cycle>.pe.csv case.global.<cycle>.pe.jcb | The “global” parameter ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.<cycle>.oe.csv case.global.<cycle>.oe.jcb | The “global” simulated output (e.g., observation) ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.<cycle>.obs+noise..csv case.global.<cycle>.obs+noise.jcb | The “global” observations plus noise ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.<iter>.par.csv case.<cycle>.<iter>.par.jcb | The parameter ensemble at the end of cycle <cycle> and iteration <iter>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.<iter>.obs.csv case.<cycle>.<iter>.obs.jcb | The simulated output (e.g., observation) ensemble at the end of cycle <cycle> and iteration <iter>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.obs+noise.csv case.<cycle>.obs+noise.jcb | The observations plus noise ensemble at the start of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format. |
| case.<cycle>.<iter>.base.par | A pest parameter value file for the “base” realization if present in the ensemble |
| case.<cycle>.<iter>.base.rei | A pest residual value file for the “base” realization if present in the ensemble |
| case.global.prior.pe.csv case.gobal.prior.pe.jcb | The global prior parameter ensemble. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.phi.actual.csv | The global actual objective function (phi) ensemble csv record. “actual” refers to fact that these objective function values do not rely on the noise realizations. |
| Case.global.<cycle>.< iter>.pcs.csv | The global parameter change summary for cycle <cycle> after iteration <iter> |
| File | Contents |
|---|---|
| case.rec | Run record file. This file records a complete history of the inversion process. It is available for user-inspection at any time during that process. |
| case.rmr | Parallel run management record file. |
| case.log | performance record. This file records the times commenced and completed various processing tasks. |
| case.global.<cycle>.pe.csv case.global.<cycle>.pe.jcb | The “global” parameter ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.<cycle>.oe.csv case.global.<cycle>.oe.jcb | The “global” simulated output (e.g., observation) ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.<cycle>.obs+noise..csv case.global.<cycle>.obs+noise.jcb | The “global” observations plus noise ensemble at the end of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.<iter>.par.csv case.<cycle>.<iter>.par.jcb | The parameter ensemble at the end of cycle <cycle> and iteration <iter>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.<iter>.obs.csv case.<cycle>.<iter>.obs.jcb | The simulated output (e.g., observation) ensemble at the end of cycle <cycle> and iteration <iter>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<cycle>.obs+noise.csv case.<cycle>.obs+noise.jcb | The observations plus noise ensemble at the start of cycle <cycle>. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format. |
| case.<cycle>.<iter>.base.par | A pest parameter value file for the “base” realization if present in the ensemble |
| case.<cycle>.<iter>.base.rei | A pest residual value file for the “base” realization if present in the ensemble |
| case.global.prior.pe.csv case.gobal.prior.pe.jcb | The global prior parameter ensemble. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.global.phi.actual.csv | The global actual objective function (phi) ensemble csv record. “actual” refers to fact that these objective function values do not rely on the noise realizations. |
| Case.global.<cycle>.< iter>.pcs.csv | The global parameter change summary for cycle <cycle> after iteration <iter> |
| File | Contents |
|---|---|
| case.rec | Run record file. This file records a complete history of the inversion process. It is available for user-inspection at any time during that process. |
| case.rmr | Parallel run management record file. |
| case.log | performance record. This file records the times commenced and completed various processing tasks. |
| case.pareto.summary.csv | A summary of pareto dominant solutions for each generation. |
| case.chance.obs_pop.csv case.chance.obs_pop.jcb | The current generation chance shifted simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.chance.dv_pop.csv case.chance.dv_pop.jcb | The current generation shifted decision-variable population that corresponds with the chance-shifted simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.obs_pop.csv case.obs_pop.jcb | The current generation raw (unshifted) simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case..dv_pop.csv case.dv_pop.jcb | The current generation decision-variable population that corresponds with the raw simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.obs_pop.csv case.<iter>.obs_pop.jcb | The <iter> generation raw (unshifted) simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.dv_pop.csv case.<iter>.dv_pop.jcb | The <iter> generation decision-variable population that corresponds with the raw simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.chance.obs_pop.csv case.<iter>.chance.obs_pop.jcb | The <iter> generation chance-shifted simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.chance.dv_pop.csv case.<iter>.chance.dv_pop.jcb | The <iter> generation decision-variable population that corresponds with the chance-shifted simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.lineage.csv | The listing of parents used to generate each offspring for each generation |
| File | Contents |
|---|---|
| case.rec | Run record file. This file records a complete history of the inversion process. It is available for user-inspection at any time during that process. |
| case.rmr | Parallel run management record file. |
| case.log | performance record. This file records the times commenced and completed various processing tasks. |
| case.pareto.summary.csv | A summary of pareto dominant solutions for each generation. |
| case.chance.obs_pop.csv case.chance.obs_pop.jcb | The current generation chance shifted simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.chance.dv_pop.csv case.chance.dv_pop.jcb | The current generation shifted decision-variable population that corresponds with the chance-shifted simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.obs_pop.csv case.obs_pop.jcb | The current generation raw (unshifted) simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case..dv_pop.csv case.dv_pop.jcb | The current generation decision-variable population that corresponds with the raw simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.obs_pop.csv case.<iter>.obs_pop.jcb | The <iter> generation raw (unshifted) simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.dv_pop.csv case.<iter>.dv_pop.jcb | The <iter> generation decision-variable population that corresponds with the raw simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.chance.obs_pop.csv case.<iter>.chance.obs_pop.jcb | The <iter> generation chance-shifted simulate outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.<iter>.chance.dv_pop.csv case.<iter>.chance.dv_pop.jcb | The <iter> generation decision-variable population that corresponds with the chance-shifted simulated outputs. Depending on the value of SAVE_BINARY, the file may be stored in csv format or binary format |
| case.lineage.csv | The listing of parents used to generate each offspring for each generation |
| 3 4 2 3.4423 23.323 2.3232 1.3232 5.4231 3.3124 4.4331 3.4442 7.4233 5.4432 7.5362 8.4232 * row names apar1 apar2 apar3 * column names aobs1 aobs2 aobs3 aobs4 |
| 3 4 2 3.4423 23.323 2.3232 1.3232 5.4231 3.3124 4.4331 3.4442 7.4233 5.4432 7.5362 8.4232 * row names apar1 apar2 apar3 * column names aobs1 aobs2 aobs3 aobs4 |
|---|
| 5 5 -1 4.5 4.5 2.4 7.53 5.32 * row and column names par1 par2 par3 par4 par5 |
| 5 5 -1 4.5 4.5 2.4 7.53 5.32 * row and column names par1 par2 par3 par4 par5 |
|---|
| ~ An example of an uncertainty file START STANDARD_DEVIATION std_multiplier 3.0 ro9 1.0 ro10 1.0 ro4 1.0 END STANDARD_DEVIATION START COVARIANCE_MATRIX file "mat.dat" variance_multiplier 1e-2 END COVARIANCE_MATRIX START COVARIANCE_MATRIX file "cov.mat" variance_multiplier 1.0 parameter_list_file “list.dat” END COVARIANCE_MATRIX START COVARIANCE_MATRIX file "cov1.mat" first_parameter kpp1 last_parameter kpp129 END COVARIANCE_MATRIX |
| ~ An example of an uncertainty file START STANDARD_DEVIATION std_multiplier 3.0 ro9 1.0 ro10 1.0 ro4 1.0 END STANDARD_DEVIATION START COVARIANCE_MATRIX file "mat.dat" variance_multiplier 1e-2 END COVARIANCE_MATRIX START COVARIANCE_MATRIX file "cov.mat" variance_multiplier 1.0 parameter_list_file “list.dat” END COVARIANCE_MATRIX START COVARIANCE_MATRIX file "cov1.mat" first_parameter kpp1 last_parameter kpp129 END COVARIANCE_MATRIX |
|---|
| negncol, nrow 32 bit integers ncount 32 bit integer index, value 32 bit integer, 64 bit real repeat the above ncount times parname 12 bit character repeat the above ncol times obsname 20 bit character repeat the above nrow times |
| negncol, nrow 32 bit integers ncount 32 bit integer index, value 32 bit integer, 64 bit real repeat the above ncount times parname 12 bit character repeat the above ncol times obsname 20 bit character repeat the above nrow times |
|---|
| ncol, nrow 32 bit integers ncount 32 bit integer irow, icol, value 32 bit integer, 32 bit integer, 64 bit real repeat the above noount times colname 200 bit character repeat the above ncol times rowname 200 bit character repeat the above nrow times |
| ncol, nrow 32 bit integers ncount 32 bit integer irow, icol, value 32 bit integer, 32 bit integer, 64 bit real repeat the above noount times colname 200 bit character repeat the above ncol times rowname 200 bit character repeat the above nrow times |
|---|