- nominal_parameter_valuesThe nominal values of the parameters around which we shall perturb them.
C++ Type:std::vector<double>
Unit:(no unit assumed)
Controllable:No
Description:The nominal values of the parameters around which we shall perturb them.
DirectPerturbationSampler
Sampler that creates samples for a direct perturbation-based sensitivity study.
Overview
The direct perturbation method is the simplest approach for computing local sensitivity coefficients using the finite difference approximation of the derivatives at a certain point in the parameter domain. The coordinates of the reference location can be supplied through the "nominal_parameter_values" parameter. The parameter vector holding the parameters can be denoted by: , where is the number of parameters. The direct perturbation-based sensitivity coefficients can then be computed using the following two methods:
Central difference approximation: We assume that the sensitivity coefficient for parameter can be approximated as:
where are the vectors with the -th entries perturbed in the positive and negative direction (so they are replaced by and ), respectively. Parameter "relative_perturbation_intervals" can be used to specify the perturbation interval around the nominal values. For the central difference approach a 0.1 value would mean that the parameter is perturbed by 5% in both directions making the total perturbation centered around the nominal value. This approach is more accurate, but needs model evaluations. We add an additional model evaluation for the reference point.
Forward difference approximation: We assume that the sensitivity coefficient for parameter can be approximated as:
where is the vector with the -th entry perturbed in the positive direction (i.e. it is are replaced by ). Parameter "relative_perturbation_intervals" can be used to specify the perturbation interval from the nominal values. For the forward difference approach a 0.1 value would mean that the parameter is perturbed by 10% in one direction. This approach is less accurate, but only needs model evaluations.
The multiplication factor in the expressions above depends on if the user requested relative sensitivities in the DirectPerturbationReporter. If an absolute sensitivity was requested , for relative sensitivities , where and are the parameter value and quantity of interest at the reference point.
This sampler is responsible for creating parameter vectors with perturbed entries. The computation of the sensitivity coefficients is done using DirectPerturbationReporter. The differencing approach can be selected using the "perturbation_method" parameter. The implementation is fully parallelized meaning that the model evaluations and the sensitivity calculation all happen in parallel.
Example Input Syntax
the following input generates perturbed samples for a 3-dimensional parameter space around a nominal value using the central difference approach.
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/directperturbation.i)This results in the following parameters:
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/gold/directperturbation_out_data_0001.csv)With forward differencing the sample output is the following:
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/gold/dp_fd_data_0001.csv)Input Parameters
- execute_onLINEARThe list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
Default:LINEAR
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Controllable:No
Description:The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
- limit_get_global_samples429496729The maximum allowed number of items in the DenseMatrix returned by getGlobalSamples method.
Default:429496729
C++ Type:unsigned long
Unit:(no unit assumed)
Controllable:No
Description:The maximum allowed number of items in the DenseMatrix returned by getGlobalSamples method.
- limit_get_local_samples429496729The maximum allowed number of items in the DenseMatrix returned by getLocalSamples method.
Default:429496729
C++ Type:unsigned long
Unit:(no unit assumed)
Controllable:No
Description:The maximum allowed number of items in the DenseMatrix returned by getLocalSamples method.
- limit_get_next_local_row429496729The maximum allowed number of items in the std::vector returned by getNextLocalRow method.
Default:429496729
C++ Type:unsigned long
Unit:(no unit assumed)
Controllable:No
Description:The maximum allowed number of items in the std::vector returned by getNextLocalRow method.
- max_procs_per_row4294967295This will ensure that the sampler is partitioned properly when 'MultiApp/*/max_procs_per_app' is specified. It is not recommended to use otherwise.
Default:4294967295
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:This will ensure that the sampler is partitioned properly when 'MultiApp/*/max_procs_per_app' is specified. It is not recommended to use otherwise.
- min_procs_per_row1This will ensure that the sampler is partitioned properly when 'MultiApp/*/min_procs_per_app' is specified. It is not recommended to use otherwise.
Default:1
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:This will ensure that the sampler is partitioned properly when 'MultiApp/*/min_procs_per_app' is specified. It is not recommended to use otherwise.
- perturbation_methodcentral_differenceThe perturbation method to use for creating samples.
Default:central_difference
C++ Type:MooseEnum
Unit:(no unit assumed)
Controllable:No
Description:The perturbation method to use for creating samples.
- relative_perturbation_intervals0.01 The numbers by which the nominal values are multiplied to get a perturbed value.
Default:0.01
C++ Type:std::vector<double>
Unit:(no unit assumed)
Controllable:No
Description:The numbers by which the nominal values are multiplied to get a perturbed value.
- seed0Random number generator initial seed
Default:0
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:Random number generator initial seed
Optional Parameters
- control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
- enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set the enabled status of the MooseObject.