Implements Latin Hypercube Sampling (LHS) over a set of distributions. More...

#include <LatinHypercubeSampler.h>

Inheritance diagram for LatinHypercubeSampler:

Public Types
enum	SampleMode { SampleMode::GLOBAL, SampleMode::LOCAL }

typedef DataFileName	DataFileParameterType

Public Member Functions
	LatinHypercubeSampler (const InputParameters &parameters)

std::vector< Real >	getNextLocalRow ()

dof_id_type	getNumberOfRows () const

dof_id_type	getNumberOfCols () const

dof_id_type	getNumberOfLocalRows () const

const LocalRankConfig &	getRankConfig (bool batch_mode) const

virtual bool	isAdaptiveSamplingCompleted () const

libMesh::Parallel::Communicator &	getLocalComm ()

virtual bool	enabled () const

std::shared_ptr< MooseObject >	getSharedPtr ()

std::shared_ptr< const MooseObject >	getSharedPtr () const

bool	isKokkosObject () const

MooseApp &	getMooseApp () const

const std::string &	type () const

const std::string &	name () const

std::string	typeAndName () const

MooseObjectParameterName	uniqueParameterName (const std::string &parameter_name) const

MooseObjectName	uniqueName () const

const InputParameters &	parameters () const

const hit::Node *	getHitNode () const

bool	hasBase () const

const std::string &	getBase () const

const T &	getParam (const std::string &name) const

std::vector< std::pair< T1, T2 > >	getParam (const std::string &param1, const std::string &param2) const

const T *	queryParam (const std::string &name) const

const T &	getRenamedParam (const std::string &old_name, const std::string &new_name) const

T	getCheckedPointerParam (const std::string &name, const std::string &error_string="") const

bool	haveParameter (const std::string &name) const

bool	isParamValid (const std::string &name) const

bool	isParamSetByUser (const std::string &name) const

void	connectControllableParams (const std::string &parameter, const std::string &object_type, const std::string &object_name, const std::string &object_parameter) const

void	paramError (const std::string &param, Args... args) const

void	paramWarning (const std::string &param, Args... args) const

void	paramWarning (const std::string &param, Args... args) const

void	paramInfo (const std::string &param, Args... args) const

std::string	messagePrefix (const bool hit_prefix=true) const

std::string	errorPrefix (const std::string &) const

void	mooseError (Args &&... args) const

void	mooseDocumentedError (const std::string &repo_name, const unsigned int issue_num, Args &&... args) const

void	mooseErrorNonPrefixed (Args &&... args) const

void	mooseWarning (Args &&... args) const

void	mooseWarning (Args &&... args) const

void	mooseWarningNonPrefixed (Args &&... args) const

void	mooseWarningNonPrefixed (Args &&... args) const

void	mooseDeprecated (Args &&... args) const

void	mooseDeprecated (Args &&... args) const

void	mooseDeprecatedNoTrace (Args &&... args) const

void	mooseInfo (Args &&... args) const

void	callMooseError (std::string msg, const bool with_prefix, const hit::Node *node=nullptr, const bool show_trace=true) const

std::string	getDataFileName (const std::string &param) const

std::string	getDataFileNameByName (const std::string &relative_path) const

std::string	getDataFilePath (const std::string &relative_path) const

virtual void	initialSetup ()

virtual void	timestepSetup ()

virtual void	jacobianSetup ()

virtual void	residualSetup ()

virtual void	subdomainSetup ()

virtual void	customSetup (const ExecFlagType &)

const ExecFlagEnum &	getExecuteOnEnum () const

PerfGraph &	perfGraph ()

T &	getSampler (const std::string &name)

Sampler &	getSampler (const std::string &name)

T &	getSamplerByName (const SamplerName &name)

Sampler &	getSamplerByName (const SamplerName &name)

const VectorPostprocessorValue &	getVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name, bool needs_broadcast) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name) const

bool	hasVectorPostprocessor (const std::string &param_name, const std::string &vector_name) const

bool	hasVectorPostprocessor (const std::string &param_name) const

bool	hasVectorPostprocessorByName (const VectorPostprocessorName &name, const std::string &vector_name) const

bool	hasVectorPostprocessorByName (const VectorPostprocessorName &name) const

const VectorPostprocessorName &	getVectorPostprocessorName (const std::string &param_name) const

DenseMatrix< Real >	getGlobalSamples ()

DenseMatrix< Real >	getGlobalSamples ()

DenseMatrix< Real >	getLocalSamples ()

DenseMatrix< Real >	getLocalSamples ()

dof_id_type	getLocalRowBegin () const

dof_id_type	getLocalRowBegin () const

dof_id_type	getLocalRowEnd () const

dof_id_type	getLocalRowEnd () const

const Distribution &	getDistribution (const std::string &name) const

const T &	getDistribution (const std::string &name) const

