Polynomial Chaos Expansions¶

Introduction¶

In their most basic use, polynomial chaos expansions (PCE) create an emulator for a quantity that depends on a random variable. For simplicity, we will assume that this random variable is finite-dimensional. Let \(\xi\) denote a \(d\)-dimensional random variable. For some function \(f: \mathbb{R}^d \rightarrow \mathbb{R}\), the PCE approach performs the approximation,

(1)¶\[f(\xi) \approx f_N(\xi) := \sum_{n=1}^N \hat{f}_n \phi_n(\xi),\]

where \(\{\phi_n\}_{n=1}^\infty\) are polynomial functions of the random variable \(\xi\), and \(\{hat{f}_n\}_{n=1}^\infty\) are coefficients. If such an emulator can be constructed, then statistics are evaluated as statistics of the emulator.

For example, the (approximation to the) mean is

(2)¶\[\mathbb{E} f(\xi) \approx \sum_{n=1}^N \hat{f}_n \mathbb{E}[\phi_n(\xi)],\]

which can be efficiently evaluated by manipulation of the coefficients \(\hat{f}_n\). The terms \(\mathbb{E}[\phi_n(\xi)]\) can be evaluated exactly using properties of the \(\phi_n\) polynomials.

All of the above extends to the case when the function \(f\) depends on other variables, such as space \(x\) or time \(t\). For example, if \(f = f(x,t,\xi)\), then the PCE approach becomes

\[f(x,t,\xi) \approx f_N(x,t,\xi) := \sum_{n=1}^N \hat{f}_n(x,t) \phi_n(\xi),\]

so that the coefficients depend on \((x,t)\). Then the space- and time-varying expectation can be evaluated in a manner similar to (2).

For PCE approaches, most of the computation involves computing the coefficients \(\{\hat{f}_n\}_{n=1}^\infty\). Non-intrusive PCE strategies accomplish this by computing values of \(f\) on a specific sampling grid or experimental design in stochastic space: \(\{\xi_m\}_{m=1}^M\). The procedures used in UncertainSCI typically require the number of samples \(M\) to scale with the degrees of freedom in the emulator \(N\).

In order to utilize the PCE approaches in UncertainSCI, two items must be provided:

The distribution of the random variable \(\xi\). See Distributions for how to generate this distribution.
The type of polynomial functions in (1). This amounts to defining a particular polynomial subspace. See Polynomial Spaces for how to generate this subspace.

PolynomialChaosExpansion¶

class UncertainSCI.pce.PolynomialChaosExpansion(index_set=None, distribution=None, order=None, plabels=None, sampling='greedy-induced', training='wlsq', **kwargs)¶

Base polynomial chaos expansion class.

Provides interface to construct and manipulate polynomial chaos expansions.

Attributes:¶

coefficients: A numpy array of polynomial chaos expansion coefficients. indices: A MultiIndexSet instance specifying the polynomial

approximation space.

distribution: A ProbabilityDistribution instance indicating the
distribution of the random variable.

samples: The experimental or sample design in stochastic space.

adapt_expressivity(max_new_samples=10, **chase_bulk_options)¶: Adapts the PCE approximation by increasing expressivity. (Intended to combat residual error.)

adapt_robustness(max_new_samples=10, verbosity=1)¶: Adapts the PCE approximation by increasing robustness. (Intended to combat cross-validation error.)

assert_pce_built()¶

augment_samples_idist(K, weights=None, fast_sampler=True)¶: Augments random samples from induced distribution. Typically done via an adaptive refinement procedure. As such some inputs can be given to customize how the samples are drawn in the context of adaptivity:

K: how many samples to add (required) weights: a discrete probability distribution on

self.index_set.get_indices() that describes how the induced distrubtion is sampled. Default is uniform.

build(model=None, model_output=None, **options)¶

Builds PCE from sampling and approximation settings.

Parameters:

model – A pointer to a function with the syntax xi —> model(xi), which returns a vector corresponding to the model evaluated at the stochastic parameter value xi. The input xi to the model function should be a vector of size self.dim, and the output should be a 1D numpy array. If model_output is None, this is required. If model_output is given, this is ignored.
model_output – A numpy.ndarray corresponding to the output of the model at the sample locations specified by self.samples. This is required if the input model is None.

Return type:

None

build_pce_wlsq()¶: Performs a (weighted) least squares PCE surrogate using saved samples and model output.

chase_bulk(delta=0.5, max_new_samples=None, max_new_indices=None, add_rule=None, mult_rule=None, verbosity=1)¶

Performs adaptive bulk chasing, which (i) adds the most “important” indices to the polynomial index set, (ii) takes more samples, (iii) updates the PCE approximation, including statistics and error metrics.

Parameters:

max_new_samples (int) – Maximum number of new samples to add. Defaults to None.
max_new_indices (int) – Maximum number of new PCE indices to add. Defaults to None.
add_rule (int) – Specifies number of samples added as a function of number of added indices. Nsamples = Nindices + add_rule. Defaults to None.
mult_rule (float) – Specifies number of samples added as a function of number of added indices. Nsamples = int(Nindices * add_rule). Defaults to None.

