Overview¶

BET is an initialism of Butler, Estep and Tavener, the primary authors of a series of papers that introduced the mathematical framework for measure-based data-consistent stochastic inversion, for which BET included a computational implementation. However, since it’s initial inception it has grown to include a broad range of data- consistent methods that can also be density-based. It has been applied to a wide variety of application problems, many of which can be found here.

Mathematical Theory¶

For more information about the methods and algorithms for the Measure-Based Data-Consistent framework, see A Measure-Theoretic Computational Method for Inverse Sensitivity Problems III: Multiple Quantities of Interest for the formulation of the stochastic inverse problem along with proofs of existence and uniqueness of solutions, Solving Stochastic Inverse Problems using Sigma-Algebras on Contour Maps for the convergence and error analysis of the non-intrusive algorithm, and Definition and solution of a stochastic inverse problem for the Manning’s n parameter field in hydrodynamic models for a less technical description of the method for engineers as well as application to a physically relevant problem in coastal ocean modeling.

For more information about the methods and algorithms for Density-Based Data-Consistent framework see Combining Push-Forward Measures and Bayes’ Rule to Construct Consistent Solutions to Stochastic Inverse Problems and Data-Consistent Inversion for Stochastic Input-to-Output Maps.

Installation¶

The code currently resides at GitHub. 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, SciPy, matplotlib, pyDOE, pytest, and mpi4py (optional) (see requirements.txt for version information). For some optional features LUQ is also required.

License¶

GNU Lesser General Public License (LGPL)

Citing BET¶

Please include the citation:

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

Lindley Graham, Steven Mattis, Michael Pilosov, Scott Walsh, Troy Butler, Michael Pilosov, … Damon McDougall. (2020, July 9). UT-CHG/BET: BET v3.0.0 (Version v3.0.0). Zenodo. http://doi.org/10.5281/zenodo.3936258

or in BibTEX:

  @software{lindley_graham_2020_3936258,
  author       = {Lindley Graham and
                  Steven Mattis and
                  Michael Pilosov and
                  Scott Walsh and
                  Troy Butler and
                  Wenjuan Zhang and
                  Damon McDougall},
title          =  UT-CHG/BET: BET v3.0.0},
month          =  jul,
year           =  2020,
publisher      =  {Zenodo},
version        =  {v3.0.0},
doi            =  {10.5281/zenodo.3936258},
url            =  {https://doi.org/10.5281/zenodo.3936258}
}

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:

sphinx-apidoc -f -o doc bet
cd doc/
make html
make html

This creates the relevant documentation at bet/gh-pages/html. To change the build location of the documentation you will need to update doc/makefile.

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.

Testing¶

To run the tests in the root directory with pytest in serial call:

$ pytest ./test/

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 pytest ./test/

Make sure to have a working MPI environment (we recommend mpich). if you want to use parallel features.

Contributors¶

See the GitHub contributors page.

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!

Please note that we are using continuous integration and issues for bug tracking.

Package Layout¶

The package layout is as follows:

bet/
  util
  Comm
  sample
  surrogates
  calculateP/
    calculateP
    calculateError
    simpleFunP
    calculateR
  sampling/
    basicSampling
    useLUQ
    LpGeneralizedSamples
  postProcess/
    plotP
    plotDomains
    postTools
    plotVoronoi
  sensitivity/
    gradients
    chooseQoIs

Code Overview¶

`bet.sample` module¶

This module contains the main data structures and exceptions for BET. Notably:

sample_set_base provides the basic data structure for input and output sets
sample_set is the default sample set.
voronoi_sample_set is a sample set based on a Voronoi discretization (same as default).
rectangle_sample_set is a sample set based on a hyper-rectangle.
ball_sample_set is a sample set based on balls in R^n
cartesian_sample_set is a sample set based on a Cartesian grid.
discretization provides the basic data structure for and input to output stochastic map.
length_not_matching is an Exception class.
dim_not_matching is an Exception class.
evaluate_pdf() evaluates probability density functions.
evaluate_pdf_marginal() evaluates marginal probability density functions.

`bet.util` module¶

This module contains general tools for BET including saving and loading objects, and reshaping objects. The most important methods are:

get_global_values concatenates local arrays into global arrays.
save_object saves all types of objects.
load_object loads all types of saved objects.
load_object_parallel loads all types of saved parallel objects.

`bet.Comm` module¶

This module provides a workaround for people without mpi4py installed to run BET.

`bet.calculateP` Sub-package¶

This subpackage provides classes and methods for calculating the probability measure \(P_{\Lambda}\).

calculateP provides methods for approximating probability densities in the measure-based approach.
simpleFunP provides methods for creating simple function approximations of probability densities for the measure-based approach.
calculateR provides methods for density-based approach.
calculateError provides methods for approximating numerical and sampling errors.

`bet.sampling` Sub-package¶

This subpackage contains

basicSampling a general class and associated set of methods that sample spaces and solve models through an interface.
sampler requests data (QoI) at a specified set of parameter samples.
LpGeneralizedSamples provides methods for sampling on balls in Lp spaces.
useLUQ provides methods for interfacing with the LUQ package.

`bet.postProcess` Sub-package¶

This subpackage contains

plotP plots \(P\) and/or volumes (\(\mu\)) of Voronoi cells
plotDomains plots the data domain \(\mathcal{D}\) in 2D
postTools has tools for postprocessing
compareP has tools for comparing measures

`bet.sensitivity` Sub-package¶

This subpackage provides methods for approximating gradients of QoI maps and choosing optimal QoIs to use in the inverse problem.

gradients provides methods for approximating gradients of QoI maps.
chooseQoIs provides methods for choosing optimal QoIs to use in the inverse problem.