Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

#### Closed issues

- Fix the envelope gradient of `ot.batch.solve_batch` with respect to the marginals `a` and `b` for the PyTorch backend: `grad="envelope"` returned no gradient (entropy) or an incorrect one (KL) because the transport plan is detached and the marginals only entered through the solver. The gradient is now registered locally with a batch-aware VJP from the converged dual potentials, including the explicit KL reference-measure term; the existing gradient path to `M` and the forward `value` and `plan` are unchanged. This is a first-order, PyTorch-only correction; JAX/TensorFlow batch marginal gradients and higher-order differentiation are not affected
- Fix ordinary JAX gradients for dense `ot.emd2` and preserve the magnitude and higher-order dependence of gradients supplied to `JaxBackend.set_gradients`, including the envelope gradients in `ot.solve` (Issue #625)
- Fix `ot.semidiscrete_wasserstein2_unif_circle` pairing sorted sample locations with unsorted weights, which broke permutation and rotation invariance for nonuniform weights (Issue #921)
- Fix an out-of-bounds read in `ot.bsp.merge_bijections`: the number of plans was taken from `perms.shape[1]` (the number of samples) instead of `perms.shape[0]`, so merging fewer plans than samples read past the array and merging more silently dropped plans. A `perms` outside the documented `(n_plans, n_samples)` layout, an empty plan stack and rows that are not permutations are now rejected (PR #911, Issue #910)
Expand Down
86 changes: 80 additions & 6 deletions ot/batch/_linear.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
#
# License: MIT License

from ..backend import get_backend
from ..backend import get_backend, torch
from ..utils import OTResult, check_marginal
from ._utils import (
bregman_log_projection_batch,
Expand All @@ -25,6 +25,32 @@

solve_batch_grad_lst = ["detach", "autodiff", "last_step", "envelope"]

if torch:

class _BatchEnvelopeMarginals(torch.autograd.Function):
r"""Attach batch-aware marginal VJP to an envelope-mode value.

``Backend.set_gradients`` implements a scalar-output VJP: its Torch
``ValFunction.backward`` multiplies each gradient by ``grad_output``
without a batch dimension. That is invalid for the vector-valued
``value`` returned by :func:`solve_batch` (silent mis-broadcast when
``B`` matches a trailing dimension, otherwise a shape error). This
local Function keeps the batch axis aligned with the upstream
cotangent and leaves the existing differentiable path to ``M`` intact.
"""

@staticmethod
def forward(ctx, value, grad_a, grad_b, a, b):
ctx.save_for_backward(grad_a, grad_b)
return value

@staticmethod
def backward(ctx, grad_output):
grad_a, grad_b = ctx.saved_tensors
w = grad_output.reshape((-1,) + (1,) * (grad_a.ndim - 1))
# gradients: value, grad_a, grad_b, a, b
return grad_output, None, None, w * grad_a, w * grad_b


def dist_lp_batch(X, Y, p=2, q=1, nx=None):
r"""Computes the cost matrix for a batch of samples using the Lp norm.
Expand Down Expand Up @@ -295,11 +321,18 @@ def solve_batch(
grad : str, optional
Type of gradient computation, either 'detach', 'autodiff', 'last_step' or 'envelope'.
'detach' does not compute the gradients.
'autodiff' provides gradients of all outputs (`plan, value, value_linear`) but with important memory cost.
'autodiff' provides gradients of all outputs (`plan, value, value_linear`) but with important memory cost.
'last_step' provides gradients of all outputs (`plan, value, value_linear`) only for the last method iteration, useful for memory saving.
'envelope' provides gradients only for `value`.
'envelope' provides gradients only for `value`. With PyTorch, the
envelope gradient of ``value`` is available with respect to ``M``,
``a`` and ``b`` (first order only); the existing gradient path to ``M``
is unchanged. For ``reg_type="kl"`` the dependency of the reference
measure ``a (x) b`` is included. This marginal gradient is specific to
the PyTorch backend: JAX and TensorFlow batch marginal gradients are
not part of this behaviour, and the custom marginal gradient does not
support higher-order differentiation.
Default is 'envelope'.


Returns
-------
Expand Down Expand Up @@ -411,15 +444,54 @@ def solve_batch(
T = nx.detach(T)

value_linear = loss_linear_batch(M, T)

# The local envelope VJP is registered only for Torch, where the marginal
# sensitivities can be attached to the vector-valued output. Other
# backends keep their previous behaviour unchanged.
local_envelope = (
grad == "envelope"
and reg is not None
and reg > 0
and torch
and isinstance(value_linear, torch.Tensor)
)

if reg_type == "entropy" and reg is not None:
entr = -entropy_batch(T, nx=nx)
value = value_linear + reg * entr
elif reg_type == "kl" and reg is not None:
ref = nx.einsum("bi,bj->bij", a, b)
# When the local VJP is active the marginal gradient is supplied
# explicitly below. Detaching the reference measure then avoids an
# incorrect duplicate autodiff term through the detached plan. For
# backends without the local VJP the reference stays differentiable,
# preserving the previous behaviour.
ref_a, ref_b = (nx.detach(a), nx.detach(b)) if local_envelope else (a, b)
ref = nx.einsum("bi,bj->bij", ref_a, ref_b)
kl = nx.sum(T * nx.log(T / ref + 1e-16), axis=(1, 2))
value = value_linear + reg * kl
else:
value = value_linear

if local_envelope:
# Envelope sensitivities at convergence. The dual potentials are in
# log space for log_sinkhorn/proximal and in scaling space for sinkhorn.
# The proximal inner regularisation is active in the dual relation.
reg_eff = reg + inner_reg if method == "proximal" else reg
u, v = out["potentials"]
if method == "sinkhorn":
u, v = nx.log(u), nx.log(v)
n_u, n_v = u.shape[1], v.shape[1]
grad_a = reg_eff * (u - nx.sum(u, axis=1, keepdims=True) / n_u)
grad_b = reg_eff * (v - nx.sum(v, axis=1, keepdims=True) / n_v)
if reg_type == "kl":
# KL(P||a (x) b) = sum P log P - sum a log a - sum b log b on U(a,b),
# so the reference measure adds an explicit -reg log(a) term.
log_a, log_b = nx.log(a), nx.log(b)
grad_a = grad_a - reg * (log_a - nx.sum(log_a, axis=1, keepdims=True) / n_u)
grad_b = grad_b - reg * (log_b - nx.sum(log_b, axis=1, keepdims=True) / n_v)
value = _BatchEnvelopeMarginals.apply(
value, nx.detach(grad_a), nx.detach(grad_b), a, b
)
log = {"n_iter": out["n_iters"]}

res = OTResult(
Expand Down Expand Up @@ -488,7 +560,9 @@ def solve_sample_batch(
'detach' does not compute the gradients.
'autodiff' provides gradients of all outputs (`plan, value, value_linear`) but with important memory cost.
'last_step' provides gradients of all outputs (`plan, value, value_linear`) only for the last method iteration, useful for memory saving.
'envelope' provides gradients only for `value`.
'envelope' provides gradients only for `value`. See :func:`solve_batch`
for the backend-specific scope of the envelope gradient with respect
to ``a`` and ``b``.
Default is 'envelope'.

Returns
Expand Down
145 changes: 145 additions & 0 deletions test/batch/test_solve_batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -209,3 +209,148 @@ def test_solve_batch_device(method):
M = dist_batch(Xd, Xd)
res = solve_batch(M, reg=0.1, max_iter=10, tol=1e-5, method=method)
assert res.plan.device == Xd.device


@pytest.mark.skipif(not torch, reason="torch not installed")
@pytest.mark.parametrize("batch_size", [1, 2, 3, 8])
def test_solve_batch_envelope_entropy_gradients_torch(batch_size):
"""Envelope mode must propagate M and marginal gradients batch-wise."""
rng = np.random.RandomState(0)
p_np = 0.5 + 0.4 * rng.rand(batch_size)
w_np = rng.randn(batch_size)

p = torch.tensor(p_np, dtype=torch.float64, requires_grad=True)
a = torch.stack([p, 1 - p], dim=1)
b = torch.full((batch_size, 2), 0.5, dtype=torch.float64)
M = torch.zeros((batch_size, 2, 2), dtype=torch.float64, requires_grad=True)
w = torch.tensor(w_np, dtype=torch.float64)

res = solve_batch(
M, reg=1.0, a=a, b=b, method="log_sinkhorn", reg_type="entropy",
grad="envelope", max_iter=2000, tol=1e-14,
)
grad_M, grad_p = torch.autograd.grad(
(res.value * w).sum(), (M, p), allow_unused=True
)

# M = 0 gives F(p) = reg*(p log p + (1-p) log(1-p) - log 2)
expected_p = w_np * (np.log(p_np) - np.log(1 - p_np))
expected_M = w_np[:, None, None] * res.plan.detach().numpy()
assert grad_p is not None
np.testing.assert_allclose(grad_p.detach().numpy(), expected_p, atol=1e-10)
np.testing.assert_allclose(grad_M.numpy(), expected_M, atol=1e-12)
assert grad_p.shape == p.shape and grad_p.dtype == p.dtype
assert grad_M.shape == M.shape and grad_M.device == M.device


@pytest.mark.skipif(not torch, reason="torch not installed")
def test_solve_batch_envelope_two_batch_exact_cotangent():
"""p1=3/4, p2=4/5 with w=(1,-2) must give (log 3, -2 log 4)."""
p = torch.tensor([0.75, 0.8], dtype=torch.float64, requires_grad=True)
a = torch.stack([p, 1 - p], dim=1)
b = torch.full((2, 2), 0.5, dtype=torch.float64)
M = torch.zeros((2, 2, 2), dtype=torch.float64, requires_grad=True)
res = solve_batch(
M, reg=1.0, a=a, b=b, method="log_sinkhorn", reg_type="entropy",
grad="envelope", max_iter=2000, tol=1e-14,
)
_, grad_p = torch.autograd.grad(
(res.value * torch.tensor([1.0, -2.0], dtype=torch.float64)).sum(),
(M, p), allow_unused=True,
)
np.testing.assert_allclose(
grad_p.numpy(), [np.log(3.0), -2 * np.log(4.0)], atol=1e-12
)


@pytest.mark.skipif(not torch, reason="torch not installed")
@pytest.mark.parametrize("reg_type", ["entropy", "kl"])
def test_solve_batch_envelope_marginal_vs_finite_difference(reg_type):
"""Independent mass-conserving finite difference, including KL reference term."""
M_np = np.array([[0.1, 0.9], [1.3, 0.2]], dtype=np.float64)
p0 = 0.75
h = 1e-6

def value_at(p):
a = np.array([[p, 1 - p]], dtype=np.float64)
b = np.full((1, 2), 0.5, dtype=np.float64)
return float(solve_batch(
M_np[None], reg=1.0, a=a, b=b, method="log_sinkhorn",
reg_type=reg_type, grad="detach", max_iter=5000, tol=1e-14,
).value[0])

oracle = (value_at(p0 + h) - value_at(p0 - h)) / (2 * h)

p = torch.tensor([p0], dtype=torch.float64, requires_grad=True)
a = torch.cat([p, 1 - p]).unsqueeze(0)
b = torch.full((1, 2), 0.5, dtype=torch.float64)
M = torch.tensor(M_np[None], dtype=torch.float64, requires_grad=True)
res = solve_batch(
M, reg=1.0, a=a, b=b, method="log_sinkhorn", reg_type=reg_type,
grad="envelope", max_iter=5000, tol=1e-14,
)
_, grad_p = torch.autograd.grad(res.value.sum(), (M, p), allow_unused=True)
assert grad_p is not None
np.testing.assert_allclose(grad_p.item(), oracle, atol=1e-7)


@pytest.mark.skipif(not torch, reason="torch not installed")
@pytest.mark.parametrize("reg_type", ["entropy", "kl"])
def test_solve_batch_envelope_forward_unchanged(reg_type):
"""Envelope VJP registration must not alter value or plan."""
rng = np.random.RandomState(1)
M_np = rng.rand(2, 3, 4)
a_np = rng.rand(2, 3)
a_np /= a_np.sum(axis=1, keepdims=True)
b_np = rng.rand(2, 4)
b_np /= b_np.sum(axis=1, keepdims=True)

def solve(grad):
return solve_batch(
torch.tensor(M_np, requires_grad=True),
reg=0.5, a=torch.tensor(a_np), b=torch.tensor(b_np),
method="log_sinkhorn", reg_type=reg_type, grad=grad,
max_iter=1000, tol=1e-12,
)

ref, env = solve("detach"), solve("envelope")
np.testing.assert_array_equal(env.value.detach().numpy(), ref.value.numpy())
np.testing.assert_array_equal(env.plan.detach().numpy(), ref.plan.numpy())


@pytest.mark.skipif(not torch, reason="torch not installed")
def test_solve_batch_envelope_both_marginals_analytic_torch():
"""Both a and b gradients in one autograd call, against closed-form values.

For M=0 and reg=1 the envelope objective separates as
F = a log a + b log b, hence with a=(p,1-p), p=3/4 and
b=(q, 1/3, 2/3-q), q=1/2: dF/dp = dF/dq = log 3.
"""
p = torch.tensor([0.75], dtype=torch.float64, requires_grad=True)
q = torch.tensor([0.5], dtype=torch.float64, requires_grad=True)
a = torch.cat([p, 1 - p]).unsqueeze(0)
b = torch.cat([q, torch.tensor([1.0 / 3.0], dtype=torch.float64), 2.0 / 3.0 - q])
b = b.unsqueeze(0)
M = torch.zeros((1, 2, 3), dtype=torch.float64, requires_grad=True)
w = torch.tensor([-2.0], dtype=torch.float64)

res = solve_batch(
M, reg=1.0, a=a, b=b, method="log_sinkhorn", reg_type="entropy",
grad="envelope", max_iter=2000, tol=1e-14,
)
grad_M, grad_p, grad_q = torch.autograd.grad(
(res.value * w).sum(), (M, p, q), allow_unused=True
)

expected = float(np.log(3.0))
assert grad_p is not None and grad_q is not None
# Upstream cotangent scaling w=-2 is applied to both marginals.
np.testing.assert_allclose(grad_p.numpy(), [w.item() * expected], atol=1e-12)
np.testing.assert_allclose(grad_q.numpy(), [w.item() * expected], atol=1e-12)
# grad_M = w * P* and only the M path is scaled by the plan.
np.testing.assert_allclose(
grad_M.numpy(), w.item() * res.plan.detach().numpy(), atol=1e-12
)
assert grad_p.shape == p.shape and grad_q.shape == q.shape
assert grad_p.dtype == p.dtype and grad_q.dtype == q.dtype
assert grad_p.device == p.device and grad_q.device == q.device
Loading