torchdeltaflow 0.2.1__tar.gz → 0.2.3.dev21__tar.gz

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/.github/workflows/ci.yml

@@ -1,25 +1,25 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
-      - name: Test
-        run: pytest --cov=deltaflow
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest --cov=deltaflow

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/.github/workflows/docs.yml

@@ -1,43 +1,43 @@
-name: docs
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[docs]"
-      - name: Build site
-        run: mkdocs build --strict
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

torchdeltaflow-0.2.3.dev21/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: publish
+
+# Publishes torchdeltaflow to PyPI in two cases:
+#
+#   1. A version tag (e.g. v0.2.2) is pushed -> a stable release. The version is
+#      derived from the tag by setuptools_scm, so the tag is the single source
+#      of truth. To cut a release, run:
+#
+#          git tag v0.2.2
+#          git push origin v0.2.2
+#
+#   2. A pull request is merged into main -> a dev pre-release. setuptools_scm
+#      derives a clean PEP 440 version from the commit distance to the last tag
+#      (e.g. "0.2.3.dev4"), which is unique per merge. "skip-existing" below
+#      guards against the rare case where the same version was already uploaded.
+#
+# Authentication uses a PyPI API token stored as the repository secret
+# PYPI_API_TOKEN. Create the token at https://pypi.org/manage/account/token/
+# (scope it to the torchdeltaflow project), then add it under
+# Settings > Secrets and variables > Actions as PYPI_API_TOKEN.
+
+on:
+  push:
+    tags:
+      - "v*"
+  pull_request:
+    branches: [main]
+    types: [closed]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    # Run for pushed version tags, or when a PR is actually merged (not just
+    # closed). Plain "closed" without merge must not publish.
+    if: github.event_name == 'push' || github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm needs the full history and tags to derive the version.
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/torchdeltaflow/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # Merge builds may reproduce an existing dev version if no new commits
+          # changed the distance to the last tag. Skip rather than fail.
+          skip-existing: true

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/.gitignore

@@ -1,82 +1,83 @@
-# --- Python ---
-__pycache__/
-*.py[cod]
-*.pyo
-*.pyd
-*$py.class
-.Python
-
-# --- Build / packaging ---
-build/
-dist/
-wheels/
-*.egg-info/
-*.egg
-.eggs/
-pip-wheel-metadata/
-MANIFEST
-
-# setuptools_scm writes deltaflow/_version.py; keep it out of git
-deltaflow/_version.py
-
-# --- Virtual environments ---
-venv/
-.venv/
-env/
-.env
-.env.*
-
-# --- Testing / coverage ---
-.pytest_cache/
-.coverage
-.coverage.*
-htmlcov/
-coverage.xml
-.tox/
-.nox/
-.hypothesis/
-
-# --- Type checkers / linters ---
-.mypy_cache/
-.pyright/
-.ruff_cache/
-.pytype/
-
-# --- Docs ---
-site/
-docs/_build/
-
-# --- Jupyter ---
-.ipynb_checkpoints/
-
-# --- Training artifacts (created by deltaflow.trainer + examples) ---
-checkpoints/
-outputs/
-runs/
-wandb/
-logs/
-*.pt
-*.pth
-*.ckpt
-*.safetensors
-
-# --- Data ---
-data/
-datasets/local/
-*.h5
-*.hdf5
-*.npy
-*.npz
-
-# --- Local agent instructions (not shared) ---
-.github/copilot-instructions.md
-
-# --- OS / editor ---
-.DS_Store
-Thumbs.db
-Desktop.ini
-*.swp
-*.swo
-.idea/
-.vscode/
-*.log
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*$py.class
+.Python
+
+# --- Build / packaging ---
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+MANIFEST
+
+# setuptools_scm writes deltaflow/_version.py; keep it out of git
+deltaflow/_version.py
+
+# --- Virtual environments ---
+venv/
+.venv/
+env/
+.env
+.env.*
+
+# --- Testing / coverage ---
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.hypothesis/
+
+# --- Type checkers / linters ---
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytype/
+
+# --- Docs ---
+site/
+docs/_build/
+
+# --- Jupyter ---
+.ipynb_checkpoints/
+
+# --- Training artifacts (created by deltaflow.trainer + examples) ---
+checkpoints/
+outputs/
+runs/
+wandb/
+logs/
+*.pt
+*.pth
+*.ckpt
+*.safetensors
+
+# --- Data ---
+data/
+datasets/local/
+*.h5
+*.hdf5
+*.npy
+*.npz
+
+# --- Local agent instructions (not shared) ---
+.github/copilot-instructions.md
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.swp
+*.swo
+.idea/
+.vscode/
+*.log
+SUMMARY.md

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/CHANGELOG.md

