Metadata-Version: 2.4
Name: bits_for_gaps
Version: 0.2.0
Summary: Bayesian Information-Theoretic Sampling for hierarchical GAussian Process Surrogates (BITS for GAPS)
Project-URL: Homepage, https://github.com/dowlinglab/bits_for_gaps
Project-URL: Repository, https://github.com/dowlinglab/bits_for_gaps
Project-URL: Documentation, https://bits-for-gaps.readthedocs.io
Project-URL: Changelog, https://github.com/dowlinglab/bits_for_gaps/blob/main/CHANGELOG.md
Project-URL: Paper, https://doi.org/10.1016/j.compchemeng.2026.109650
Author: Kyla D. Jones
Author-email: "Alexander W. Dowling" <adowling@nd.edu>
License: BSD 3-Clause License
        
        Copyright (c) 2026, Alexander W. Dowling and Kyla D. Jones
        (University of Notre Dame)
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: bayesian-optimization,experimental-design,gaussian-process,hybrid-modeling,information-theory,surrogate-modeling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.9
Requires-Dist: gpflow==2.9.2
Requires-Dist: numpy<2,>=1.26
Requires-Dist: scipy<1.14,>=1.13
Requires-Dist: setuptools<81
Requires-Dist: tensorflow-macos==2.16.2; platform_system == 'Darwin' and platform_machine == 'arm64'
Requires-Dist: tensorflow-probability==0.24.0
Requires-Dist: tensorflow==2.16.2; platform_system != 'Darwin' or platform_machine != 'arm64'
Requires-Dist: tf-keras==2.16.0
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: vle
Requires-Dist: juliacall==0.9.23; extra == 'vle'
Requires-Dist: juliapkg==0.1.13; extra == 'vle'
Description-Content-Type: text/markdown

# BITS for GAPS

[![CI](https://github.com/dowlinglab/bits_for_gaps/actions/workflows/ci.yml/badge.svg)](https://github.com/dowlinglab/bits_for_gaps/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/dowlinglab/bits_for_gaps/branch/main/graph/badge.svg)](https://codecov.io/gh/dowlinglab/bits_for_gaps)
[![PyPI](https://img.shields.io/pypi/v/bits_for_gaps.svg)](https://pypi.org/project/bits_for_gaps/)
[![Docs](https://readthedocs.org/projects/bits-for-gaps/badge/?version=latest)](https://bits-for-gaps.readthedocs.io/en/latest/?badge=latest)

**B**ayesian **I**nformation-**T**heoretic **S**ampling for hierarchical **GA**ussian **P**rocess **S**urrogates.

![BITS for GAPS framework overview: a hierarchical Gaussian process surrogate (GAPS) places priors on the kernel hyperparameters; Bayesian information-theoretic sampling (BITS) repeatedly selects the next input by maximizing the predictive differential entropy and collects data there; the result is an information-optimal surrogate whose predictions average over the hyperparameter posterior.](https://raw.githubusercontent.com/dowlinglab/bits_for_gaps/main/docs/graphical_abstract.jpg)

*Graphical abstract from the paper (© 2026 The Authors, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)).*

A framework for information-theoretic sequential experimental design with Bayesian
hierarchical Gaussian-process surrogates. Prior physical knowledge is encoded through
priors on the GP hyperparameters; sampling is guided by maximizing the predictive
differential entropy, so hyperparameter uncertainty (not just predictive variance)
drives data acquisition.

Reference: K. D. Jones and A. W. Dowling, "BITS for GAPS: Bayesian Information-Theoretic
Sampling for hierarchical GAussian Process Surrogates," *Computers & Chemical
Engineering* **211** (2026) 109650. https://doi.org/10.1016/j.compchemeng.2026.109650

The paper is **bundled in this repository** so you can read the method alongside the code:
[`paper/bits_for_gaps_paper.pdf`](paper/bits_for_gaps_paper.pdf). It is redistributed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (© 2026 The Authors, published by
Elsevier Ltd); the DOI above is the canonical citation.

## Install

```bash
pip install bits_for_gaps
```

The **core library is pure Python** (GPflow / TensorFlow / NumPy / SciPy) with no Julia
dependency. Julia + Clapeyron are only needed for the `vle_distillation` example, which
isn't part of the PyPI package -- see "From source" below.

Supports **Python 3.9-3.12**. Python 3.13+ isn't available: this package depends on
GPflow, and GPflow requires `numpy<2` in every release -- no NumPy 1.x publishes a
Python 3.13 wheel. That's an upstream constraint, not something this package can work
around; see [`docs/installation.md`](docs/installation.md) for the full explanation.

**macOS note:** set `export PYTHON_JULIACALL_HANDLE_SIGNALS=yes` before importing
`juliacall`, or Julia crashes with a bus error (SIGBUS).

### From source (for `examples/`, `paper/`, and development)

```bash
git clone https://github.com/dowlinglab/bits_for_gaps
cd bits_for_gaps
conda env create -f environment.yml
conda activate bits_for_gaps
pip install -e ".[dev]"          # core + test tools
# pip install -e ".[dev,vle]"    # add the Julia/Clapeyron VLE example backend
```

## Layout

```
src/bits_for_gaps/   the library (algorithm)
examples/            worked examples (incl. the paper's VLE/distillation case study)
paper/               scripts + reference metrics to reproduce the published figures
tests/               unit / integration / regression tests
docs/                Sphinx documentation (ReadTheDocs)
```

## Quick test

```bash
pytest -q
```

To measure coverage locally (scoped to `src/bits_for_gaps` -- `examples/`, `paper/`,
and `tests/` are repo-only and excluded from the denominator):

```bash
pytest --cov=bits_for_gaps --cov-report=term-missing
```

## Provenance

The research code behind the paper was originally developed in a private repository over the
course of the study. It was then migrated here and reorganized into an installable, tested
package: the algorithm was separated from the vapor–liquid-equilibrium case study, generalized
to arbitrary input dimension, and covered by a test suite. That private repository holds only
the development history — **nothing you need to use this package or to reproduce the paper's
figures is missing from this repository.** The data the figure scripts read is committed here
under `paper/data/` (see [`paper/REPRODUCTION.md`](paper/REPRODUCTION.md)).

## Docs

Full docs (installation, a pure-Python quickstart, theory notes, the VLE example,
reproducing the paper's figures, and the API reference):
https://bits-for-gaps.readthedocs.io

To build and browse locally instead:

```bash
pip install -e ".[docs]"
sphinx-build -W docs docs/_build/html
open docs/_build/html/index.html   # or your platform's equivalent
```
