libopenturns-dev 1.7-3 / usr / include / openturns / swig / CovarianceModelImplementation_doc.i

%define OT_CovarianceModel_doc
"Covariance model.

Notes
-----
We consider :math:`X: \\\\Omega \\\\times\\\\cD \\\\mapsto \\\\Rset^d` a multivariate
stochastic process of dimension :math:`d`, where :math:`\\\\omega \\\\in \\\\Omega`
is an event, :math:`\\\\cD` is a domain of :math:`\\\\Rset^n`,
:math:`\\\\vect{t}\\\\in \\\\cD` is a multivariate index and
:math:`X(\\\\omega, \\\\vect{t}) \\\\in \\\\Rset^d`.

We note :math:`X_{\\\\vect{t}}: \\\\Omega \\\\rightarrow \\\\Rset^d` the random variable at
index :math:`\\\\vect{t} \\\\in \\\\cD` defined by
:math:`X_{\\\\vect{t}}(\\\\omega)=X(\\\\omega, \\\\vect{t})` and
:math:`X(\\\\omega): \\\\cD  \\\\mapsto \\\\Rset^d` a realization of the process
:math:`X`, for a given :math:`\\\\omega \\\\in \\\\Omega` defined by
:math:`X(\\\\omega)(\\\\vect{t})=X(\\\\omega, \\\\vect{t})`.

If the process is a second order process, we note:

- :math:`m : \\\\cD \\\\mapsto  \\\\Rset^d` its *mean function*, defined by
  :math:`m(\\\\vect{t})=\\\\Expect{X_{\\\\vect{t}}}`,
- :math:`C : \\\\cD \\\\times \\\\cD \\\\mapsto  \\\\cM_{d \\\\times d}(\\\\Rset)` its
  *covariance function*, defined by
  :math:`C(\\\\vect{s}, \\\\vect{t})=\\\\Expect{(X_{\\\\vect{s}}-m(\\\\vect{s}))\\\\Tr{(X_{\\\\vect{t}}-m(\\\\vect{t}))}}`,
- :math:`R : \\\\cD \\\\times \\\\cD \\\\mapsto  \\\\mathcal{M}_{d \\\\times d}(\\\\Rset)` its
  *correlation function*, defined for all :math:`(\\\\vect{s}, \\\\vect{t})`,
  by :math:`R(\\\\vect{s}, \\\\vect{t})` such that for all :math:`(i,j)`,
  :math:`R_{ij}(\\\\vect{s}, \\\\vect{t})=C_{ij}(\\\\vect{s}, \\\\vect{t})/\\\\sqrt{C_{ii}(\\\\vect{s}, \\\\vect{t})C_{jj}(\\\\vect{s}, \\\\vect{t})}`.

A CovarianceModel object can be created only through its derived classes:
:class:`~openturns.StationaryCovarianceModel`,
:class:`~openturns.UserDefinedCovarianceModel`,
:class:`~openturns.GeneralizedExponential`,
:class:`~openturns.AbsoluteExponential`,
:class:`~openturns.SquaredExponential`,
:class:`~openturns.ExponentialModel`,
:class:`~openturns.MaternModel`,
:class:`~openturns.SphericalModel`,
:class:`~openturns.ExponentiallyDampedCosineModel`."

%enddef
%feature("docstring") OT::CovarianceModelImplementation
OT_CovarianceModel_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_computeAsScalar_doc
"Compute the covariance function for 1-d model.

Available usages:
    computeAsScalar(s, t)

    computeAsScalar(tau)

Parameters
----------
s, t : sequences of float
    Inputs.
tau : sequence of float
    Input.

Returns
-------
covariance : float
    Covariance.

Notes
-----
*computeAsScalar* evaluates the covariance model
:math:`C : \\\\cD \\\\times \\\\cD \\\\mapsto  \\\\cM_{d \\\\times d}(\\\\Rset)` at
:math:`(s,t)\\\\in \\\\Rset^n`:

.. math::

    C(\\\\vect{s}, \\\\vect{t})=\\\\Expect{\\\\Tr{(X_{\\\\vect{s}}-m(\\\\vect{s}))(X_{\\\\vect{t}}-m(\\\\vect{t}))}}

