1%feature("docstring") OT::KarhunenLoeveP1Algorithm
2"Computation of Karhunen-Loeve decomposition using P1 approximation.
3
4Parameters
5----------
6mesh : :class:`~openturns.Mesh`
7    The mesh :math:`\cD_N` that discretizes the domain :math:`\cD`.
8covariance : :class:`~openturns.CovarianceModel`
9    The covariance function to decompose.
10s : float, :math:`\geq0`
11    The threshold used to select the most significant eigenmodes, defined in  :class:`~openturns.KarhunenLoeveAlgorithm`.
12
13Notes
14-----
15The Karhunen-Loeve :math:`P_1` algorithm solves the Fredholm problem  associated to the covariance function :math:`C`: see :class:`~openturns.KarhunenLoeveAlgorithm` to get the notations.
16
17The Karhunen-Loeve :math:`P_1` approximation uses the :math:`P_1` functional basis :math:`(\theta_p)_{1 \leq p \leq N}` where  :math:`\theta_p: \cD_N \mapsto \Rset` are the basis functions of the :math:`P_1` finite element space associated to :math:`\cD_N`, which vertices are :math:`(\vect{s}_i)_{1 \leq i \leq N}`.
18
19The covariance function :math:`\mat{C}` is approximated by its :math:`P_1` approximation :math:`\hat{\mat{C}}` on :math:`\cD_N`:
20
21.. math::
22
23   \hat{\mat{C}}(\vect{s},\vect{t})=\sum_{\vect{s}_i,\vect{s}_j\in\cV_N}\mat{C}(\vect{s}_i,\vect{s}_j)\theta_i(\vect{s})\theta_j(\vect{t}), \quad  \forall \vect{s},\vect{t}\in\cD_N
24
25The Galerkin approach and the collocation one are equivalent in the :math:`P_1` approach and both lead to the following formulation:
26
27.. math::
28
29    \mat{C}\, \mat{G}\, \mat{\Phi}  =   \mat{\Phi}\, \mat{\Lambda}
30
31
32where :math:`\mat{G} = (G_{ij})_{1\leq i,j \leq N}` with :math:`G_{i\ell}= \int_{\cD} \theta_i(\vect{s})\theta_\ell(\vect{s})\,  d\vect{s}`, :math:`\mat{\Lambda}=diag(\vect{\lambda})`.
33
34Though the eigenvalues computation is performed by LAPACK by default, several other solvers can be used. The solver to use must be specified by setting ``KarhunenLoeveP1Algorithm-EigenvaluesSolver`` key in :class:`~openturns.ResourceMap`. Some solvers set limits to the number of eigenvalues they can compute with regards to the size of the problem. The following table summarizes the supported solvers and their maximum number of eigenvalues for a problem of size :math:`n`:
35
36+-------------+---------------------+----------------------+
37| Solver      | ResourceMap key     | Maximum EV number    |
38+=============+=====================+======================+
39| Lapack      | LAPACK              | :math:`n`            |
40+-------------+---------------------+----------------------+
41| Spectra     | SPECTRA             | :math:`n-2`          |
42+-------------+---------------------+----------------------+
43
44For large dimension problems, it can be useful to generate the covariance matrix of the problem as a :class:`~openturns.HMatrix` instead of a standard dense matrix. In this case, one can set ``KarhunenLoeveP1Algorithm-CovarianceMatrixStorage`` key in :class:`~openturns.ResourceMap` to ``HMAT`` (instead of ``DENSE``).
45
46Examples
47--------
48Create a Karhunen-Loeve P1 algorithm:
49
50>>> import openturns as ot
51>>> mesh = ot.IntervalMesher([10]*2).build(ot.Interval([-1.0]*2, [1.0]*2))
52>>> s = 0.01
53>>> model = ot.AbsoluteExponential([1.0]*2)
54>>> algorithm = ot.KarhunenLoeveP1Algorithm(mesh, model, s)
55
56Run it!
57
58>>> algorithm.run()
59>>> result = algorithm.getResult()"
60
61// ---------------------------------------------------------------------
62
63%feature("docstring") OT::KarhunenLoeveP1Algorithm::run
64"Computation of the eigenvalues and eigenfunctions values at nodes.
65
66Notes
67-----
68Runs the algorithm and creates the result structure :class:`~openturns.KarhunenLoeveResult`."
69
70// ---------------------------------------------------------------------
71
72%feature("docstring") OT::KarhunenLoeveP1Algorithm::getMesh
73"Accessor to the mesh.
74
75Returns
76-------
77mesh : :class:`~openturns.Mesh`
78    The mesh :math:`\cD_N` that discretizes the domain :math:`\cD`."
79
80