[JaylenTang]

Types of changes

Documentation and example update.

Motivation and context / Related issue

Related to #890.

Hi, I've put together a first version of the transported-mass explanation proposed in #890.

The guide already gives the partial OT formulation, and the 1D example shows different numbers of transported samples. This extends the existing 2D example to help explain what m means for weighted distributions:

• Distinguish transported weight from a point count or a normalized fraction, including inputs with unequal total weights.
• Compare m=0.25, 0.5, 0.75, and 1 on the same data with a fixed seed.
• Show how much Gaussian and remote-sample weight is used, separately for the source and target.
• Explain why lower raw cost can mean less weight was transported, rather than better matching.

It uses the existing solver and keeps the original entropic and Gromov-Wasserstein sections and attribution. The example also checks transported mass, marginal limits, and the balanced OT endpoint.

I'd appreciate feedback on the scope and whether this fits best in the existing guide and example or in a separate focused example. Thanks!

How has this been tested (if it applies)

Local checks on Python 3.12 with the NumPy CPU backend:

• pytest test/ -q --doctest-modules --disable-warnings: 1,524 passed, 134 skipped, 4 expected failures.
• Partial/LP doctests with the project's test/conftest.py: 20 passed.
• Local example/export checks: 11 passed, covering constraints, repeatability, group-mass accounting, the balanced endpoint, and figure preservation.
• Changed-file pre-commit hooks and explicit Ruff lint passed.
• Sphinx HTML and the focused gallery build completed; the selected example executed and both new figures were checked. Existing reference and optional-dependency diagnostics remain.

PR checklist

• I have read the CONTRIBUTING document.
• I checked the generated documentation and example figures.
• The available NumPy CPU tests, doctests, and local example checks pass.
• I added a release note linked to Issue [DOC] Clarify transported mass and extend the partial OT example #890.

This is a draft for feedback on the documentation and example.

[JaylenTang]

Hi @rflamary, I've added an initial implementation of the idea in #890 to this PR. When you have a chance, could you let me know whether this would be a useful addition to the documentation? I'm happy to adjust the scope. Thanks!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.57%. Comparing base (0b6f8d5) to head (875f765).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #902      +/-   ##
==========================================
- Coverage   97.01%   94.57%   -2.45%     
==========================================
  Files         130      130              
  Lines       26879    26879              
==========================================
- Hits        26078    25420     -658     
- Misses        801     1459     +658     

🚀 New features to boost your workflow:

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

[rflamary]

Thanks for the PR @JaylenTang , I have some suggestions below about shortening the user guide and about the new info in the exmaple.

[rflamary]

this discussion is interesting but much too detailed for a user's guide. you can eitehr move it to the exmaple file where it makes more sens or remove it. only keep a sentence with areference to the example please.

[rflamary]

names are unclear please dont' use in and out that can mean source/target in OT but inlier outlier possibly . Actually it would porably be more clear with aplot (and maybe more valyues of m?) where you can have larger legends for the plots