# SPDX-FileCopyrightText: Copyright (c) 2023 - 2026 NVIDIA CORPORATION & AFFILIATES.
# SPDX-FileCopyrightText: All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""DPM-Solver++(2M) multistep sampler for diffusion ODEs."""
from typing import Callable
import torch
from jaxtyping import Float
from torch import Tensor
from physicsnemo.diffusion.base import Denoiser
from ._utils import _nonlinear_weight
from .base import Solver
[docs]
class DPMPlusPlus2M(Solver):
r"""
Sample diffusion ODEs with DPM-Solver++(2M).
This solver offers second-order sampling with one denoiser evaluation per
step. Use it as a computationally efficient alternative to
:class:`HeunSolver`, which requires two evaluations per step.
The solver integrates ODEs with an extended semi-linear right-hand side:
.. math::
\frac{d\mathbf{x}}{dt} = D(\mathbf{x}, t)
= a(t) \, \mathbf{x} + b(t) \, N(\mathbf{x}, t)
The ``denoiser`` provides the full right-hand side :math:`D`;
``bias_fn`` and ``bias_int_fn`` provide the bias coefficient
:math:`a(t)` and its antiderivative :math:`\mathcal{A}(t)`
(:math:`\mathcal{A}'(t) = a(t)`); ``slope_fn`` provides the slope
coefficient :math:`b(t)`. A noise scheduler can provide all these
callables.
Each step advances the state from the current time :math:`t_n` to the
target time :math:`t_{n-1}`, with :math:`t_{n+1}` denoting the time of
the previous step (sampling proceeds from large to small times):
.. math::
\mathbf{x}_{n-1} = E_n \, \mathbf{x}_n + J_n \left[ N_n
+ \frac{1}{2}
\frac{\lambda(t_{n-1}) - \lambda(t_n)}{\lambda(t_n) - \lambda(t_{n+1})}
\left( N_n - N_{n+1} \right) \right]
where :math:`E_n = e^{\mathcal{A}(t_{n-1}) - \mathcal{A}(t_n)}` is the
exact linear propagator and
.. math::
J_n = \int_{t_n}^{t_{n-1}} e^{\mathcal{A}(t_{n-1}) - \mathcal{A}(s)}
\, b(s) \, ds
is the weight of the nonlinear term.
The function :math:`\lambda(t)`, provided by ``lambda_fn``, is the
extrapolation coordinate: the solver extrapolates
:math:`N` linearly in :math:`\lambda(t)` rather than in :math:`t`.
The original DPM-Solver++(2M) measures the extrapolation in the log-SNR
:math:`\lambda(t) = \log(\alpha(t) / \sigma(t))` of the noise schedule.
The default :math:`\lambda(t) = t` extrapolates in diffusion time.
The ``bias_fn``, ``bias_int_fn``, ``slope_fn``, and ``lambda_fn``
callables have the signatures:
.. code-block:: python
def bias_fn(
t: Tensor, # shape: (B,) or broadcastable
) -> Tensor: ... # bias coefficient a(t), same shape as t
def bias_int_fn(
t: Tensor, # shape: (B,) or broadcastable
) -> Tensor: ... # antiderivative of a(t), same shape as t
def slope_fn(
t: Tensor, # shape: (B,) or broadcastable
) -> Tensor: ... # slope coefficient b(t), same shape as t
def lambda_fn(
t: Tensor, # shape: (B,)
) -> Tensor: ... # extrapolation coordinate lambda(t), shape: (B,)
.. note::
This solver is **stateful**: it caches the previous predictor-like
evaluation across calls to :meth:`step`, so a single instance tracks
a single trajectory. Call :meth:`reset` before reusing an instance on
a new trajectory. String-key selection in
:func:`~physicsnemo.diffusion.samplers.sample` constructs a fresh
instance for each call, which is always safe.
Parameters
----------
denoiser : Denoiser
Right-hand side :math:`D(x, t)` of the ODE to integrate, following
the :class:`~physicsnemo.diffusion.Denoiser` interface. Typically from
:meth:`~physicsnemo.diffusion.noise_schedulers.NoiseScheduler.get_denoiser`,
but any callable with the correct signature works.
bias_fn : Callable[[Tensor], Tensor] | None, optional
Bias coefficient :math:`a(t)`, with the signature shown above.
Requires ``bias_int_fn`` when provided. Typically from
:meth:`~physicsnemo.diffusion.noise_schedulers.LinearGaussianNoiseScheduler.get_linear_denoiser`
with the same predictor parameterization as ``denoiser``; any
callable with the correct signature works. The default is ``None``,
which corresponds to a zero bias.
bias_int_fn : Callable[[Tensor], Tensor] | None, optional
Antiderivative :math:`\mathcal{A}(t)` of the bias, with the signature
shown above. Requires ``bias_fn`` when provided. The default is
``None``, which corresponds to a zero bias.
slope_fn : Callable[[Tensor], Tensor] | None, optional
Slope coefficient :math:`b(t)` of the nonlinear term, with the
signature shown above. The default is ``None``, which uses a constant
slope (:math:`b = 1`). A zero value disables the nonlinear term; use it
only when the denoiser is fully described by the linear bias.
lambda_fn : Callable[[Tensor], Tensor] | None, optional
Extrapolation coordinate :math:`\lambda(t)`, with the signature shown
above. For DPM-Solver++(2M), pass the schedule's log-SNR:
``lambda t: torch.log(scheduler.snr(t))``. The default is ``None``,
which extrapolates in diffusion time.
Note
----
Reference: `DPM-Solver++: Fast Solver for Guided Sampling of Diffusion
Probabilistic Models <https://arxiv.org/abs/2211.01095>`_
Examples
--------
This class can express different multistep samplers through its callback
configuration. The examples below show a classical Adams-Bashforth solver
and the original DPM-Solver++(2M) method.
>>> import torch
>>> from physicsnemo.diffusion.noise_schedulers import EDMNoiseScheduler
>>> from physicsnemo.diffusion.samplers import DPMPlusPlus2M
>>>
>>> scheduler = EDMNoiseScheduler()
>>> x0_pred = lambda x, t: x * 0.1 # Toy x0-predictor
>>> # Both configurations use the same EDM probability-flow ODE.
>>> denoiser = scheduler.get_denoiser(x0_predictor=x0_pred)
>>> # The default callbacks recover classical two-step Adams-Bashforth.
>>> ab2_solver = DPMPlusPlus2M(denoiser)
>>> x_t = torch.randn(1, 3, 8, 8)
>>> x_mid = ab2_solver.step(x_t, torch.tensor([5.0]), torch.tensor([2.5]))
>>> x_next = ab2_solver.step(x_mid, torch.tensor([2.5]), torch.tensor([1.0]))
>>> x_next.shape
torch.Size([1, 3, 8, 8])
To use DPM-Solver++(2M) instead, provide the scheduler's bias and slope
callbacks and use its log-SNR as the extrapolation coordinate:
>>> # Separate the known affine structure from the denoiser output.
>>> bias, bias_int, slope = scheduler.get_linear_denoiser(
... prediction_type="x0"
... )
>>> # Extrapolation variable is the schedule's log-SNR.
>>> log_snr = lambda t: torch.log(scheduler.snr(t))
>>> dpmpp_solver = DPMPlusPlus2M(
... denoiser,
... bias_fn=bias,
... bias_int_fn=bias_int,
... slope_fn=slope,
... lambda_fn=log_snr,
... )
>>> x_mid = dpmpp_solver.step(x_t, torch.tensor([5.0]), torch.tensor([2.5]))
>>> x_next = dpmpp_solver.step(x_mid, torch.tensor([2.5]), torch.tensor([1.0]))
>>> x_next.shape
torch.Size([1, 3, 8, 8])
>>> dpmpp_solver.reset() # Before reusing it on a new trajectory
For domain-parallel DPM-Solver++(2M), use
:class:`~physicsnemo.diffusion.noise_schedulers.DomainParallelNoiseScheduler`
for distributed scheduler operations and get the scalar callbacks from
its ``inner_scheduler``. Given an initialized ``domain_mesh``:
.. code-block:: python
from physicsnemo.diffusion.noise_schedulers import (
DomainParallelNoiseScheduler,
EDMNoiseScheduler,
)
from physicsnemo.diffusion.samplers import DPMPlusPlus2M
scheduler = DomainParallelNoiseScheduler(
EDMNoiseScheduler(), domain_mesh, shard_dim=2
)
x0_pred = lambda x, t: x * 0.1 # Toy x0-predictor
denoiser = scheduler.get_denoiser(x0_predictor=x0_pred)
# A plain scheduler provides callbacks directly; the domain-parallel
# wrapper keeps these scalar functions on its inner scheduler.
inner = scheduler.inner_scheduler
bias, bias_int, slope = inner.get_linear_denoiser(
prediction_type="x0"
)
log_snr = lambda t: torch.log(inner.snr(t))
solver = DPMPlusPlus2M(
denoiser,
bias_fn=bias,
bias_int_fn=bias_int,
slope_fn=slope,
lambda_fn=log_snr,
)
"""
def __init__(
self,
denoiser: Denoiser,
bias_fn: Callable[[Float[Tensor, " B"]], Float[Tensor, " B"]] | None = None,
bias_int_fn: Callable[[Float[Tensor, " B"]], Float[Tensor, " B"]] | None = None,
slope_fn: Callable[[Float[Tensor, " B"]], Float[Tensor, " B"]] | None = None,
lambda_fn: Callable[[Float[Tensor, " B"]], Float[Tensor, " B"]] | None = None,
) -> None:
self.denoiser = denoiser
if bias_fn is None and bias_int_fn is None:
self.bias_fn = lambda t: torch.zeros_like(t)
self.bias_int_fn = lambda t: torch.zeros_like(t)
elif bias_fn is not None and bias_int_fn is not None:
self.bias_fn = bias_fn
self.bias_int_fn = bias_int_fn
else:
raise ValueError(
"bias_fn and bias_int_fn must both be provided or both None."
)
if slope_fn is None:
self.slope_fn = lambda t: torch.ones_like(t)
else:
self.slope_fn = slope_fn
if lambda_fn is None:
self.lambda_fn = lambda t: t
else:
self.lambda_fn = lambda_fn
self._n_prev: Tensor | None = None
self._lam_prev: Tensor | None = None
[docs]
def reset(self) -> None:
r"""
Clear the cached history from the previous trajectory.
Call this method before starting a new trajectory with an existing
solver instance. The next :meth:`step` call uses a first-order update
because no previous predictor-like evaluation is available.
Returns
-------
None
This method updates the solver state in place.
"""
self._n_prev = None
self._lam_prev = None
[docs]
def step(
self,
x: Float[Tensor, " B *dims"],
t_cur: Float[Tensor, " B"],
t_next: Float[Tensor, " B"],
) -> Float[Tensor, " B *dims"]:
r"""
Advance one step with DPM-Solver++(2M).
Successive calls must belong to a single trajectory with consecutive
time intervals (``t_cur`` equal to the previous call's ``t_next``);
see :meth:`reset`.
Parameters
----------
x : Tensor
Current noisy latent state :math:`\mathbf{x}_{n}` of shape
:math:`(B, *)` where :math:`B` is the batch size.
t_cur : Tensor
Current diffusion time :math:`t_n` of shape :math:`(B,)`.
t_next : Tensor
Target diffusion time :math:`t_{n-1}` of shape :math:`(B,)`.
Returns
-------
Tensor
Updated latent state :math:`\mathbf{x}_{n-1}` at time
``t_next``, same shape as ``x``.
"""
# Ensure contiguous strides so successive denoiser calls (across
# sampling steps) present the same stride layout to torch.compile,
# avoiding spurious recompilations / silently divergent traces.
t_cur = t_cur.contiguous()
t_next = t_next.contiguous()
# Shape for broadcasting time-only quantities: (B,) -> (B, 1, ..., 1)
expected_shape = (-1,) + (1,) * (x.ndim - 1)
lam_cur_bc = self.lambda_fn(t_cur).reshape(expected_shape)
# Recover the predictor-like term of the RHS: N = (D - a x) / b; the
# zero-slope guard drops the nonlinear term instead of dividing by
# zero
d_cur = self.denoiser(x, t_cur)
a_bc = self.bias_fn(t_cur).reshape(expected_shape)
b_bc = self.slope_fn(t_cur).reshape(expected_shape)
b_safe = torch.where(b_bc == 0, torch.ones_like(b_bc), b_bc)
inv_b_bc = torch.where(b_bc == 0, torch.zeros_like(b_bc), 1 / b_safe)
n_cur = (d_cur - a_bc * x) * inv_b_bc
# Exact linear propagator from the antiderivative of the bias, and
# exponential-kernel weight of the nonlinear term
e_bc = torch.exp(
(self.bias_int_fn(t_next) - self.bias_int_fn(t_cur)).reshape(expected_shape)
)
j_bc = _nonlinear_weight(
t_cur, t_next, self.bias_fn, self.bias_int_fn, self.slope_fn
).reshape(expected_shape)
if self._n_prev is None or self._lam_prev is None:
# Seed placeholder history on the first step: the equal previous
# lambda zeroes the masked extrapolation below, so the update
# degenerates to a first-order exponential Euler step.
n_prev = n_cur
lam_prev = lam_cur_bc
else:
n_prev = self._n_prev
lam_prev = self._lam_prev
# Extrapolation ratio of successive steps, measured in the lambda
# coordinate and masked to fall back to first order on repeated
# nodes or non-finite lambda values (for example the log-SNR at
# t = 0). Use finite dummy denominators because torch.where
# evaluates both branches.
num_bc = self.lambda_fn(t_next).reshape(expected_shape) - lam_cur_bc
den_bc = lam_cur_bc - lam_prev
ok = torch.isfinite(num_bc) & torch.isfinite(den_bc) & (den_bc != 0)
r_safe = torch.where(ok, num_bc, torch.zeros_like(num_bc)) / torch.where(
ok, den_bc, torch.ones_like(den_bc)
)
q_half_bc = torch.where(ok, r_safe / 2, torch.zeros_like(r_safe))
x_next = e_bc * x + j_bc * (n_cur + q_half_bc * (n_cur - n_prev))
# Rebind immutable history instead of mutating graph-connected
# tensors in place. Clone only the batch-sized lambda value so a
# callback returning its input cannot alias caller-owned storage.
self._n_prev = n_cur
self._lam_prev = lam_cur_bc.clone()
return x_next