In the second usage, the covariance model must be stationary. Then we note
:math:`C^{stat}(\\\\vect{\\\\tau})` for :math:`C(\\\\vect{s}, \\\\vect{s}+\\\\vect{\\\\tau})` as
this quantity does not depend on :math:`\\\\vect{s}`."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::computeAsScalar
OT_CovarianceModel_computeAsScalar_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_computeStandardRepresentative_doc
"Compute the standard representative function of the covariance model.

Available usages:
    computeStandardRepresentative(s, t)

    computeStandardRepresentative(tau)

Parameters
----------
s, t : floats or sequences of float
    Inputs.
tau : floats orsequence of float
    Input.

Returns
-------
rho : float
    Scaling covariance.

Notes
-----
*computeStandardRepresentative* evaluates the correlation function on two spatial points:
:math:`\\\\rho : \\\\cD \\\\times \\\\cD \\\\mapsto \\\\Rset`.

A covariance function express at :math:`(s,t)\\\\in \\\\Rset^n` as follows :


.. math::

    C(\\\\vect{s}, \\\\vect{t}) = \\\\mat{\\\\Sigma} \\\\rho\\\\left(\\\\frac{\\\\vect{s}}{\\\\vect{\\\\theta}}, \\\\frac{\\\\vect{t}}{\\\\vect{\\\\theta}}\\\\right)

where :math:`\\\\frac{\\\\vect{s}}{\\\\vect{\\\\theta}} = (\\\\frac{\\\\vect{s}_1}{\\\\vect{\\\\theta}_1},\\\\cdots,\\\\frac{\\\\vect{s}_n}{\\\\vect{\\\\theta}_n})` is the scaled point and
:math:`\\\\mat{\\\\Sigma}` is a covariance matrix that explains the covariance structure.

In the second usage, the covariance model must be stationary."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::computeStandardRepresentative
OT_CovarianceModel_computeStandardRepresentative_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_discretize_doc
"Discretize the covariance function on a given RegularGrid/Mesh.

Parameters
----------
meshOrGrid : :class:`~openturns.Mesh` or :class:`~openturns.RegularGrid`
    Mesh or time grid of size :math:`N` associated with the process.

Returns
-------
covarianceMatrix : :class:`~openturns.CovarianceMatrix`
    Covariance matrix :math:`\\\\in\\\\cM_{nd\\\\times nd}(\\\\Rset)` (if the process is of
    dimension :math:`d`).

Notes
-----
This method makes a discretization of the model on *meshOrGrid* composed of
the vertices :math:`(\\\\vect{t}_1, \\\\dots, \\\\vect{t}_{N-1})` and returns the
covariance matrix:

.. math ::

    \\\\mat{C}_{1,\\\\dots,k} = \\\\left(
        \\\\begin{array}{cccc}
        C(\\\\vect{t}_1, \\\\vect{t}_1) &C(\\\\vect{t}_1, \\\\vect{t}_2) & \\\\dots & C(\\\\vect{t}_1, \\\\vect{t}_{k}) \\\\\\\\
        \\\\dots & C(\\\\vect{t}_2, \\\\vect{t}_2)  & \\\\dots & C(\\\\vect{t}_2, \\\\vect{t}_{k}) \\\\\\\\
        \\\\dots & \\\\dots & \\\\dots & \\\\dots \\\\\\\\
        \\\\dots & \\\\dots & \\\\dots & C(\\\\vect{t}_{k}, \\\\vect{t}_{k})
        \\\\end{array} \\\\right)"
%enddef
%feature("docstring") OT::CovarianceModelImplementation::discretize
OT_CovarianceModel_discretize_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_discretizeAndFactorize_doc
"Discretize and factorize the covariance function on a given RegularGrid/Mesh.

Parameters
----------
meshOrGrid : :class:`~openturns.Mesh` or :class:`~openturns.RegularGrid`
    Mesh or time grid of size :math:`N` associated with the process.

Returns
-------
CholeskyMatrix : :class:`~openturns.TriangularMatrix`
    Cholesky factor of the covariance matrix :math:`\\\\in\\\\cM_{nd\\\\times nd}(\\\\Rset)` (if the process is of
    dimension :math:`d`).

Notes
-----
This method makes a discretization of the model on *meshOrGrid* composed of
the vertices :math:`(\\\\vect{t}_1, \\\\dots, \\\\vect{t}_{N-1})` thanks to the `discretize`
method and returns its Cholesky factor."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::discretizeAndFactorize
OT_CovarianceModel_discretizeAndFactorize_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_discretizeHMatrix_doc
"Discretize the covariance function on a given RegularGrid/Mesh using HMatrix result.