@@ -1,58 +1,94 @@
-# Changelog
-
-All notable changes to this project are documented here.
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-
-## [Unreleased]
-
-## [0.2.1]
-
-### Fixed
-
-- README images used relative paths (`docs/assets/...`), which don't resolve
-  on PyPI's standalone README renderer. Switched to absolute
-  `raw.githubusercontent.com` URLs so images load correctly on PyPI.
-
-## [0.2.0]
-
-### Added
-
-- `deltaflow.interpolants.OTInterpolant`: the linear path applied after a
-  mini-batch optimal-transport re-ordering of `x0`.
-- `deltaflow.trainer` couplings: `IndependentCoupling` and `OTCoupling`
-  (Hungarian assignment, greedy fallback) plus `ConditionalFlowMatchingLoss`.
-- `deltaflow.solvers`: `EulerSolver`, `HeunSolver` (second-order integration),
-  and `PosteriorSolver`, which wraps a base solver with a per-step
-  measurement-likelihood gradient.
-- `deltaflow.inverse`: measurement operators (`MaskOperator`, `BlurOperator`,
-  `DownsampleOperator`, `IdentityOperator`), Tweedie estimators
-  (`LinearTweedie`, `VPTweedie`), and `GaussianLikelihood` with an optional
-  decoder pullback for the latent-space case.
-- `deltaflow.interpolants.VariancePreservingInterpolant` (trigonometric
-  diffusion path).
-- Showcase examples: `01-landmark-viz`, `02-sampling-flow-viz`,
-  `03-minibatch-ot-viz`, `04-inverse-posterior-viz`, reproducing the README
-  figures and animations.
-- MkDocs Material documentation site (`docs/`), published via
-  `.github/workflows/docs.yml`.
-- Animated logo, favicon, and algorithm figures under `docs/assets/`.
-
-### Changed
-
-- Rewrote `README.md` in a component-table style with paper references,
-  visuals, and per-method usage snippets (flow matching, OT couplings,
-  variance-preserving path, delta alignment, posterior sampling).
-- Fixed paper attributions and introduced a `Likelihood` protocol in
-  `deltaflow.inverse`.
-
-## [0.1.0]
-
-### Added
-
-- Initial scaffold: `core`, `interpolants` (`LinearInterpolant`), `samplers`
-  (`FlowSampler`), `losses` (`FlowMatchingLoss`, `DeltaAlignmentLoss`),
-  `models` (`MultiScaleProjector`, `EMA`), `datasets` (generic radiograph
-  wrappers).
-- Tiered examples (`00-foundations`, `10-sampling`, `20-training`,
-  `90-showcase`).
-- Unit tests for interpolants, samplers, losses, and models.
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Changed
+
+- `scipy` is now a core dependency (previously gated behind the `ot`
+  extra), so `OTInterpolant`/`OTCoupling` use the exact Hungarian-algorithm
+  mini-batch OT assignment by default. The `ot` extra is kept as a
+  backwards-compatible no-op, and the greedy nearest-neighbour matcher
+  remains as a defensive fallback if `scipy` is ever missing.
+
+## [0.2.2]
+
+### Added
+
+- API-reference docstrings now include the underlying mathematics in
+  LaTeX (rendered via MathJax/arithmatex): probability paths and target
+  velocities for the interpolants (`Linear`, `VariancePreserving`, `OT`,
+  `SchrodingerBridge`), the Euler/Heun update rules, the DPS posterior-solver
+  step, the conditional-flow-matching and delta-alignment objectives, the
+  `LinearTweedie`/`VPTweedie` inversions, and the Gaussian likelihood.
+
+- `deltaflow.interpolants.SchrodingerBridgeInterpolant`: an entropic
+  Schrödinger-bridge probability path (a Brownian bridge with tunable
+  diffusivity `sigma` around the straight-line mean). `sigma=0` recovers
+  `LinearInterpolant` exactly. Intended to be paired with
+  `deltaflow.trainer.OTCoupling` for a simulation-free approximation of the
+  dynamic Schrödinger bridge.
+- Showcase example `05-schrodinger-bridge-viz`: visualises the bridge path
+  at increasing `sigma` (`bridge_paths.png` static, `bridge_paths.gif`
+  animated), then trains a velocity field against it (with `OTCoupling`)
+  and inspects the resulting sampler on a two-moons target.
+- Showcase example `06-algorithm-comparison`: trains the same model on the
+  same target under all four interpolant/coupling configurations (linear
+  independent, OT coupling, variance-preserving, Schrödinger bridge) and
+  compares final samples, sampled trajectories, and an animated side-by-side
+  sampling GIF. A README section ("Comparing the paths") links these
+  figures, alongside the Schrödinger-bridge sampling animation.
+
+## [0.2.1]
+
+### Fixed
+
+- README images used relative paths (`docs/assets/...`), which don't resolve
+  on PyPI's standalone README renderer. Switched to absolute
+  `raw.githubusercontent.com` URLs so images load correctly on PyPI.
+
+## [0.2.0]
+
+### Added
+
+- `deltaflow.interpolants.OTInterpolant`: the linear path applied after a
+  mini-batch optimal-transport re-ordering of `x0`.
+- `deltaflow.trainer` couplings: `IndependentCoupling` and `OTCoupling`
+  (Hungarian assignment, greedy fallback) plus `ConditionalFlowMatchingLoss`.
+- `deltaflow.solvers`: `EulerSolver`, `HeunSolver` (second-order integration),
+  and `PosteriorSolver`, which wraps a base solver with a per-step
+  measurement-likelihood gradient.
+- `deltaflow.inverse`: measurement operators (`MaskOperator`, `BlurOperator`,
+  `DownsampleOperator`, `IdentityOperator`), Tweedie estimators
+  (`LinearTweedie`, `VPTweedie`), and `GaussianLikelihood` with an optional
+  decoder pullback for the latent-space case.
+- `deltaflow.interpolants.VariancePreservingInterpolant` (trigonometric
+  diffusion path).
+- Showcase examples: `01-landmark-viz`, `02-sampling-flow-viz`,
+  `03-minibatch-ot-viz`, `04-inverse-posterior-viz`, reproducing the README
+  figures and animations.
+- MkDocs Material documentation site (`docs/`), published via
+  `.github/workflows/docs.yml`.
+- Animated logo, favicon, and algorithm figures under `docs/assets/`.
+
+### Changed
+
+- Rewrote `README.md` in a component-table style with paper references,
+  visuals, and per-method usage snippets (flow matching, OT couplings,
+  variance-preserving path, delta alignment, posterior sampling).
+- Fixed paper attributions and introduced a `Likelihood` protocol in
+  `deltaflow.inverse`.
+
+## [0.1.0]
+
+### Added
+
+- Initial scaffold: `core`, `interpolants` (`LinearInterpolant`), `samplers`
+  (`FlowSampler`), `losses` (`FlowMatchingLoss`, `DeltaAlignmentLoss`),
+  `models` (`MultiScaleProjector`, `EMA`), `datasets` (generic radiograph
+  wrappers).
+- Tiered examples (`00-foundations`, `10-sampling`, `20-training`,
+  `90-showcase`).
+- Unit tests for interpolants, samplers, losses, and models.

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/CITATION.cff

