LatinHypercube

Latin Hypercube Sampler.

Overview

This sampler implements the Latin hypercube strategy presented in McKay et al. (1979) as:

If we wish to ensure also that each of the input variables $var element = document.getElementById("moose-equation-a9130e50-a826-4bf4-b9db-67f06d36b9b9");katex.render("X_k", element, {displayMode:false,throwOnError:false});$ has all portions of its distribution represented by input values, we can divide the range of each $var element = document.getElementById("moose-equation-8e58308b-81fd-447d-b87c-1b4757b21579");katex.render("X_k", element, {displayMode:false,throwOnError:false});$ into $var element = document.getElementById("moose-equation-9ccac725-4e34-40a9-bf7f-576cd2d87e0b");katex.render("N", element, {displayMode:false,throwOnError:false});$ strata of equal marginal probability $var element = document.getElementById("moose-equation-96be0958-6331-4ae9-b24a-b77119a7f4c0");katex.render("l/N", element, {displayMode:false,throwOnError:false});$ , and sample once from each stratum. Let this sample be $var element = document.getElementById("moose-equation-a478ee62-bf76-4ec1-be8f-0b67504955a1");katex.render("X_{kj},\\,j=l,\\ldots,N", element, {displayMode:false,throwOnError:false});$ . These form the $var element = document.getElementById("moose-equation-ec0d88d6-2428-42e6-87de-0ee16b4fcd0c");katex.render("X_k", element, {displayMode:false,throwOnError:false});$ , component, $var element = document.getElementById("moose-equation-3695b97d-08a4-44ae-a595-65eae7af2de7");katex.render("k=l,\\ldots,K", element, {displayMode:false,throwOnError:false});$ , in $var element = document.getElementById("moose-equation-004dcb13-627f-4b8f-9b3a-c5806acb6cc8");katex.render("X_i,\\,i = 1,\\ldots,N", element, {displayMode:false,throwOnError:false});$ . The components of the various $var element = document.getElementById("moose-equation-dff2b076-48b0-47cd-ba3b-c9b9fcffed57");katex.render("X_k", element, {displayMode:false,throwOnError:false});$ 's are matched at random.

Example Input File Syntax

The following input file creates a Latin hypercube sample from two uniform distributions with 10 samples of each distribution.

[Distributions<<<{"href": "../../syntax/Distributions/index.html"}>>>]
  [a]
    type = Uniform<<<{"description": "Continuous uniform distribution.", "href": "../distributions/Uniform.html"}>>>
    lower_bound<<<{"description": "Distribution lower bound"}>>> = 100
    upper_bound<<<{"description": "Distribution upper bound"}>>> = 200
  []
  [b]
    type = Uniform<<<{"description": "Continuous uniform distribution.", "href": "../distributions/Uniform.html"}>>>
    lower_bound<<<{"description": "Distribution lower bound"}>>> = 10
    upper_bound<<<{"description": "Distribution upper bound"}>>> = 20
  []
[]

[Samplers<<<{"href": "../../syntax/Samplers/index.html"}>>>]
  [sample]
    type = LatinHypercube<<<{"description": "Latin Hypercube Sampler.", "href": "LatinHypercubeSampler.html"}>>>
    distributions<<<{"description": "The distribution names to be sampled, the number of distributions provided defines the number of columns per matrix."}>>> = 'a b'
    num_rows<<<{"description": "The size of the square matrix to generate."}>>> = 10
    seed<<<{"description": "Random number generator initial seed"}>>> = 1980
    execute_on<<<{"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."}>>> = 'INITIAL TIMESTEP_END'
  []
[]

The graph in Figure 1 show the Latin hypercube sample generated from the input file snippet where the grid lines are defined with the associated probability based bins.

Figure 1: Latin hypercube sampled data with tick marks defined at the probability intervals.

Input Parameters

distributionsThe distribution names to be sampled, the number of distributions provided defines the number of columns per matrix.
C++ Type:std::vector<DistributionName>
Controllable:No
Description:The distribution names to be sampled, the number of distributions provided defines the number of columns per matrix.
num_rowsThe size of the square matrix to generate.
C++ Type:unsigned long
Controllable:No
Description:The size of the square matrix to generate.

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
Options:NONE, INITIAL, LINEAR, LINEAR_CONVERGENCE, NONLINEAR, NONLINEAR_CONVERGENCE, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, MULTIAPP_FIXED_POINT_CONVERGENCE, 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
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
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
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
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
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.
seed0Random number generator initial seed
Default:0
C++ Type:unsigned int
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>
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
Controllable:No
Description:Set the enabled status of the MooseObject.

Advanced Parameters

References

Michael D McKay, Richard J Beckman, and William J Conover. Comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics, 21(2):239–245, 1979.

@article{mckay1979comparison,
    author = "McKay, Michael D and Beckman, Richard J and Conover, William J",
    title = "Comparison of three methods for selecting values of input variables in the analysis of output from a computer code",
    journal = "Technometrics",
    volume = "21",
    number = "2",
    pages = "239--245",
    year = "1979",
    publisher = "Taylor \\& Francis"
}

(moose/modules/stochastic_tools/test/tests/samplers/latin_hypercube/latin_hypercube.i)

[StochasticTools]
[]

[Distributions]
  [a]
    type = Uniform
    lower_bound = 100
    upper_bound = 200
  []
  [b]
    type = Uniform
    lower_bound = 10
    upper_bound = 20
  []
[]

[Samplers]
  [sample]
    type = LatinHypercube
    distributions = 'a b'
    num_rows = 10
    seed = 1980
    execute_on = 'INITIAL TIMESTEP_END'
  []
[]

[VectorPostprocessors]
  [data]
    type = SamplerData
    sampler = sample
    sampler_method = get_global_samples
    execute_on = 'INITIAL TIMESTEP_END'
  []
[]

[Outputs]
  execute_on = 'INITIAL TIMESTEP_END'
  csv = true
[]

Overview
Example Input File Syntax
Input Parameters
References