Refactoring hypercube quadrature

CHANGELOG.rst

@@ -1,6 +1,34 @@
 Master Branch
 =============
 
+Refactoring `quadrature` module.
+
+ADDED:
+  * `chaospy.quadrature.fejer_1` is added.
+  * Dedicated classical quadrature schemes added: ``
+CHANGED:
+  * Refactored hypercube quadrature to common backend. This gives lots of flags
+    like `seqments` and
+  * All `caospy.quad_*` functions announced to be deprecated.
+    `chaospy.quadrature.*` to take their place. So instead of
+    `chaospy.quad_clenshaw_curtis`, do `chaospy.quadrature.clenshaw_curtis`.
+    This to make clearer sub-module structure to chaospy as it grows. Warning
+    is raised if old functions are used for now.
+  * `gauss_`-prefixes removed so to make names sorter and more consist. Instead
+    of `chaospy.quad_gauss_radau` and flag `rule="gauss_radau"`, we now have
+    `chaospy.quadrature.radau` and flag `rule="radau"`.
+  * Renaming `fejer -> fejer_2` is in-fact Fejer type II and `fejer_1` is added
+    to the mix.
+  * Rename `legendre -> legendre_proxy` as `legendre` is now reserved for pure
+    legendre.
+  * 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 deprecated as it does not fit the `chaospy` scheme very well.
+
+
 Version 4.2.2 (2020-12-07)
 ==========================
 

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/__init__.py

@@ -6,3 +6,4 @@
 from .hammersley import create_hammersley_samples
 from .sobol import create_sobol_samples
 from .korobov import create_korobov_samples
+from .van_der_corput import create_van_der_corput_samples

chaospy/distributions/sampler/sequences/chebyshev.py

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

chaospy/distributions/sampler/sequences/grid.py

@@ -47,19 +47,21 @@
 
 def create_grid_samples(order, dim=1):
     """
-    Create samples from a regular grid.
+    Generate samples from a regular grid.
 
     Args:
         order (int):
             The order of the grid. Defines the number of samples.
         dim (int):
             The number of dimensions in the grid
 
-    Returns (numpy.ndarray):
-        Regular grid with ``shape == (dim, order)``.
+    Returns:
+        (numpy.ndarray):
+            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 = chaospy.quadrature.utils.combine([x_data]*dim)
     return x_data.T
 
 

chaospy/distributions/sampler/sequences/halton.py

@@ -1,29 +1,11 @@
 """
-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.
+Create samples from the Halton sequence.
 
 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
 """
 import numpy
 
@@ -33,9 +15,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 +37,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::
 
@@ -34,8 +29,6 @@
     Cube (in Russian),
     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