refactor orthogonal->expansion

Author: jonathf

CHANGELOG.rst

@@ -1,6 +1,44 @@
 Master Branch
 =============
 
+Version 4.3.1 (2021-03-18)
+==========================
+
+Refactoring `orthogonal -> expansion` module.
+
+ADDED:
+  * Dedicated classical orthogonal expansion schemes:
+    `chaospy.expansion.{chebyshev_1,chebyshev_2,gegenbauer,hermite,jacobi,laguerre,legendre}`
+CHANGED:
+  * Function renames:
+    `chaospy.{orth_ttr,orth_chol,orth_gs,lagrange_polynomial} ->
+    chaospy.expansion.{stieltjes,cholesky,gram_schmidt,lagrange}`
+  * Docs update.
+
+Version 4.3.0 (2021-01-20)
+==========================
+
+Refactoring `quadrature` module.
+
+ADDED:
+  * `chaospy.quadrature.fejer_1` is added.
+  * Dedicated classical quadrature schemes:
+    `chaospy.quadrature.{chebyshev,gegenbauer,hermite,jacobi,laguerre,legendre}`
+CHANGED:
+  * Bound checks for the triangle distribution. (Thanks to @yoelcortes.)
+  * Refactored hypercube quadrature to common backend. This gives lots of flags
+    like `seqments` and
+  * Function renames:
+    `chaospy.quad_{clenshaw_curtis,discrete,fejer,gaussian,grid,gauss_lengendre,gauss_kronrod,gauss_lobatto,gauss_patterson,gauss_radau} ->
+    chaospy.quadrature.{clenshaw_curtis,fejer_2,gaussian,grid,legendre_proxy,kronrod,lobatto,patterson,radau}`
+  * Patterson growth rule changed from `0, 3, 7, ...` to `0, 1, 2, ...` but
+    maps backwards. Defaults to not have growth parameter, as setting it false
+    makes no sense.
+  * Renamed: `chaospy.generate_sparse_grid -> chaospy.quadrature.sparse_grid`
+REMOVED:
+  * Genz-Keister quadrature `quad_genz_keister` is deprecated as it does not
+    fit the `chaospy` scheme very well.
+
 Version 4.2.4 (2021-02-23)
 ==========================
 

chaospy/__init__.py

@@ -12,15 +12,15 @@
 
 import chaospy.descriptives
 import chaospy.distributions
-import chaospy.orthogonal
+import chaospy.expansion
 import chaospy.spectral
 import chaospy.quadrature
 import chaospy.saltelli
 import chaospy.regression
 import chaospy.recurrence
 
 from chaospy.distributions import *
-from chaospy.orthogonal import *
+from chaospy.expansion import *
 from chaospy.spectral import *
 from chaospy.quadrature import *
 from chaospy.saltelli import *

chaospy/distributions/approximation.py

