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: μ=[μ1,μ2,μ3,...,μNp]T\vec{\mu}=\left[\mu_1,\mu_2,\mu_3,...,\mu_{N_p}\right]^T, where NpN_p 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 μi\mu_i can be approximated as:

    Sμi=CΦ(μi+)Φ(μi)μi+μi,S_{\mu_i} =C\frac{\Phi(\vec{\mu}_{i+})-\Phi(\vec{\mu}_{i-})}{\mu_{i+}-\mu_{i-}},

    where μi+/\vec{\mu}_{i+/-} are the vectors with the ii-th entries perturbed in the positive and negative direction (so they are replaced by μi+\mu_{i+} and μi\mu_{i-}), 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 2Np+12N_p+1 model evaluations. We add an additional model evaluation for the reference point.

  • Forward difference approximation: We assume that the sensitivity coefficient for parameter μi\mu_i can be approximated as:

    Sμi=CΦ(μi+)Φ(μ)μi+μ,S_{\mu_i} =C \frac{\Phi(\vec{\mu}_{i+})-\Phi(\vec{\mu})}{\mu_{i+}-\mu},

    where mui+\vec{mu}_{i+} is the vector with the ii-th entry perturbed in the positive direction (i.e. it is are replaced by μi+\mu_{i+}). 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 Np+1N_p+1 model evaluations.

The multiplication factor CC in the expressions above depends on if the user requested relative sensitivities in the DirectPerturbationReporter. If an absolute sensitivity was requested C=1C=1, for relative sensitivities C=μrefΦrefC=\frac{\mu_{ref}}{\Phi_{ref}}, where μref\mu_{ref} and Φref\Phi_{ref} 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.

[Samplers]
  [directperturbation]
    type = DirectPerturbationSampler
    nominal_parameter_values = '0.1 0.2 0.3'
    relative_perturbation_intervals = '0.1 0.2 0.3'
    perturbation_method = central_difference
  []
[]
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/directperturbation.i)

This results in the following parameters:

directperturbation_0,directperturbation_1,directperturbation_2
0.1,0.2,0.3
0.105,0.2,0.3
0.095,0.2,0.3
0.1,0.22,0.3
0.1,0.18,0.3
0.1,0.2,0.345
0.1,0.2,0.255
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/gold/directperturbation_out_data_0001.csv)

With forward differencing the sample output is the following:

directperturbation_0,directperturbation_1,directperturbation_2
0.1,0.2,0.3
0.11,0.2,0.3
0.1,0.24,0.3
0.1,0.2,0.39
(contrib/moose/modules/stochastic_tools/test/tests/samplers/directperturbation/gold/dp_fd_data_0001.csv)

Input Parameters

  • 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.

Required 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)

    Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM, PRE_MULTIAPP_SETUP

    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)

    Options:central_difference, forward_difference

    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.

Advanced Parameters