PointToFieldFunctionalChaosAlgorithm

class PointToFieldFunctionalChaosAlgorithm(*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 makes it possible to build a response surface of the function h defined by the equation:

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

with \cM_N a mesh of \cD \subset \Rset^n.

The mapping h is known from the N vectors (\vect{X}_1, \dots, \vect{X}_N) of the associated input random vector \vect{X} and N fields (\mat{Y}_1,\dots,\mat{Y}_N) that fully characterize the output process \mat{Y}.

The linear projection function \pi_{ \vect{\lambda}, \vect{\varphi}} of the Karhunen-Loeve decomposition by SVD is used to project the output 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.

where \cS^{\Nset} = \left \{ (\zeta_k)_{k \geq 1} \in \Rset^{\Nset} \, | \, \sum_{k=1}^{\infty}\lambda_k \zeta_k^2 < +\infty \right \}.

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

\mat{M}_j \mat{Y}_i^j = \left( \begin{array}{l} \xi_1^j \\ \vdots \\ \xi_{K_j}^j \end{array} \right) \in \Rset^{K_j}, \quad \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 output. The projections of all the d components of n fields are assembled in the \mat{Q} matrix:

\begin{align*} \mat{Q} = \mat{M} \mat{Y} = \left( \begin{array}{l} \mat{M}_1 \mat{Y}^1 \\ \vdots \\ \mat{M}_d \mat{Y}^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 output components.

Then a functional chaos decomposition is built between the input samples \vect{X} and the projected modes sample \mat{Q}. The ResourceMap string entry PointToFieldFunctionalChaosAlgorithm-Expansion allows one to switch between LeastSquaresExpansion and FunctionalChaosAlgorithm.

\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 functional chaos metamodel and the Karhunen-Loeve projections.

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

Here the projected modes sample has a dimension K_T but being on the output side of the functional chaos expansion (FCE) this approach is not affected by the curse of dimensionality, it will just require as much FCE marginals runs.

Parameters:
xSample

Input sample.

yProcessSample

Output process sample.

distributionDistribution

Input distribution

Methods

getBlockIndices()

Accessor to the output block indices.

getClassName()

Accessor to the object's name.

getInputSample()

Accessor to the input sample.

getName()

Accessor to the object's name.

getNbModes()

Accessor to the maximum number of modes to compute.

getOutputProcessSample()

Accessor to the output sample.

getRecompress()

Accessor to the recompression flag.

getResult()

Result accessor.

getThreshold()

Accessor to the eigenvalues cutoff ratio.

hasName()

Test if the object is named.

run()

Compute the response surfaces.

setBlockIndices(blockIndices)

Accessor to the output block indices.

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.

setThreshold(threshold)

Accessor to the eigenvalues cutoff ratio.

See also

openturns.FieldToPointFunctionalChaosAlgorithm
openturns.FieldFunctionalChaosSobolIndices
openturns.KarhunenLoeveAlgorithm
openturns.FunctionalChaosAlgorithm

Notes

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

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 output is truncated. The default value can be set through the ResourceMap key PointToFieldFunctionalChaosAlgorithm-DefaultRecompress.

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

It is possible to partition output variables into independent blocks with setBlockIndices(). This way Karhunen-Loeve process decompositions are done on each block rather than on all output variables at once (at the price of increased chaos decomposition output dimension) which then makes sensitivity analysis possible for each output variable or group of output variables.

Examples

>>> import openturns as ot
>>> import openturns.experimental as otexp
>>> ot.RandomGenerator.SetSeed(0)
>>> mesh = ot.RegularGrid(0.0, 0.1, 20)
>>> X = ot.Normal(4)
>>> x = X.getSample(50)
>>> g = ot.SymbolicFunction(['t', 'x1', 'x2', 'x3', 'x4'], ['x1 + x2 * sin(t)', 'x2 + x3 * cos(t)', 'x4 * t'])
>>> f = ot.VertexValuePointToFieldFunction(g, mesh)
>>> y = f(x)
>>> algo = otexp.PointToFieldFunctionalChaosAlgorithm(x, y, X)
>>> algo.setThreshold(4e-2)
>>> # Temporarily lower the basis size for the sake of this example.
>>> ot.ResourceMap.SetAsUnsignedInteger('FunctionalChaosAlgorithm-BasisSize', 100)
>>> algo.run()
>>> result = algo.getResult()
>>> metamodel = result.getPointToFieldMetaModel()
>>> y0hat = metamodel(x[0])
>>> ot.ResourceMap.Reload()
__init__(*args)
getBlockIndices()

Accessor to the output block indices.

Returns:
blockIndicesIndicesCollection

Independent output components indices.

getClassName()

Accessor to the object’s name.

Returns:
class_namestr

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

getInputSample()

Accessor to the input sample.

Returns:
inputSampleSample

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.

getOutputProcessSample()

Accessor to the output sample.

Returns:
outputSampleProcessSample

Output sample.

getRecompress()

Accessor to the recompression flag.

Returns:
recompressbool

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

getResult()

Result accessor.

Returns:
resultopenturns.FieldFunctionalChaosResult

Result class.

getThreshold()

Accessor to the eigenvalues cutoff ratio.

Returns:
sfloat, \geq 0

The threshold s.

hasName()

Test if the object is named.

Returns:
hasNamebool

True if the name is not empty.

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 output block indices.

Parameters:
blockIndices2-d sequence of int

Independent output components indices.

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 output Karhunen-Loeve decompositions. The modes are truncated a second time according to a global eigen value bound across output decompositions. This can only be enabled if the scale of the output variable blocks is the same.

setThreshold(threshold)

Accessor to the eigenvalues cutoff ratio.

Parameters:
sfloat, \geq 0

The threshold s.

Examples using the class

Viscous free fall: metamodel of a field function

Viscous free fall: metamodel of a field function