python-openturns 1.5-7build2 / usr / lib / python2.7 / dist-packages / openturns / uncertainty.py

# This file was automatically generated by SWIG (http://www.swig.org).
# Version 2.0.12
#
# Do not make changes to this file unless you know what you are doing--modify
# the SWIG interface file instead.




"""
Probabilistic meta-package.
"""


from sys import version_info
if version_info >= (2,6,0):
    def swig_import_helper():
        from os.path import dirname
        import imp
        fp = None
        try:
            fp, pathname, description = imp.find_module('_uncertainty', [dirname(__file__)])
        except ImportError:
            import _uncertainty
            return _uncertainty
        if fp is not None:
            try:
                _mod = imp.load_module('_uncertainty', fp, pathname, description)
            finally:
                fp.close()
            return _mod
    _uncertainty = swig_import_helper()
    del swig_import_helper
else:
    import _uncertainty
del version_info
try:
    _swig_property = property
except NameError:
    pass # Python < 2.2 doesn't have 'property'.
def _swig_setattr_nondynamic(self,class_type,name,value,static=1):
    if (name == "thisown"): return self.this.own(value)
    if (name == "this"):
        if type(value).__name__ == 'SwigPyObject':
            self.__dict__[name] = value
            return
    method = class_type.__swig_setmethods__.get(name,None)
    if method: return method(self,value)
    if (not static):
        self.__dict__[name] = value
    else:
        raise AttributeError("You cannot add attributes to %s" % self)

def _swig_setattr(self,class_type,name,value):
    return _swig_setattr_nondynamic(self,class_type,name,value,0)

def _swig_getattr(self,class_type,name):
    if (name == "thisown"): return self.this.own()
    method = class_type.__swig_getmethods__.get(name,None)
    if method: return method(self)
    raise AttributeError(name)

def _swig_repr(self):
    try: strthis = "proxy of " + self.this.__repr__()
    except: strthis = ""
    return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)

try:
    _object = object
    _newclass = 1
except AttributeError:
    class _object : pass
    _newclass = 0


class SwigPyIterator(_object):
    __swig_setmethods__ = {}
    __setattr__ = lambda self, name, value: _swig_setattr(self, SwigPyIterator, name, value)
    __swig_getmethods__ = {}
    __getattr__ = lambda self, name: _swig_getattr(self, SwigPyIterator, name)
    def __init__(self, *args, **kwargs): raise AttributeError("No constructor defined - class is abstract")
    __repr__ = _swig_repr
    __swig_destroy__ = _uncertainty.delete_SwigPyIterator
    __del__ = lambda self : None;
    def value(self): return _uncertainty.SwigPyIterator_value(self)
    def incr(self, n=1): return _uncertainty.SwigPyIterator_incr(self, n)
    def decr(self, n=1): return _uncertainty.SwigPyIterator_decr(self, n)
    def distance(self, *args): return _uncertainty.SwigPyIterator_distance(self, *args)
    def equal(self, *args): return _uncertainty.SwigPyIterator_equal(self, *args)
    def copy(self): return _uncertainty.SwigPyIterator_copy(self)
    def next(self): return _uncertainty.SwigPyIterator_next(self)
    def __next__(self): return _uncertainty.SwigPyIterator___next__(self)
    def previous(self): return _uncertainty.SwigPyIterator_previous(self)
    def advance(self, *args): return _uncertainty.SwigPyIterator_advance(self, *args)
    def __eq__(self, *args): return _uncertainty.SwigPyIterator___eq__(self, *args)
    def __ne__(self, *args): return _uncertainty.SwigPyIterator___ne__(self, *args)
    def __iadd__(self, *args): return _uncertainty.SwigPyIterator___iadd__(self, *args)
    def __isub__(self, *args): return _uncertainty.SwigPyIterator___isub__(self, *args)
    def __add__(self, *args): return _uncertainty.SwigPyIterator___add__(self, *args)
    def __sub__(self, *args): return _uncertainty.SwigPyIterator___sub__(self, *args)
    def __iter__(self): return self
