SobolStatistics

Compute SOBOL statistics values of a given VectorPostprocessor objects and vectors.

Overview

This object computes the Sobol sensitivity indices following the procedure defined by Saltelli (2002). This includes the first-order and total-effect indices and optionally the second-order indices as well. The SobolStatistics object only operates on result data generated from Sobol-based sampling strategy, which is provided by the Sobol.

Example Input File Syntax

The following input snippet uses the GFunction test object, which is defined as:

var element = document.getElementById("moose-equation-d0f6307b-bfff-4baf-a35b-e194903aa630");katex.render("g(x_1, x_2, \\ldots, x_n) = \\prod_{i=1}^n\\frac{|4x_i-2|+q_i}{1+q_i},", element, {displayMode:true,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});

where $var element = document.getElementById("moose-equation-b95801fd-3d8d-4eff-b5f6-ac452fede068");katex.render("\\vec{q}", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ is defined in the input file, $var element = document.getElementById("moose-equation-5a602998-b402-4147-8872-024408fa4f29");katex.render("x", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ is the vector of model data, and $var element = document.getElementById("moose-equation-8eb5eba5-c247-4dbb-8161-8b5655e145d4");katex.render("n", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ is the number of input variables. The $var element = document.getElementById("moose-equation-f1ffdb22-d67a-4f15-b94b-106a79fea8db");katex.render("x", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ data is generated by the Sobol sampler object.

[Samplers]
  [sample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2011
  []
  [resample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2013
  []
  [sobol]
    type = Sobol
    sampler_a = sample
    sampler_b = resample
  []
[]

[VectorPostprocessors]
  [results]
    type = GFunction
    sampler = sample
    q_vector = '0 0.5 3 9 99 99'
    execute_on = INITIAL
    outputs = none
  []
  [sobol]
    type = SobolStatistics
    sampler = sobol
    results = results
    execute_on = FINAL
  []
[]

The resulting data includes a single list of all the computed statistics, in the following order: $var element = document.getElementById("moose-equation-48be153b-0de7-4465-9850-995ec447db90");katex.render("S_1,\\ldots,S_n,S^T_1,\\ldots,S^T_n, S_{21}, S_{31}, S_{32}, S_{41}, S_{42}, S_{43},\\ldots", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ , where $var element = document.getElementById("moose-equation-c95102fc-8aa2-460c-9239-a26ceaa71985");katex.render("S_i", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ give the first-order indices, $var element = document.getElementById("moose-equation-608909e5-fd08-40b7-8b23-c85b51961629");katex.render("S^T_i", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ are the total-effect indices, and $var element = document.getElementById("moose-equation-97d7177f-88aa-43ea-8fbb-4bd7acb47aa5");katex.render("S_{ij}", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ are the second-order indices for $var element = document.getElementById("moose-equation-747989e8-a616-4dae-8ccf-87726209bed6");katex.render("i=1\\ldots n", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ , $var element = document.getElementById("moose-equation-edde31ce-9b5e-4fe9-a002-5606105a3686");katex.render("j=1\\ldots n", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ for $var element = document.getElementById("moose-equation-35df433c-c1c1-43b9-8c53-36a4d648faa3");katex.render("i\\neq j", element, {displayMode:false,throwOnError:false,macros:{"\\pf":"\\frac{\\partial #1}{\\partial #2}"}});$ .

results_g_values
0.58775354989454
0.2632494383694
0.035660144918828
0.0056970432830808
5.7774189019761e-05
5.7064241636837e-05
0.6855752603234
0.35589828400645
0.056283261074271
0.006731599671748
-0.0013038267007721
-0.0013173393507955
0.086111877716527
0.0076533281426128
-0.0042528183099492
-0.0059920611119531
-0.0058620907349385
-0.0030183647923982
-0.0030919023968987
-0.0045615778350568
-0.0046244835076265
0.00032316096075386
0.00029440227225901
0.00022338741127334
2.7320523764526e-05
3.5429693653785e-05
2.0772174871302e-08

Input Parameters

contains_complete_historyFalseSet this flag to indicate that the values in all vectors declared by this VPP represent a time history (e.g. with each invocation, new values are added and old values are never removed). This changes the output so that only a single file is output and updated with each invocation
Default:False
C++ Type:bool
Options:
Description:Set this flag to indicate that the values in all vectors declared by this VPP represent a time history (e.g. with each invocation, new values are added and old values are never removed). This changes the output so that only a single file is output and updated with each invocation
execute_onTIMESTEP_ENDThe list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.
Default:TIMESTEP_END
C++ Type:ExecFlagEnum
Options:NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM
Description:The list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.
parallel_typeREPLICATEDSet how the data is represented within the VectorPostprocessor (VPP); 'distributed' indicates that data within the VPP is distributed and no auto communication is preformed, this setting will result in parallel output within the CSV output; 'replicated' indicates that the data within the VPP is correct on processor 0, the data will automatically be broadcast to all processors unless the '_auto_broadcast' param is set to false within the validParams function.
Default:REPLICATED
C++ Type:MooseEnum
Options:DISTRIBUTED, REPLICATED
Description:Set how the data is represented within the VectorPostprocessor (VPP); 'distributed' indicates that data within the VPP is distributed and no auto communication is preformed, this setting will result in parallel output within the CSV output; 'replicated' indicates that the data within the VPP is correct on processor 0, the data will automatically be broadcast to all processors unless the '_auto_broadcast' param is set to false within the validParams function.
resultsStochasticResults object containing data to use for calculation.
C++ Type:VectorPostprocessorName
Options:
Description:StochasticResults object containing data to use for calculation.
samplerSobolSampler object.
C++ Type:SamplerName
Options:
Description:SobolSampler object.

Optional Parameters

allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
Default:False
C++ Type:bool
Options:
Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Options:
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Options:
Description:Set the enabled status of the MooseObject.
force_preauxFalseForces the GeneralUserObject to be executed in PREAUX
Default:False
C++ Type:bool
Options:
Description:Forces the GeneralUserObject to be executed in PREAUX
force_preicFalseForces the GeneralUserObject to be executed in PREIC during initial setup
Default:False
C++ Type:bool
Options:
Description:Forces the GeneralUserObject to be executed in PREIC during initial setup
outputsVector of output names were you would like to restrict the output of variables(s) associated with this object
C++ Type:std::vector<OutputName>
Options:
Description:Vector of output names were you would like to restrict the output of variables(s) associated with this object
use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
Default:False
C++ Type:bool
Options:
Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Advanced Parameters

Input Files

(modules/stochastic_tools/examples/sobol/master.i)
(modules/stochastic_tools/test/tests/vectorpostprocessors/sobol_statistics/sobol.i)

References

Andrea Saltelli. Making best use of model evaluations to compute sensitivity indices. Computer Physics Communications, 145(2):280–297, 2002. URL: https://doi.org/10.1016/S0010-4655(02)00280-1.

@article{saltelli2002making,
    author = "Saltelli, Andrea",
    title = "Making best use of model evaluations to compute sensitivity indices",
    journal = "Computer Physics Communications",
    volume = "145",
    number = "2",
    pages = "280--297",
    year = "2002",
    publisher = "Elsevier",
    url = "https://doi.org/10.1016/S0010-4655(02)00280-1"
}

(modules/stochastic_tools/test/tests/vectorpostprocessors/sobol_statistics/sobol.i)

[StochasticTools]
[]

[Distributions/uniform]
  type = Uniform
  lower_bound = 0
  upper_bound = 1
[]

[Samplers]
  [sample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2011
  []
  [resample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2013
  []
  [sobol]
    type = Sobol
    sampler_a = sample
    sampler_b = resample
  []
[]

[VectorPostprocessors]
  [results]
    type = GFunction
    sampler = sample
    q_vector = '0 0.5 3 9 99 99'
    execute_on = INITIAL
    outputs = none
  []
  [sobol]
    type = SobolStatistics
    sampler = sobol
    results = results
    execute_on = FINAL
  []
[]

[Outputs]
  execute_on = 'FINAL'
  csv = true
[]

(modules/stochastic_tools/test/tests/vectorpostprocessors/sobol_statistics/gold/sobol_out_sobol_0002.csv)

results_g_values
0.58775354989454
0.2632494383694
0.035660144918828
0.0056970432830808
5.7774189019761e-05
5.7064241636837e-05
0.6855752603234
0.35589828400645
0.056283261074271
0.006731599671748
-0.0013038267007721
-0.0013173393507955
0.086111877716527
0.0076533281426128
-0.0042528183099492
-0.0059920611119531
-0.0058620907349385
-0.0030183647923982
-0.0030919023968987
-0.0045615778350568
-0.0046244835076265
0.00032316096075386
0.00029440227225901
0.00022338741127334
2.7320523764526e-05
3.5429693653785e-05
2.0772174871302e-08

(modules/stochastic_tools/examples/sobol/master.i)

[StochasticTools]
[]

[Distributions]
  [gamma]
    type = Uniform
    lower_bound = 0.5
    upper_bound = 2.5
  []
  [q_0]
    type = Weibull
    location = -110
    scale = 20
    shape = 1
  []
  [T_0]
    type = Normal
    mean = -10
    standard_deviation = 1.5
  []
  [s]
    type = Normal
    mean = 1
    standard_deviation = 0.25
  []
[]

[Samplers]
  [hypercube_a]
    type = LatinHypercube
    num_rows = 10000
    distributions = 'gamma q_0 T_0 s'
    seed = 2011
  []
  [hypercube_b]
    type = LatinHypercube
    num_rows = 10000
    distributions = 'gamma q_0 T_0 s'
    seed = 2013
  []
  [sobol]
    type = Sobol
    sampler_a = hypercube_a
    sampler_b = hypercube_b
  []
[]

[MultiApps]
  [runner]
    type = SamplerFullSolveMultiApp
    sampler = sobol
    input_files = 'diffusion.i'
    mode = batch-restore
  []
[]

[Transfers]
  [parameters]
    type = SamplerParameterTransfer
    multi_app = runner
    sampler = sobol
    parameters = 'Materials/constant/prop_values Kernels/source/value BCs/right/value BCs/left/value'
    to_control = 'stochastic'
  []
  [results]
    type = SamplerPostprocessorTransfer
    multi_app = runner
    sampler = sobol
    to_vector_postprocessor = results
    from_postprocessor = 'T_avg q_left'
  []
[]

[VectorPostprocessors]
  [results]
    type = StochasticResults
  []
  [samples]
    type = SamplerData
    sampler = sobol
  []
  [stats]
    type = Statistics
    vectorpostprocessors = results
    compute = 'mean'
    ci_method = 'percentile'
    ci_levels = '0.05'
  []
  [sobol]
    type = SobolStatistics
    sampler = sobol
    results = results
  []
[]

[Outputs]
  csv = true
  execute_on = 'FINAL'
[]

(modules/stochastic_tools/test/tests/vectorpostprocessors/sobol_statistics/sobol.i)

[StochasticTools]
[]

[Distributions/uniform]
  type = Uniform
  lower_bound = 0
  upper_bound = 1
[]

[Samplers]
  [sample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2011
  []
  [resample]
    type = MonteCarlo
    distributions = 'uniform uniform uniform uniform uniform uniform'
    num_rows = 4
    seed = 2013
  []
  [sobol]
    type = Sobol
    sampler_a = sample
    sampler_b = resample
  []
[]

[VectorPostprocessors]
  [results]
    type = GFunction
    sampler = sample
    q_vector = '0 0.5 3 9 99 99'
    execute_on = INITIAL
    outputs = none
  []
  [sobol]
    type = SobolStatistics
    sampler = sobol
    results = results
    execute_on = FINAL
  []
[]

[Outputs]
  execute_on = 'FINAL'
  csv = true
[]

Overview
Example Input File Syntax
Input Parameters
Input Files
References

Install MOOSE

New Users

Examples and Tutorials

Application Usage

Physics and Syntax

Application Development

Framework Development

MOOSEDocs

Infrastructure

Questions

Information and Tools

INL Applications and Remote Access