const Distribution &	getDistribution (const std::string &name) const

const T &	getDistribution (const std::string &name) const

const Distribution &	getDistributionByName (const DistributionName &name) const

const T &	getDistributionByName (const std::string &name) const

const Distribution &	getDistributionByName (const DistributionName &name) const

const T &	getDistributionByName (const std::string &name) const

bool	isVectorPostprocessorDistributed (const std::string &param_name) const

bool	isVectorPostprocessorDistributed (const std::string &param_name) const

bool	isVectorPostprocessorDistributedByName (const VectorPostprocessorName &name) const

bool	isVectorPostprocessorDistributedByName (const VectorPostprocessorName &name) const

const Parallel::Communicator &	comm () const

processor_id_type	n_processors () const

processor_id_type	processor_id () const

Static Public Member Functions
static InputParameters	validParams ()

static void	callMooseError (MooseApp const app, const InputParameters &params, std::string msg, const bool with_prefix, const hit::Node node, const bool show_trace=true)

Public Attributes
	usingCombinedWarningSolutionWarnings

const ConsoleStream	_console

Static Public Attributes
static const std::string	type_param

static const std::string	name_param

static const std::string	unique_name_param

static const std::string	app_param

static const std::string	moose_base_param

static const std::string	kokkos_object_param

Protected Member Functions
virtual void	executeTearDown () override
	Constructs one MooseRandomPerturbation per column, each seeded independently from generator 1. More...

virtual Real	computeSample (dof_id_type row_index, dof_id_type col_index) override
	Return the sample value for the given row and column. More...

void	setNumberOfRandomSeeds (std::size_t number)

Real	getRand (std::size_t n, unsigned int index=0) const

unsigned int	getRandl (std::size_t n, unsigned int lower, unsigned int upper, unsigned int index=0) const

virtual LocalRankConfig	constructRankConfig (bool batch_mode) const

void	flagInvalidSolutionInternal (const InvalidSolutionID invalid_solution_id) const

InvalidSolutionID	registerInvalidSolutionInternal (const std::string &message, const bool warning) const

PerfID	registerTimedSection (const std::string &section_name, const unsigned int level) const

PerfID	registerTimedSection (const std::string &section_name, const unsigned int level, const std::string &live_message, const bool print_dots=true) const

std::string	timedSectionName (const std::string &section_name) const

virtual void	addVectorPostprocessorDependencyHelper (const VectorPostprocessorName &) const

const ReporterContextBase &	getReporterContextBaseByName (const ReporterName &reporter_name) const

const ReporterName &	getReporterName (const std::string &param_name) const

virtual void	addReporterDependencyHelper (const ReporterName &)

void	setNumberOfRows (dof_id_type n_rows)

void	setNumberOfRows (dof_id_type n_rows)

void	setNumberOfCols (dof_id_type n_cols)

void	setNumberOfCols (dof_id_type n_cols)

virtual void	computeSampleMatrix (DenseMatrix< Real > &matrix)

virtual void	computeSampleMatrix (DenseMatrix< Real > &matrix)

virtual void	computeLocalSampleMatrix (DenseMatrix< Real > &matrix)

virtual void	computeLocalSampleMatrix (DenseMatrix< Real > &matrix)

virtual void	computeSampleRow (dof_id_type i, std::vector< Real > &data)

virtual void	computeSampleRow (dof_id_type i, std::vector< Real > &data)

virtual void	advanceGenerators (const dof_id_type count)

virtual void	advanceGenerators (const dof_id_type count)

virtual void	advanceGenerator (const unsigned int seed_index, const dof_id_type count)

virtual void	advanceGenerator (const unsigned int seed_index, const dof_id_type count)

void	setAutoAdvanceGenerators (const bool state)

void	setAutoAdvanceGenerators (const bool state)

virtual void	executeSetUp ()

virtual void	executeSetUp ()

const T &	getReporterValue (const std::string &param_name, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, ReporterMode mode, const std::size_t time_index=0)

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

Protected Attributes
std::vector< Distribution const * >	_distributions
	Distribution objects, one per column, whose quantile functions are sampled. More...

std::vector< std::unique_ptr< MooseRandomPerturbation > >	_shufflers
	Per-column pseudo-random permuters that enforce the LHS bin assignment. More...

const dof_id_type	_min_procs_per_row

const dof_id_type	_max_procs_per_row

libMesh::Parallel::Communicator	_local_comm

const bool &	_enabled

MooseApp &	_app

Factory &	_factory

ActionFactory &	_action_factory

const std::string &	_type

const std::string &	_name

const InputParameters &	_pars

const ExecFlagEnum &	_execute_enum

const ExecFlagType &	_current_execute_flag

MooseApp &	_pg_moose_app

const std::string	_prefix

const Parallel::Communicator &	_communicator

Detailed Description

Implements Latin Hypercube Sampling (LHS) over a set of distributions.

