FieldToPointFunctionalChaosAlgorithm¶

class FieldToPointFunctionalChaosAlgorithm(*args)¶

Functional metamodel algorithm based on chaos decomposition.

Warning

This class is experimental and likely to be modified in future releases. To use it, import the openturns.experimental submodule.

The present algorithm allows to build a response surface of the application $h$ of the form:

$h: \left| \begin{array}{ccl} \cM_N \times (\Rset^d)^N & \rightarrow & \Rset^p \\ \mat{X} & \mapsto & \vect{Y} \end{array} \right.$

The application $h$ is known from $n$ fields $(\mat{X_1}, \dots, \mat{X_n})$ of the associated input process $\mat{X}$ and $n$ vectors $(\vect{Y_1},\dots,\vect{Y_n})$ that fully characterize the output vector $\vect{Y}$

The linear projection function $\pi_{ \vect{\lambda}, \vect{\varphi}}$ of the Karhunen-Loeve decomposition by SVD is used to project the input fields, see KarhunenLoeveSVDAlgorithm and KarhunenLoeveAlgorithm for the notations.

$\pi_{\vect{\lambda}, \vect{\varphi}}: \left| \begin{array}{ccl} L^2(\cD, \Rset^d) & \rightarrow & \cS^{\Nset} \\ f & \mapsto &\left(\dfrac{1}{\sqrt{\lambda_k}}\int_{\cD}f(\vect{t}) \vect{\varphi}_k(\vect{t})\, d\vect{t}\right)_{k \geq 1} \end{array} \right.$

The Karhunen-Loeve algorithm allows to replace this integral by a specific weighted and finite sum and to write the projections of the j-th marginal of i-th input field $\vect{X_i^j}$ by multiplication with the projection matrix $\mat{M^j} \in \Rset^{K_j} \times \Rset^{Nd}$ :

$\mat{M_j} \vect{X_i^j} = \left( \begin{array}{l} \xi_1^j \\ \dots \\ \xi_{K_j}^j \end{array} \right) \in \Rset^{K_j}, \forall i \in [1, n], \forall j \in [1, d]$

with $K_j$ the retained number of modes in the decomposition of the j-th input. The projections of all the $d$ components of $n$ fields are assembled in the $Q$ matrix:

$\begin{align*} \mat{Q} = \mat{M} \mat{X} = \left( \begin{array}{l} \mat{M_1} \mat{X^1} \\ \dots \\ \mat{M_d} \mat{X^d} \end{array} \right) \in \Rset^{K_T} \times \Rset^n \end{align*}$

with $K_T = \sum_{j=1}^d{K_j}$ the total number of modes across input components.

Then a functional chaos decomposition is built between the projected modes sample $\mat{Q}$ and the output samples $\mat{Y}$ , see FunctionalChaosAlgorithm for details.

$\tilde{g}(x) = \sum_{k=1}^{K_c} \beta_{\vect{\alpha}_k} \Psi_{\vect{\alpha}_k}(x)$

with $K_c$ the number of terms in the chaos decomposition.

The final metamodel consists in the composition of the Karhunen-Loeve projections and the functional chaos metamodel.

$\tilde{h}: \left| \begin{array}{ccccl} \cM_N \times (\Rset^d)^N & \rightarrow & \Rset^{K_T} & \rightarrow & \Rset^p \\ \mat{X} & \mapsto & \vect{Q} & \mapsto & \vect{Y} \end{array} \right.$

A limitation of this approach is that the projected modes sample has a dimension $K_T$ so the dimension of the input fields $\mat{X_i}$ and the associated number of modes must remain modest (curse of dimensionality).

Parameters:

xProcessSample: Input process sample.
ySample: Output sample.

See also

FieldFunctionalChaosSobolIndices, KarhunenLoeveAlgorithm, FunctionalChaosAlgorithm

Notes

As the input process decomposition is done with the values decomposition approach, it is possible to control the number of modes retained per input, the idea being to avoid a large input dimension for the chaos decomposition step. As done in KarhunenLoeveSVDAlgorithm, the setThreshold() and setNbModes() methods allow to control the spectrum ratio and maximum count.