SwigPyIterator_swigregister = _uncertainty.SwigPyIterator_swigregister
SwigPyIterator_swigregister(SwigPyIterator)

GCC_VERSION = _uncertainty.GCC_VERSION
class TestFailed:
    """TestFailed is used to raise an uniform exception in tests."""

    __type = "TestFailed"

    def __init__(self, reason=""):
        self.reason = reason

    def type(self):
        return TestFailed.__type

    def what(self):
        return self.reason

    def __str__(self):
        return TestFailed.__type + ": " + self.reason

    def __lshift__(self, ch):
        self.reason += ch
        return self

import openturns.base
import openturns.common
import openturns.wrapper
import openturns.typ
import openturns.statistics
import openturns.graph
import openturns.func
import openturns.geom
import openturns.diff
import openturns.optim
import openturns.solver
import openturns.algo
import openturns.experiment
import openturns.model_copula
import openturns.randomvector
import openturns.dist_bundle1
import openturns.dist_bundle2
import openturns.weightedexperiment
import openturns.classification
import openturns.orthogonalbasis
import openturns.metamodel
class QuadraticCumul(openturns.common.PersistentObject):
    __swig_setmethods__ = {}
    for _s in [openturns.common.PersistentObject]: __swig_setmethods__.update(getattr(_s,'__swig_setmethods__',{}))
    __setattr__ = lambda self, name, value: _swig_setattr(self, QuadraticCumul, name, value)
    __swig_getmethods__ = {}
    for _s in [openturns.common.PersistentObject]: __swig_getmethods__.update(getattr(_s,'__swig_getmethods__',{}))
    __getattr__ = lambda self, name: _swig_getattr(self, QuadraticCumul, name)
    def getClassName(self):
        """
        Accessor to the object's name.

        Returns
        -------
        class_name : str
            The object class name (`object.__class__.__name__`).
        """
        return _uncertainty.QuadraticCumul_getClassName(self)

    def __repr__(self): return _uncertainty.QuadraticCumul___repr__(self)
    def getLimitStateVariable(self): return _uncertainty.QuadraticCumul_getLimitStateVariable(self)
    def getMeanFirstOrder(self): return _uncertainty.QuadraticCumul_getMeanFirstOrder(self)
    def getMeanSecondOrder(self): return _uncertainty.QuadraticCumul_getMeanSecondOrder(self)
    def getCovariance(self): return _uncertainty.QuadraticCumul_getCovariance(self)
    def getValueAtMean(self): return _uncertainty.QuadraticCumul_getValueAtMean(self)
    def getGradientAtMean(self): return _uncertainty.QuadraticCumul_getGradientAtMean(self)
    def getHessianAtMean(self): return _uncertainty.QuadraticCumul_getHessianAtMean(self)
    def getImportanceFactors(self): return _uncertainty.QuadraticCumul_getImportanceFactors(self)
    def drawImportanceFactors(self): return _uncertainty.QuadraticCumul_drawImportanceFactors(self)
    def __init__(self, *args): 
        this = _uncertainty.new_QuadraticCumul(*args)
        try: self.this.append(this)
        except: self.this = this
    __swig_destroy__ = _uncertainty.delete_QuadraticCumul
    __del__ = lambda self : None;
QuadraticCumul_swigregister = _uncertainty.QuadraticCumul_swigregister
QuadraticCumul_swigregister(QuadraticCumul)

