From 1a0b5ce8b36295e7b7749f096ac1d95888244cbd Mon Sep 17 00:00:00 2001 From: xihaian251 Date: Tue, 17 Nov 2026 00:30:39 +0800 Subject: [PATCH] Fix batched envelope gradients with respect to marginals --- RELEASES.md | 1 + ot/batch/_linear.py | 86 +++++++++++++++++-- test/batch/test_solve_batch.py | 145 +++++++++++++++++++++++++++++++++ 3 files changed, 226 insertions(+), 6 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 03093ac6f..61000129c 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -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) diff --git a/ot/batch/_linear.py b/ot/batch/_linear.py index 59c3e5c5a..fb2bf594f 100644 --- a/ot/batch/_linear.py +++ b/ot/batch/_linear.py @@ -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, @@ -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. @@ -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 ------- @@ -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( @@ -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 diff --git a/test/batch/test_solve_batch.py b/test/batch/test_solve_batch.py index 14cde06ee..9da78d7dd 100644 --- a/test/batch/test_solve_batch.py +++ b/test/batch/test_solve_batch.py @@ -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