@@ -1,11 +1,11 @@
-cff-version: 1.2.0
-message: "If you use this software, please cite it as below."
-title: "torchDeltaFlow: Flow Matching, Optimal-Transport Coupling, and Posterior Sampling for Inverse Problems in PyTorch"
-authors:
-  - family-names: "Limbunlom"
-    given-names: "Phrugsa"
-    email: "phrugsa.lim@gmail.com"
-date-released: 2026-07-22
-url: "https://github.com/phrugsa-limbunlom/deltaflow"
-repository-code: "https://github.com/phrugsa-limbunlom/deltaflow"
-license: MIT
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "torchDeltaFlow: Flow Matching, Optimal-Transport Coupling, and Posterior Sampling for Inverse Problems in PyTorch"
+authors:
+  - family-names: "Limbunlom"
+    given-names: "Phrugsa"
+    email: "phrugsa.lim@gmail.com"
+date-released: 2026-07-22
+url: "https://github.com/phrugsa-limbunlom/deltaflow"
+repository-code: "https://github.com/phrugsa-limbunlom/deltaflow"
+license: MIT

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/CODE_OF_CONDUCT.md

@@ -1,28 +1,28 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics,
-gender identity and expression, level of experience, education,
-socio-economic status, nationality, personal appearance, race, religion, or
-sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment include
-being respectful of differing opinions, giving and gracefully accepting
-constructive feedback, and focusing on what is best for the community.
-
-Examples of unacceptable behavior include harassment, insulting or
-derogatory comments, and other conduct which could reasonably be considered
-inappropriate in a professional setting.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the project maintainers. All complaints will be reviewed and
-investigated promptly and fairly.
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education,
+socio-economic status, nationality, personal appearance, race, religion, or
+sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include
+being respectful of differing opinions, giving and gracefully accepting
+constructive feedback, and focusing on what is best for the community.
+
+Examples of unacceptable behavior include harassment, insulting or
+derogatory comments, and other conduct which could reasonably be considered
+inappropriate in a professional setting.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

