KarhunenLoeveResult

class KarhunenLoeveResult(*args)

Result structure of a Karhunen-Loeve algorithm.

Parameters
covModelCovarianceModel

The covariance model.

sfloat, \geq0

The threshold used to select the most significant eigenmodes, defined in KarhunenLoeveAlgorithm.

lambdaPoint

The first eigenvalues of the Fredholm problem.

modesBasis

The first modes of the Fredholm problem.

modesAsProcessSampleProcessSample

The values of the modes on the mesh associated to the KarhunenLoeve algorithm.

projectionMatrix

The projection matrix.

Notes

Structure generally created by the method run() of a KarhunenLoeveAlgorithm and obtained thanks to the method getResult().

We consider C:\cD \times \cD \rightarrow  \cS^+_d(\Rset) a covariance function defined on \cD \in \Rset^n, continuous at \vect{0}.

We note (\lambda_k,  \vect{\varphi}_k)_{1 \leq k \leq K} the solutions of the Fredholm problem associated to C where K is the highest index K such that \lambda_K \geq s \lambda_1.

We note \vect{\lambda} the eigenvalues sequence and \vect{\varphi} the eigenfunctions sequence.

Then we define the linear projection function \pi_{ \vect{\lambda}, \vect{\varphi}} by:

(1)\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 \}.

According to the Karhunen-Loeve algorithm, the integral of (1) is replaced by a specific weighted and finite sum. Thus, the linear relation (1) becomes a relation between fields which allows the following matrix representation:

(2)\left|
  \begin{array}{ccl}
     \cM_N \times (\Rset^d)^N & \rightarrow & \Rset^K \\
     F & \mapsto & (\xi_1, \dots, \xi_K) = MF
  \end{array}
\right.

where F = (\vect{t}_i, \vect{v}_i)_{1 \leq i \leq N} is a Field and M the projection matrix.

The inverse of \pi_{\vect{\lambda}, \vect{\varphi}} is the lift function defined by:

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

If the function f(.) = X(\omega_0, .) where X is the centered process which covariance function is associated to the eigenvalues and eigenfunctions (\vect{\lambda}, \vect{\varphi}), then the getEigenvalues method enables to obtain the K first eigenvalues of the Karhunen-Loeve decomposition of X and the method getModes enables to get the associated modes.

Examples

>>> import openturns as ot
>>> N = 256
>>> mesh = ot.IntervalMesher([N - 1]).build(ot.Interval(-1, 1))
>>> covariance_X = ot.AbsoluteExponential([1])
>>> process_X = ot.GaussianProcess(covariance_X, mesh)
>>> s = 0.001
>>> algo_X = ot.KarhunenLoeveP1Algorithm(mesh, covariance_X, s)
>>> algo_X.run()
>>> result_X = algo_X.getResult()

Methods

drawCumulatedEigenvaluesRemainder()

Accessor to the cumulated eigen values normalized remainder graph.

drawEigenvalues()

Accessor to the eigen values graph.

getClassName()

Accessor to the object's name.

getCovarianceModel()

Accessor to the covariance model.

getEigenvalues()

Accessor to the eigenvalues of the Karhunen-Loeve decomposition.

getId()

Accessor to the object's id.

getImplementation()

Accessor to the underlying implementation.

getMesh()

Accessor to the mesh.

getModes()

Get the modes as functions.

getModesAsProcessSample()

Accessor to the modes as a process sample.

getName()

Accessor to the object's name.

getProjectionMatrix()

Accessor to the projection matrix.

getScaledModes()

Get the modes as functions scaled by the square-root of the corresponding eigenvalue.

getScaledModesAsProcessSample()

Accessor to the scaled modes as a process sample.

getThreshold()

Accessor to the limit ratio on eigenvalues.

lift(coefficients)

Lift the coefficients into a function.

liftAsField(coefficients)

Lift the coefficients into a field.

liftAsSample(coefficients)

Lift the coefficients into a sample.

project(*args)

Project a function or a field on the eigenmodes basis.

setName(name)

Accessor to the object's name.

__init__(*args)
drawCumulatedEigenvaluesRemainder()

Accessor to the cumulated eigen values normalized remainder graph.

Draw the values of cumulated eigen values normalized remainder:

cevr_i = 1 - \frac{\sum_{j=1}^i \lambda_j}{\sum_{j=1}^K \lambda_j}

Returns
graphGraph

The cumulated and normalized eigen values graph.

drawEigenvalues()

Accessor to the eigen values graph.

Returns
graphGraph

The eigen values graph.

getClassName()

Accessor to the object’s name.

Returns
class_namestr

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

getCovarianceModel()

Accessor to the covariance model.

Returns
covModelCovarianceModel

The covariance model.

getEigenvalues()

Accessor to the eigenvalues of the Karhunen-Loeve decomposition.

Returns
eigenValPoint

