Chaos: Add missing docstrings

python/src/AdaptiveStrategyImplementation_doc.i.in

@@ -74,7 +74,7 @@ OT_AdaptiveStrategy_getBasis_doc
 
 Returns
 -------
-P : integer
+maximumDimension : int
     Maximum dimension of the truncated basis."
 
 %enddef
@@ -115,7 +115,7 @@ OT_AdaptiveStrategy_getPsi_doc
 
 Parameters
 ----------
-P : integer
+maximumDimension : int
     Maximum dimension of the truncated basis."
 
 %enddef

python/src/CleaningStrategy_doc.i.in

@@ -16,46 +16,62 @@ maximumDimension : positive int
     to determine the last term of the basis.
 maximumSize : positive int
     Parameter that characterizes the cleaning strategy. It represents the 
-    number of efficient coefficients of the basis. Its default value is set to 
-    20.
+    number of efficient coefficients of the basis.
+    Its default value is the `CleaningStrategy-DefaultMaximumSize` key of
+    the :class:`~openturns.ResourceMap`.
 significanceFactor : float 
-    Parameter used as a threshold for selecting the efficient coefficients of
-    the basis. The real threshold represents the multiplication of the
-    significanceFactor with the maximum magnitude of the current determined 
-    coefficients. Its default value is equal to :math:`1e^{-4}`.
-
+    Parameter used as a threshold factor for selecting the efficient coefficients of
+    the basis. The actual threshold is the product of the
+    *significanceFactor* with the maximum magnitude of the current
+    coefficients.
+    Its default value is the `CleaningStrategy-DefaultSignificanceFactor` key of
+    the :class:`~openturns.ResourceMap`.
+verbose : bool
+    Used for the online monitoring of the current basis updates (removed or
+    added coefficients).
 
 See also
 --------
 AdaptiveStrategy, FixedStrategy
 
 Notes
 -----
-The cleaning strategy aims at building a PC expansion containing at most
-:math:`P` significant coefficients, i.e. at most :math:`P` significant basis
-functions. It proceeds as follows:
-
-- Generate an initial PC basis made of the :math:`P` first polynomials
+The cleaning strategy aims at building a PC expansion containing
+only a subset of the coefficients of the full expansion.
+Hence, this strategy can lead to a sparse expansion which can
+limit the chances of potential surrogate model overfitting.
+
+Let *maximumDimension* be the number of coefficients in the full expansion
+and let *maximumSize* be the maximum number of coefficients defined
+by the user.    
+On output, at most the minimum of *maximumDimension* and *maximumSize*
+coefficients are selected.
+Let :math:`\epsilon` be the value of the *significanceFactor*.
+The method proceeds as follows:
+
+- Generate an initial PC basis made of the *maximumDimension* first polynomials
   (according to the adopted :class:`~openturns.EnumerateFunction`), or
-  equivalently an initial set of indices :math:`K = \{0, \ldots, P-1\}`.
+  equivalently an initial set of indices :math:`\cK = \{0, \ldots, \textrm{maximumDimension} - 1\}`.
 
-- Discard from the basis all those polynomials :math:`\Psi_j` associated with 
-  insignificance coefficients, i.e. the coefficients that satisfy:
+- Discard from the basis any polynomial :math:`\Psi_j` associated with 
+  an insignificant coefficient, i.e. such that:
 
 .. math::
 
-    |a_j| \leq \epsilon \times \max_{ k \in K, k \neq 0 } |a_k|
-
-where :math:`\epsilon` is the significance factor, default is
-:math:`\epsilon = 10^{-4}`.
+    |a_j| \leq \epsilon \times \max_{ k \in \cK, k \neq 0 } |a_k|.
 
-- Add the next basis term :math:`\Psi_{k+1}` to the current basis :math:`K`.
-- Reiterate the procedure until either :math:`P` terms have been retained or if
-  the given maximum index :math:`P_{max}` has been reached.
+- Add the next basis term :math:`\Psi_{k+1}` to the current basis :math:`\cK`.
+- Reiterate the procedure until the minimum of *maximumDimension* and
+  *maximumSize* has been reached.
 
 
 Examples
 --------
+In the next example, we select, among the `maximumDimension = 100` first polynomials of
+the multivariate basis, those which have the `maximumSize = 20` most
+significant contribution (greatest absolute value of the coefficients), with respect to the
+significance factor :math:`10^{-4}`.
+
 >>> import openturns as ot
 >>> ot.RandomGenerator.SetSeed(0)
 >>> # Define the model