{torchdeltaflow-0.2.1 → torchdeltaflow-0.2.3.dev21}/CONTRIBUTING.md

@@ -1,26 +1,26 @@
-# Contributing
-
-Contributions are welcome. This project is small and research-oriented, so
-please open an issue to discuss non-trivial changes before sending a PR.
-
-## Setup
-
-```bash
-git clone https://github.com/yourname/deltaflow
-cd deltaflow
-pip install -e ".[dev]"
-```
-
-## Before opening a PR
-
-```bash
-black deltaflow tests examples
-isort deltaflow tests examples
-pytest
-```
-
-## Adding an example
-
-Examples live under `examples/<tier>/<NN-name>/main.py`, where `<tier>` is
-one of `00-foundations`, `10-sampling`, `20-training`, `90-showcase`. Each
-example should run standalone in well under a minute on CPU.
+# Contributing
+
+Contributions are welcome. This project is small and research-oriented, so
+please open an issue to discuss non-trivial changes before sending a PR.
+
+## Setup
+
+```bash
+git clone https://github.com/yourname/deltaflow
+cd deltaflow
+pip install -e ".[dev]"
+```
+
+## Before opening a PR
+
+```bash
+black deltaflow tests examples
+isort deltaflow tests examples
+pytest
+```
+
+## Adding an example
+
+Examples live under `examples/<tier>/<NN-name>/main.py`, where `<tier>` is
+one of `00-foundations`, `10-sampling`, `20-training`, `90-showcase`. Each
+example should run standalone in well under a minute on CPU.