By default the input process data is assumed to not be centered, and the method setCenteredSample() allows to skip centering of the data for both the computation of modes coefficients and inside the metamodel.

In the case of homogenous data (if variables have the same unit or scale), it is also possible to recompress the modes at the global level with setRecompress(). When enabled, the eigenvalues are gathered and sorted so as to find a global spectrum cut-off value by which the spectrum of each input is truncated. The default value can be set through the ResourceMap key FieldToPointFunctionalChaosAlgorithm-DefaultRecompress.

For the chaos metamodel step, it is possible to specify the basis size with the ResourceMap key FunctionalChaosAlgorithm-BasisSize.

It is possible to group input variables by independent blocks with setBlockIndices(), this way Karhunen-Loeve process decompositions are done on each block rather than on each variable thus reducing the total number of modes and help reduce the chaos input dimension.

Examples

>>> import openturns as ot
>>> import openturns.experimental as otexp
>>> ot.RandomGenerator.SetSeed(0)
>>> mesh = ot.RegularGrid(0.0, 0.1, 20)
>>> cov = ot.KroneckerCovarianceModel(ot.MaternModel([2.0], 1.5), ot.CovarianceMatrix(4))
>>> X = ot.GaussianProcess(cov, mesh)
>>> x = X.getSample(500)
>>> y = [[m[0] + m[1] + m[2] - m[3] + m[0] * m[1] - m[2] * m[3] - 0.1 * m[0] * m[1] * m[2]] for m in [xi.computeMean() for xi in x]]
>>> algo = otexp.FieldToPointFunctionalChaosAlgorithm(x, y)
>>> algo.setThreshold(4e-2)
>>> # Temporarily lower the basis size for the sake of this example.
>>> # We need to store the original size.
>>> bs = ot.ResourceMap.GetAsUnsignedInteger('FunctionalChaosAlgorithm-BasisSize')
>>> ot.ResourceMap.SetAsUnsignedInteger('FunctionalChaosAlgorithm-BasisSize', 100)
>>> algo.run()
>>> # The algorithm has been run with the lower basis size:
>>> # we can now restore the original value.
>>> ot.ResourceMap.SetAsUnsignedInteger('FunctionalChaosAlgorithm-BasisSize', bs)
>>> result = algo.getResult()
>>> metamodel = result.getFieldToPointMetamodel()
>>> y0hat = metamodel(x[0])

Methods

`BuildDistribution`(modesSample)	Build the distribution of Karhunen-Loeve coefficients.
`getBlockIndices`()	Accessor to the block indices.
`getCenteredSample`()	Accessor to centered sample flag.
`getClassName`()	Accessor to the object's name.
`getId`()	Accessor to the object's id.
`getInputProcessSample`()	Accessor to the input sample.
`getName`()	Accessor to the object's name.
`getNbModes`()	Accessor to the maximum number of modes to compute.
`getOutputSample`()	Accessor to the output sample.
`getRecompress`()	Accessor to the recompression flag.
`getResult`()	Result accessor.
`getShadowedId`()	Accessor to the object's shadowed id.
`getThreshold`()	Accessor to the eigenvalues cutoff ratio.
`getVisibility`()	Accessor to the object's visibility state.
`hasName`()	Test if the object is named.
`hasVisibleName`()	Test if the object has a distinguishable name.
`run`()	Compute the response surfaces.
`setBlockIndices`(blockIndices)	Accessor to the block indices.
`setCenteredSample`(centered)	Accessor to centered sample flag.
`setName`(name)	Accessor to the object's name.
`setNbModes`(nbModes)	Accessor to the maximum number of modes to compute.
`setRecompress`(recompress)	Accessor to the recompression flag.
`setShadowedId`(id)	Accessor to the object's shadowed id.
`setThreshold`(threshold)	Accessor to the eigenvalues cutoff ratio.
`setVisibility`(visible)	Accessor to the object's visibility state.

__init__(*args)¶

static BuildDistribution(modesSample)¶

Build the distribution of Karhunen-Loeve coefficients.