class ANCOVA(_object):
    """
    ANalysis of COVAriance method (ANCOVA).

    Available constructor:
        ANCOVA(*functionalChaosResult, correlatedInput*)

    Parameters
    ----------
    functionalChaosResult : :class:`~openturns.FunctionalChaosResult`
        Functional chaos result approximating the model response with
        uncorrelated inputs.
    correlatedInput : 2D float sequence
        Correlated inputs used to compute the real values of the output.
        Its dimension must be equal to the number of inputs of the model.

    Notes
    -----
    ANCOVA, a variance-based method described in [Caniou2012]_, is a generalization
    of the ANOVA (ANalysis Of VAriance) decomposition for models with correlated
    input parameters.

    Let us consider a model :math:`Y = h(\\vect{X})` without making any hypothesis
    on the dependence structure of :math:`\\vect{X} = \\{X^1, \\ldots, X^{n_X} \\}`, a
    n_X-dimensional random vector. The covariance decomposition requires a functional
    decomposition of the model. Thus the model response :math:`Y` is expanded as a
    sum of functions of increasing dimension as follows:

    .. math::
        :label: model

        h(\\vect{X}) = h_0 + \\sum_{u\\subseteq\\{1,\\dots,n_X\\}} h_u(X_u)

    :math:`h_0` is the mean of :math:`Y`. Each function :math:`h_u` represents,
    for any non empty set :math:`u\\subseteq\\{1, \\dots, n_X\\}`, the combined
    contribution of the variables :math:`X_u` to :math:`Y`.

    Using the properties of the covariance, the variance of :math:`Y` can be
    decomposed into a variance part and a covariance part as follows:

    .. math::

        Var[Y]&= Cov\\left[h_0 + \\sum_{u\\subseteq\\{1,\\dots,n_X\\}} h_u(X_u), h_0 + \\sum_{u\\subseteq\\{1,\\dots,n_X\\}} h_u(X_u)\\right] \\\\
              &= \\sum_{u\\subseteq\\{1,\\dots,n_X\\}} \\left[Var[h_u(X_u)] + Cov[h_u(X_u), \\sum_{v\\subseteq\\{1,\\dots,n_X\\}, v\\cap u=\\varnothing} h_v(X_v)]\\right]

    This variance formula enables to define each total part of variance of
    :math:`Y` due to :math:`X_u`, :math:`S_u`, as the sum of a *physical*
    (or *uncorrelated*) part and a *correlated* part such as:

    .. math::

        S_u = \\frac{Cov[Y, h_u(X_u)]} {Var[Y]} = S_u^U + S_u^C

    where :math:`S_u^U` is the uncorrelated part of variance of Y due to :math:`X_u`:

    .. math::

        S_u^U = \\frac{Var[h_u(X_u)]} {Var[Y]}

    and :math:`S_u^C` is the contribution of the correlation of :math:`X_u` with the
    other parameters:

    .. math::

        S_u^C = \\frac{Cov\\left[h_u(X_u), \\displaystyle \\sum_{v\\subseteq\\{1,\\dots,n_X\\}, v\\cap u=\\varnothing} h_v(X_v)\\right]}
                     {Var[Y]}

    As the computational cost of the indices with the numerical model :math:`h`
    can be very high, [Caniou2012]_ suggests to approximate the model response with
    a polynomial chaos expansion:

    .. math::

        Y \\simeq \\hat{h} = \\sum_{j=0}^{P-1} \\alpha_j \\Psi_j(x)

    However, for the sake of computational simplicity, the latter is constructed
    considering *independent* components :math:`\\{X^1,\\dots,X^{n_X}\\}`. Thus the
    chaos basis is not orthogonal with respect to the correlated inputs under
    consideration, and it is only used as a metamodel to generate approximated
    evaluations of the model response and its summands :eq:`model`.

    The next step consists in identifying the component functions. For instance, for
    :math:`u = \\{1\\}`:

    .. math::

        h_1(X_1) = \\sum_{\\alpha | \\alpha_1 \\neq 0, \\alpha_{i \\neq 1} = 0} y_{\\alpha} \\Psi_{\\alpha}(\\vect{X})

    where :math:`\\alpha` is a set of degrees associated to the :math:`n_X` univariate
    polynomial :math:`\\psi_i^{\\alpha_i}(X_i)`.

    Then the model response :math:`Y` is evaluated using a sample
    :math:`X=\\{x_k, k=1,\\dots,N\\}` of the correlated joint distribution. Finally,
    the several indices are computed using the model response and its component
    functions that have been identified on the polynomial chaos.

    Examples
    --------
    >>> import openturns as ot
    >>> ot.RandomGenerator.SetSeed(0)
    >>> # Model and distribution definition
    >>> model = ot.NumericalMathFunction(['X1','X2'], ['Y'], ['4.*X1 + 5.*X2'])
    >>> distribution = ot.ComposedDistribution([ot.Normal()] * 2)
    >>> S = ot.CorrelationMatrix(2)
    >>> S[1, 0] = 0.3
    >>> R = ot.NormalCopula().GetCorrelationFromSpearmanCorrelation(S)
    >>> CorrelatedInputDistribution = ot.ComposedDistribution([ot.Normal()] * 2, ot.NormalCopula(R))
    >>> sample = CorrelatedInputDistribution.getSample(2000)
    >>> # Functional chaos computation
    >>> productBasis = ot.OrthogonalProductPolynomialFactory([ot.HermiteFactory()] * 2, ot.EnumerateFunction(2))
    >>> adaptiveStrategy = ot.FixedStrategy(productBasis, 15)
    >>> projectionStrategy = ot.LeastSquaresStrategy(ot.MonteCarloExperiment(250))
    >>> algo = ot.FunctionalChaosAlgorithm(model, distribution, adaptiveStrategy, projectionStrategy)
    >>> algo.run()
    >>> ancovaResult = ot.ANCOVA(algo.getResult(), sample)
    >>> indices = ancovaResult.getIndices()
    >>> print(indices)
    [0.411077,0.588923]
    >>> uncorrelatedIndices = ancovaResult.getUncorrelatedIndices()
    >>> print(uncorrelatedIndices)
    [0.29868,0.476527]
    >>> # Get indices measuring the correlated effects
    >>> print(indices - uncorrelatedIndices)
    [0.112397,0.112397]
    """
    __swig_setmethods__ = {}
    __setattr__ = lambda self, name, value: _swig_setattr(self, ANCOVA, name, value)
    __swig_getmethods__ = {}
    __getattr__ = lambda self, name: _swig_getattr(self, ANCOVA, name)
    __repr__ = _swig_repr
    def getUncorrelatedIndices(self, marginalIndex=0):
        """
        Accessor to the ANCOVA indices measuring uncorrelated effects.

        Parameters
        ----------
        marginalIndex : int, :math:`0 \\leq i < n`, optional
            Index of the model's marginal used to estimate the indices.
            By default, marginalIndex is equal to 0.

        Returns
        -------
        indices : float sequence
            List of the ANCOVA indices measuring uncorrelated effects of the inputs.
            The effects of the correlation are represented by the indices resulting
            from the subtraction of the :meth:`getIndices` and
            :meth:`getUncorrelatedIndices` lists.
        """
        return _uncertainty.ANCOVA_getUncorrelatedIndices(self, marginalIndex)

    def getIndices(self, marginalIndex=0):
        """
        Accessor to the ANCOVA indices.

        Parameters
        ----------
        marginalIndex : int, :math:`0 \\leq i < n`, optional
            Index of the model's marginal used to estimate the indices.
            By default, marginalIndex is equal to 0.

        Returns
        -------
        indices : float sequence
            List of the ANCOVA indices measuring the contribution of the
            input variables to the variance of the model. These indices are made up
            of a *physical* part and a *correlated* part. The first one is obtained
            thanks to :meth:`getUncorrelatedIndices`.
            The effects of the correlation are represented by the indices resulting
            from the subtraction of the :meth:`getIndices` and
            :meth:`getUncorrelatedIndices` lists.
        """
        return _uncertainty.ANCOVA_getIndices(self, marginalIndex)

    def __init__(self, *args): 
        this = _uncertainty.new_ANCOVA(*args)
        try: self.this.append(this)
        except: self.this = this
    __swig_destroy__ = _uncertainty.delete_ANCOVA
    __del__ = lambda self : None;
