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

%feature("docstring") OT::QuadraticCumul
"First and second order quadratic cumul formulas.

Available constructors:
    QuadraticCumul(*limitStateVariable*)

Parameters
----------
limitStateVariable : :class:`~openturns.RandomVector`
    This RandomVector must be of type *Composite*, which means it must have
    been defined with the fourth usage of declaration of a RandomVector
    (from a NumericalMathFunction and an antecedent Distribution) or with
    the class :class:`~openturns.CompositeRandomVector`.

Notes
-----
The quadratic cumul is a probabilistic approach designed to
propagate the uncertainties of the input variables :math:`\\\\uX` through the
model :math:`h` towards the output variables :math:`\\\\uY`. It enables to access
the central dispersion (Expectation, Variance) of the output variables.

This method is based on a Taylor decomposition of the output variable
:math:`\\\\uY` towards the :math:`\\\\uX` random vectors around the mean point
:math:`\\\\muX`. Depending on the order of the Taylor decomposition (classically
first order or second order), one can obtain different formulas introduced
hereafter.

As :math:`\\\\uY=h(\\\\uX)`, the Taylor decomposition around :math:`\\\\ux = \\\\muX` at
the second order yields to:

.. math::

    \\\\uY = h(\\\\muX) + <\\\\vect{\\\\vect{\\\\nabla}}h(\\\\muX) , \\\\: \\\\uX - \\\\muX> + \\\\frac{1}{2}<<\\\\vect{\\\\vect{\\\\vect{\\\\nabla }}}^2 h(\\\\muX,\\\\: \\\\vect{\\\\mu}_{\\\\:X}),\\\\: \\\\uX - \\\\muX>,\\\\: \\\\uX - \\\\muX> + o(\\\\Cov \\\\uX)

where:

- :math:`\\\\muX = \\\\Expect{\\\\uX}` is the vector of the input variables at the mean
  values of each component.

- :math:`\\\\Cov \\\\uX` is the covariance matrix of the random vector `\\\\uX`. The
  elements are the followings :
  :math:`(\\\\Cov \\\\uX)_{ij} = \\\\Expect{\\\\left(X^i - \\\\Expect{X^i} \\\\right)^2}`

- :math:`\\\\vect{\\\\vect{\\\\nabla}} h(\\\\muX) = \\\\: \\\\Tr{\\\\left( \\\\frac{\\\\partial y^i}{\\\\partial x^j}\\\\right)}_{\\\\ux\\\\: =\\\\: \\\\muX} = \\\\: \\\\Tr{\\\\left( \\\\frac{\\\\partial h^i(\\\\ux)}{\\\\partial x^j}\\\\right)}_{\\\\ux\\\\: =\\\\: \\\\muX}`
  is the transposed Jacobian matrix with :math:`i=1,\\\\ldots,n_Y` and
  :math:`j=1,\\\\ldots,n_X`.

- :math:`\\\\vect{\\\\vect{\\\\vect{\\\\nabla^2}}} h(\\\\ux\\\\:,\\\\ux)` is a tensor of order 3. It
  is composed by the second order derivative towards the :math:`i^\\\\textrm{th}`
  and :math:`j^\\\\textrm{th}` components of :math:`\\\\ux` of the
  :math:`k^\\\\textrm{th}` component of the output vector :math:`h(\\\\ux)`. It
  yields to:
  :math:`\\\\left( \\\\nabla^2 h(\\\\ux) \\\\right)_{ijk} = \\\\frac{\\\\partial^2 (h^k(\\\\ux))}{\\\\partial x^i \\\\partial x^j}`

- :math:`<\\\\vect{\\\\vect{\\\\nabla}}h(\\\\muX) , \\\\: \\\\uX - \\\\muX> = \\\\sum_{j=1}^{n_X} \\\\left( \\\\frac{\\\\partial {\\\\uy}}{\\\\partial {x^j}}\\\\right)_{\\\\ux = \\\\muX} . \\\\left( X^j-\\\\muX^j \\\\right)`

-
  .. math::

      <<\\\\vect{\\\\vect{\\\\vect{\\\\nabla }}}^2 h(\\\\muX,\\\\: \\\\vect{\\\\mu}_{X}),\\\\: \\\\uX - \\\\muX>,\\\\: \\\\uX - \\\\muX> = \\\\left( \\\\Tr{(\\\\uX^i - \\\\muX^i)}. \\\\left(\\\\frac{\\\\partial^2 y^k}{\\\\partial x^i \\\\partial x^k}\\\\right)_{\\\\ux = \\\\muX}. (\\\\uX^j - \\\\muX^j) \\\\right)_{ijk}

**Approximation at the order 1:**

Expectation:

.. math::

    \\\\Expect{\\\\uY} \\\\approx \\\\vect{h}(\\\\muX)

