Repository navigation
[MRG] Honor the documented unbalanced=float("inf") contract without changing the objective - #895
Open
xihaian251 wants to merge 3 commits into
Open
xihaian251 wants to merge 3 commits into
xihaian251 wants to merge 3 commits into
Conversation
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #895 +/- ##
==========================================
- Coverage 97.09% 97.08% -0.01%
==========================================
Files 130 131 +1
Lines 27229 27399 +170
==========================================
+ Hits 26437 26600 +163
- Misses 792 799 +7 🚀 New features to boost your workflow:
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Types of changes
Motivation and context
ot.solvedocumentsunbalanced=float("inf")as the balanced OT limit. On unmodified master the exact (MM) and L-BFGSB paths do not honor this sentinel:reg=0, unbalanced=infreturnsvalue=NaNand an all-NaN plan;reg>0, reg_type="L2"|"entropy", unbalanced=infreturnsvalue=NaNwhile silently returning a balanced plan[[0.25,0.25],[0.25,0.25]];(+inf, rho)returns NaN or silently solves the balanced problem.The root cause is objective mismatch: the hard marginal-constraint limit of
⟨M,T⟩+λR(T;c)+ρ_aD(T1,a)+ρ_bD(Tᵀ1,b)keeps the original⟨M,T⟩+λR(T;c), which is only equal to what the balanced branch minimizes for a subset of combinations. Dispatching allinfcases to the balanced solver solves a different problem.Mathematical contract (independent Wolfram oracles)
M=[[0,1],[1,0]],a=b=[0.5,0.5],c=abᵀ): hard limit⟨M,T⟩+(reg/2)‖T−c‖²givesV*=0.125(reg=1) /0.25(reg=2), while balanced⟨M,T⟩+(reg/2)‖T‖²gives0.25/0.50. With non-uniforma=[0.7,0.3], b=[0.6,0.4], the optimal plans differ:T00=0.42vs0.40. This holds even after PR [MRG] Report the half-squared L2 objective that smooth_ot_dual minimises #914 corrected the balanced value coefficient.c:⟨M,T⟩+KL(T‖c),c=[[0.45,0.05],[0.05,0.45]]givesT00*=9e/(2+18e)=0.4803648497,V*=0.0652983360. The entropic KL Sinkhorn path implements this correctly and is left untouched.ΣT(log T−1)andΣT log Tdiffer byregat unit mass; plans coincide but reported values do not.a=[0.6,0.4],b=[0.5,0.5],M=[[0,2],[0,2]],rho=4, first-column massz. Wolfram givesF(z)=3-6z+4z^2,z*=0.75,F*=0.75, versus balancedz=0.5,F=1.0— a strict gap of 0.25. A feasible nonnegative plan isT=[[0.4,0.2],[0.35,0.05]](row sums 0.6/0.4, column sums 0.75/0.25). This proves the semi-relaxed optimum is genuinely different from the balanced plan, not merely non-unique.Combinations whose limit is not the balanced objective raise an explicit
NotImplementedErrorrather than silently solving another problem.Implementation
+inf(scalar, tuple, list, array) before dispatch; tracers and non-positive-inf values keep prior behavior.reg=0(regularizer vanishes),reg_type="KL"with defaultc=abᵀ, and user-supplied(f, df)pairs.c,potentials_init,method).mm_unbalanced,lbfgsb_unbalancedthatot.solveresolves the sentinel before calling them.The MM / L-BFGSB / Sinkhorn cores are not rewritten. This PR does not change the existing balanced L2 implementation. PR #914 separately fixes that objective's half-squared coefficient and is not yet merged into master; therefore on a tree containing only this PR,
reg=1, reg_type="L2", unbalanced=Nonestill reports the pre-#914 value0.5. This is expected and is not a regression of this PR — it must not be fixed here by mixing in #914 code. In the validated combined integration tree (#914 + #895), the corrected value0.25is preserved and the infinity dispatch contract still holds.How has this been tested
pytest -q test/unbalanced/test_inf_marginal.py: 97 passed / 2 skipped.pytest -q test/unbalanced/: 681 passed / 33 skipped.pytest -q test/test_solvers.py test/test_ot.py test/test_backend.py(integration tree): 1046 passed / 105 skipped.test/test_bspot.pyandtest/test_helpers.pydue to two pre-existing local environment limits: BSP native-extension ABI mismatch and sandbox-blocked MSVC probe): 3701 passed / 470 skipped / 6 xfailed. After the latest upstream sync ([MRG] Clarify transported mass in partial OT #902) the functional code is byte-for-byte unchanged (onlyRELEASES.md,docs/source/user_guide.rstand one example file changed), so targeted re-runs were performed instead:test_inf_marginal.py97 passed / 2 skipped,test/unbalanced/681 passed / 33 skipped.ot/, andgit diff --checkall pass.Scope and limitations
This PR changes only
ot.solvedispatch and documentation; it does not add semi-relaxed exact OT or extend L-BFGSB to infinite penalties. Combinations raisingNotImplementedErrorrequire either a finite relaxation or an explicit balanced call with the understanding that it solves a different objective. When upstream master changes further, the merge should be re-validated against the Wolfram oracles and the four-tree compatibility matrix in the audit reports.