Parameters
----------
meshOrGrid : :class:`~openturns.Mesh` or :class:`~openturns.RegularGrid`
    Mesh or time grid of size :math:`N` associated with the process.

Returns
-------
HMatrix : :class:`~openturns.HMatrix`
    Covariance matrix :math:`\\\\in\\\\cM_{nd\\\\times nd}(\\\\Rset)` (if the process is of
    dimension :math:`d`), stored in hierarchical format (H-Matrix)

Notes
-----
This method si similar to the *discretize* method. This method requires that OpenTURNS has been compiled with the hmat library.
The method is helpfull for very large parameters (Mesh, grid, NumericalSample) as its compress data.
"
%enddef
%feature("docstring") OT::CovarianceModelImplementation::discretizeHMatrix
OT_CovarianceModel_discretizeHMatrix_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_discretizeAndFactorizeHMatrix_doc
"Discretize and factorize the covariance function on a given RegularGrid/Mesh using HMatrix result.

Parameters
----------
meshOrGrid : :class:`~openturns.Mesh` or :class:`~openturns.RegularGrid`
    Mesh or time grid of size :math:`N` associated with the process.

Returns
-------
HMatrix : :class:`~openturns.HMatrix`
    Cholesk matrix :math:`\\\\in\\\\cM_{nd\\\\times nd}(\\\\Rset)` (if the process is of
    dimension :math:`d`), stored in hierarchical format (H-Matrix)

Notes
-----
This method si similar to the *discretizeAndFactorize* method. This method requires that OpenTURNS has been compiled with the hmat library.
The method is helpfull for very large parameters (Mesh, grid, NumericalSample) as its compress data.
"
%enddef
%feature("docstring") OT::CovarianceModelImplementation::discretizeAndFactorizeHMatrix
OT_CovarianceModel_discretizeAndFactorizeHMatrix_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_discretizeRow_doc
"**(TODO)**"
%enddef
%feature("docstring") OT::CovarianceModelImplementation::discretizeRow
OT_CovarianceModel_discretizeRow_doc


// ---------------------------------------------------------------------

%define OT_CovarianceModel_getAmplitude_doc
"Get the amplitude parameter of the covariance function.

Returns
-------
amplitude : :class:`~openturns.NumericalPoint`
    The amplitude parameter used in the covariance function."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getAmplitude
OT_CovarianceModel_getAmplitude_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getDimension_doc
"Get the dimension of the *CovarianceModel*.

Returns
-------
dimension : int
    Dimension of the *CovarianceModel*."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getDimension
OT_CovarianceModel_getDimension_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_get_marginal
"Get the ith marginal of the model.

Returns
-------
marginal : int
    index of marginal of the model."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getMarginal
OT_CovarianceModel_get_marginal

// ---------------------------------------------------------------------

%define OT_CovarianceModel_get_nugget_factor_doc
"Accessor to the nugget factor.

This parameter allows smooth predictions from noisy data.
The nugget is added to the diagonal of the assumed training covariance
(thanks to discretize) and acts as a Tikhonov regularization in the
problem.

Returns
-------
nuggetFactor : float
    nugget factor used for the regularization of the discretized covariance matrix."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getNuggetFactor
OT_CovarianceModel_get_nugget_factor_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getParameter_doc
"Get the parameters of the covariance function.

Returns
-------
parameters : :class:`~openturns.NumericalPoint`
    Sequence containing the parameters of the covariance function.
    Usually the parameters is of size (spatialDim + dim) : the spatialDim first elements correpond
    to the scale, the dim following to the amplitude."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getParameter
OT_CovarianceModel_getParameter_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getParameterDescription_doc
"Get the description of the covariance function parameters.

Returns
-------
descriptionParam : :class:`~openturns.Description`
    Sequence containing the description for each component of the parameters."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getParameterDescription
OT_CovarianceModel_getParameterDescription_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getScale_doc
"Get the scale parameter of the covariance function.

Returns
-------
scale : :class:`~openturns.NumericalPoint`
    The scale parameter used in the covariance function."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getScale
OT_CovarianceModel_getScale_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getSpatialCorrelation_doc
"Get the spatial correlation matrix of the covariance function.

