adding dependency tutorial (#329)

* adding dependency tutorial
* fixing caching
* remove n-dim mom approx
* rearanging docs

Author: jonathf

.circleci/config.yml

@@ -76,7 +76,7 @@ jobs:
           command: |
             source /home/circleci/venv/bin/activate
             coverage run --source=chaospy/ --module pytest --nbval-lax --doctest-modules \
-                chaospy/ tests/ docs/*/*.ipynb docs/*/*.rst README.rst
+                chaospy/ tests/ docs/*/*.ipynb docs/index.rst docs/*/*.rst
             bash <(curl -s https://codecov.io/bash)
   deploy:
     executor: python-container

README.rst

@@ -18,127 +18,98 @@
 .. |binder| image:: https://mybinder.org/badge_logo.svg
     :target: https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Ftutorials
 
-Chaospy is a numerical tool for performing uncertainty quantification using
-polynomial chaos expansions and advanced Monte Carlo methods implemented in
-Python.
-
 * `Documentation <https://chaospy.readthedocs.io/en/master>`_
 * `Interactive tutorials with Binder <https://mybinder.org/v2/gh/jonathf/chaospy/master?filepath=docs%2Ftutorials>`_
-* `Source code <https://github.com/jonathf/chaospy>`_
-* `Issue tracker <https://github.com/jonathf/chaospy/issues>`_
-* `Code of Conduct <https://github.com/jonathf/chaospy/blob/master/CODE_OF_CONDUCT.md>`_
-* `Contribution Guideline <https://github.com/jonathf/chaospy/blob/master/CONTRIBUTING.md>`_
-* `Changelog <https://github.com/jonathf/chaospy/blob/master/CHANGELOg.md>`_
+* `Code of conduct <https://github.com/jonathf/chaospy/blob/master/CODE_OF_CONDUCT.md>`_
+* `Contribution guideline <https://github.com/jonathf/chaospy/blob/master/CONTRIBUTING.md>`_
+* `Changelog <https://github.com/jonathf/chaospy/blob/master/CHANGELOG.md>`_
+* `License <https://github.com/jonathf/chaospy/blob/master/LICENCE.txt>`_
+
+Chaospy is a numerical toolbox for performing uncertainty quantification using
+polynomial chaos expansions, advanced Monte Carlo methods implemented in
+Python. It also include a full suite of tools for doing low-discrepancy
+sampling, quadrature creation, polynomial manipulations, and a lot more.
+
+The philosophy behind ``chaospy`` is not to be a single tool that solves every
+uncertainty quantification problem, but instead be a specific tools to aid to
+let the user solve problems themselves. This includes both well established
+problems, but also to be a foundry for experimenting with new problems, that
+are not so well established. To do this, emphasis is put on the following:
+
+* Focus on an easy to use interface that embraces the `pythonic code style
+  <https://docs.python-guide.org/writing/style/>`_.
+* Make sure the code is "composable", such a way that changing one part of the
+  code with something user defined should be easy and encouraged.
+* Try to support a broad width of the various methods for doing uncertainty
+  quantification where that makes sense to involve ``chaospy``.
+* Make sure that ``chaospy`` plays nice with a large set of of other other
+  similar projects. This includes `numpy <https://numpy.org/>`_, `scipy
+  <https://scipy.org/>`_, `scikit-learn <https://scikit-learn.org>`_,
+  `statsmodels <https://statsmodels.org/>`_, `openturns
+  <https://openturns.org/>`_, and `gstools <https://geostat-framework.org/>`_
+  to mention a few.
+* Contribute all code to the community open source.
 
 Installation
-------------
+============
 
-Installation should be straight forward using `pip <https://pypi.org/>`_:
+Installation should be straight forward from `pip <https://pypi.org/>`_:
 
 .. code-block:: bash
 
-    $ pip install chaospy
-
-For more installation details, see the `installation guide
-<https://chaospy.readthedocs.io/en/master/installation.html>`_.
-
-Example Usage
--------------
-
-``chaospy`` is created to work well inside numerical Python ecosystem. You
-therefore typically need to import `Numpy <https://numpy.org/>`_ along side
-``chaospy``:
-
-.. code-block:: python
-
-    >>> import numpy
-    >>> import chaospy
-
-``chaospy`` is problem agnostic, so you can use your own code using any means
-you find fit. The only requirement is that the output is compatible with
-`numpy.ndarray` format:
-
-.. code-block:: python
-
-    >>> coordinates = numpy.linspace(0, 10, 100)
-
-    >>> def forward_solver(coordinates, parameters):
-    ...     """Function to do uncertainty quantification on."""
-    ...     param_init, param_rate = parameters
-    ...     return param_init*numpy.e**(-param_rate*coordinates)
+    pip install chaospy
 
-We here assume that ``parameters`` contains aleatory variability with known
-probability. We formalize this probability in ``chaospy`` as a joint
-probability distribution. For example:
+Or if `Conda <https://conda.io/>`_ is more to your liking:
 
-.. code-block:: python
-
-    >>> distribution = chaospy.J(chaospy.Uniform(1, 2), chaospy.Normal(0, 2))
-
-    >>> print(distribution)
-    J(Uniform(lower=1, upper=2), Normal(mu=0, sigma=2))
-
-Most probability distributions have an associated expansion of orthogonal
-polynomials. These can be automatically constructed:
-
-.. code-block:: python
-
-    >>> expansion = chaospy.generate_expansion(8, distribution)
-
-    >>> print(expansion[:5].round(8))
-    [1.0 q1 q0-1.5 q0*q1-1.5*q1 q0**2-3.0*q0+2.16666667]
-
-Here the polynomial is defined positional, such that ``q0`` and ``q1`` refers
-to the uniform and normal distribution respectively.
+.. code-block:: bash
 
-The distribution can also be used to create (pseudo-)random samples and
-low-discrepancy sequences. For example to create Sobol sequence samples:
+    conda install -c conda-forge chaospy
 
-.. code-block:: python
+Then go over to the
+`tutorial collection <https://chaospy.readthedocs.io/en/master/tutorials>`_
+to see how to use the toolbox.
 
-    >>> samples = distribution.sample(1000, rule="sobol")
+Development
+===========
 
-    >>> print(samples[:, :4].round(8))
-    [[ 1.5         1.75        1.25        1.375     ]
-     [ 0.         -1.3489795   1.3489795  -0.63727873]]
+Chaospy uses `poetry`_ to manage its development installation. Assuming
+`poetry`_ installed on your system, installing ``chaospy`` for development can
+be done from the repository root with the command::
 
-We can evaluating the forward solver using these samples:
+    poetry install
 
-.. code-block:: python
+This will install all required dependencies and chaospy into a virtual
+environment. If you are not already managing your own virtual environment, you
+can use poetry to activate and deactivate with::
 
-    >>> evaluations = numpy.array([forward_solver(coordinates, sample)
-    ...                            for sample in samples.T])
+    poetry shell
+    exit
 
-    >>> print(evaluations[:3, :5].round(8))
-    [[1.5        1.5        1.5        1.5        1.5       ]
-     [1.75       2.00546578 2.29822457 2.63372042 3.0181921 ]
-     [1.25       1.09076905 0.95182169 0.83057411 0.72477163]]
+.. _poetry: https://poetry.eustace.io/
 
-Having all these components in place, we have enough components to perform
-point collocation. Or in other words, we can create a polynomial approximation
-of ``forward_solver``:
+Testing
+-------
 
-.. code-block:: python
+To ensure that the code run on your local system, run the following:
 
-    >>> approx_solver = chaospy.fit_regression(expansion, samples, evaluations)
+.. code-block:: bash
 
-    >>> print(approx_solver[:2].round(4))
-    [q0 -0.0002*q0*q1**3+0.0051*q0*q1**2-0.101*q0*q1+q0]
+    poetry run pytest --nbval-lax --doctest-modules \
+        chaospy/ tests/ docs/*/*.{rst,ipynb}
 
-Since the model approximations are polynomials, we can do inference on them
-directly. For example:
+Documentation
+-------------
 
-.. code-block:: python
+The documentation build assumes that ``pandoc`` is installed on your
+system and available in your path.
 
-    >>> expected = chaospy.E(approx_solver, distribution)
-    >>> deviation = chaospy.Std(approx_solver, distribution)
+To build documentation locally on your system, use ``make`` from the ``docs/``
+folder:
 
-    >>> print(expected[:5].round(8))
-    [1.5        1.53092356 1.62757217 1.80240142 2.07915608]
-    >>> print(deviation[:5].round(8))
-    [0.28867513 0.43364958 0.76501802 1.27106355 2.07110879]
+.. code-block:: bash
 
-For more extensive guides on this approach an others, see the `tutorial
-collection`_.
+    cd docs/
+    make html
 
-.. _tutorial collection: https://chaospy.readthedocs.io/en/master/tutorials
+Run ``make`` without argument to get a list of build targets.
+The HTML target stores output to the folder ``doc/.build/html``.

chaospy/distributions/approximation.py

@@ -186,15 +186,14 @@ def approximate_moment(
         7.0
 
     """
-    if order is None:
-        order = int(1e5**(1./len(distribution)))
-    assert isinstance(order, int)
     assert isinstance(distribution, chaospy.Distribution)
     k_loc = tuple(numpy.asarray(k_loc).tolist())
     assert len(k_loc) == len(distribution), "incorrect size of exponents"
     assert all([isinstance(k, int) for k in k_loc]), (
         "exponents must be integers: %s found" % type(k_loc[0]))
+    assert len(distribution) == 1, "only 1-D distributions support approximate moment."
 
+    order = int(1e5 if order is None else order)
     if (distribution, order) not in MOMENTS_QUADS:
         MOMENTS_QUADS[distribution, order] = chaospy.generate_quadrature(
             order, distribution, rule=rule, **kwargs)

chaospy/distributions/baseclass/distribution.py

@@ -657,7 +657,7 @@ def _get_cache(self, idx, cache, get=None):
         The cached values are as follows:
 
         -----------  -------------  -------------
-        Context      Get 1          Get 2
+        Context      Get 0          Get 1
         -----------  -------------  -------------
         pdf          Input values   Output values
         cdf/fwd      Input values   Output values
@@ -681,22 +681,13 @@ def _get_cache(self, idx, cache, get=None):
 
         """
         if (idx, self) in cache:
-            out = cache[idx, self]
-        else:
-            out = self._cache(idx, cache)
-        if not isinstance(out, Distribution) and get is not None:
             assert get in (0, 1)
-            out = out[get]
-        return out
-        if self in cache:
-            out = cache[idx, self]
+            out = cache[idx, self][get]
         else:
-            out = self._cache(idx, cache)
-        if not isinstance(out, Distribution):
-            out = out[1]
+            out = self._cache(idx=idx, cache=cache, get=get)
         return out
 
-    def _cache(self, idx, cache):
+    def _cache(self, idx, cache, get):
         """Backend function of retrieving cache values."""
         return self
 

chaospy/distributions/baseclass/lower_upper.py

@@ -32,6 +32,7 @@ def __init__(
             repr_args=None,
     ):
         assert isinstance(dist, Distribution), "'dist' should be a distribution"
+        assert len(dist) == 1
         if repr_args is None:
             repr_args = dist._repr_args[:]
         repr_args += chaospy.format_repr_kwargs(lower=(lower, 0), upper=(upper, 1))
@@ -43,6 +44,9 @@ def __init__(
             rotation=rotation,
             extra_parameters=dict(dist=dist),
         )
+        assert len(dependencies) == 1
+        assert len(parameters["lower"]) == 1
+        assert len(parameters["upper"]) == 1
         super(LowerUpperDistribution, self).__init__(
             parameters=parameters,
             dependencies=dependencies,
@@ -57,16 +61,12 @@ def get_parameters(self, idx, cache, assert_numerical=True):
         lower = parameters["lower"]
         if isinstance(lower, Distribution):
             lower = lower._get_cache(idx, cache, get=0)
-        if idx is not None and len(lower) > 1:
-            lower = lower[idx]
         upper = parameters["upper"]
         if isinstance(upper, Distribution):
             upper = upper._get_cache(idx, cache, get=0)
-        if idx is not None and len(upper) > 1:
-            upper = upper[idx]
         assert not assert_numerical or not (isinstance(lower, Distribution) or
                                             isinstance(upper, Distribution))
-        assert numpy.all(upper.ravel() > lower.ravel()), (
+        assert numpy.all(upper > lower), (
             "condition not satisfied: `upper > lower`")
         lower0 = self._dist._get_lower(idx, cache.copy())
         upper0 = self._dist._get_upper(idx, cache.copy())

chaospy/distributions/baseclass/operator.py

@@ -59,3 +59,8 @@ def get_parameters(self, idx, cache, assert_numerical=True):
         if idx is None:
             del parameters["idx"]
         return parameters
+
+    def _cache(self, idx, cache, get):
+        assert get == 0
+        parameters = self.get_parameters(idx, cache)
+        return self._operator(parameters["left"], parameters["right"])

chaospy/distributions/baseclass/shift_scale.py

@@ -70,13 +70,15 @@ def get_parameters(self, idx, cache, assert_numerical=True):
             shift = shift._get_cache(idx, cache, get=0)
         elif idx is not None and len(shift) > 1:
             shift = shift[idx]
+        assert not isinstance(shift, Distribution), shift
 
         scale = self._parameters["scale"]
         if isinstance(scale, Distribution):
             scale = scale._get_cache(idx, cache, get=0)
         elif idx is not None and len(scale) > 1:
             scale = scale[idx]
-        assert scale > 0, "condition not satisfied: `scale > 0`"
+        assert not isinstance(scale, Distribution), scale
+        assert numpy.all([scale]) > 0, "condition not satisfied: `scale > 0`"
 
         assert not assert_numerical or not (isinstance(shift, Distribution) or
                                             isinstance(scale, Distribution))

chaospy/distributions/baseclass/slice_.py

@@ -52,10 +52,10 @@ def _mom(self, kloc, parent, parameters):
     def _ttr(self, kloc, parent, parameters):
         raise chaospy.StochasticallyDependentError("TTR not supported")
 
-    def _cache(self, idx, cache):
+    def _cache(self, idx, cache, get):
         if idx is None:
             return self
         assert idx == 0
         idx = int(self._parameters["index"])
         parent = self._parameters["parent"]
-        return parent._get_cache(idx, cache)
+        return parent._get_cache(idx, cache, get)

chaospy/distributions/operators/addition.py

@@ -62,12 +62,6 @@
     array([[3.01, 3.5 , 3.99],
            [5.11, 6.  , 6.89]])
 
-Raw moments::
-
-    >>> joint1.mom([(0, 1, 1), (1, 0, 1)]).round(4)
-    array([ 6.    ,  2.5   , 15.0834])
-    >>> joint2.mom([(0, 1, 1), (1, 0, 1)]).round(4)
-    array([ 6.    ,  3.5   , 21.0834])
 """
 from __future__ import division
 from scipy.special import comb
@@ -80,6 +74,8 @@
 class Add(OperatorDistribution):
     """Addition operator."""
 
+    _operator = lambda self, left, right: (left.T+right.T).T
+
     def __init__(self, left, right):
         super(Add, self).__init__(
             left=left,
@@ -103,7 +99,7 @@ def _lower(self, idx, left, right, cache):
             left = left._get_lower(idx, cache=cache)
         if isinstance(right, Distribution):
             right = right._get_lower(idx, cache=cache)
-        return left+right
+        return self._operator(left, right)
 
     def _upper(self, idx, left, right, cache):
         """
@@ -122,7 +118,7 @@ def _upper(self, idx, left, right, cache):
             left = left._get_upper(idx, cache=cache)
         if isinstance(right, Distribution):
             right = right._get_upper(idx, cache=cache)
-        return (left.T+right.T).T
+        return self._operator(left, right)
 
     def _cdf(self, xloc, idx, left, right, cache):
         if isinstance(right, Distribution):
@@ -165,7 +161,8 @@ def _ppf(self, uloc, idx, left, right, cache):
         if isinstance(right, Distribution):
             left, right = right, left
         xloc = left._get_inv(uloc, idx, cache=cache)
-        return (xloc.T+numpy.asfarray(right).T).T
+        right = numpy.asfarray(right)
+        return self._operator(xloc, right)
 
     def _mom(self, keys, left, right, cache):
         """