Metadata-Version: 2.4
Name: bits_for_gaps
Version: 0.1.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: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.10,>=3.9
Requires-Dist: gpflow==2.9.2
Requires-Dist: numpy<2,>=1.26
Requires-Dist: scipy<1.14,>=1.13
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)
[![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)

<!--
The PyPI badge 404s (shields.io renders it as "invalid" or "pypi | not found") until
Phase 10's RELEASE.md STEP 3 actually publishes v0.1.0; the Docs badge similarly needs
RELEASE.md STEP 4's ReadTheDocs import to be done once. Both are inert placeholders
until then -- not a bug in this file.
-->

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

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

> **Status: pre-1.0, under active refactor.** This repository is being extracted from the
> paper's research code into a reusable library. See `REFACTOR_PLAN.md` for the roadmap and
> `HANDOFF.md` for the current state.

## Install (development)

```bash
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
```

The **core library is pure Python** (GPflow / TensorFlow / NumPy / SciPy) with no Julia
dependency. Julia + Clapeyron are only needed for the `vle_distillation` example.

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

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

## Docs

```bash
pip install -e ".[docs]"
sphinx-build -W docs docs/_build/html
```

Full docs (installation, a pure-Python quickstart, theory notes, the VLE example, and
the API reference): `docs/index.md`, or built and browsed locally as above. See
`HANDOFF.md` for ReadTheDocs setup status.