check_distribution()¶

check_indices()¶

check_sampling()¶: Determines if a valid sampling type has been specified.

check_training()¶: Determines if a valid training type has been specified.

christoffel_weights()¶: Generates sample weights associated to Christoffel preconditioning.

eval(p, components=None)¶

Evaluates the PCE at particular parameter locations.

Parameters:

p – An array (satisfying p.shape[1]==self.dim) containing a set of parameter points at which to evaluate the PCE prediction.
components – An array of non-negative integers specifying which indices in the model output to compute. Other indices are ignored. If given as None (default), then all components are computed.

Returns:

An array containing evaluations (predictions) from the PCE emulator. If the input components is None, this array is of size ( self.p.shape[0] x self.coefficients.shape[1] ). Otherwise, the second dimension is of size components.size.

Return type:

numpy.ndarray

generate_samples(**kwargs)¶

Generates sample/experimental design for use in PCE construction.

Parameters:: new_samples (array-like, optional) – Specifies samples that must be part of the ensemble.

global_derivative_sensitivity(dim_list)¶

Computes global derivative-based sensitivity indices. For a PCE with respect to a \(d\)-dimensional random variable \(Z\), then this senstivity index along dimension \(i\) is defined as

\[S_i \colon = E \left[ p(Z) \right] = \int p(z) \omega(z) d z,\]

where \(E[\cdot]\) it expectation operator, \(p\) is the PCE emulator, and \(\omega\) is the probability density function for the random variable \(Z\).

These sensitivity indices measure the average rate-of-change of the PCE response with respect to dimension \(i\).

Parameters:

dim_lists – A list-type iterable with D entries, containing dimensional indices in 0-based indexing. All entries must be between 0 and self.distribution.dim.

Returns:

DxK array, where each row corresponds to the sensitivity index: \(S_i\) across all K features of the PCE model.

Return type:

S

global_sensitivity(dim_lists=None, interaction_orders=None, vartol=1e-16)¶

Computes global sensitivity associated to dimensional indices dim_lists from PCE coefficients.

dim_lists should be a list of index lists. The global sensitivity for each index list is returned.

interaction_orders (list): Computes sensitivities corresponding to variable interactions for the specified orders. E.g., order 2 implies binary interactions, 3 is ternary interactions, [2,3] computes both of these orders.

The output is len(dim_lists) x self.coefficients.shape[1]

identify_bulk(delta=0.5)¶: Performs (adaptive) bulk chasing for refining polynomial spaces. Returns the indices associated with a delta-bulk of a OMP-type indicator.

integration_weights()¶: Generates sample weights associated to integration.

map_to_model_space(p)¶

Maps parameter values from standard space to model space.

Parameters:: p (array-like) – Samples in standard space.
Returns:: Samples in model space
Return type:: q (numpy.ndarray)

map_to_standard_space(q)¶

Maps parameter values from model space to standard space.

Parameters:: q (array-like) – Samples in model space.
Returns:: Samples in standard space
Return type:: p (numpy.ndarray)

mean()¶

Returns PCE mean.

Returns:

A vector containing the PCE mean, of size equal to the size: of the vector of the model output.

Return type:

numpy.ndarray

pce_eval(p, components=None)¶

Evaluates the PCE at particular parameter locations.

Parameters:

p – An array (satisfying p.shape[1]==self.dim) containing a set of parameter points at which to evaluate the PCE prediction.
components – An array of non-negative integers specifying which indices in the model output to compute. Other indices are ignored. If given as None (default), then all components are computed.

Returns:

An array containing evaluations (predictions) from the PCE emulator. If the input components is None, this array is of size ( self.p.shape[0] x self.coefficients.shape[1] ). Otherwise, the second dimension is of size components.size.

Return type:

numpy.ndarray

quantile(q, M=100)¶: Computes q-quantiles using M-point Monte Carlo sampling.

set_distribution(distribution)¶

Sets type of probability distribution of random variable.

Parameters:: distribution – A ProbabilityDistribution instance specifying the distribution of the random variable.
Return type:: None

set_indices(index_set)¶

Sets multi-index set for polynomial approximation.

Parameters:: indices – A MultiIndexSet instance specifying the polynomial approximation space.
Return type:: None

set_samples(samples)¶

set_weights()¶: Sets weights based on assigned samples.

stdev()¶

Returns PCE standard deviation

Returns:

A vector containing the PCE standard deviation, of size: equal to the size of the vector of the model output.

Return type:

numpy.ndarray

total_sensitivity(dim_indices=None, vartol=1e-16)¶

Computes total sensitivity associated to dimensions dim_indices from PCE coefficients. dim_indices should be a list-type containing dimension indices.

The output is len(js) x self.coefficients.shape[1]