This method aims at building a possibly parametric representation of Karhunen-Loeve coefficients based on their Gaussian or independent theorical properties in order to build efficient metamodels. When this is not possible it falls back to non-parametric representations for the marginals and the dependence structure.

Parameters:

modesSampleSample: Karhunen-Loeve modes sample.

Returns:

distributionDistribution: Distribution of coefficients.

Notes

The strategy for marginals is to test for a Normal hypothesis via the CramerVonMisesNormal() test, else fallback to Histogram.

For the dependence structure it tests for an IndependentCopula thanks to the Spearman() test, else fallback to the Normal or Beta copula (see EmpiricalBernsteinCopula) according to the ResourceMap key FieldToPointFunctionalChaosAlgorithm-CopulaType.

getBlockIndices()¶

Accessor to the block indices.

Returns:

blockIndicesIndicesCollection: Independent components indices.

getCenteredSample()¶

Accessor to centered sample flag.

Parameters:

centeredbool: Whether the input sample is centered. When set to True, it allows to skip centering of the input process data.

getClassName()¶

Accessor to the object’s name.

Returns:

class_namestr: The object class name (object.__class__.__name__).

getId()¶

Accessor to the object’s id.

Returns:

idint: Internal unique identifier.

getInputProcessSample()¶

Accessor to the input sample.

Returns:

inputSampleProcessSample: Input sample.

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getNbModes()¶

Accessor to the maximum number of modes to compute.

Returns:

nint: The maximum number of modes to compute. The actual number of modes also depends on the threshold criterion.

getOutputSample()¶

Accessor to the output sample.

Returns:

outputSampleSample: Output sample.

getRecompress()¶

Accessor to the recompression flag.

Returns:

recompressbool: Whether to recompress the input Karhunen-Loeve decompositions. This can only be enabled if the scale of the input variable blocks is the same.

getResult()¶

Result accessor.

Returns:

resultFieldFunctionalChaosResult: Result class.

getShadowedId()¶

Accessor to the object’s shadowed id.

Returns:

idint: Internal unique identifier.

getThreshold()¶

Accessor to the eigenvalues cutoff ratio.

Returns:

sfloat, $\geq 0$: The threshold $s$ .

getVisibility()¶

Accessor to the object’s visibility state.

Returns:

visiblebool: Visibility flag.

hasName()¶

Test if the object is named.

Returns:

hasNamebool: True if the name is not empty.

hasVisibleName()¶

Test if the object has a distinguishable name.

Returns:

hasVisibleNamebool: True if the name is not empty and not the default one.

run()¶

Compute the response surfaces.

Notes

It computes the response surfaces and creates a MetaModelResult structure containing all the results.

setBlockIndices(blockIndices)¶

Accessor to the block indices.

Parameters:

blockIndices2-d sequence of int: Independent components indices.

setCenteredSample(centered)¶

Accessor to centered sample flag.

Parameters:

centeredbool: Whether the input sample is centered. When set to True, it allows to skip centering of the input process data.

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setNbModes(nbModes)¶

Accessor to the maximum number of modes to compute.

Parameters:

nint: The maximum number of modes to compute. The actual number of modes also depends on the threshold criterion.

setRecompress(recompress)¶

Accessor to the recompression flag.

Parameters:

recompressbool: Whether to recompress the input Karhunen-Loeve decompositions. The modes are truncated a second time according to a global eigen value bound across input decompositions. This can only be enabled if the scale of the input variable blocks is the same.

setShadowedId(id)¶

Accessor to the object’s shadowed id.

Parameters:

idint: Internal unique identifier.

setThreshold(threshold)¶

Accessor to the eigenvalues cutoff ratio.

Parameters:

sfloat, $\geq 0$: The threshold $s$ .

setVisibility(visible)¶

Accessor to the object’s visibility state.

Parameters:

visiblebool: Visibility flag.

Examples using the class¶

Estimate Sobol indices on a field to point function

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Table of Contents

Previous topic

Next topic

This Page

FieldToPointFunctionalChaosAlgorithm¶

Examples using the class¶