bfflearn 0.1.0.dev3__tar.gz → 0.2.0__tar.gz

bfflearn-0.2.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## Unreleased
+
+## `0.2.0` - 2026-06-01
+
+The public reproduction snapshot for the published study is archived as
+[`v0.0.1`](https://github.com/vojtechkostal/BayesicForceFields/tree/v0.0.1).
+Use that tag for exact reproduction of the paper results. The current
+`0.2.0` release is a substantial workflow refactor.
+
+### Reference Points
+
+The code history contains two useful paper-era reference points:
+
+- Earlier paper-era branches parsed and modified GROMACS topologies through
+  ParmEd.
+- The later public `v0.0.1` reproduction snapshot had already removed ParmEd
+  and used an intermediate `gmxtop` parser together with MDAnalysis.
+- The current development line uses `gmxtopology` for GROMACS topology
+  handling and MDAnalysis selections for flexible atom grouping.
+
+### Publication Snippet
+
+Relative to the paper-era implementation, Bayesic Force Fields has been
+refactored into a staged, configuration-driven workflow for system preparation,
+reference-data generation, force-field sampling, surrogate fitting, posterior
+learning, and validation. The refactor replaces the external `emcee` sampling
+backend with an in-package Torch MCMC implementation, moves topology handling
+away from the earlier ParmEd-based path, and adds reusable quantity-of-interest
+datasets, local and Slurm execution, hierarchical charge constraints, broader
+GROMACS topology updates, and notebook-first examples for externally generated
+data.
+
+### Architecture Changes
+
+| Area | Paper-Era Implementation | `0.2.0` |
+| --- | --- | --- |
+| Posterior sampling | `emcee.EnsembleSampler` with an `emcee` HDF backend | In-package Torch parallel Metropolis-Hastings sampler with an adaptive Gaussian proposal |
+| MCMC diagnostics | Autocorrelation handling through `emcee` results | Checkpoint and restart support, rank-normalized split R-hat, integrated autocorrelation time, and effective sample size diagnostics |
+| Topology handling | Earlier branches used ParmEd; `v0.0.1` used the intermediate `gmxtop` parser | `gmxtopology` topology model with MDAnalysis selections and complete-topology updates |
+| Charge constraints | One molecule of interest, one total molecular charge, and one implicit charge parameter | Reconstructable residue- or system-level hierarchical constraints with separate implicit parameters and compatibility checks |
+| Training data | Monolithic `TrainData` arrays and YAML sidecar files | Serialized `QoIDataset` objects that can also be assembled from external data |
+| Learning results | `MCMCResults` and `InferenceResults` inside a broad `structures.py` module | Focused `LearningProblem`, `PosteriorResults`, priors, proposal, sampler, and convergence modules |
+| Workflow API | Broad `initialize`, `runsims`, `analyze`, and `learn` commands | Focused `build`, `prepare-assets`, `evaluate-snapshots`, `sample`, `analyze`, `fit`, `learn`, and `validate` stages |
+
+### Highlights
+
+- Removed the runtime `emcee` dependency and added a Torch-native MCMC stack
+  with adaptive proposals, checkpoints, restart support, and convergence
+  diagnostics.
+- Replaced the earlier ParmEd topology path with a GROMACS-native topology
+  model and MDAnalysis selections.
+- Split the former monolithic structures and inference code into focused
+  domain, MCMC, learning, and results modules.
+- Added reconstructable `specs.yaml` files and hierarchical residue- or
+  system-level charge constraints with explicit compatibility checks.
+- Added CP2K snapshot staging and collection, EXTXYZ output, PLUMED and Colvars
+  bias inputs, and local or Slurm execution.
+- Unified analyzed observables as reusable quantity-of-interest datasets and
+  added notebook workflows for arbitrary tabular data and Neon RDF inference.
+- Added callable Gaussian-process means, numerical-stability improvements, and
+  more reliable posterior plotting and MAP selection.
+- Added GROMACS function-9 dihedral force-constant sampling through labels such
+  as `dihedraltype9_3_180`, updating every matching topology term.
+- Expanded documentation, packaged examples, regression coverage, and release
+  automation.
+
+## `v0.0.1`: Publication Snapshot
+
+Archived public snapshot for reproducing the results reported in:
+
+Kostal, V.; Shanks, B. L.; Jungwirth, P.; Martinez-Seara, H.
+*Bayesian Learning for Accurate and Robust Biomolecular Force Fields.*
+J. Chem. Theory Comput. **2026**, 22 (5), 2652-2663.
+[https://doi.org/10.1021/acs.jctc.5c02051](https://doi.org/10.1021/acs.jctc.5c02051)

bfflearn-0.2.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use BFF, please cite the repository and the associated paper."
+title: "Bayesic Force Fields"
+version: "0.2.0"
+date-released: "2026-06-01"
+authors:
+  - family-names: Kostal
+    given-names: Vojtech
+url: "https://github.com/vojtechkostal/BayesicForceFields"
+repository-code: "https://github.com/vojtechkostal/BayesicForceFields"
+license: "GPL-3.0-only"
+preferred-citation:
+  type: article
+  title: "Bayesian Learning for Accurate and Robust Biomolecular Force Fields"
+  authors:
+    - family-names: Kostal
+      given-names: Vojtech
+    - family-names: Shanks
+      given-names: Brennon L.
+    - family-names: Jungwirth
+      given-names: Pavel
+    - family-names: Martinez-Seara
+      given-names: Hector
+  journal: "Journal of Chemical Theory and Computation"
+  year: 2026
+  volume: 22
+  issue: 5
+  start: 2652
+  end: 2663
+  doi: "10.1021/acs.jctc.5c02051"
+  url: "https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051"

bfflearn-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code Of Conduct
+
+Bayesic Force Fields welcomes constructive participation. Be respectful,
+assume good faith, discuss technical disagreements directly, and avoid
+harassment or discriminatory language.
+
+Report unacceptable behavior privately to the repository maintainer at
+vojtakostal8@gmail.com. Reports will be reviewed in confidence.

bfflearn-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thank you for improving Bayesic Force Fields.
+
+## Development Setup
+
+Create the repository environment and install the PyTorch build appropriate
+for your machine:
+
+```bash
+mamba env create -f environment.yaml
+mamba activate bfflearn
+```
+
+See the [development guide](https://vojtechkostal.github.io/BayesicForceFields/development/)
+for the branch workflow and repository layout.
+
+## Before Opening A Pull Request
+
+Run the release-facing checks:
+
+```bash
+python -m compileall -q bff
+ruff check .
+python -m pytest -q
+mkdocs build --strict
+python -m build
+python -m twine check dist/*
+```
+
+Keep pull requests focused, describe observable behavior changes, and add
+regression tests when fixing a bug.

bfflearn-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CHANGELOG.md
+include CITATION.cff
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+include SUPPORT.md
+include mkdocs.yml
+recursive-include docs *.md *.pdf *.svg
+recursive-include tests *.py

bfflearn-0.2.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: bfflearn
+Version: 0.2.0
+Summary: Bayesian workflows for fixed-charge molecular force fields
+Author-email: Vojtech Kostal <vojtakostal8@gmail.com>
+License-Expression: GPL-3.0-only
+Project-URL: Documentation, https://vojtechkostal.github.io/BayesicForceFields/
+Project-URL: Homepage, https://github.com/vojtechkostal/BayesicForceFields
+Project-URL: Issues, https://github.com/vojtechkostal/BayesicForceFields/issues
+Project-URL: Publication, https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051
+Project-URL: Preprint, https://arxiv.org/abs/2511.05398
+Project-URL: Releases, https://github.com/vojtechkostal/BayesicForceFields/releases
+Project-URL: Repository, https://github.com/vojtechkostal/BayesicForceFields
+Keywords: bayesian-inference,force-fields,gromacs,molecular-dynamics,physical-chemistry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gmxtopology>=0.1.1
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: MDAnalysis>=2.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: typer>=0.12
+Provides-Extra: notebook
+Requires-Dist: ipykernel; extra == "notebook"
+Requires-Dist: ipython; extra == "notebook"
+Requires-Dist: ipywidgets; extra == "notebook"
+Requires-Dist: jupyterlab; extra == "notebook"
+Requires-Dist: notebook; extra == "notebook"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: pymdown-extensions; extra == "docs"
+Dynamic: license-file
+
+# Bayesic Force Fields
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vojtechkostal/BayesicForceFields/main/docs/assets/bff-logo.svg" alt="BFF logo" width="300">
+</p>
+
+[![Docs](https://img.shields.io/badge/docs-latest-brightgreen)](https://vojtechkostal.github.io/BayesicForceFields/)
+[![Paper](https://img.shields.io/badge/paper-JCTC%202026-blue)](https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051)
+[![Release](https://img.shields.io/github/v/tag/vojtechkostal/BayesicForceFields?label=release)](https://github.com/vojtechkostal/BayesicForceFields/releases)
+[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE)
+
+Bayesic Force Fields (BFF) is a Python toolkit for learning fixed-charge
+molecular force-field parameters from molecular-dynamics observables. It
+coordinates simulation campaigns, trajectory analysis, surrogate fitting, and
+Bayesian posterior learning.
+
+Full documentation:
+[vojtechkostal.github.io/BayesicForceFields](https://vojtechkostal.github.io/BayesicForceFields/)
+
+## Workflow
+
+```text
+build -> prepare-assets -> evaluate-snapshots
+                       -> sample -> analyze -> fit -> learn -> validate
+```
+
+The command-line interface guides a force-field model from prepared molecular
+systems to sampled trajectories, quantities of interest, surrogate models, and
+validated posterior samples. See the [CLI reference](https://vojtechkostal.github.io/BayesicForceFields/cli/)
+for the
+individual commands.
+
+## Installation
+
+Create an environment, install the [PyTorch build appropriate for your
+machine](https://pytorch.org/get-started/locally/), and then install BFF:
+
+```bash
+mamba create -n bfflearn python=3.10 pip
+mamba activate bfflearn
+pip install bfflearn
+```
+
+> **WARNING:** GPU-enabled PyTorch must be installed separately. Use the
+> [official PyTorch installation selector](https://pytorch.org/get-started/locally/)
+> to choose the command matching your CUDA version before running fitting,
+> learning, or the posterior notebooks.
+
+Full MD workflows also require GROMACS. CP2K and PLUMED are needed only for the
+stages that use them. See the [installation guide](https://vojtechkostal.github.io/BayesicForceFields/installation/)
+for
+details, CUDA guidance, and the repository-development setup.
+
+## Quick Start
+
+Install the example tree and choose a walkthrough:
+
+```bash
+bff examples
+cd examples/acetate
+```
+
+- [Acetate](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/acetate):
+  complete staged MD workflow.
+- [Arbitrary data](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/arbitrary-data):
+  notebook using existing tabular
+  simulation results and targets.
+- [Neon Mie](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/neon-mie-lgpmd):
+  notebook using published RDF data.
+
+The [examples guide](https://vojtechkostal.github.io/BayesicForceFields/examples/)
+explains which starting point fits your data. The
+[acetate walkthrough](https://vojtechkostal.github.io/BayesicForceFields/examples/acetate/)
+shows the full command sequence.
+
+## Supported Parameters
+
+BFF currently updates and learns four GROMACS force-field parameter families:
+
+| Parameter | Bound label example |
+| --- | --- |
+| Partial charge | `charge O1 O2` |
+| Lennard-Jones sigma | `sigma OW` |
+| Lennard-Jones epsilon | `epsilon OW` |
+| Function-9 dihedral force constant | `dihedraltype9_3_180` |
+
+Multiple names in one label share one learned value. Charges can additionally
+participate in hierarchical residue- or system-level constraints. The [sample
+configuration reference](https://vojtechkostal.github.io/BayesicForceFields/configuration/sample/#parameter-labels)
+documents the complete syntax and matching rules.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["YAML configs or Python API"] --> B["Simulation workflows"]
+    B --> C["Trajectories and reference data"]
+    C --> D["QoIDataset"]
+    D --> E["Gaussian-process surrogates"]
+    E --> F["Posterior learning and validation"]
+```
+
+The [architecture guide](https://vojtechkostal.github.io/BayesicForceFields/architecture/)
+describes the package modules, workflow stages, persisted artifacts, and
+repository layout.
+
+## Documentation
+
+- [Installation](https://vojtechkostal.github.io/BayesicForceFields/installation/)
+- [Examples](https://vojtechkostal.github.io/BayesicForceFields/examples/)
+- [Configuration reference](https://vojtechkostal.github.io/BayesicForceFields/configuration/build/)
+- [Architecture](https://vojtechkostal.github.io/BayesicForceFields/architecture/)
+- [Changelog](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CHANGELOG.md)
+- [Development](https://vojtechkostal.github.io/BayesicForceFields/development/)
+- [Contributing](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CONTRIBUTING.md)
+- [Support](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SUPPORT.md)
+- [Security](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SECURITY.md)
+
+## Citation
+
+If you use BFF, please cite:
+
+> Kostal, V.; Shanks, B. L.; Jungwirth, P.; Martinez-Seara, H.
+> Bayesian Learning for Accurate and Robust Biomolecular Force Fields.
+> *J. Chem. Theory Comput.* **2026**, *22* (5), 2652-2663.
+> [https://doi.org/10.1021/acs.jctc.5c02051](https://doi.org/10.1021/acs.jctc.5c02051)
+
+The exact publication snapshot is archived as
+[`v0.0.1`](https://github.com/vojtechkostal/BayesicForceFields/tree/v0.0.1).
+
+## License
+
+BFF is distributed under the
+[GNU GPL v3](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE).

bfflearn-0.2.0/README.md

@@ -0,0 +1,134 @@
+# Bayesic Force Fields
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vojtechkostal/BayesicForceFields/main/docs/assets/bff-logo.svg" alt="BFF logo" width="300">
+</p>
+
+[![Docs](https://img.shields.io/badge/docs-latest-brightgreen)](https://vojtechkostal.github.io/BayesicForceFields/)
+[![Paper](https://img.shields.io/badge/paper-JCTC%202026-blue)](https://pubs.acs.org/doi/10.1021/acs.jctc.5c02051)
+[![Release](https://img.shields.io/github/v/tag/vojtechkostal/BayesicForceFields?label=release)](https://github.com/vojtechkostal/BayesicForceFields/releases)
+[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE)
+
+Bayesic Force Fields (BFF) is a Python toolkit for learning fixed-charge
+molecular force-field parameters from molecular-dynamics observables. It
+coordinates simulation campaigns, trajectory analysis, surrogate fitting, and
+Bayesian posterior learning.
+
+Full documentation:
+[vojtechkostal.github.io/BayesicForceFields](https://vojtechkostal.github.io/BayesicForceFields/)
+
+## Workflow
+
+```text
+build -> prepare-assets -> evaluate-snapshots
+                       -> sample -> analyze -> fit -> learn -> validate
+```
+
+The command-line interface guides a force-field model from prepared molecular
+systems to sampled trajectories, quantities of interest, surrogate models, and
+validated posterior samples. See the [CLI reference](https://vojtechkostal.github.io/BayesicForceFields/cli/)
+for the
+individual commands.
+
+## Installation
+
+Create an environment, install the [PyTorch build appropriate for your
+machine](https://pytorch.org/get-started/locally/), and then install BFF:
+
+```bash
+mamba create -n bfflearn python=3.10 pip
+mamba activate bfflearn
+pip install bfflearn
+```
+
+> **WARNING:** GPU-enabled PyTorch must be installed separately. Use the
+> [official PyTorch installation selector](https://pytorch.org/get-started/locally/)
+> to choose the command matching your CUDA version before running fitting,
+> learning, or the posterior notebooks.
+
+Full MD workflows also require GROMACS. CP2K and PLUMED are needed only for the
+stages that use them. See the [installation guide](https://vojtechkostal.github.io/BayesicForceFields/installation/)
+for
+details, CUDA guidance, and the repository-development setup.
+
+## Quick Start
+
+Install the example tree and choose a walkthrough:
+
+```bash
+bff examples
+cd examples/acetate
+```
+
+- [Acetate](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/acetate):
+  complete staged MD workflow.
+- [Arbitrary data](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/arbitrary-data):
+  notebook using existing tabular
+  simulation results and targets.
+- [Neon Mie](https://github.com/vojtechkostal/BayesicForceFields/tree/main/examples/neon-mie-lgpmd):
+  notebook using published RDF data.
+
+The [examples guide](https://vojtechkostal.github.io/BayesicForceFields/examples/)
+explains which starting point fits your data. The
+[acetate walkthrough](https://vojtechkostal.github.io/BayesicForceFields/examples/acetate/)
+shows the full command sequence.
+
+## Supported Parameters
+
+BFF currently updates and learns four GROMACS force-field parameter families:
+
+| Parameter | Bound label example |
+| --- | --- |
+| Partial charge | `charge O1 O2` |
+| Lennard-Jones sigma | `sigma OW` |
+| Lennard-Jones epsilon | `epsilon OW` |
+| Function-9 dihedral force constant | `dihedraltype9_3_180` |
+
+Multiple names in one label share one learned value. Charges can additionally
+participate in hierarchical residue- or system-level constraints. The [sample
+configuration reference](https://vojtechkostal.github.io/BayesicForceFields/configuration/sample/#parameter-labels)
+documents the complete syntax and matching rules.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["YAML configs or Python API"] --> B["Simulation workflows"]
+    B --> C["Trajectories and reference data"]
+    C --> D["QoIDataset"]
+    D --> E["Gaussian-process surrogates"]
+    E --> F["Posterior learning and validation"]
+```
+
+The [architecture guide](https://vojtechkostal.github.io/BayesicForceFields/architecture/)
+describes the package modules, workflow stages, persisted artifacts, and
+repository layout.
+
+## Documentation
+
+- [Installation](https://vojtechkostal.github.io/BayesicForceFields/installation/)
+- [Examples](https://vojtechkostal.github.io/BayesicForceFields/examples/)
+- [Configuration reference](https://vojtechkostal.github.io/BayesicForceFields/configuration/build/)
+- [Architecture](https://vojtechkostal.github.io/BayesicForceFields/architecture/)
+- [Changelog](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CHANGELOG.md)
+- [Development](https://vojtechkostal.github.io/BayesicForceFields/development/)
+- [Contributing](https://github.com/vojtechkostal/BayesicForceFields/blob/main/CONTRIBUTING.md)
+- [Support](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SUPPORT.md)
+- [Security](https://github.com/vojtechkostal/BayesicForceFields/blob/main/SECURITY.md)
+
+## Citation
+
+If you use BFF, please cite:
+
+> Kostal, V.; Shanks, B. L.; Jungwirth, P.; Martinez-Seara, H.
+> Bayesian Learning for Accurate and Robust Biomolecular Force Fields.
+> *J. Chem. Theory Comput.* **2026**, *22* (5), 2652-2663.
+> [https://doi.org/10.1021/acs.jctc.5c02051](https://doi.org/10.1021/acs.jctc.5c02051)
+
+The exact publication snapshot is archived as
+[`v0.0.1`](https://github.com/vojtechkostal/BayesicForceFields/tree/v0.0.1).
+
+## License
+
+BFF is distributed under the
+[GNU GPL v3](https://github.com/vojtechkostal/BayesicForceFields/blob/main/LICENSE).

bfflearn-0.2.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the latest tagged BFF release.
+
+## Reporting A Vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Report it
+privately through
+[GitHub private vulnerability reporting](https://github.com/vojtechkostal/BayesicForceFields/security/advisories/new).
+If private vulnerability reporting is not enabled, email
+vojtakostal8@gmail.com. Include the affected version, reproduction steps, and
+expected impact.

bfflearn-0.2.0/SUPPORT.md

@@ -0,0 +1,11 @@
+# Support
+
+For installation questions, unexpected behavior, and feature requests, open a
+[GitHub issue](https://github.com/vojtechkostal/BayesicForceFields/issues).
+
+Include the BFF version, Python version, operating system, relevant
+configuration fragment, and the complete error message. For GROMACS, CP2K, or
+PLUMED issues, also include the external tool version and invocation.
+
+Report security-sensitive issues privately as described in
+[SECURITY.md](SECURITY.md).

bfflearn-0.2.0/bff/__init__.py

@@ -0,0 +1,121 @@
+"""Bayesic Force Fields public package namespace."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from pathlib import Path
+from typing import Any
+
+__version__ = "0.2.0"
+
+_INTERNAL_MODULES = {
+    "bayes",
+    "data",
+    "domain",
+    "io",
+    "plotting",
+    "qoi",
+    "tools",
+}
+
+__all__ = [
+    "Project",
+    "build",
+    "prepare_assets",
+    "evaluate_snapshots",
+    "sample",
+    "analyze",
+    "fit",
+    "learn",
+    "validate",
+    "QoI",
+    "QoIDataset",
+    "PosteriorResults",
+]
+
+
+def _run_workflow(module_name: str, fn_config: str | Path):
+    workflow = import_module(module_name)
+    return workflow.main(Path(fn_config))
+
+
+def build(fn_config: str | Path):
+    return _run_workflow("bff.workflows.build", fn_config)
+
+
+def prepare_assets(fn_config: str | Path):
+    return _run_workflow("bff.workflows.prepare_assets", fn_config)
+
+
+def evaluate_snapshots(fn_config: str | Path):
+    return _run_workflow("bff.workflows.evaluate_snapshots", fn_config)
+
+
+def sample(fn_config: str | Path):
+    return _run_workflow("bff.workflows.sample", fn_config)
+
+
+def analyze(fn_config: str | Path):
+    return _run_workflow("bff.workflows.analyze", fn_config)
+
+
+def fit(fn_config: str | Path):
+    return _run_workflow("bff.workflows.fit", fn_config)
+
+
+def learn(fn_config: str | Path):
+    return _run_workflow("bff.workflows.learn", fn_config)
+
+
+def validate(fn_config: str | Path):
+    return _run_workflow("bff.workflows.validate", fn_config)
+
+
+class Project:
+    def __init__(self, root: str | Path):
+        self.root = Path(root).expanduser().resolve()
+
+    def _resolve(self, fn_config: str | Path) -> Path:
+        fn_config = Path(fn_config)
+        if fn_config.is_absolute():
+            return fn_config
+        return (self.root / fn_config).resolve()
+
+    def build(self, fn_config: str | Path):
+        return build(self._resolve(fn_config))
+
+    def prepare_assets(self, fn_config: str | Path):
+        return prepare_assets(self._resolve(fn_config))
+
+    def evaluate_snapshots(self, fn_config: str | Path):
+        return evaluate_snapshots(self._resolve(fn_config))
+
+    def sample(self, fn_config: str | Path):
+        return sample(self._resolve(fn_config))
+
+    def analyze(self, fn_config: str | Path):
+        return analyze(self._resolve(fn_config))
+
+    def fit(self, fn_config: str | Path):
+        return fit(self._resolve(fn_config))
+
+    def learn(self, fn_config: str | Path):
+        return learn(self._resolve(fn_config))
+
+    def validate(self, fn_config: str | Path):
+        return validate(self._resolve(fn_config))
+
+
+def __getattr__(name: str) -> Any:
+    if name in _INTERNAL_MODULES:
+        return import_module(f".{name}", __name__)
+    if name == "QoI":
+        from .qoi.data import QoI
+        return QoI
+    if name == "QoIDataset":
+        from .qoi.data import QoIDataset
+        return QoIDataset
+    if name == "PosteriorResults":
+        from .bayes.results import PosteriorResults
+        return PosteriorResults
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")