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 XkX_k has all portions of its distribution represented by input values, we can divide the range of each XkX_k into NN strata of equal marginal probability l/Nl/N, and sample once from each stratum. Let this sample be Xkj,j=l,,NX_{kj},\,j=l,\ldots,N. These form the XkX_k, component, k=l,,Kk=l,\ldots,K, in Xi,i=1,,NX_i,\,i = 1,\ldots,N. The components of the various XkX_k'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]
  [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'
  []
[]
(contrib/moose/modules/stochastic_tools/test/tests/samplers/latin_hypercube/latin_hypercube.i)

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.

1001101201301401501601701801902001011121314151617181920
Uniform "a" (100,200)Uniform "b" (10,20)

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>

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

    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.

  • 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

References

  1. 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.[BibTeX]