cmp::sobol::SobolSaltelli Class Reference

Performs Global Sensitivity Analysis (GSA) using the Saltelli formulation of Sobol indices. More...

#include <sobol.h>

Public Member Functions
	SobolSaltelli ()=default
	Default constructor.
	SobolSaltelli (size_t nObs, size_t dim, bool secondOrder=false)
	Constructs a Sobol-Saltelli analyzer with the given configuration.
size_t	nTotalObs () const
	Gets the total number of evaluations required based on \( N \), \( d \), and analysis order.
size_t	dim () const
	Gets the number of dimension parameters \( d \).
size_t	nObs () const
	Gets the number of base samples \( N \).
Eigen::MatrixXd	evaluationGrid (size_t nObs, std::shared_ptr< cmp::grid::Grid > gridType, bool secondOrder=false)
	Constructs the Sobol evaluation grid using the Saltelli sampling scheme.
Eigen::VectorXd	sliceSaltelliOutput (const Eigen::VectorXd &Y, const Eigen::VectorXs &idx, size_t nObs, size_t dim, bool secondOrder)
	Slices the output vector Y from the Sobol evaluation grid to keep only valid or specified indices.
SobolResults	compute (const Eigen::VectorXd &Y)
	Computes Sobol indices from the output vector Y obtained by evaluating the Saltelli grid.
std::pair< SobolResults, SobolResults >	computeWithBootstrap (const Eigen::VectorXd &Y, size_t nBootstrap, size_t randomSeed=42)
	Computes Sobol indices with bootstrap resampling to estimate statistical confidence intervals.

Private Attributes
size_t	nObs_ = 0
	The number of base samples \( N \).
size_t	nTotalObs_ = 0
	The total number of evaluations required across all matrices.
size_t	dim_ = 0
	The dimensionality \( d \) of the input parameter space.
bool	secondOrder_ = false
	Flag indicating whether second-order indices should be computed.

Detailed Description

Performs Global Sensitivity Analysis (GSA) using the Saltelli formulation of Sobol indices.

Mathematical Foundations

Sobol sensitivity analysis decomposes the total variance \(V(Y)\) of a model \(Y = f(X_1, \dots, X_d)\) with independent inputs into contributions from individual inputs and their interactions:

\[ V(Y) = \sum_{i=1}^d V_i + \sum_{1 \le i < j \le d} V_{ij} + \dots + V_{1\dots d} \]

Where:

• First-Order Index (Main Effect): Measures the fractional variance contribution of input \(X_i\) alone:

  \[ S_i = \frac{V_i}{V(Y)} = \frac{\mathrm{Var}_{X_i}\left(\mathbb{E}_{\mathbf{X}_{\sim i}}[Y | X_i]\right)}{\mathrm{Var}(Y)} \]

• Second-Order Index (Interaction Effect): Measures the interaction effect of inputs \(X_i\) and \(X_j\):

  \[ S_{ij} = \frac{V_{ij}}{V(Y)} = \frac{\mathrm{Var}_{X_i, X_j}\left(\mathbb{E}_{\mathbf{X}_{\sim i,j}}[Y | X_i, X_j]\right) - V_i - V_j}{\mathrm{Var}(Y)} \]

• Total-Order Index: Measures the total effect of \(X_i\) including all its interactions:

  \[ S_{Ti} = 1 - \frac{\mathrm{Var}_{\mathbf{X}_{\sim i}}\left(\mathbb{E}_{X_i}[Y | \mathbf{X}_{\sim i}]\right)}{\mathrm{Var}(Y)} \]

Implementation Algorithms (Saltelli 2010 Scheme)

1. Grid Generation: We draw two independent sample matrices \(\mathbf{A}\) and \(\mathbf{B}\) of size \(N \times d\). We construct \(d\) hybrid matrices \(\mathbf{A}_B^i\) (where column \(i\) is from \(\mathbf{B}\), rest from \(\mathbf{A}\)) and \(d(d-1)/2\) hybrid matrices \(\mathbf{A}_B^{ij}\) (where columns \(i\) and \(j\) are from \(\mathbf{B}\), rest from \(\mathbf{A}\)).
2. Evaluation: Evaluate the model outputs: \(\mathbf{y}_A\), \(\mathbf{y}_B\), \(\mathbf{y}_{AB}^i\), and \(\mathbf{y}_{AB}^{ij}\).
3. Estimator Formulations:

• First-Order:

  \[ S_i = \frac{\frac{1}{N} \sum_{k=1}^N y_B^{(k)} (y_{AB}^{(i)(k)} - y_A^{(k)})}{\mathrm{Var}(Y)} \]

• Total-Order:

  \[ S_{Ti} = \frac{\frac{1}{2N} \sum_{k=1}^N (y_A^{(k)} - y_{AB}^{(i)(k)})^2}{\mathrm{Var}(Y)} \]

Constraints & Invariants