Returns
-------
spatialCorrelation : :class:`~openturns.CorrelationMatrix`
    Correlation matrix :math:`\\\\mat{R} \\\\in \\\\mathcal{M}_{d \\\\times d}(\\\\Rset)`."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::getSpatialCorrelation
OT_CovarianceModel_getSpatialCorrelation_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_getSpatialDimension_doc
"Get the spatial dimension of the covariance function.

Returns
-------
spatialDimension : int
    SpatialDimension of the *CovarianceModel*."

%enddef
%feature("docstring") OT::CovarianceModelImplementation::getSpatialDimension
OT_CovarianceModel_getSpatialDimension_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_isDiagonal_doc
"Test whether the model is diagonal or not.

Returns
-------
isDiagonal : bool
    *True* if the model is diagonal."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::isDiagonal
OT_CovarianceModel_isDiagonal_doc
// ---------------------------------------------------------------------

%define OT_CovarianceModel_isStationary_doc
"Test whether the model is stationary or not.

Returns
-------
isStationary : bool
    *True* if the model is stationary.

Notes
-----
The covariance function :math:`C` is stationary when it is invariant by
translation:

.. math::

    \\\\forall(\\\\vect{s},\\\\vect{t},\\\\vect{h}) \\\\in \\\\cD, & \\\\, \\\\quad
    C(\\\\vect{s}, \\\\vect{s}+\\\\vect{h}) = C(\\\\vect{t}, \\\\vect{t}+\\\\vect{h})

We note :math:`C^{stat}(\\\\vect{\\\\tau})` for :math:`C(\\\\vect{s}, \\\\vect{s}+\\\\vect{\\\\tau})`."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::isStationary
OT_CovarianceModel_isStationary_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_partialGradient_doc
"Compute the gradient of the covariance function.

Parameters
----------
s, t : sequence of float
    Inputs.

Returns
-------
gradient : :class:`~openturns.Matrix`
    Gradient of the covariance function."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::partialGradient
OT_CovarianceModel_partialGradient_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_setAmplitude_doc
"Set the amplitude parameter of the covariance function.

Parameters
----------
amplitude : :class:`~openturns.NumericalPoint`
    The amplitude parameter to be used in the covariance function."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::setAmplitude
OT_CovarianceModel_setAmplitude_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_setScale_doc
"Set the scale parameter of the covariance function.

Parameters
----------
scale : :class:`~openturns.NumericalPoint`
    The scale parameter to be used in the covariance function.
    It should be of size dimension."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::setScale
OT_CovarianceModel_setScale_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_set_nugget_factor_doc
"Set the nugget factor for the regularization.

Acts on the discretized covariance matrix.

Parameters
----------
nuggetFactor : float
    nugget factor to be used for the regularization of the discretized covariance matrix."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::setNuggetFactor
OT_CovarianceModel_set_nugget_factor_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_setParameter_doc
"Set the parameters of the covariance function.

Returns
-------
parameters : :class:`~openturns.NumericalPointWithDescription`
    Sequence containing the parameters of the covariance function with a
    description for each component.
    The parameters should be of size (spatialDim + dim) : it sets the spatialDim first elements to scale
    and the dim following to amplitude."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::setParameter
OT_CovarianceModel_setParameter_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_setSpatialCorrelation_doc
"Set the spatial correlation matrix of the covariance function.

Parameters
----------
spatialCorrelation : :class:`~openturns.CorrelationMatrix`
    Correlation matrix :math:`\\\\mat{R} \\\\in \\\\mathcal{M}_{d \\\\times d}(\\\\Rset)`."
%enddef
%feature("docstring") OT::CovarianceModelImplementation::setSpatialCorrelation
OT_CovarianceModel_setSpatialCorrelation_doc

// ---------------------------------------------------------------------

%define OT_CovarianceModel_operator_doc
"Evaluate the covariance function.

Available usages:
    __call__(s, t)

    __call__(tau)

Parameters
----------
s, t : sequences of float
    Inputs.
tau : sequence of float
    Input.

Returns
-------
covariance : CovarianceMatrix
    The evaluation of the covariance function.

"
%enddef
%feature("docstring") OT::CovarianceModelImplementation::operator()
OT_CovarianceModel_operator_doc

// ---------------------------------------------------------------------