Pay attention that :math:`\\\\Expect{\\\\uY}` is a vector. The :math:`k^\\\\textrm{th}`
component of this vector is equal to the :math:`k^\\\\textrm{th}` component of the
output vector computed by the model :math:`h` at the mean value.
:math:`\\\\Expect{\\\\uY}` is thus the computation of the model at mean.

Variance:

.. math::

    \\\\Cov \\\\uY \\\\approx \\\\Tr{\\\\vect{\\\\vect{\\\\nabla}}}\\\\:\\\\vect{h}(\\\\muX).\\\\Cov \\\\uX.\\\\vect{\\\\vect{\\\\nabla}}\\\\:\\\\vect{h}(\\\\muX)

**Approximation at the order 2:**

Expectation:

.. math::

    (\\\\Expect{\\\\uY})_k \\\\approx (\\\\vect{h}(\\\\muX))_k +
                              \\\\left(
                              \\\\sum_{i=1}^{n_X}\\\\frac{1}{2} (\\\\Cov \\\\uX)_{ii}.{(\\\\nabla^2\\\\:h(\\\\uX))}_{iik} +
                              \\\\sum_{i=1}^{n_X} \\\\sum_{j=1}^{i-1} (\\\\Cov X)_{ij}.{(\\\\nabla^2\\\\:h(\\\\uX))}_{ijk}
                              \\\\right)_k

Variance:

The decomposition of the variance at the order 2 is not implemented in the
standard version of OpenTURNS. It requires both the knowledge of higher order
derivatives of the model and the knowledge of moments of order strictly greater
than 2 of the PDF.

Examples
--------
>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> myFunc = ot.NumericalMathFunction(['x1', 'x2', 'x3', 'x4'], ['y1', 'y2'],
...     ['(x1*x1+x2^3*x1)/(2*x3*x3+x4^4+1)', 'cos(x2*x2+x4)/(x1*x1+1+x3^4)'])
>>> R = ot.CorrelationMatrix(4)
>>> for i in range(4):
...     R[i, i - 1] = 0.25
>>> distribution = ot.Normal([0.2]*4, [0.1, 0.2, 0.3, 0.4], R)
>>> # We create a distribution-based RandomVector
>>> X = ot.RandomVector(distribution)
>>> # We create a composite RandomVector Y from X and myFunc
>>> Y = ot.RandomVector(myFunc, X)
>>> # We create a quadraticCumul algorithm
>>> myQuadraticCumul = ot.QuadraticCumul(Y)
>>> print(myQuadraticCumul.getMeanFirstOrder())
[0.0384615,0.932544]"

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

%feature("docstring") OT::QuadraticCumul::getCovariance
"Get the approximation at the first order of the covariance matrix.

Returns
-------
covariance : :class:`~openturns.CovarianceMatrix`
    Approximation at the first order of the covariance matrix of the random
    vector."

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

%feature("docstring") OT::QuadraticCumul::getGradientAtMean
"Get the gradient of the function.

Returns
-------
gradient : :class:`~openturns.Matrix`
    Gradient of the NumericalMathFunction which defines the random vector at
    the mean point of the input random vector."

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

%feature("docstring") OT::QuadraticCumul::getHessianAtMean
"Get the hessian of the function.

Returns
-------
hessian : :class:`~openturns.SymmetricTensor`
    Hessian of the NumericalMathFunction which defines the random vector at
    the mean point of the input random vector."

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

%feature("docstring") OT::QuadraticCumul::getImportanceFactors
"Get the importance factors.

Returns
-------
factors : :class:`~openturns.NumericalPoint`
    Importance factors of the inputs : only when randVect is of dimension 1."

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

%feature("docstring") OT::QuadraticCumul::getLimitStateVariable
"Get the limit state variable.

Returns
-------
limitStateVariable : :class:`~openturns.RandomVector`
    Limit state variable."

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

%feature("docstring") OT::QuadraticCumul::getMeanFirstOrder
"Get the approximation at the first order of the mean.

Returns
-------
mean : :class:`~openturns.NumericalPoint`
    Approximation at the first order of the mean of the random vector."

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

%feature("docstring") OT::QuadraticCumul::getMeanSecondOrder
"Get the approximation at the second order of the mean.

Returns
-------
mean : :class:`~openturns.NumericalPoint`
    Approximation at the second order of the mean of the random vector
    (it requires that the hessian of the NumericalMathFunction has been defined)."

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

%feature("docstring") OT::QuadraticCumul::getValueAtMean
"Get the value of the function.

Returns
-------
value : :class:`~openturns.NumericalPoint`
    Value of the NumericalMathFunction which defines the random vector at
    the mean point of the input random vector."

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

%feature("docstring") OT::QuadraticCumul::drawImportanceFactors
"Draw the importance factors.

Returns
-------
graph : :class:`~openturns.Graph`
    Graph containing the pie corresponding to the importance factors of the
    probabilistic variables."