Refactor submodule layout

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

@@ -156,7 +156,7 @@ def approximate_inverse(
 def approximate_moment(
         distribution,
         k_loc,
-        order=None,
+        order=100000,
         rule="clenshaw_curtis",
         **kwargs
 ):
@@ -171,12 +171,11 @@ 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.
         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/baseclass/distribution.py

@@ -1,4 +1,5 @@
 """Abstract baseclass for all distributions."""
+import typing
 import logging
 import numpy
 
@@ -15,8 +16,9 @@ class Distribution(object):
 
     interpret_as_integer = False
     """
-    Flag indicating that return value from the methods sample, and inv
-    should be interpreted as integers instead of floating point.
+    Flag indicating that return value from the methods
+    :func:`Distribution.sample`, and :func:`Distribution.inv` should be
+    interpreted as integers instead of floating point.
     """
 
     @property
@@ -204,6 +206,10 @@ def fwd(self, x_data):
         q_data = q_data.reshape(shape)
         return q_data
 
+    def _cdf(self, x_data, **parameters):
+        raise NotImplementedError(
+            "%s most define _cdf method." % self.__class__.__name__)
+
     def _get_fwd(self, x_data, idx, cache):
         """In-process function for getting cdf-values."""
         logger = logging.getLogger(__name__)
@@ -691,9 +697,9 @@ def _cache(self, idx, cache, get):
         """Backend function of retrieving cache values."""
         return self
 
-    def __getitem__(self, index):
+    def __getitem__(self, index: typing.Union[int, numpy.ndarray, slice]):
         if isinstance(index, numpy.number):
-            assert index.dtype == int
+            assert numpy.asarray(index).dtype == int
             index = int(index)
         if isinstance(index, int):
             if not -len(self) < index < len(self):

chaospy/distributions/operators/joint.py

@@ -221,18 +221,3 @@ def _cache(self, idx, cache, get):
         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

@@ -42,12 +42,14 @@
 
 """
 import numpy
+
 import chaospy
+from chaospy.quadrature import utils
 
 
 def create_chebyshev_samples(order, dim=1):
     """
-    Chebyshev sampling function.
+    Generate Chebyshev pseudo-random samples.
 
     Args:
         order (int):
@@ -58,9 +60,19 @@ 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 = chaospy.quadrature.combine([x_data]*dim)
+    x_data = utils.combine([x_data]*dim)
     return x_data.T
 
 

chaospy/distributions/sampler/sequences/grid.py

@@ -42,7 +42,9 @@
 
 """
 import numpy
+
 import chaospy
+from chaospy.quadrature import utils
 
 
 def create_grid_samples(order, dim=1):
@@ -59,7 +61,7 @@ def create_grid_samples(order, dim=1):
         Regular grid with ``shape == (dim, order)``.
     """
     x_data = numpy.arange(1, order+1)/(order+1.)
-    x_data = chaospy.quadrature.combine([x_data]*dim)
+    x_data = utils.combine([x_data]*dim)
     return x_data.T
 
 

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