@@ -69,16 +85,12 @@ Examples
 ...     polyColl[i] = ot.StandardDistributionPolynomialFactory(distribution.getMarginal(i))
 >>> enumerateFunction = ot.LinearEnumerateFunction(inputDim)
 >>> productBasis = ot.OrthogonalProductPolynomialFactory(polyColl, enumerateFunction)
->>> # Truncature strategy of the multivariate orthonormal basis
->>> # We want to select, among the maximumDimension = 100 first polynomials of
->>> # the multivariate basis, those which have the maximumSize = 20 most 
->>> # significant contribution (greatest coefficients), with respect to the 
->>> # significance factor = 10^-4.
 >>> maximumDimension = 100
 >>> maximumSize = 20
 >>> significanceFactor = 1e-4
->>> adaptiveStrategy = ot.CleaningStrategy(productBasis, maximumDimension,
-...                                          maximumSize, significanceFactor)"
+>>> adaptiveStrategy = ot.CleaningStrategy(
+...     productBasis, maximumDimension, maximumSize, significanceFactor
+... )"
 
 // ---------------------------------------------------------------------
 
@@ -97,7 +109,7 @@ index : integer
 
 Returns
 -------
-size : integer
+maximumSize : int
     Maximum number of significant terms of the basis.
 
 See also
@@ -111,7 +123,7 @@ setMaximumSize"
 
 Returns
 -------
-factor : float
+significanceFactor : float
     Value of the significance factor.
 
 See also
@@ -125,7 +137,7 @@ setSignificanceFactor"
 
 Parameters
 ----------
-size : integer
+maximumSize : int
     Maximum number of significant terms of the basis.
 
 See also
@@ -139,10 +151,57 @@ getMaximumSize"
 
 Parameters
 ----------
-factor : float
+significanceFactor : float
     Value of the significance factor.
 
 See also
 --------
 getSignificanceFactor"
 
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::CleaningStrategy::updateBasis
+"Update the basis for the next iteration of approximation.
+
+In this strategy, the *residual* and the *relativeError* input arguments
+are ignored.
+
+Parameters
+----------
+alpha_k : sequence of floats
+    The coefficients of the expansion at this step.
+residual : float
+    The current value of the residual. Ignored.
+relativeError : float
+    The relative error. Ignored.
+
+Examples
+--------
+>>> import openturns as ot
+>>> dimension = 3
+>>> enumerateFunction = ot.LinearEnumerateFunction(dimension)
+>>> productBasis = ot.OrthogonalProductPolynomialFactory(
+...     [ot.LegendreFactory()] * dimension, enumerateFunction
+... )
+>>> degree = 6
+>>> basisSize = enumerateFunction.getBasisSizeFromTotalDegree(degree)
+>>> maximumDimension = 100
+>>> maximumSize = 20
+>>> significanceFactor = 1e-4
+>>> adaptiveStrategy = ot.CleaningStrategy(
+...     productBasis, maximumDimension, maximumSize, significanceFactor
+... )
+>>> adaptiveStrategy.computeInitialBasis()
+>>> print(adaptiveStrategy.getCurrentVectorIndex())
+20
+>>> psi = adaptiveStrategy.getPsi()
+>>> print(len(psi))
+20
+>>> alpha_k = [3.5, 0.1, 0.0, -0.2, 0.0, 0.3, 0.0, -0.4, 0.0, -0.5]
+>>> residual = 0.0  # Ignored
+>>> relativeError = 0.0  # Ignored
+>>> adaptiveStrategy.updateBasis(alpha_k, residual, relativeError)
+>>> psi = adaptiveStrategy.getPsi()
+>>> print(len(psi))
+7"

python/src/FixedStrategy_doc.i.in

@@ -17,22 +17,24 @@ AdaptiveStrategy, CleaningStrategy
 
 Notes
 -----
-The so-called fixed strategy simply consists in retaining the first :math:`P`
+The so-called fixed strategy simply consists in selecting the first :math:`P`
 elements of the PC basis, the latter being ordered according to a given
 :class:`~openturns.EnumerateFunction` (hyperbolic or not). The retained set is
 built in a single pass. The truncated PC expansion is given by:
 
 .. math::
 
