[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!