@@ -171,12 +171,12 @@ def approximate_moment(
         k_loc (Sequence[int, ...]):
             The exponents of the moments of interest with ``shape == (dim,)``.
         order (int):
-            The quadrature order used in approximation. If omitted, calculated
-            to be ``1000/log2(len(distribution)+1)``.
+            The quadrature order used in approximation. If omitted, defaults to
+            ``1e5**(1./len(distribution))``.
         rule (str):
             Quadrature rule for integrating moments.
         kwargs:
-            Extra args passed to `chaospy.generate_quadrature`.
+            Extra args passed to :func:`chaospy.generate_quadrature`.
 
     Examples:
         >>> distribution = chaospy.Uniform(1, 4)

chaospy/distributions/operators/joint.py

@@ -225,18 +225,3 @@ def _cache(self, idx, cache):
         if isinstance(out, chaospy.Distribution):
             return self
         return out
-
-
-# def J(*args, **kwargs):
-#     """
-#     Joint random variable.
-
-#     Too be deprecated, use `chaospy.J` instead.
-
-#     Args:
-#         args (chaospy.Distribution):
-#             Distribution to join together.
-#     """
-#     logger = logging.getLogger(__name__)
-#     logger.warning("DepricationWarning: J to be replaced with Joint.")
-#     return Joint(*args, **kwargs)

chaospy/distributions/sampler/sequences/chebyshev.py

@@ -49,7 +49,7 @@
 
 def create_chebyshev_samples(order, dim=1):
     """
-    Chebyshev sampling function.
+    Generate Chebyshev pseudo-random samples.
 
     Args:
         order (int):
@@ -60,6 +60,16 @@ def create_chebyshev_samples(order, dim=1):
     Returns:
         samples following Chebyshev sampling scheme mapped to the
         ``[0, 1]^dim`` hyper-cube and ``shape == (dim, order)``.
+
+    Examples:
+        >>> samples = chaospy.create_chebyshev_samples(6, 1)
+        >>> samples.round(4)
+        array([[0.0495, 0.1883, 0.3887, 0.6113, 0.8117, 0.9505]])
+        >>> samples = chaospy.create_chebyshev_samples(3, 2)
+        >>> samples.round(3)
+        array([[0.146, 0.146, 0.146, 0.5  , 0.5  , 0.5  , 0.854, 0.854, 0.854],
+               [0.146, 0.5  , 0.854, 0.146, 0.5  , 0.854, 0.146, 0.5  , 0.854]])
+
     """
     x_data = .5*numpy.cos(numpy.arange(order, 0, -1)*numpy.pi/(order+1)) + .5
     x_data = utils.combine([x_data]*dim)

chaospy/distributions/sampler/sequences/halton.py

@@ -1,30 +1,4 @@
-"""
-Create samples from the `Halton sequence`_.
-
-In statistics, Halton sequences are sequences used to generate points in space
-for numerical methods such as Monte Carlo simulations. Although these sequences
-are deterministic, they are of low discrepancy, that is, appear to be random
-for many purposes. They were first introduced in 1960 and are an example of
-a quasi-random number sequence. They generalise the one-dimensional van der
-Corput sequences.
-
-Example usage
--------------
-
-Standard usage::
-
-    >>> distribution = chaospy.J(chaospy.Uniform(0, 1), chaospy.Uniform(0, 1))
-    >>> samples = distribution.sample(3, rule="halton")
-    >>> samples.round(4)
-    array([[0.125 , 0.625 , 0.375 ],
-           [0.4444, 0.7778, 0.2222]])
-    >>> samples = distribution.sample(4, rule="halton")
-    >>> samples.round(4)
-    array([[0.125 , 0.625 , 0.375 , 0.875 ],
-           [0.4444, 0.7778, 0.2222, 0.5556]])
-
-.. _Halton sequence: https://en.wikipedia.org/wiki/Halton_sequence
-"""
+"""Create samples from the Halton sequence."""
 import numpy
 
 from .van_der_corput import create_van_der_corput_samples
@@ -33,9 +7,15 @@
 
 def create_halton_samples(order, dim=1, burnin=-1, primes=()):
     """
-    Create Halton sequence.
+    Create samples from the Halton sequence.
 
-    For ``dim == 1`` the sequence falls back to Van Der Corput sequence.
+    In statistics, Halton sequences are sequences used to generate points in
+    space for numerical methods such as Monte Carlo simulations. Although these
+    sequences are deterministic, they are of low discrepancy, that is, appear
+    to be random for many purposes. They were first introduced in 1960 and are
+    an example of a quasi-random number sequence. They generalise the
+    one-dimensional van der Corput sequences. For ``dim == 1`` the sequence
+    falls back to Van Der Corput sequence.
 
     Args:
         order (int):
@@ -49,8 +29,21 @@ def create_halton_samples(order, dim=1, burnin=-1, primes=()):
             The (non-)prime base to calculate values along each axis. If
             empty, growing prime values starting from 2 will be used.
 
-    Returns (numpy.ndarray):
-        Halton sequence with ``shape == (dim, order)``.
+    Returns:
+        (numpy.ndarray):
+            Halton sequence with ``shape == (dim, order)``.
+
+    Examples:
+        >>> distribution = chaospy.J(chaospy.Uniform(0, 1), chaospy.Uniform(0, 1))
+        >>> samples = distribution.sample(3, rule="halton")
+        >>> samples.round(4)
+        array([[0.125 , 0.625 , 0.375 ],
+               [0.4444, 0.7778, 0.2222]])
+        >>> samples = distribution.sample(4, rule="halton")
+        >>> samples.round(4)
+        array([[0.125 , 0.625 , 0.375 , 0.875 ],
+               [0.4444, 0.7778, 0.2222, 0.5556]])
+
     """
     primes = list(primes)
     if not primes:

chaospy/distributions/sampler/sequences/hammersley.py

@@ -1,26 +1,4 @@
-"""
-Create samples from the `Hammersley set`_.
-
-The Hammersley set is equivalent to the Halton sequence, except for one
-dimension is replaced with a regular grid.
-
-Example usage
--------------
-
-Standard usage::
-
-    >>> distribution = chaospy.J(chaospy.Uniform(0, 1), chaospy.Uniform(0, 1))
-    >>> samples = distribution.sample(3, rule="hammersley")
-    >>> samples.round(4)
-    array([[0.75 , 0.125, 0.625],
-           [0.25 , 0.5  , 0.75 ]])
-    >>> samples = distribution.sample(4, rule="hammersley")
-    >>> samples.round(4)
-    array([[0.75 , 0.125, 0.625, 0.375],
-           [0.2  , 0.4  , 0.6  , 0.8  ]])
-
-.. _Hammersley set: https://en.wikipedia.org/wiki/Low-discrepancy_sequence#Hammersley_set
-"""
+"""Create samples from the Hammersley set."""
 import numpy
 
 from .halton import create_halton_samples
@@ -30,7 +8,8 @@ def create_hammersley_samples(order, dim=1, burnin=-1, primes=()):
     """
     Create samples from the Hammersley set.
 
-    For ``dim == 1`` the sequence falls back to Van Der Corput sequence.
+    The Hammersley set is equivalent to the Halton sequence, except for one
+    dimension is replaced with a regular grid.
 
     Args:
         order (int):
@@ -47,6 +26,18 @@ def create_hammersley_samples(order, dim=1, burnin=-1, primes=()):
     Returns:
         (numpy.ndarray):
             Hammersley set with ``shape == (dim, order)``.
+
+    Examples:
+        >>> distribution = chaospy.J(chaospy.Uniform(0, 1), chaospy.Uniform(0, 1))
+        >>> samples = distribution.sample(3, rule="hammersley")
+        >>> samples.round(4)
+        array([[0.75 , 0.125, 0.625],
+               [0.25 , 0.5  , 0.75 ]])
+        >>> samples = distribution.sample(4, rule="hammersley")
+        >>> samples.round(4)
+        array([[0.75 , 0.125, 0.625, 0.375],
+               [0.2  , 0.4  , 0.6  , 0.8  ]])
+
     """
     if dim == 1:
         return create_halton_samples(

chaospy/distributions/sampler/sequences/sobol.py

@@ -1,10 +1,5 @@
 """
-
-Example usage
--------------
-
-Standard usage::
-
+Generates samples from the Sobol sequence.
 
 Papers::
 
@@ -35,7 +30,6 @@
     Preprint IPM Akad. Nauk SSSR,
     Number 40, Moscow 1976.
 
-.. _Sobel sequence: https://en.wikipedia.org/wiki/Sobol_sequence
 """
 import math
 

chaospy/distributions/sampler/sequences/van_der_corput.py

@@ -1,36 +1,20 @@
-"""
-Create `Van Der Corput` low discrepancy sequence samples.
-
-A van der Corput sequence is an example of the simplest one-dimensional
-low-discrepancy sequence over the unit interval; it was first described in 1935
-by the Dutch mathematician J. G. van der Corput. It is constructed by reversing
-the base-n representation of the sequence of natural numbers (1, 2, 3, ...).
-
-In practice, use Halton sequence instead of Van Der Corput, as it is the
-same, but generalized to work in multiple dimensions.
-
-Example usage
--------------
-
-Using base 10::
-
-    >>> create_van_der_corput_samples(range(11), number_base=10)
-    array([0.1 , 0.2 , 0.3 , 0.4 , 0.5 , 0.6 , 0.7 , 0.8 , 0.9 , 0.01, 0.11])
-
-Using base 2::
-
-    >>> create_van_der_corput_samples(range(8), number_base=2)
-    array([0.5   , 0.25  , 0.75  , 0.125 , 0.625 , 0.375 , 0.875 , 0.0625])
-
-.. Van Der Corput: https://en.wikipedia.org/wiki/Van_der_Corput_sequence
-"""
+"""Create Van Der Corput low discrepancy sequence samples."""
 from __future__ import division
 import numpy
 
 
 def create_van_der_corput_samples(idx, number_base=2):
     """
-    Van der Corput samples.
+    Create Van Der Corput low discrepancy sequence samples.
+
+    A van der Corput sequence is an example of the simplest one-dimensional
+    low-discrepancy sequence over the unit interval; it was first described in
+    1935 by the Dutch mathematician J. G. van der Corput. It is constructed by
+    reversing the base-n representation of the sequence of natural numbers
+    :math:`(1, 2, 3, ...)`.
+
+    In practice, use Halton sequence instead of Van Der Corput, as it is the
+    same, but generalized to work in multiple dimensions.
 
     Args:
         idx (int, numpy.ndarray):
@@ -39,8 +23,16 @@ def create_van_der_corput_samples(idx, number_base=2):
         number_base (int):
             The numerical base from where to create the samples from.
 
-    Returns (float, numpy.ndarray):
-        Van der Corput samples.
+    Returns:
+        (numpy.ndarray):
+            Van der Corput samples.
+
+    Examples:
+        #>>> chaospy.create_van_der_corput_samples(range(11), number_base=10)
+        #array([0.1 , 0.2 , 0.3 , 0.4 , 0.5 , 0.6 , 0.7 , 0.8 , 0.9 , 0.01, 0.11])
+        #>>> chaospy.create_van_der_corput_samples(range(8), number_base=2)
+        #array([0.5   , 0.25  , 0.75  , 0.125 , 0.625 , 0.375 , 0.875 , 0.0625])
+
     """
     assert number_base > 1
 

chaospy/expansion/__init__.py

@@ -0,0 +1,38 @@
+r"""Collection of polynomial expansion constructors."""
+import logging
+from functools import wraps
+
+from .chebyshev import chebyshev_1, chebyshev_2
+from .cholesky import cholesky
+from .frontend import generate_expansion
+from .gegenbauer import gegenbauer
+from .gram_schmidt import gram_schmidt
+from .hermite import hermite
+from .jacobi import jacobi
+from .stieltjes import stieltjes
+from .lagrange import lagrange
+from .laguerre import laguerre
+from .legendre import legendre
+
+__all__ = ["generate_expansion"]
+
+
+def expansion_deprecation_warning(name, func):
+
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        """Function wrapper adds warnings."""
+        logger = logging.getLogger(__name__)
+        logger.warning("chaospy.%s name is to be deprecated; "
+                       "Use chaospy.expansion.%s instead",
+                       name, func.__name__)
+        return func(*args, **kwargs)
+
+    globals()[name] = wrapped
+    __all__.append(name)
+
+
+expansion_deprecation_warning("orth_ttr", stieltjes)
+expansion_deprecation_warning("orth_chol", cholesky)
+expansion_deprecation_warning("orth_gs", gram_schmidt)
+expansion_deprecation_warning("lagrange_polynomial", lagrange)