Merge pull request #382 from UT-CHG/v3-dev

Version 3 Soft Release
UT-CHG · Jul 8, 2020 · c1d3177 · c1d3177
2 parents 491b939 + 03e52c0
commit c1d3177
Show file tree

Hide file tree

Showing 132 changed files with 3,872 additions and 11,310 deletions.
diff --git a/.codecov.yml b/.codecov.yml
@@ -0,0 +1,9 @@
+coverage:
+  status:
+    patch:
+      default:
+        target: 70%
+    project:
+      default:
+        target: 70%
+        threshold: 5%
diff --git a/.travis.yml b/.travis.yml
@@ -13,14 +13,16 @@ before_install:
   - sudo apt-get install gfortran libblas-dev liblapack-dev mpich libmpich-dev
 
 install:
-  - pip install matplotlib mpi4py nose codecov Sphinx sphinx_rtd_theme
-  - python setup.py install
+  - pip install .
+  - pip install codecov pytest-cov Sphinx sphinx_rtd_theme
+  - pip install git+https://github.com/CU-Denver-UQ/LUQ
+  - pip install mpi4py
 
 script:
-  - nosetests --with-coverage --cover-package=bet --cover-erase --cover-html
-  - mpirun -n 2 nosetests
+  - pytest --cov=./bet/ ./test/
+  - mpirun -n 2 pytest  ./test/
   - pip uninstall -y mpi4py
-  - nosetests
+  - pytest ./test/
   - sphinx-apidoc -f -o doc bet
   - cd doc/
   - make html
@@ -32,8 +34,6 @@ notifications:
     email:
         recipients:
             - [email protected]
-            - [email protected]
-            - [email protected]
             - [email protected]
         on_success: change
         on_failure: always
@@ -42,6 +42,7 @@ notifications:
 branches:
     only:
         - master
+        - v3-dev
 
 # Push the results back to codecov
 after_success:

