torchdeltaflow 0.1.0__tar.gz

torchdeltaflow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +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

torchdeltaflow-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# --- 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
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.swp
+*.swo
+.idea/
+.vscode/
+*.log

torchdeltaflow-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### 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.1.0/CITATION.cff

@@ -0,0 +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

torchdeltaflow-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +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.

torchdeltaflow-0.1.0/CONTRIBUTING.md

@@ -0,0 +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.

torchdeltaflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeltaFlow Contributors
+
+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.

torchdeltaflow-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include deltaflow *.py

torchdeltaflow-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: torchdeltaflow
+Version: 0.1.0
+Summary: Flow matching, mini-batch optimal transport coupling, and posterior sampling for inverse problems in PyTorch
+Author-email: Phrugsa Limbunlom <phrugsa.lim@gmail.com>
+Maintainer-email: Phrugsa Limbunlom <phrugsa.lim@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 DeltaFlow Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/phrugsa-limbunlom/deltaflow
+Project-URL: Repository, https://github.com/phrugsa-limbunlom/deltaflow
+Project-URL: Issues, https://github.com/phrugsa-limbunlom/deltaflow/issues
+Project-URL: Changelog, https://github.com/phrugsa-limbunlom/deltaflow/blob/main/CHANGELOG.md
+Keywords: pytorch,flow-matching,rectified-flow,optimal-transport,diffusion-models,generative-models,posterior-sampling,inverse-problems,medical-imaging,deep-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy
+Requires-Dist: einops
+Requires-Dist: tqdm
+Provides-Extra: images
+Requires-Dist: pillow>=9.0; extra == "images"
+Provides-Extra: ot
+Requires-Dist: scipy>=1.10; extra == "ot"
+Provides-Extra: all
+Requires-Dist: pillow>=9.0; extra == "all"
+Requires-Dist: scipy>=1.10; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: pillow>=9.0; extra == "dev"
+Requires-Dist: scipy>=1.10; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.18; extra == "docs"
+Requires-Dist: pymdown-extensions>=9.0; extra == "docs"
+Dynamic: license-file
+
+# DeltaFlow
+
+**Flow matching and anatomy-invariant guidance alignment for radiograph generative pretraining.**
+
+`DeltaFlow` provides composable PyTorch primitives for two things that are
+usually bundled together in ad-hoc research code:
+
+- **Flow matching** — a simulation-free generative objective that regresses
+  a velocity field onto the conditional velocity of a probability path
+  (Lipman et al., 2023), sampled with a simple Euler ODE solver.
+- **Delta alignment** — a multi-scale, anatomy-cancelling loss that aligns
+  the *guidance-difference* feature `Δh = h_cond - h_uncond` across
+  augmented views, instead of aligning raw (anatomy-entangled) features.
+  This is the mechanism behind the name: **Delta** is the guidance-difference
+  feature, **Flow** is the flow-matching engine that consumes it.
+
+The library targets 2D radiography (chest X-ray, cephalometric, and hand
+radiographs), but the core primitives (`interpolants`, `samplers`, `losses`,
+`models.projector`) are domain-agnostic.
+
+## What's inside
+
+| Module | Role |
+|---|---|
+| `deltaflow.core` | `BaseVelocityField` — the interface every backbone implements |
+| `deltaflow.interpolants` | Probability paths, e.g. `LinearInterpolant` (rectified flow) |
+| `deltaflow.samplers` | `FlowSampler` — Euler ODE integration |
+| `deltaflow.losses` | `FlowMatchingLoss`, `DeltaAlignmentLoss` |
+| `deltaflow.models` | `MultiScaleProjector` (per-level projection heads), `EMA` |
+| `deltaflow.datasets` | Generic radiograph dataset wrappers (chest / cephalo / hand) |
+
+## Install
+
+```bash
+pip install -e .
+# or, for docs/dev tooling:
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Flow matching
+
+```python
+import torch
+from deltaflow.interpolants import LinearInterpolant
+from deltaflow.losses import FlowMatchingLoss
+from deltaflow.samplers import FlowSampler
+
+loss_fn = FlowMatchingLoss(interpolant=LinearInterpolant())
+loss = loss_fn(model, x1)               # model(x_t, t) -> predicted velocity
+loss.backward()
+
+samples = FlowSampler(model).sample(torch.randn(1000, 2), n_steps=50)
+```
+
+### Delta alignment
+
+```python
+from deltaflow.losses.delta_alignment import DeltaAlignmentLoss
+from deltaflow.models import MultiScaleProjector
+
+projector = MultiScaleProjector(feature_dims={"enc_1_4": 256, "bottleneck": 1024})
+loss_fn = DeltaAlignmentLoss(projector, lambda_flow=1.0, lambda_align=5.0)
+
+total, loss_dict = loss_fn(
+    v_c1, v_u1, target_v1,
+    v_c2, v_u2, target_v2,
+    feats_u1, feats_c1, feats_u2, feats_c2,
+)
+```
+
+See [`examples/`](examples/) for runnable, tiered walkthroughs
+(`00-foundations/`, `10-sampling/`, `20-training/`, `90-showcase/`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Citation
+
+If you use DeltaFlow in your research, please cite it (see [CITATION.cff](CITATION.cff)).

torchdeltaflow-0.1.0/README.md

@@ -0,0 +1,93 @@
+# DeltaFlow
+
+**Flow matching and anatomy-invariant guidance alignment for radiograph generative pretraining.**
+
+`DeltaFlow` provides composable PyTorch primitives for two things that are
+usually bundled together in ad-hoc research code:
+
+- **Flow matching** — a simulation-free generative objective that regresses
+  a velocity field onto the conditional velocity of a probability path
+  (Lipman et al., 2023), sampled with a simple Euler ODE solver.
+- **Delta alignment** — a multi-scale, anatomy-cancelling loss that aligns
+  the *guidance-difference* feature `Δh = h_cond - h_uncond` across
+  augmented views, instead of aligning raw (anatomy-entangled) features.
+  This is the mechanism behind the name: **Delta** is the guidance-difference
+  feature, **Flow** is the flow-matching engine that consumes it.
+
+The library targets 2D radiography (chest X-ray, cephalometric, and hand
+radiographs), but the core primitives (`interpolants`, `samplers`, `losses`,
+`models.projector`) are domain-agnostic.
+
+## What's inside
+
+| Module | Role |
+|---|---|
+| `deltaflow.core` | `BaseVelocityField` — the interface every backbone implements |
+| `deltaflow.interpolants` | Probability paths, e.g. `LinearInterpolant` (rectified flow) |
+| `deltaflow.samplers` | `FlowSampler` — Euler ODE integration |
+| `deltaflow.losses` | `FlowMatchingLoss`, `DeltaAlignmentLoss` |
+| `deltaflow.models` | `MultiScaleProjector` (per-level projection heads), `EMA` |
+| `deltaflow.datasets` | Generic radiograph dataset wrappers (chest / cephalo / hand) |
+
+## Install
+
+```bash
+pip install -e .
+# or, for docs/dev tooling:
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Flow matching
+
+```python
+import torch
+from deltaflow.interpolants import LinearInterpolant
+from deltaflow.losses import FlowMatchingLoss
+from deltaflow.samplers import FlowSampler
+
+loss_fn = FlowMatchingLoss(interpolant=LinearInterpolant())
+loss = loss_fn(model, x1)               # model(x_t, t) -> predicted velocity
+loss.backward()
+
+samples = FlowSampler(model).sample(torch.randn(1000, 2), n_steps=50)
+```
+
+### Delta alignment
+
+```python
+from deltaflow.losses.delta_alignment import DeltaAlignmentLoss
+from deltaflow.models import MultiScaleProjector
+
+projector = MultiScaleProjector(feature_dims={"enc_1_4": 256, "bottleneck": 1024})
+loss_fn = DeltaAlignmentLoss(projector, lambda_flow=1.0, lambda_align=5.0)
+
+total, loss_dict = loss_fn(
+    v_c1, v_u1, target_v1,
+    v_c2, v_u2, target_v2,
+    feats_u1, feats_c1, feats_u2, feats_c2,
+)
+```
+
+See [`examples/`](examples/) for runnable, tiered walkthroughs
+(`00-foundations/`, `10-sampling/`, `20-training/`, `90-showcase/`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Citation
+
+If you use DeltaFlow in your research, please cite it (see [CITATION.cff](CITATION.cff)).

torchdeltaflow-0.1.0/benchmarks/README.md

@@ -0,0 +1,7 @@
+# Benchmarks
+
+Placeholder for reproducible benchmark scripts (e.g. wall-clock/memory of
+`FlowSampler` at different step counts, or convergence speed of
+`DeltaAlignmentLoss` vs. a raw-feature alignment baseline). Follow
+`torchebm`'s pattern: one script per benchmark, results written to a
+tracked JSON/CSV so regressions are visible in CI.

torchdeltaflow-0.1.0/deltaflow/__init__.py

@@ -0,0 +1,40 @@
+"""
+DeltaFlow: a PyTorch library for flow matching, mini-batch optimal-transport
+coupling, and posterior sampling for inverse problems.
+
+Module map:
+
+- :mod:`deltaflow.core`         -- abstract base classes every component
+  subclasses (:class:`BaseVelocityField`, :class:`BaseInterpolant`,
+  :class:`BaseSolver`, :class:`BaseLoss`).
+- :mod:`deltaflow.interpolants` -- probability paths (linear, mini-batch OT,
+  variance-preserving).
+- :mod:`deltaflow.losses`       -- conditional flow matching, plus the
+  optional delta-alignment loss for guidance-representation pretraining.
+- :mod:`deltaflow.solvers`      -- Euler, Heun, and the
+  :class:`~deltaflow.solvers.PosteriorSolver` which *wraps* a base solver
+  and injects the measurement-likelihood gradient per step (FlowDPS /
+  Flower style).
+- :mod:`deltaflow.trainer`      -- streaming image dataset, mixed-precision
+  training loop with grad accumulation and checkpoint/resume, and
+  train-time coupling strategies (independent vs OT).
+- :mod:`deltaflow.inverse`      -- measurement operators, Tweedie
+  decomposition, and Gaussian likelihood. v1 targets pixel space with an
+  optional decoder pullback for the latent-space case (see
+  ``deltaflow.inverse.__init__`` docstring).
+- :mod:`deltaflow.models`       -- backbone wrappers, EMA, and projector
+  heads used by the delta-alignment loss.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # The distribution name on PyPI is ``torchdeltaflow`` (the plain
+    # ``deltaflow`` name is claimed by an unrelated 2020 package). The
+    # *import* name is still ``deltaflow``, which is why we can't just
+    # call ``version(__name__)``.
+    __version__ = version("torchdeltaflow")
+except PackageNotFoundError:  # pragma: no cover - not installed
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

torchdeltaflow-0.1.0/deltaflow/core/__init__.py

@@ -0,0 +1,18 @@
+"""Base abstractions shared across DeltaFlow's models, losses, and solvers.
+
+Every user-facing component (velocity field, interpolant, solver, loss)
+subclasses one of these bases, so new variants are drop-in and not
+rewrites of the surrounding machinery.
+"""
+
+from .base_interpolant import BaseInterpolant
+from .base_loss import BaseLoss
+from .base_solver import BaseSolver
+from .base_velocity_field import BaseVelocityField
+
+__all__ = [
+    "BaseInterpolant",
+    "BaseLoss",
+    "BaseSolver",
+    "BaseVelocityField",
+]

torchdeltaflow-0.1.0/deltaflow/core/base.py

@@ -0,0 +1,8 @@
+"""Backward-compatibility shim. Prefer importing from the split modules
+(:mod:`deltaflow.core.base_velocity_field`, etc.) or from :mod:`deltaflow.core`
+directly.
+"""
+
+from .base_velocity_field import BaseVelocityField
+
+__all__ = ["BaseVelocityField"]

torchdeltaflow-0.1.0/deltaflow/core/base_interpolant.py

@@ -0,0 +1,26 @@
+"""Base class for probability-path interpolants."""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Tuple
+
+import torch
+
+
+class BaseInterpolant(ABC):
+    """Base class for a probability path between noise ``x0`` and data ``x1``.
+
+    An interpolant defines, for each ``t in [0, 1]``, an intermediate point
+    ``x_t`` and its conditional target velocity ``u_t`` such that regressing
+    a model onto ``u_t`` (in expectation over the path) yields the marginal
+    velocity field of the flow-matching ODE.
+
+    Convention used throughout DeltaFlow: ``t = 0`` corresponds to noise
+    (``x_t = x_0``) and ``t = 1`` corresponds to data (``x_t = x_1``).
+    """
+
+    @abstractmethod
+    def interpolate(
+        self, x1: torch.Tensor, t: torch.Tensor, x0: Optional[torch.Tensor] = None
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """Return ``(x_t, target_velocity)`` for the given data/time (and optional noise)."""
+        raise NotImplementedError

torchdeltaflow-0.1.0/deltaflow/core/base_loss.py

@@ -0,0 +1,19 @@
+"""Base class for DeltaFlow training objectives."""
+
+from abc import ABC, abstractmethod
+
+import torch
+
+
+class BaseLoss(ABC):
+    """Base class for a callable training loss.
+
+    Subclasses must implement :meth:`__call__` and return a scalar tensor
+    with ``requires_grad=True`` (assuming the model has trainable
+    parameters). The signature is intentionally flexible - individual losses
+    define which positional and keyword arguments they consume.
+    """
+
+    @abstractmethod
+    def __call__(self, *args, **kwargs) -> torch.Tensor:
+        raise NotImplementedError

torchdeltaflow-0.1.0/deltaflow/core/base_solver.py

@@ -0,0 +1,76 @@
+"""Base class for ODE/SDE solvers that integrate a learned velocity field."""
+
+from abc import ABC, abstractmethod
+from typing import Callable, Optional
+
+import torch
+
+
+class BaseSolver(ABC):
+    """Base class for numerical integrators of ``dx/dt = v_theta(x, t)``.
+
+    A solver holds a reference to a velocity model and exposes two methods:
+
+    - :meth:`step` performs a single integration step from ``(x, t)`` to
+      ``(x', t + dt)``. Subclasses implement the actual stepping rule.
+    - :meth:`sample` drives :meth:`step` in a loop from ``t_start`` to
+      ``t_end`` and returns the final state.
+
+    Design note: :class:`~deltaflow.solvers.posterior_solver.PosteriorSolver`
+    wraps a :class:`BaseSolver` and hooks the likelihood gradient into every
+    call to :meth:`step`, so the base stepping logic is never duplicated.
+
+    Args:
+        model: callable ``model(x, t, **cond) -> velocity`` with the same
+            signature as :class:`~deltaflow.core.BaseVelocityField`.
+        time_scale: multiplies the continuous ``t in [0, 1]`` before it is
+            passed to the model; useful when the backbone was trained with a
+            different numeric time convention (e.g. diffusion timesteps).
+    """
+
+    def __init__(self, model: Callable, time_scale: float = 1.0):
+        self.model = model
+        self.time_scale = time_scale
+
+    def _time_tensor(self, x: torch.Tensor, t: float) -> torch.Tensor:
+        return torch.full((x.shape[0],), t, device=x.device, dtype=x.dtype)
+
+    def _eval_velocity(self, x: torch.Tensor, t: float, **cond) -> torch.Tensor:
+        t_tensor = self._time_tensor(x, t) * self.time_scale
+        return self.model(x, t_tensor, **cond)
+
+    @abstractmethod
+    def step(self, x: torch.Tensor, t: float, dt: float, **cond) -> torch.Tensor:
+        """Advance the state ``x`` from time ``t`` to ``t + dt``."""
+        raise NotImplementedError
+
+    def sample(
+        self,
+        x: torch.Tensor,
+        n_steps: int = 50,
+        t_start: float = 0.0,
+        t_end: float = 1.0,
+        show_progress: bool = True,
+        progress_desc: Optional[str] = None,
+        **cond,
+    ) -> torch.Tensor:
+        """Integrate from ``t_start`` to ``t_end`` in ``n_steps`` uniform steps."""
+        dt = (t_end - t_start) / n_steps
+        steps = range(n_steps)
+        if show_progress:
+            try:
+                from tqdm import tqdm
+
+                steps = tqdm(
+                    steps,
+                    desc=progress_desc or type(self).__name__,
+                    total=n_steps,
+                    leave=False,
+                )
+            except ImportError:
+                pass
+
+        for i in steps:
+            t_val = t_start + i * dt
+            x = self.step(x, t_val, dt, **cond)
+        return x