# 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¶

## 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.

See also

Module Index for detailed documentation of modules, classes, etc.