ANCOVA_swigregister = _uncertainty.ANCOVA_swigregister
ANCOVA_swigregister(ANCOVA)

class FAST(_object):
    """
    Fourier Amplitude Sensitivity Testing (FAST).

    Available constructor:
        FAST(*model, distribution, N, Nr=1, M=4*)

    Parameters
    ----------
    model : :class:`~openturns.NumericalMathFunction`
        Definition of the model to analyse.
    distribution : :class:`~openturns.Distribution`
        Contains the distributions of each model's input.
        Its dimension must be equal to the number of inputs.
    N : int, :math:`N > Nr`
        Size of the sample from which the Fourier series are calculated.
        It represents the length of the discretization of the s-space.
    Nr : int, :math:`Nr \\geq 1`
        Number of resamplings. The extended FAST method involves a part of
        randomness in the computation of the indices. So it can be asked to
        realize the procedure *Nr* times and then to calculate the
        arithmetic means of the results over the *Nr* estimates.
    M : int, :math:`0 < M < N`
        Interference factor usually equal to 4 or higher.
        It corresponds to the truncation level of the Fourier series, i.e. the
        number of harmonics that are retained in the decomposition.

    Notes
    -----
    FAST is a sensitivity analysis method which is based upon the ANOVA
    decomposition of the variance of the model response :math:`y = f(\\vect{X})`,
    the latter being represented by its Fourier expansion.
    :math:`\\vect{X}=\\{X^1,\\dots,X^{n_X}\\}` is an input random vector of :math:`n_X`
    independent components.

    OpenTURNS implements the extended FAST method consisting in computing
    alternately the first order and the total-effect indices of each input.
    This approach, widely described in the paper by [Saltelli1999]_, relies upon a
    Fourier decomposition of the model response. Its key idea is to recast this
    representation as a function of a *scalar* parameter :math:`s`, by defining
    parametric curves :math:`s \\mapsto x_i(s), i=1, \\dots, n_X` exploring the
    support of the input random vector :math:`\\vect{X}`.

    Then the Fourier expansion of the model response is:

    .. math::

        f(s) = \\sum_{k \\in \\Zset^N} A_k cos(ks) + B_k sin(ks)

    where :math:`A_k` and :math:`B_k` are Fourier coefficients whose estimates are:

    .. math::

        \\hat{A}_k &= \\frac{1}{N} \\sum_{j=1}^N f(x_j^1,\\dots,x_j^{N_X}) cos\\left(\\frac{2k\\pi (j-1)}{N} \\right) \\quad , \\quad -\\frac{N}{2} \\leq k \\leq \\frac{N}{2} \\\\
        \\hat{B}_k &= \\frac{1}{N} \\sum_{j=1}^N f(x_j^1,\\dots,x_j^{N_X}) sin\\left(\\frac{2k\\pi (j-1)}{N} \\right) \\quad , \\quad -\\frac{N}{2} \\leq k \\leq \\frac{N}{2}


    The first order indices are estimated by:

    .. math::

        \\hat{S}_i = \\frac{\\hat{D}_i}{\\hat{D}}
                  = \\frac{\\sum_{p=1}^M(\\hat{A}_{p\\omega_i}^2 + \\hat{B}_{p\\omega_i}^2)^2}
                          {\\sum_{n=1}^{(N-1)/2}(\\hat{A}_n^2 + \\hat{B}_n^2)^2}

    and the total order indices by:

    .. math::

        \\hat{T}_i = 1 - \\frac{\\hat{D}_{-i}}{\\hat{D}}
                  = 1 - \\frac{\\sum_{k=1}^{\\omega_i/2}(\\hat{A}_k^2 + \\hat{B}_k^2)^2}
                              {\\sum_{n=1}^{(N-1)/2}(\\hat{A}_n^2 + \\hat{B}_n^2)^2}

    where :math:`\\hat{D}` is the total variance, :math:`\\hat{D}_i` the portion
    of :math:`D` arising from the uncertainty of the :math:`i^{th}` input and
    :math:`\\hat{D}_{-i}` is the part of the variance due to all the inputs
    except the :math:`i^{th}` input.

    :math:`N` is the size of the sample using to compute the Fourier series and
    :math:`M` is the interference factor. *Saltelli et al.* (1999) recommanded to
    set :math:`M` to a value in the range :math:`[4, 6]`.
    :math:`\\{\\omega_i\\}, \\forall i=1, \\dots, n_X` is a set of integer frequencies
    assigned to each input :math:`X^i`. The frequency associated with the input
    for which the sensitivity indices are computed, is set to the maximum admissible
    frequency satisfying the Nyquist criterion (which ensures to avoid aliasing effects):

    .. math::

        \\omega_i = \\frac{N - 1}{2M}

    In the paper by Saltelli et al. (1999), for high sample size, it is suggested
    that :math:`16 \\leq \\omega_i/N_r \\leq 64`.


    Examples
    --------
    >>> import openturns as ot
    >>> ot.RandomGenerator.SetSeed(0)
    >>> formulaIshigami = ['sin(_pi*X1)+7*sin(_pi*X2)*sin(_pi*X2)+0.1*((_pi*X3)*(_pi*X3)*(_pi*X3)*(_pi*X3))*sin(_pi*X1)']
    >>> modelIshigami = ot.NumericalMathFunction(['X1', 'X2', 'X3'], ['y'], formulaIshigami)
    >>> distributions = ot.ComposedDistribution([ot.Uniform(-1.0, 1.0)] * 3)
    >>> sensitivityAnalysis = ot.FAST(modelIshigami, distributions, 400)
    >>> print(sensitivityAnalysis.getFirstOrderIndices())
    [0.307461,0.442524,4.18878e-07]
    """
    __swig_setmethods__ = {}
    __setattr__ = lambda self, name, value: _swig_setattr(self, FAST, name, value)
    __swig_getmethods__ = {}
    __getattr__ = lambda self, name: _swig_getattr(self, FAST, name)
    __repr__ = _swig_repr
    def getFirstOrderIndices(self, marginalIndex=0):
        """
        Accessor to the first order indices.

        Parameters
        ----------
        marginalIndex : int, :math:`0 \\leq i < n`, optional
            Index of the model's marginal used to estimate the indices.
            By default, marginalIndex is equal to 0.

        Returns
        -------
        indices : float sequence
            List of the first order indices of all the inputs.
        """
        return _uncertainty.FAST_getFirstOrderIndices(self, marginalIndex)

    def getTotalOrderIndices(self, marginalIndex=0):
        """
        Accessor to the total order indices.

        Parameters
        ----------
        marginalIndex : int, :math:`0 \\leq i < n`, optional
            Index of the model's  marginal used to estimate the indices.
            By default, marginalIndex is equal to 0.

        Returns
        -------
        indices : float sequence
            List of the total-effect order indices of all the inputs.
        """
        return _uncertainty.FAST_getTotalOrderIndices(self, marginalIndex)

    def getFFTAlgorithm(self):
        """
        Accessor to the FFT algorithm implementation.

        Returns
        -------
        fft : a :class:`~openturns.FFT`
            A FFT algorithm.
        """
        return _uncertainty.FAST_getFFTAlgorithm(self)

    def setFFTAlgorithm(self, *args):
        """
        Accessor to the FFT algorithm implementation.

        Parameters
        ----------
        fft : a :class:`~openturns.FFT`
            A FFT algorithm.
        """
        return _uncertainty.FAST_setFFTAlgorithm(self, *args)

    def __init__(self, *args): 
        this = _uncertainty.new_FAST(*args)
        try: self.this.append(this)
        except: self.this = this
    __swig_destroy__ = _uncertainty.delete_FAST
    __del__ = lambda self : None;
FAST_swigregister = _uncertainty.FAST_swigregister
FAST_swigregister(FAST)

import openturns.transformation
import openturns.analytical
import openturns.simulation
import openturns.stattests
import openturns.model_process
# This file is compatible with both classic and new-style classes.