PolynomialChaosSobolStatistics

Compute SOBOL statistics values of a trained PolynomialChaos surrogate.

Overview

This object computes Sobol sensitivity indices based on a trained PolynomialChaos surrogate model. The alogrithm is based on computations described in Sudret (2008). The sensitivities to be computed are defined by the input parameter "sensitivity_order": first computes first-order sensitivities, second computes second-order sensitivities, all computes all sensitivities (replacing first and second), and total comutes the total sensitivities.

Example Syntax

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

where is defined in the input file, is the vector of model data, and is the number of input variables. The data is generated by QuadratureSampler object.

[VectorPostprocessors]
  [results]
    type = GFunction
    sampler = sample
    q_vector = '0 0.5 3 9 99 99'
    execute_on = INITIAL
    outputs = none
  []
  [sobol]
    type = PolynomialChaosSobolStatistics
    pc_name = poly_chaos
    sensitivity_order = 'all total'
    execute_on = timestep_end
  []
[]
(modules/stochastic_tools/test/tests/surrogates/poly_chaos/sobol.i)

Example Output

The resulting output contains a single column of all the sensitivities and columnes containing the indicies. The column i_T is the total sensitivity index, i_1 is the first index, i_2 second, and so on to i_n. For sensitivity orders less than , the last index is repeated and can be ignored.

poly_chaos,i_T,i_1,i_2,i_3,i_4,i_5,i_6
0.66924780365628,0,0,0,0,0,0,0
0.28619846733258,1,0,0,0,0,0,0
0.038392996228437,2,0,0,0,0,0,0
0.0060411077026529,3,0,0,0,0,0,0
5.9812540024784e-05,4,0,0,0,0,0,0
5.9812540024784e-05,5,0,0,0,0,0,0
0.66924780365628,0,0,0,0,0,0,0
0.28619846733258,0,1,1,1,1,1,1
0.038392996228437,0,2,2,2,2,2,2
0.0060411077026529,0,3,3,3,3,3,3
5.9812540024784e-05,0,4,4,4,4,4,4
5.9812540024784e-05,0,5,5,5,5,5,5
5.285967493225e-29,0,0,1,1,1,1,1
4.830441079516e-30,0,0,2,2,2,2,2
2.3537404069876e-31,0,0,3,3,3,3,3
1.2851971453103e-31,0,0,4,4,4,4,4
9.7243393783398e-32,0,0,5,5,5,5,5
2.8036255956726e-31,0,1,2,2,2,2,2
5.6458324345948e-32,0,1,3,3,3,3,3
5.201235192063e-32,0,1,4,4,4,4,4
3.8229032758747e-32,0,1,5,5,5,5,5
3.6702787303277e-33,0,2,3,3,3,3,3
6.8822775950545e-33,0,2,4,4,4,4,4
5.0863886742273e-33,0,2,5,5,5,5,5
9.4052217449154e-34,0,3,4,4,4,4,4
8.2525733364501e-34,0,3,5,5,5,5,5
1.1437129538783e-35,0,4,5,5,5,5,5
8.3110407141877e-33,0,0,1,2,2,2,2
4.3564024206612e-35,0,0,1,3,3,3,3
2.2616474877005e-35,0,0,1,4,4,4,4
0,0,0,1,5,5,5,5
6.0559817026029e-37,0,0,2,3,3,3,3
4.9864238916151e-35,0,0,2,4,4,4,4
1.2773220117863e-35,0,0,2,5,5,5,5
2.2616474877005e-35,0,0,3,4,4,4,4
2.2462790842028e-36,0,0,3,5,5,5,5
3.6186359803208e-36,0,0,4,5,5,5,5
8.4742207610772e-36,0,1,2,3,3,3,3
4.9864238916151e-35,0,1,2,4,4,4,4
6.5128801849667e-37,0,1,2,5,5,5,5
6.0559817026029e-37,0,1,3,4,4,4,4
4.7849731971184e-37,0,1,3,5,5,5,5
1.1995661973331e-36,0,1,4,5,5,5,5
1.137261858829e-36,0,2,3,4,4,4,4
1.3291592214218e-38,0,2,3,5,5,5,5
5.615697710507e-37,0,2,4,5,5,5,5
2.0768112834715e-36,0,3,4,5,5,5,5
0,0,0,1,2,3,3,3
0,0,0,1,2,4,4,4
0,0,0,1,2,5,5,5
0,0,0,1,3,4,4,4
0,0,0,1,3,5,5,5
0,0,0,1,4,5,5,5
0,0,0,2,3,4,4,4
0,0,0,2,3,5,5,5
0,0,0,2,4,5,5,5
0,0,0,3,4,5,5,5
0,0,1,2,3,4,4,4
0,0,1,2,3,5,5,5
0,0,1,2,4,5,5,5
0,0,1,3,4,5,5,5
0,0,2,3,4,5,5,5
0,0,0,1,2,3,4,4
0,0,0,1,2,3,5,5
0,0,0,1,2,4,5,5
0,0,0,1,3,4,5,5
0,0,0,2,3,4,5,5
0,0,1,2,3,4,5,5
0,0,0,1,2,3,4,5
(modules/stochastic_tools/test/tests/surrogates/poly_chaos/gold/sobol_out_sobol_0002.csv)

Input Parameters

  • pc_nameName of PolynomialChaos.

    C++ Type:std::vector<UserObjectName>

    Options:

    Description:Name of PolynomialChaos.

  • sensitivity_orderOrder of sensitivities to compute. The all option computes all possible orders.

    C++ Type:MultiMooseEnum

    Options:first, second, all, total

    Description:Order of sensitivities to compute. The all option computes all possible orders.

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

  • prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.

    C++ Type:MaterialPropertyName

    Options:

    Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.

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_postauxFalseForces the UserObject to be executed in POSTAUX

    Default:False

    C++ Type:bool

    Options:

    Description:Forces the UserObject to be executed in POSTAUX

  • force_preauxFalseForces the UserObject to be executed in PREAUX

    Default:False

    C++ Type:bool

    Options:

    Description:Forces the UserObject to be executed in PREAUX

  • force_preicFalseForces the UserObject to be executed in PREIC during initial setup

    Default:False

    C++ Type:bool

    Options:

    Description:Forces the UserObject 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

References

  1. Bruno Sudret. Global sensitivity analysis using polynomial chaos expansions. Reliability Engineering & System Safety, 93(7):964–979, 2008. Bayesian Networks in Dependability. doi:10.1016/j.ress.2007.04.002.[BibTeX]