diff --git a/README.md b/README.md
@@ -1,18 +1,57 @@
-BET
-===
+# BET
 [![Build Status](https://travis-ci.org/UT-CHG/BET.svg?branch=master)](https://travis-ci.org/UT-CHG/BET) [![DOI](https://zenodo.org/badge/18813599.svg)](https://zenodo.org/badge/latestdoi/18813599) [![codecov](https://codecov.io/gh/UT-CHG/BET/branch/master/graph/badge.svg)](https://codecov.io/gh/UT-CHG/BET) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/UT-CHG/BET/master)
 
+BET is a Python package for data-consistent stochastic forward and inverse problems. The package is very flexible and is applicable to a wide variety of problems. 
 
-BET is in active development. Hence, some features are still being added and you may find bugs we have overlooked. If you find something please report these problems to us through GitHub so that we can fix them. Thanks! 
+BET is an initialism of Butler, Estep and Tavener, the primary authors of a [series](https://epubs.siam.org/doi/abs/10.1137/100785946) [of](https://epubs.siam.org/doi/abs/10.1137/100785958) [papers](https://epubs.siam.org/doi/abs/10.1137/130930406) that introduced the mathematical framework for measure-based data-consistent stochastic inversion, for which BET included a computational implementation. However, since its initial inception it has grown to include a broad range of [data-](https://iopscience.iop.org/article/10.1088/1361-6420/ab8f83/meta)[consistent](https://epubs.siam.org/doi/abs/10.1137/16M1087229) [methods](https://onlinelibrary.wiley.com/doi/abs/10.1002/nme.6078). It has been applied to a wide variety of application problems, many of which can be found [here](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=915741139550333528,6038673497778212734,182199236207122617).
 
-Please note that we are using continuous integration and issues for bug tracking.
+## Installation
+The current development branch of BET can be installed from GitHub,  using ``pip``:
+
+    pip install git+https://github.com/UT-CHG/BET
+
+Another option is to clone the repository and install BET using
+``python setup.py install``
+
+
+## Dependencies
+BET is tested on Python 3.6 and 3.7 (but should work on most recent Python 3 versions) and depends on [NumPy](http://www.numpy.org/), [SciPy](http://www.scipy.org/), [matplotlib](http://matplotlib.org/), [pyDOE](https://pythonhosted.org/pyDOE/), [pytest](https://docs.pytest.org/), and [mpi4py](https://mpi4py.readthedocs.io/en/stable/) (optional) (see [requirements.txt](requirements.txt) for version information). For some optional features [LUQ](https://github.com/CU-Denver-UQ/LUQ) is also required. mpi4py is required to take advantage of parallel features and requires an mpi implementation. It can be installed by:
+
+    pip install mpi4py
+
+
+## License
+[GNU Lesser General Public License (LGPL)](LICENSE.txt)
 
-## Butler, Estep, Tavener method
+## Citing BET
+Please include the citation:
 
-This code has been documented with sphinx. the documentation is available online at http://ut-chg.github.io/BET. to build documentation run 
+Lindley Graham, Steven Mattis, Scott Walsh, Troy Butler, Michael Pilosov, and Damon McDougall. “BET: Butler, Estep, Tavener Method V2.0.0”. Zenodo, August 10, 2016. [doi:10.5281/zenodo.59964](https://doi.org/10.5281/zenodo.59964)
+
+or in BibTEX:
+
+    @software{BET,
+    author       = {Lindley Graham and
+                    Steven Mattis and
+                    Scott Walsh and
+                    Troy Butler and
+                    Michael Pilosov and
+                    Damon McDougall},
+    title        = {BET: Butler, Estep, Tavener Method v2.0.0},
+    month        = aug,
+    year         = 2016,
+    publisher    = {Zenodo},
+    version      = {v2.0.0},
+    doi          = {10.5281/zenodo.59964},
+    url          = {https://doi.org/10.5281/zenodo.59964}
+    }
+
+## Documentation
+
+This code has been documented with sphinx. the documentation is available online at http://ut-chg.github.io/BET. To build documentation run 
 ``make html`` in the ``doc/`` folder.
 
-To build/update the documentation use the following commands::
+To build/update the documentation use the following commands:
 
     sphinx-apidoc -f -o doc bet
     cd doc/
@@ -24,42 +63,34 @@ To change the build location of the documentation you will need to update ``doc/
 
 You will need to run sphinx-apidoc and reinstall bet anytime a new module or method in the source code has been added. 
 If only the `*.rst` files have changed then you can simply run ``make html`` twice in the doc folder.
+Building the docs requires Sphinx and the Read the Docs Sphinx theme, which can be installed with `pip` by:
 
-Useful scripts are contained in ``examples/``, as are the following sets of example Jupyter Notebooks:
+    pip install Sphinx sphinx_rtd_theme
 
-- [Plotting](./examples/plotting/Plotting_Examples.ipynb)
-    (this allows execution any of the following examples and plots the associated results)
-- [Contaminant Transport](./examples/contaminantTransport/contaminant.ipynb)
-- [Validation Example](./examples/validationExample/linearMap.ipynb)
-- [Linear (QoI) Sensitivity](./examples/sensitivity/linear_sensitivity.ipynb)
-- [Linear Map](./examples/linearMap/linearMapUniformSampling.ipynb)
+## Examples
+Examples scripts are contained in [here](examples/). 
 
-Furthermore, the `examples/templates` directory contains a [notebook](./examples/templates/Example_Notebook_Template.ipynb) that serves as a template for the examples.
 You can also try out BET in your browser using [Binder](https://mybinder.org/v2/gh/UT-CHG/BET/master).
 
-Tests
------
+## Testing
 
-To run tests in serial call::
+To run the tests in the root directory with `pytest` in serial call:
 
-    nosetests
+    pytest ./test/
 
-To run tests in parallel call::
+Some features of BET (primarily those associated with the measure-based approach) have the ability to work in parallel. To run tests in parallel call:
 
-    mpirun -np nproc nosetests
+    mpirun -np NPROC pytest ./test/
 
-Make you to have a working MPI environment (we recommend [mpich](http://www.mpich.org/downloads/)).
+Make sure to have a working MPI environment (we recommend [mpich](http://www.mpich.org/downloads/)) if you want to use parallel features.
 
 
-Dependencies
-------------
+(Note: you may need to set `~/.config/matplotlib/matplotlibrc` to include `backend:agg` if there is no `DISPLAY` port in your environment). 
 
-`bet` requires the following packages:
+## Contributors
+See the [GitHub contributors page](https://github.com/UT-CHG/BET/graphs/contributors).
 
-1. [numpy](http://www.numpy.org/)
-2. [scipy](http://www.scipy.org/)
-3. [nose](https://nose.readthedocs.org/en/latest/)
-4. [pyDOE](https://pythonhosted.org/pyDOE/)
-5. [matplotlib](http://matplotlib.org/)
+## Contact
+BET is in active development. Hence, some features are still being added and you may find bugs we have overlooked. If you find something please report these problems to us through GitHub so that we can fix them. Thanks! 
 
-(Note: you may need to set `~/.config/matplotlib/matplotlibrc` to include `backend:agg` if there is no `DISPLAY` port in your environment). 
+Please note that we are using continuous integration and issues for bug tracking.
diff --git a/bet/Comm.py b/bet/Comm.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2019 The BET Development Team
+# Copyright (C) 2014-2020 The BET Development Team
 
 """
 This module provides a workaround for people without mpi4py installed

diff --git a/bet/__init__.py b/bet/__init__.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2019 The BET Development Team
+# Copyright (C) 2014-2020 The BET Development Team
 
 """
 Butler, Estep, Tavener Method
@@ -7,26 +7,14 @@
 measure-theoretic. It is named for the developers of the key algorithm in
 :mod:`bet.calculateP.calculateP`.
 
-Comm :mod:`~bet.Comm` provides a work around for users who do not which to
-    install :program:``mpi4py``.
-
-util :mod:`~bet.util` provides some general use methods for creating grids,
-    checking/fixing dimensions, and globalizing arrays.
-
-calculateP :mod:`~bet.calculateP` provides tools to approximate probabilities.
-
-sampling :mod:`~bet.sampling` provides various sampling algorithms.
-
-sensitivity :mod:`~bet.sensitivity` provides tools for approximating
-    derivatives and optimally choosing quantities of interest.
-
-postProcess :mod:`~bet.postProcess` provides plotting tools and tools to sort
-    samples by probabilities.
-
-sample :mod:`~bet.sample` provides data structures to store sets of samples and
-    their associated arrays.
-
-surrogates :mod:`~bet.surrogates` provides methods for generating and using
+* :mod:`~bet.Comm` provides a work around for users who do not which to install :program:``mpi4py``.
+* :mod:`~bet.util` provides some general use methods for creating grids, checking/fixing dimensions, and globalizing arrays.
+* :mod:`~bet.calculateP` provides tools to approximate probabilities.
+* :mod:`~bet.sampling` provides various sampling algorithms.
+* :mod:`~bet.sensitivity` provides tools for approximating derivatives and optimally choosing quantities of interest.
+* :mod:`~bet.postProcess` provides plotting tools and tools to sort samples by probabilities.
+* :mod:`~bet.sample` provides data structures to store sets of samples and their associated arrays.
+* :mod:`~bet.surrogates` provides methods for generating and using
     surrogate models.
 
 """

diff --git a/bet/calculateP/__init__.py b/bet/calculateP/__init__.py
@@ -1,15 +1,12 @@
-# Copyright (C) 2014-2019 The BET Development Team
+# Copyright (C) 2014-2020 The BET Development Team
 
 r"""
-This subpackage provides classes and methods for calulating the
+This subpackage provides classes and methods for calculating the
 probability measure :math:`P_{\Lambda}`.
 
-* :mod:`~bet.calculateP.calculateP` provides methods for approximating
-     probability densities
-* :mod:`~bet.calculateP.simpleFunP` provides methods for creating simple
-    function approximations of probability densisties
-* :mod:`~bet.calculateP.indicatorFunctions` provides methods for creating
-    indicator functions for use by various other classes.
+* :mod:`~bet.calculateP.calculateP` provides methods for approximating probability densities in the measure-based approach.
+* :mod:`~bet.calculateP.simpleFunP` provides methods for creating simple function approximations of probability densities for the measure-based approach.
+* :mod:`~bet.calculateP.calculateR` provides methods for density-based approach.
+* :mod:`~bet.calculateP.calculateError` provides methods for approximating numerical and sampling errors.
 """
-__all__ = ['calculateP', 'simpleFunP', 'indicatorFunctions',
-           'calculateError']
+__all__ = ['calculateP', 'simpleFunP', 'calculateError', 'calculateR']
diff --git a/bet/calculateP/calculateError.py b/bet/calculateP/calculateError.py
@@ -1,18 +1,14 @@
-# Copyright (C) 2014-2019 The BET Development Team
+# Copyright (C) 2014-2020 The BET Development Team
 
 r"""
-This module provides methods for calulating error estimates of
+This module provides methods for calculating error estimates of
 the probability measure for calculate probability measures. See
 `Butler et al. 2015. <http://arxiv.org/pdf/1407.3851>`.
 
-* :meth:`~bet.calculateErrors.cell_connectivity_exact` calculates
-    the connectivity of cells.
-* :meth:`~bet.calculateErrors.boundary_sets` calculates which cells are
-    on the boundary and strictly interior for contour events.
-* :class:`~bet.calculateErrors.sampling_error` is for calculating error
-    estimates due to sampling
-* :class:`~bet.calculateErrors.model_error` is for calculating error
-    estimates due to error in solution of QoIs
+* :mod:`~bet.calculateErrors.cell_connectivity_exact` calculates the connectivity of cells.
+* :mod:`~bet.calculateErrors.boundary_sets` calculates which cells are on the boundary and strictly interior for contour events.
+* :class:`~bet.calculateErrors.sampling_error` is for calculating error estimates due to sampling.
+* :class:`~bet.calculateErrors.model_error` is for calculating error estimates due to error in solution of QoIs
 
 """
 
@@ -51,7 +47,7 @@ def cell_connectivity_exact(disc):
         msg = "The argument must be of type bet.sample.discretization."
         raise wrong_argument_type(msg)
 
-    if not isinstance(disc._input_sample_set, samp.voronoi_sample_set):
+    if not isinstance(disc.get_input_sample_set(), samp.voronoi_sample_set):
         msg = "disc._input_sample_set must be of type bet.sample.voronoi"
         msg += "_sample_set defined with the 2-norm"
         raise wrong_argument_type(msg)

diff --git a/bet/calculateP/calculateP.py b/bet/calculateP/calculateP.py
@@ -1,32 +1,28 @@
-# Copyright (C) 2014-2019 The BET Development Team
+# Copyright (C) 2014-2020 The BET Development Team
 
 r"""
-This module provides methods for calulating the probability measure
+This module provides methods for calculating the probability measure
 :math:`P_{\Lambda}`.
 
-* :mod:`~bet.calculateP.prob_on_emulated_samples` provides a skeleton class and
-    calculates the probability for a set of emulation points.
-* :mod:`~bet.calculateP.calculateP.prob` estimates the
-    probability based on pre-defined volumes.
-* :mod:`~bet.calculateP.calculateP.prob_with_emulated` estimates the
-    probability using volume emulation.
-* :mod:`~bet.calculateP.calculateP.prob_from_sample_set` estimates the
-    probability based on probabilities from another sample set on the same
-    space.
+* :mod:`~bet.calculateP.prob_on_emulated_samples` provides a skeleton class and calculates the probability for a set of emulation points.
+* :mod:`~bet.calculateP.calculateP.prob` estimates the probability based on pre-defined volumes.
+* :mod:`~bet.calculateP.calculateP.prob_with_emulated` estimates the probability using volume emulation.
+* :mod:`~bet.calculateP.calculateP.prob_from_sample_set` estimates the probability based on probabilities from another
+sample set on the same space.
 
 """
 import logging
 import numpy as np
 from bet.Comm import comm, MPI
-import bet.util as util
 import bet.sample as samp
+import bet.util as util
 
 
 def prob_on_emulated_samples(discretization, globalize=True):
     r"""
 
     Calculates :math:`P_{\Lambda}(\mathcal{V}_{\lambda_{emulate}})`, the
-    probability associated with a set of voronoi cells defined by
+    probability associated with a set of Voronoi cells defined by
     ``num_l_emulate`` iid samples :math:`(\lambda_{emulate})`.
     This is added to the emulated input sample set object.
 
@@ -62,6 +58,7 @@ def prob_on_emulated_samples(discretization, globalize=True):
                     _probabilities[i] / Itemp_sum
 
     discretization._emulated_input_sample_set._probabilities_local = P
+    discretization._emulated_input_sample_set.set_prob_type('voronoi')
     if globalize:
         discretization._emulated_input_sample_set.local_to_global()
     pass
@@ -106,6 +103,8 @@ def prob(discretization, globalize=True):
         discretization._input_sample_set._probabilities = util.\
             get_global_values(P_local)
     discretization._input_sample_set._probabilities_local = P_local
+    discretization._input_sample_set.set_prob_type('voronoi')
+
 
 
 def prob_with_emulated_volumes(discretization):
@@ -203,6 +202,7 @@ def prob_from_sample_set_with_emulated_volumes(set_old, set_new,
 
     # Set probabilities
     set_new.set_probabilities(prob_new)
+    set_new.set_prob_type('voronoi')
     return prob_new
 
 
@@ -245,6 +245,7 @@ def prob_from_sample_set(set_old, set_new):
 
     # Set probabilities
     set_new.set_probabilities(prob_new)
+    set_new.set_prob_type('voronoi')
     return prob_new
 
 
@@ -295,4 +296,5 @@ def prob_from_discretization_input(disc, set_new):
 
     # Set probabilities
     set_new.set_probabilities(prob_new)
+    set_new.set_prob_type('voronoi')
     return prob_new