-    \hat{h} (\uX) = \sum_{j=0}^{P-1} \vect{a}_j \Psi_j (\uX)
+    \widehat{h} (\uZ) = \sum_{j=0}^{P-1} \vect{a}_j \Psi_j (\uZ)
 
 In case of a :class:`~openturns.LinearEnumerateFunction`, for a given natural
-integer :math:`p`, a usual choice is to set :math:`P` equals to:
+integer :math:`p` representing the total polynomial degree, the number of
+coefficients is equal to:
 
 .. math::
 
     P = \binom{n_X + p}{p} = \frac{(n_X + p)!}{n_X!\,p!}
 
+where :math:`n_X` is the input dimension.
 This way the set of retained basis functions :math:`\{\Psi_j, j = 0, \ldots, P-1\}`
 gathers all the polynomials with total degree not greater than :math:`p`.
 The number of terms :math:`P` grows polynomially both in :math:`n_X` and :math:`p`
@@ -63,3 +65,21 @@ Examples
 >>> # We keep all the polynomials of degree <= 4
 >>> # which corresponds to the 5 first ones
 >>> adaptiveStrategy = ot.FixedStrategy(productBasis, indexMax)"
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::FixedStrategy::updateBasis
+"Update the basis for the next iteration of approximation.
+
+No changes are made to the basis in the fixed strategy.
+Hence, the number of functions in the basis is equal to *dimension*,
+whatever the number of calls to the *updateBasis* method.
+
+Parameters
+----------
+alpha_k : sequence of floats
+    The coefficients of the expansion at this step.
+residual : float
+    The current value of the residual.
+relativeError : float
+    The relative error."

python/src/IntegrationStrategy_doc.i.in

@@ -21,14 +21,19 @@ measure : :class:`~openturns.Distribution`
     Distribution :math:`\mu` with respect to which the basis is orthonormal.
     When not precised, OpenTURNS uses the limit measure defined within the
     :class:`~openturns.WeightedExperiment`.
-inputSample, outputSample : 2-d sequence of float
-    The input random variables :math:`\vect{X}=(X_1, \dots, X_{n_X})^T`
-    and the output samples :math:`\vect{Y}` that describe the model.
+inputSample : 2-d sequence of float
+    The input random observations :math:`\left\{\vect{X}^{(1)}, ..., \vect{X}^{(n)}\right\}` 
+    where :math:`\vect{X}=(X_1, \dots, X_{n_X})^T` is the input of the physical
+    model, :math:`n_X` is the input dimension and :math:`n` is the sample size.
+outputSample : 2-d sequence of float
+    The output random observations :math:`\left\{\vect{Y}^{(1)}, ..., \vect{Y}^{(n)}\right\}` 
+    where :math:`\vect{Y}=(Y_1, \dots, Y_{n_Y})^T` is the output of the physical
+    model, :math:`n_Y` is the output dimension and :math:`n` is the sample size.
 weights : sequence of float
     Numerical point that are the weights associated to the input sample points
     such that the corresponding weighted experiment is a good approximation of
-    :math:`\mu`. If not precised, all weights are equals to 
-    :math:`\omega_i = \frac{1}{size}`, where :math:`size` is the size of the
+    :math:`\mu`. If not provided, all weights are equal to 
+    :math:`\omega_i = \frac{1}{n}`, where :math:`n` is the size of the
     sample.
 
 See also

python/src/LeastSquaresMetaModelSelection_doc.i.in

@@ -10,3 +10,43 @@ ApproximationAlgorithm, PenalizedLeastSquaresAlgorithm
 Notes
 -----
 The LeastSquaresMetaModelSelection is built from a :class:`~openturns.LeastSquaresMetaModelSelectionFactory`."
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::LeastSquaresMetaModelSelection::getBasisSequenceFactory
+"Accessor to the basis sequence factory.
+
+Returns
+-------
+basisSequenceFactory : :class:`~openturns.BasisSequenceFactory`
+    Basis sequence factory."
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::LeastSquaresMetaModelSelection::setBasisSequenceFactory
+"Set the basis sequence factory.
+
+Parameters
+----------
+basisSequenceFactory : :class:`~openturns.BasisSequenceFactory`
+    Basis sequence factory."
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::LeastSquaresMetaModelSelection::getFittingAlgorithm
+"Accessor to the fitting algorithm.
+
+Returns
+-------
+fittingAlgorithm : :class:`~openturns.FittingAlgorithm`
+    Fitting algorithm."
+
+// ---------------------------------------------------------------------
+
+%feature("docstring") OT::LeastSquaresMetaModelSelection::setFittingAlgorithm
+"Set the fitting algorithm.
+
+Parameters
+----------
+fittingAlgorithm : :class:`~openturns.FittingAlgorithm`
+    Fitting algorithm."