For N samples and K distributions the output matrix has N rows and K columns. LHS divides the [0,1] probability axis into N equal-width bins and ensures that exactly one sample falls in each bin for every column. Within each bin the sample point is drawn uniformly at random, and the bin assignment for each column is an independent pseudo-random permutation of [0, N) seeded from generator 1 during executeSetUp().

Generator usage:

Generator 0: within-bin uniform draws (one per computeSample call).
Generator 1: column shuffler seeds (one per column, drawn in executeSetUp).

Definition at line 31 of file LatinHypercubeSampler.h.

Constructor & Destructor Documentation

◆ LatinHypercubeSampler()

LatinHypercubeSampler::LatinHypercubeSampler ( const InputParameters & parameters )

Definition at line 29 of file LatinHypercubeSampler.C.

   : Sampler(parameters)
 {
   const auto & distribution_names = getParam<std::vector<DistributionName>>("distributions");
   for (const DistributionName & name : distribution_names)
     _distributions.push_back(&getDistributionByName(name));
 
   setNumberOfRows(getParam<dof_id_type>("num_rows"));
   setNumberOfCols(distribution_names.size());
   // Generator 0: within-bin uniform draws. Generator 1: column shuffler seeds.
   setNumberOfRandomSeeds(2);
 }

Member Function Documentation

◆ computeSample()

Real LatinHypercubeSampler::computeSample	(	dof_id_type	row_index,
		dof_id_type	col_index
	)

overrideprotectedvirtual

Return the sample value for the given row and column.

Maps row_index to a shuffled bin index via the column's permuter, draws a uniform random point within that bin, then transforms it through the column distribution's quantile function.

Parameters

row_index	Global row index in [0, getNumberOfRows()).
col_index	Column index in [0, getNumberOfCols()).

Returns: A sample drawn from distributions[col_index] respecting the LHS bin constraint for this row.

Implements Sampler.

Definition at line 54 of file LatinHypercubeSampler.C.

 {
   mooseAssert(_shufflers.size() > 0, "Shufflers have not been initialized.");
 
   // Divide [0,1] into N equal bins of width 1/N.
   const Real bin_size = 1. / getNumberOfRows();
 
   // Map row_index to a shuffled bin via the column's bijective permutation.
   // Because permute() is a bijection on [0, N), each row gets a distinct bin,
   // which is the core LHS stratification guarantee.
   const auto bin = _shufflers[col_index]->permute(row_index);
 
   // Draw a uniform random point within the selected bin.
   const auto lower = bin * bin_size;
   const auto upper = (bin + 1) * bin_size;
   const Real probability =
       getRand(row_index * getNumberOfCols() + col_index) * (upper - lower) + lower;
 
   // Transform the probability through the inverse CDF to obtain the sample value.
   return _distributions[col_index]->quantile(probability);
 }

◆ executeTearDown()

void LatinHypercubeSampler::executeTearDown ( )

overrideprotectedvirtual

Constructs one MooseRandomPerturbation per column, each seeded independently from generator 1.

Reimplemented from Sampler.

Definition at line 43 of file LatinHypercubeSampler.C.

 {
   _shufflers.clear();
   for (const auto col : make_range(getNumberOfCols()))
   {
     const auto seed = getRandl(col, 0, std::numeric_limits<uint32_t>::max(), 1);
     _shufflers.push_back(std::make_unique<MooseRandomPerturbation>(seed, getNumberOfRows()));
   }
 }

◆ validParams()

InputParameters LatinHypercubeSampler::validParams ( )

static

Definition at line 17 of file LatinHypercubeSampler.C.

 {
   InputParameters params = Sampler::validParams();
   params.addClassDescription("Latin Hypercube Sampler.");
   params.addRequiredParam<dof_id_type>("num_rows", "The size of the square matrix to generate.");
   params.addRequiredParam<std::vector<DistributionName>>(
       "distributions",
       "The distribution names to be sampled, the number of distributions provided defines the "
       "number of columns per matrix.");
   return params;
 }

Member Data Documentation

◆ _distributions

std::vector<Distribution const *> LatinHypercubeSampler::_distributions

protected

Distribution objects, one per column, whose quantile functions are sampled.

Definition at line 60 of file LatinHypercubeSampler.h.

Referenced by computeSample(), and LatinHypercubeSampler().

◆ _shufflers

std::vector<std::unique_ptr<MooseRandomPerturbation> > LatinHypercubeSampler::_shufflers

protected

Per-column pseudo-random permuters that enforce the LHS bin assignment.

Definition at line 62 of file LatinHypercubeSampler.h.

Referenced by computeSample(), and executeTearDown().

The documentation for this class was generated from the following files:

stochastic_tools/include/samplers/LatinHypercubeSampler.h
stochastic_tools/src/samplers/LatinHypercubeSampler.C

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes