[MRG] Fix sparse simplex projection with oversized budgets

[AHMETHAKANBEZIR1]

Types of changes

Bug fix: use ordinary simplex projection for an unconstrained sparsity budget, focused regressions, and a release note.

Motivation and context / Related issue

Fixes #875. The documented behavior for max_nz greater than the projected dimension is ordinary simplex projection. Instead, the row slice only contains the actual width while the threshold index array has length max_nz, producing a broadcasting error. When the budget is at least the row width, use the existing ordinary simplex projection directly; axis=0 and axis=None inherit this through their existing recursion. This avoids indexed mutation on TensorFlow tensors. Smaller budgets retain the sparse projection path.

How has this been tested

• Built POT's native extensions from this source checkout using MSVC 2022, OpenMP, Cython and the repository's Eigen submodule on Windows/Python 3.12.

• On unmodified master 98d09a1, the added regression yields 3 failures/3 controls with NumPy. Restoring that exact baseline function in memory in a second environment yields 6 failures/6 controls across NumPy and PyTorch CPU. No source file is altered by that baseline harness.

• After the fix, the complete test/test_utils.py module passes: 120 tests in the NumPy environment; 182 tests (2 warnings) in the NumPy/PyTorch 2.10 CPU environment. Expected values are analytic simplex solutions, covering all three axis modes with budgets equal to or larger than the projected dimension.

• Configured pre-commit hooks applicable to all three changed files pass; git diff --check passes. Hooks reporting no matching files are not counted as executed checks.

• Focused Sphinx autodoc/Napoleon build of the changed public API passes with warnings treated as errors. The harness references the existing algorithm footnote; its first isolated build warned that the existing footnote was unreferenced. The repository docstring is unchanged.

• Not run: full package suite, full project documentation/gallery, GPU, or the TensorFlow/JAX/CuPy backends. Zero/negative sparsity-budget validation is outside this change.

PR checklist

• I have read the CONTRIBUTING document.

• The documentation is up-to-date with the changes I made (check build artifacts). The documented contract already states this behavior; only the focused API build was run locally.

• All tests passed, and additional code has been covered with new tests. The complete utility module and regression passed; the full package suite was not run.

• I have added the Issue fix to RELEASES.md.

AI assistance disclosure

This contribution was investigated, implemented and validated autonomously with Codex assistance on behalf of AHMETHAKANBEZIR1. It has not received independent human code review. The commit records Codex as a co-author. Maintainer review is requested; local test evidence is not a claim of upstream CI success.

Current base validation

Updated against current master (61e13ba), preserving both release-note entries. test/test_utils.py: 120 passed.

TensorFlow CI follow-up

The initial budget cap exposed the existing indexed-assignment path on TensorFlow: the six new scalar-budget cases failed with EagerTensor item assignment errors. The unconstrained-budget path now delegates to proj_simplex, as the documented contract permits. Added vector-mass tests for both projection axes.

• Reproduced all six TensorFlow failures from the prior PR head in a baseline harness.
• Updated complete utility module: NumPy/PyTorch CPU 190 passed (2 existing warnings); NumPy/TensorFlow 2.21 CPU 158 passed, 32 existing unsupported-backend skips (1 warning). All ten unconstrained scalar/vector-budget cases pass on TensorFlow.
• Applicable configured pre-commit hooks and diff check pass. No tests were disabled to address this CI failure.
• Full package suite, GPU and new-head upstream CI have not been run locally.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.54%. Comparing base (604c47f) to head (61e13ba).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #876      +/-   ##
==========================================
- Coverage   97.00%   95.54%   -1.46%     
==========================================
  Files         128      128              
  Lines       26349    26365      +16     
==========================================
- Hits        25559    25191     -368     
- Misses        790     1174     +384     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.