python/src/LinearModelAlgorithm_doc.i.in

@@ -88,13 +88,15 @@ In this case, the Cholesky method may fail to produce accurate results.
 Examples
 --------
 >>> import openturns as ot
->>> distribution = ot.Normal()
->>> func = ot.SymbolicFunction(['x1','x2', 'x3'], ['x1 + x2 + sin(x2 * 2 * pi_)/5 + 1e-3 * x3^2'])
+>>> func = ot.SymbolicFunction(
+...     ['x1', 'x2', 'x3'],
+...     ['x1 + x2 + sin(x2 * 2 * pi_)/5 + 1e-3 * x3^2']
+... )
 >>> dimension = 3
->>> distribution = ot.JointDistribution([ot.Normal()]*dimension)
->>> input_sample = distribution.getSample(20)
->>> output_sample = func(input_sample)
->>> algo = ot.LinearModelAlgorithm(input_sample, output_sample)
+>>> distribution = ot.JointDistribution([ot.Normal()] * dimension)
+>>> inputSample = distribution.getSample(20)
+>>> outputSample = func(inputSample)
+>>> algo = ot.LinearModelAlgorithm(inputSample, outputSample)
 >>> algo.run()
 >>> result = algo.getResult()"
 

python/src/PenalizedLeastSquaresAlgorithmFactory_doc.i.in

@@ -13,5 +13,5 @@ Notes
 Implementation of an approximation algorithm implementation factory which builds
 an :class:`~openturns.ApproximationAlgorithm`.
 
-This class is not usable because it has sense only within the
-:class:`~openturns.FunctionalChaosAlgorithm`."
+This class is not usable because it operates only within the
+:class:`~openturns.FunctionalChaosAlgorithm`."

python/src/PenalizedLeastSquaresAlgorithm_doc.i.in

@@ -12,10 +12,14 @@ Available constructors:
 
 Parameters
 ----------
-x : :class:`~openturns.Sample`
-    Input sample
-y : :class:`~openturns.Sample`
-    Output sample
+x : 2-d sequence of float
+    The input random observations :math:`\left\{\vect{x}^{(1)}, ..., \vect{x}^{(n)}\right\}` 
+    where :math:`\vect{x} = \Tr{\left(x_1, \dots, x_{n_X}\right)}` is the input of the physical
+    model, :math:`n_X \in \Nset` is the input dimension and :math:`n \in \Nset` is the sample size.
+y : 2-d sequence of float
+    The output random observations :math:`\left\{\vect{y}^{(1)}, ..., \vect{y}^{(n)}\right\}` 
+    where :math:`\vect{y} = \Tr{\left(y_1, \dots, y_{n_Y}\right)}` is the output of the physical
+    model, :math:`n_Y \in \Nset` is the output dimension and :math:`n \in \Nset` is the sample size.
 weight : sequence of float
     Output weights
 psi : sequence of :class:`~openturns.Function`
@@ -35,9 +39,16 @@ ApproximationAlgorithm, LeastSquaresMetaModelSelection
 
 Notes
 -----
-Solve the least-squares problem:
+For each output marginal :math:`k \in \{1, ..., n_Y\}`,
+solve the least-squares problem:
 
 .. math::
 
-    \vect{a} = \argmin_{\vect{b} \in \Rset^P} ||y - \vect{b}^{\intercal} \vect{\Psi}(\vect{U})||^2
-"
+    \widehat{\vect{a}} = \argmin_{\vect{a} \in \Rset^P} \left\|\vect{y}_k - \Tr{\mat{\Psi}} \vect{a} \right\|^2
+
+where :math:`\vect{y}_k \in \Rset^{n}` is the :math:`k`-th marginal of the
+sample of output observations,
+:math:`P \in \Nset` is the number of coefficients,
+:math:`\mat{\Psi} \in \Rset^{n \times P}` is the design matrix
+computed from the input sample *x* and
+:math:`\vect{a} \in \Rset^P` is the vector of coefficients."