• Sample Independence: The input matrices \(\mathbf{A}\) and \(\mathbf{B}\) must be statistically independent.
• Computational Complexity: The number of model evaluations required is \(N(d + 2)\) for first and total order, and \(N(2d + 2 + d(d-1)/2)\) if second-order interaction indices are requested.

Constructor & Destructor Documentation

SobolSaltelli() [1/2]

cmp::sobol::SobolSaltelli::SobolSaltelli ( )

default

Default constructor.

SobolSaltelli() [2/2]

cmp::sobol::SobolSaltelli::SobolSaltelli ( size_t  nObs, size_t  dim, bool  secondOrder = false  )

inline

Constructs a Sobol-Saltelli analyzer with the given configuration.

Parameters

nObs	The number of base observations \( N \) (size of matrices A and B).
dim	The dimensionality \( d \) of the input space.
secondOrder	Boolean flag to enable computation of second-order interaction indices.

Member Function Documentation

compute()

cmp::sobol::SobolResults cmp::sobol::SobolSaltelli::compute

(

const Eigen::VectorXd &

Y

)

Computes Sobol indices from the output vector Y obtained by evaluating the Saltelli grid.

Parameters

Y	The output vector evaluating the full Saltelli grid sequence.

Returns

A SobolResults struct containing the estimated first-order, total-order, and optionally second-order indices.

computeWithBootstrap()

std::pair< cmp::sobol::SobolResults, cmp::sobol::SobolResults > cmp::sobol::SobolSaltelli::computeWithBootstrap	(	const Eigen::VectorXd &	Y,
		size_t	nBootstrap,
		size_t	randomSeed = 42
	)

Computes Sobol indices with bootstrap resampling to estimate statistical confidence intervals.

• Resamples the \( N \) base block sequences with replacement to construct an empirical distribution of the sensitivity indices.

• Parameters

  Y	The output vector evaluating the full Saltelli grid sequence.
  nBootstrap	Number of bootstrap resampling iterations.
  randomSeed	Seed for the internal random number generator (default is 42).

  Returns

  A std::pair of SobolResults. The first element contains the mean parameter estimates, and the second element contains the standard deviations (standard error) of the bootstrap samples.

dim()

size_t cmp::sobol::SobolSaltelli::dim ( ) const

inline

Gets the number of dimension parameters \( d \).

Returns

The dimensionality of the input space.

evaluationGrid()

Eigen::MatrixXd cmp::sobol::SobolSaltelli::evaluationGrid	(	size_t	nObs,
		std::shared_ptr< cmp::grid::Grid >	gridType,
		bool	secondOrder = false
	)

Constructs the Sobol evaluation grid using the Saltelli sampling scheme.

Parameters

nObs	The number of observations \( N \) (size of A and B matrices).
gridType	A shared pointer to a Grid object that defines the sampling strategy (e.g., Random, Latin Hypercube).
secondOrder	Whether to construct hybrid grids for second-order indices.

Returns

An Eigen::MatrixXd containing the evaluation grid with size \([(2 + d + d(d-1)/2) \times N, d]\) if secondOrder is true, otherwise \([(2 + d) \times N, d]\).

nObs()

size_t cmp::sobol::SobolSaltelli::nObs ( ) const

inline

Gets the number of base samples \( N \).

Returns

The number of base samples.

nTotalObs()

size_t cmp::sobol::SobolSaltelli::nTotalObs ( ) const

inline

Gets the total number of evaluations required based on \( N \), \( d \), and analysis order.

Returns

The total evaluation count.

sliceSaltelliOutput()

Eigen::VectorXd cmp::sobol::SobolSaltelli::sliceSaltelliOutput	(	const Eigen::VectorXd &	Y,
		const Eigen::VectorXs &	idx,
		size_t	nObs,
		size_t	dim,
		bool	secondOrder
	)

Slices the output vector Y from the Sobol evaluation grid to keep only valid or specified indices.

• Useful for handling simulations that failed or returned invalid data. It safely trims the outputs while preserving the structured blocks of the Saltelli design matrix needed for index estimation.

• Parameters

  Y	The raw output vector from the Sobol evaluation grid.
  idx	The indices of the valid observations to keep.
  nObs	The number of base observations \( N \).
  dim	The dimensionality of the input space \( d \).
  secondOrder	Whether second-order evaluations were included in Y.

  Returns

  A sliced output vector containing only the specified valid outputs.

Member Data Documentation

dim_

size_t cmp::sobol::SobolSaltelli::dim_ = 0

private

The dimensionality \( d \) of the input parameter space.

nObs_

size_t cmp::sobol::SobolSaltelli::nObs_ = 0

private

The number of base samples \( N \).

nTotalObs_

size_t cmp::sobol::SobolSaltelli::nTotalObs_ = 0

private

The total number of evaluations required across all matrices.

secondOrder_

bool cmp::sobol::SobolSaltelli::secondOrder_ = false

private

Flag indicating whether second-order indices should be computed.

---

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

• include/sobol.h
• src/sobol.cpp