The most significant eigenvalues.

Notes

OpenTURNS truncates the sequence (\lambda_k,  \vect{\varphi}_k)_{k \geq 1} to the most significant terms, selected by the threshold defined in KarhunenLoeveAlgorithm.

getId()

Accessor to the object’s id.

Returns
idint

Internal unique identifier.

getImplementation()

Accessor to the underlying implementation.

Returns
implImplementation

A copy of the underlying implementation object.

getMesh()

Accessor to the mesh.

Returns
meshMesh

The mesh corresponds to the discretization points of the integral in (1).

getModes()

Get the modes as functions.

Returns
modescollection of Function

The truncated basis (\vect{\varphi}_k)_{1 \leq k \leq K}.

Notes

The basis is truncated to (\vect{\varphi}_k)_{1 \leq k \leq K} where K is determined by the s, defined in KarhunenLoeveAlgorithm.

getModesAsProcessSample()

Accessor to the modes as a process sample.

Returns
modesAsProcessSampleProcessSample

The values of each mode on a mesh whose vertices were used to discretize the Fredholm equation.

Notes

The modes (\vect{\varphi}_k)_{1 \leq k \leq K} are evaluated on the vertices of the mesh defining the process sample. The values of the i-th field are the values of the i-th mode on these vertices.

The mesh corresponds to the discretization points of the integral in (1).

getName()

Accessor to the object’s name.

Returns
namestr

The name of the object.

getProjectionMatrix()

Accessor to the projection matrix.

Returns
projectionMatrix

The matrix M defined in (2).

getScaledModes()

Get the modes as functions scaled by the square-root of the corresponding eigenvalue.

Returns
modescollection of Function

The truncated basis (\sqrt{\lambda_k}\vect{\varphi}_k)_{1 \leq k \leq K}.

Notes

The basis is truncated to (\sqrt{\lambda_k}\vect{\varphi}_k)_{1 \leq k \leq K} where K is determined by the s, defined in KarhunenLoeveAlgorithm.

getScaledModesAsProcessSample()

Accessor to the scaled modes as a process sample.

Returns
modesAsProcessSampleProcessSample

The values of each scaled mode on a mesh whose vertices were used to discretize the Fredholm equation.

Notes

The modes (\vect{\varphi}_k)_{1 \leq k \leq K} are evaluated on the vertices of the mesh defining the process sample. The values of the i-th field are the values of the i-th mode on these vertices.

The mesh corresponds to the discretization points used to discretize the integral

(1).

getThreshold()

Accessor to the limit ratio on eigenvalues.

Returns
sfloat, \geq 0

The threshold s used to select the most significant eigenmodes, defined in KarhunenLoeveAlgorithm.

lift(coefficients)

Lift the coefficients into a function.

Parameters
coefPoint

The coefficients (\xi_1, \dots, \xi_K).

Returns
modesFunction

The function f defined in (3).

Notes

The sum defining f is truncated to the first K terms, where K is determined by the s, defined in KarhunenLoeveAlgorithm.

liftAsField(coefficients)

Lift the coefficients into a field.

Parameters
coefPoint

The coefficients (\xi_1, \dots, \xi_K).

Returns
modesField

The function f defined in (3) evaluated on the mesh associated to the discretization of (1).

Notes

The sum defining f is truncated to the first K terms, where K is determined by the s, defined in KarhunenLoeveAlgorithm.

liftAsSample(coefficients)

Lift the coefficients into a sample.

Parameters
coefPoint

The coefficients (\xi_1, \dots, \xi_K).

Returns
modesSample

The function f defined in (3) evaluated on the mesh associated to the discretization of (1).

Notes

The sum defining f is truncated to the first K terms, where K is determined by the s, defined in KarhunenLoeveAlgorithm.

project(*args)

Project a function or a field on the eigenmodes basis.

Available constructors:

project(function)

project(functions)

project(values)

project(fieldSample)

Parameters
functionFunction

A function.

functionslist of Function

A list of functions.

valuesSample

Field values.

fieldSampleProcessSample

A collection of fields.

Returns
pointPoint

The vector (\alpha_1, \dots, \alpha_K) of the components of the function or the field in the eigenmodes basis

sampleSample

The collection of the vectors (\alpha_1, \dots, \alpha_K) of the components of the collection of functions or fields in the eigenmodes basis

Notes

The project method calculates the projection (1) on a function or a field where only the first K elements of the sequences are calculated. K is determined by the s, defined in KarhunenLoeveAlgorithm.

Lets note \cM_{KL} the mesh coming from the KarhunenLoeveResult (ie the one contained in the modesAsSample ProcessSample).

The given values are defined on the input field \cM_{KL} and the associated values are directly used for the projection.

If evaluated from a function, the project method evaluates the function on \cM_{KL} and uses (2).

setName(name)

Accessor to the object’s name.

Parameters
namestr

The name of the object.