boltzmann-generators 0.2.1__tar.gz

boltzmann_generators-0.2.1/.github/workflows/cd.yml

@@ -0,0 +1,107 @@
+name: CD
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  detect-version-bump:
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.detect.outputs.should_release }}
+      version: ${{ steps.detect.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Detect version bump
+        id: detect
+        run: |
+          CURRENT=$(grep '^version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          PREVIOUS=$(git show HEAD~1:pyproject.toml 2>/dev/null | grep '^version = ' | head -1 | sed 's/version = "\(.*\)"/\1/' || true)
+
+          if [ -z "$CURRENT" ]; then
+            echo "Could not read version from pyproject.toml"
+            exit 1
+          fi
+
+          echo "Current version:  $CURRENT"
+          echo "Previous version: ${PREVIOUS:-<none>}"
+
+          if [ "$CURRENT" != "$PREVIOUS" ]; then
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+            echo "version=$CURRENT" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            echo "No version bump detected; skipping release."
+          fi
+
+  validate-changelog:
+    needs: detect-version-bump
+    if: needs.detect-version-bump.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify changelog contains release version
+        env:
+          VERSION: ${{ needs.detect-version-bump.outputs.version }}
+        run: |
+          if ! grep -q "\[${VERSION}\]" CHANGELOG.md; then
+            echo "CHANGELOG.md is missing section for version ${VERSION}"
+            exit 1
+          fi
+
+  release:
+    needs: [detect-version-bump, validate-changelog]
+    if: needs.detect-version-bump.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Install build tools
+        run: uv sync --extra dev
+      - name: Build package
+        run: uv run python -m build
+      - name: Check distribution
+        run: uv run twine check dist/*
+      - name: Create git tag
+        env:
+          VERSION: ${{ needs.detect-version-bump.outputs.version }}
+        run: |
+          TAG="v${VERSION}"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag ${TAG} already exists; skipping tag creation."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release ${TAG}"
+          git push origin "$TAG"
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+      - name: Create GitHub Release
+        env:
+          VERSION: ${{ needs.detect-version-bump.outputs.version }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${VERSION}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "GitHub release ${TAG} already exists; skipping."
+            exit 0
+          fi
+          gh release create "$TAG" \
+            --title "v${VERSION}" \
+            --notes "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md#${VERSION//./}) for details."

boltzmann_generators-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy src
+      - name: Test with coverage
+        run: uv run pytest
+      - name: Build package
+        run: uv run python -m build
+      - name: Check distribution
+        run: uv run twine check dist/*

boltzmann_generators-0.2.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual envs
+.venv
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Data + model artifacts
+data/
+*.pt
+*.pth
+*.npz
+*.h5
+
+# Reference repos (cloned, not authored here)
+references/paper_boltzmann_generators/
+
+# OS
+.DS_Store

boltzmann_generators-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-setuptools]
+        args: [--config-file=pyproject.toml]
+        files: ^src/

boltzmann_generators-0.2.1/.python-version

@@ -0,0 +1 @@
+3.11

boltzmann_generators-0.2.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-06-21
+
+### Changed
+
+- CI now runs on pull requests to `main` only.
+- CD runs on merge to `main` and publishes to PyPI when the version is bumped.
+- Release automation creates git tags and GitHub releases on version bump.
+
+## [0.2.0] - 2026-06-20
+
+### Added
+
+- OOP core abstractions: `EnergyModel`, `BaseDensityModel`, and `DensityModel`.
+- Class-based training API via `boltzmann_generators.training.Trainer`.
+- Loss strategy classes: `ForwardKLLoss`, `ReverseKLLoss`, `MixedLossStrategy`.
+- Service classes: `SamplingEngine`, `AnalysisSuite`, `CheckpointManager`.
+- PEP 561 typing marker (`py.typed`) and mypy configuration.
+- Coverage gate (`>=75%`) in pytest/CI.
+- PyPI release workflow with changelog validation and trusted publishing.
+- Example notebooks under `examples/notebooks/`.
+- Release checklist in `RELEASE.md` and migration guide in `MIGRATION.md`.
+
+### Changed
+
+- `FlowModel` and `CNFFlowModel` now inherit from `BaseDensityModel`.
+- Energy classes now inherit from `EnergyModel`.
+- `train_bg()` is deprecated in favor of `Trainer.fit()`.
+- Package version bumped to `0.2.0`.
+
+### Fixed
+
+- Removed stale `src/bg` wheel package reference that could break builds.
+- README quickstart no longer calls `.to(device)` on non-module energy objects.
+
+## [0.1.0] - 2026-06-16
+
+### Added
+
+- Initial open-source packaging of the Boltzmann Generators PyTorch implementation.
+- Split package layout with `boltzmann_generators` as the primary import path.
+- OSS project metadata, CI, contribution docs, and testing scaffold.

boltzmann_generators-0.2.1/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+title: boltzmann-generators
+message: "If you use this software, please cite this repository and the original papers."
+type: software
+authors:
+  - family-names: Martin
+    given-names: Manu
+repository-code: "https://github.com/manumartinm/boltzmann-generators"
+license: MIT
+version: 0.2.1
+date-released: 2026-06-21
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Noe
+      given-names: Frank
+    - family-names: Olsson
+      given-names: Simon
+    - family-names: Kohler
+      given-names: Jonas
+    - family-names: Wu
+      given-names: Hao
+  title: "Boltzmann Generators: Sampling Equilibrium States of Many-Body Systems with Deep Learning"
+  journal: Science
+  year: 2019
+  volume: 365
+  issue: 6457
+  doi: 10.1126/science.aaw1147

boltzmann_generators-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for your interest in contributing to `boltzmann-generators`.
+
+## Development setup
+
+```bash
+uv sync --extra dev --extra notebook
+pre-commit install
+```
+
+## Running checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run pytest
+uv run python -m build
+uv run twine check dist/*
+```
+
+## Pull request guidelines
+
+- Open PRs against `main`; CI runs automatically on each PR.
+- To release: bump version in `pyproject.toml` + `__init__.py`, update `CHANGELOG.md`, merge — CD publishes on merge.
+- Keep changes focused and scoped to a clear problem.
+- Add or update tests for behavior changes.
+- Update docs when public APIs change.
+- Add a `CHANGELOG.md` entry for user-visible changes.
+- Keep notebooks reproducible and deterministic where possible.
+
+## Code style
+
+- Python 3.11+.
+- Ruff handles linting and import sorting.
+- Prefer explicit, typed APIs for public modules.
+- Use OOP service classes (`Trainer`, `SamplingEngine`, etc.) for new features.

boltzmann_generators-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manu Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

boltzmann_generators-0.2.1/MIGRATION.md

@@ -0,0 +1,76 @@
+# Migration Guide (0.1.x → 0.2.x)
+
+Version 0.2.0 introduces a class-based OOP API while keeping backward-compatible function wrappers.
+
+## Training
+
+**Before (0.1.x):**
+
+```python
+from boltzmann_generators.train import TrainConfig, train_bg
+
+history = train_bg(model, energy, x_data=x_data, config=config, device=device)
+```
+
+**After (0.2.x, recommended):**
+
+```python
+from boltzmann_generators.training import TrainConfig, Trainer
+
+trainer = Trainer(model, energy, config, device=device)
+history = trainer.fit(x_data)
+```
+
+`train_bg()` still works but emits a `DeprecationWarning`.
+
+## Sampling and analysis
+
+**Before:**
+
+```python
+from boltzmann_generators.sampling import sample_with_weights, effective_sample_size
+from boltzmann_generators.analysis import basin_populations
+```
+
+**After (recommended service API):**
+
+```python
+from boltzmann_generators.services import SamplingEngine, AnalysisSuite
+
+engine = SamplingEngine(model, energy)
+x, log_w, log_q = engine.sample_with_weights(1024, device="cpu")
+ess = engine.effective_sample_size(log_w)
+
+suite = AnalysisSuite(engine)
+pops = suite.basin_populations(x, {"left": left_fn, "right": right_fn}, log_w=log_w)
+```
+
+Function imports in `boltzmann_generators.sampling` and `boltzmann_generators.analysis` remain available.
+
+## Checkpoints
+
+**Before:**
+
+```python
+from boltzmann_generators.io import save_checkpoint, load_checkpoint
+```
+
+**After (recommended):**
+
+```python
+from boltzmann_generators.services import CheckpointManager
+
+mgr = CheckpointManager()
+mgr.save(model, "model.pt", config={"lr": 1e-3})
+model, meta = mgr.load("model.pt", model)
+```
+
+## Type interfaces
+
+- Energies should subclass or conform to `boltzmann_generators.base.EnergyModel`.
+- Density models should subclass `boltzmann_generators.base.BaseDensityModel`.
+- Loss functions accept any object matching the `DensityModel` protocol.
+
+## Example notebooks
+
+See runnable examples in [`examples/notebooks/`](examples/notebooks/).

boltzmann_generators-0.2.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: boltzmann-generators
+Version: 0.2.1
+Summary: Boltzmann Generators in PyTorch: flows, energies, losses, and sampling utilities.
+Project-URL: Homepage, https://github.com/manumartinm/boltzmann-generators
+Project-URL: Repository, https://github.com/manumartinm/boltzmann-generators
+Project-URL: Issues, https://github.com/manumartinm/boltzmann-generators/issues
+Project-URL: Changelog, https://github.com/manumartinm/boltzmann-generators/blob/main/CHANGELOG.md
+Author: Manu Martin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: boltzmann-generators,molecular-dynamics,normalizing-flows,pytorch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0
+Requires-Dist: torch>=2.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: notebook
+Requires-Dist: jupyterlab>=4.0; extra == 'notebook'
+Requires-Dist: matplotlib>=3.8; extra == 'notebook'
+Requires-Dist: nbconvert>=7.0; extra == 'notebook'
+Requires-Dist: pandas>=2.0; extra == 'notebook'
+Provides-Extra: ode
+Requires-Dist: torchdiffeq>=0.2; extra == 'ode'
+Description-Content-Type: text/markdown
+
+# boltzmann-generators
+
+[![CI](https://github.com/manumartinm/boltzmann-generators/actions/workflows/ci.yml/badge.svg)](https://github.com/manumartinm/boltzmann-generators/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/boltzmann-generators)](https://pypi.org/project/boltzmann-generators/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+PyTorch tools for Boltzmann Generators: invertible flows, benchmark energy functions, BG losses, and reweighting diagnostics (ESS and free-energy differences). The project is designed for reproducible experiments on toy molecular systems and as a base for transferable BG research.
+
+## References
+
+1. Noé, Olsson, Köhler, Wu, *Boltzmann Generators: Sampling Equilibrium States of Many-Body Systems with Deep Learning* (Science, 2019): <https://arxiv.org/abs/1812.01729>
+2. Klein, Noé, *Transferable Boltzmann Generators* (NeurIPS, 2024): <https://openreview.net/forum?id=AYq6GxxrrY>
+3. Original reference implementation: <https://github.com/noegroup/paper_boltzmann_generators>
+
+## Installation
+
+```bash
+pip install boltzmann-generators
+```
+
+For notebooks and plots:
+
+```bash
+pip install "boltzmann-generators[notebook]"
+```
+
+For development:
+
+```bash
+pip install "boltzmann-generators[dev]"
+```
+
+For higher-accuracy CNF ODE integration:
+
+```bash
+pip install "boltzmann-generators[ode]"
+```
+
+## Quickstart
+
+```python
+import torch
+from boltzmann_generators.energies import DoubleWell2D
+from boltzmann_generators.flows import FlowModel, GaussianPrior, RealNVP
+from boltzmann_generators.training import TrainConfig, Trainer
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+
+energy = DoubleWell2D()
+prior = GaussianPrior(dim=2).to(device)
+flow = RealNVP(dim=2, num_layers=8, hidden_dim=64, mask="halves").to(device)
+model = FlowModel(prior, flow).to(device)
+
+config = TrainConfig(n_epochs=200, batch_size=256, lr=1e-3, w_ml=0.0, w_kl=1.0)
+trainer = Trainer(model, energy, config, device=device)
+history = trainer.fit(x_data=None)
+print("Final loss:", history[-1]["loss"])
+```
+
+## Project layout
+
+```text
+src/boltzmann_generators/
+  base/                # EnergyModel and BaseDensityModel ABCs
+  training/            # Trainer and loss strategy classes
+  services/            # SamplingEngine, AnalysisSuite, CheckpointManager
+  energies/            # double-well, Muller-Brown, Ramachandran-like energy
+  flows/               # base flow API, RealNVP, CNF
+  losses.py            # KL_x, KL_z, mixed loss (function wrappers)
+  sampling.py          # weighted samples, ESS, free-energy difference
+  mcmc.py              # Metropolis baseline sampler
+  train.py             # deprecated train_bg wrapper
+  analysis.py          # basin and population utilities
+
+examples/notebooks/    # curated runnable examples
+notebooks/             # end-to-end reproductions (02-07)
+```
+
+## Reproduced results
+
+| Notebook | System | Metric | Value |
+|---|---|---|---|
+| 02 | 4-mode Gaussian mixture | Final NLL | 2.23 nats (target entropy: 2.13) |
+| 03 | Double-well 2D (4 kT barrier) | ESS / DeltaF | 98% / +0.004 kT (target 0) |
+| 04 | Muller-Brown (3 basins) | ESS / populations | 96% / target [80.37, 7.74, 11.89]%, BG [80.23, 7.71, 12.05]% |
+| 05 | Double-well paper comparison | ESS | 92% |
+| 06 | Gaussian mixture (CFM) | Visual mode coverage | All 4 modes recovered |
+| 07 | Synthetic Ramachandran | Visual + basin populations | Reweighted BG close to ground truth |
+
+## Documentation
+
+- Example notebooks: [`examples/notebooks/`](examples/notebooks/)
+- Migration guide (0.1 → 0.2): [`MIGRATION.md`](MIGRATION.md)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Release process: [`RELEASE.md`](RELEASE.md)
+- Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Research notebooks: `notebooks/`
+
+If you need the original Noé group reference repository locally, clone it into:
+
+```bash
+git clone --depth 1 https://github.com/noegroup/paper_boltzmann_generators.git references/paper_boltzmann_generators
+```

boltzmann_generators-0.2.1/README.md

@@ -0,0 +1,104 @@
+# boltzmann-generators
+
+[![CI](https://github.com/manumartinm/boltzmann-generators/actions/workflows/ci.yml/badge.svg)](https://github.com/manumartinm/boltzmann-generators/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/boltzmann-generators)](https://pypi.org/project/boltzmann-generators/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+PyTorch tools for Boltzmann Generators: invertible flows, benchmark energy functions, BG losses, and reweighting diagnostics (ESS and free-energy differences). The project is designed for reproducible experiments on toy molecular systems and as a base for transferable BG research.
+
+## References
+
+1. Noé, Olsson, Köhler, Wu, *Boltzmann Generators: Sampling Equilibrium States of Many-Body Systems with Deep Learning* (Science, 2019): <https://arxiv.org/abs/1812.01729>
+2. Klein, Noé, *Transferable Boltzmann Generators* (NeurIPS, 2024): <https://openreview.net/forum?id=AYq6GxxrrY>
+3. Original reference implementation: <https://github.com/noegroup/paper_boltzmann_generators>
+
+## Installation
+
+```bash
+pip install boltzmann-generators
+```
+
+For notebooks and plots:
+
+```bash
+pip install "boltzmann-generators[notebook]"
+```
+
+For development:
+
+```bash
+pip install "boltzmann-generators[dev]"
+```
+
+For higher-accuracy CNF ODE integration:
+
+```bash
+pip install "boltzmann-generators[ode]"
+```
+
+## Quickstart
+
+```python
+import torch
+from boltzmann_generators.energies import DoubleWell2D
+from boltzmann_generators.flows import FlowModel, GaussianPrior, RealNVP
+from boltzmann_generators.training import TrainConfig, Trainer
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+
+energy = DoubleWell2D()
+prior = GaussianPrior(dim=2).to(device)
+flow = RealNVP(dim=2, num_layers=8, hidden_dim=64, mask="halves").to(device)
+model = FlowModel(prior, flow).to(device)
+
+config = TrainConfig(n_epochs=200, batch_size=256, lr=1e-3, w_ml=0.0, w_kl=1.0)
+trainer = Trainer(model, energy, config, device=device)
+history = trainer.fit(x_data=None)
+print("Final loss:", history[-1]["loss"])
+```
+
+## Project layout
+
+```text
+src/boltzmann_generators/
+  base/                # EnergyModel and BaseDensityModel ABCs
+  training/            # Trainer and loss strategy classes
+  services/            # SamplingEngine, AnalysisSuite, CheckpointManager
+  energies/            # double-well, Muller-Brown, Ramachandran-like energy
+  flows/               # base flow API, RealNVP, CNF
+  losses.py            # KL_x, KL_z, mixed loss (function wrappers)
+  sampling.py          # weighted samples, ESS, free-energy difference
+  mcmc.py              # Metropolis baseline sampler
+  train.py             # deprecated train_bg wrapper
+  analysis.py          # basin and population utilities
+
+examples/notebooks/    # curated runnable examples
+notebooks/             # end-to-end reproductions (02-07)
+```
+
+## Reproduced results
+
+| Notebook | System | Metric | Value |
+|---|---|---|---|
+| 02 | 4-mode Gaussian mixture | Final NLL | 2.23 nats (target entropy: 2.13) |
+| 03 | Double-well 2D (4 kT barrier) | ESS / DeltaF | 98% / +0.004 kT (target 0) |
+| 04 | Muller-Brown (3 basins) | ESS / populations | 96% / target [80.37, 7.74, 11.89]%, BG [80.23, 7.71, 12.05]% |
+| 05 | Double-well paper comparison | ESS | 92% |
+| 06 | Gaussian mixture (CFM) | Visual mode coverage | All 4 modes recovered |
+| 07 | Synthetic Ramachandran | Visual + basin populations | Reweighted BG close to ground truth |
+
+## Documentation
+
+- Example notebooks: [`examples/notebooks/`](examples/notebooks/)
+- Migration guide (0.1 → 0.2): [`MIGRATION.md`](MIGRATION.md)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Release process: [`RELEASE.md`](RELEASE.md)
+- Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Research notebooks: `notebooks/`
+
+If you need the original Noé group reference repository locally, clone it into:
+
+```bash
+git clone --depth 1 https://github.com/noegroup/paper_boltzmann_generators.git references/paper_boltzmann_generators
+```