Document the sparse expression path (CSRLinearExpression, sparse=True, sparse_groupby)

[FabianHofmann]

Note

The following content was generated by AI.

Describe the feature you'd like to see

Document the sparse expression path. It is currently undiscoverable.

CSRLinearExpression, groupby(...).sum(sparse=True) and options["sparse_groupby"] appear only in doc/release_notes.rst (lines 46, 55, 56, 94, 96, 202). They are absent from doc/api.rst, the user guide, the generated API stubs and every example notebook. A grep over doc/ and examples/ for sparse=True or sparse_groupby returns release notes only.

By contrast CSRConstraint is documented, in doc/api.rst:410-451 and one clause of doc/user-guide.rst:28. So the export half of the sparse story is visible and the build half is not.

A user who wants the memory win has to read release notes or the linopy/csr.py module docstring to find out the feature exists.

Implementation ideas

• An doc/api.rst entry plus generated stubs for CSRLinearExpression, matching the existing CSRConstraint entries.
• A short user-guide section covering: what the sparse path is for, the three opt-ins needed end to end (semantics="v1", sparse_groupby/sparse=True, freeze_constraints=True), which operations preserve the backing and which drop it, and the v1-only term-layout contract (Zero culling forces model rebuilding #925).
• Documenting the current preserving set is valuable even while it is small, because the failure mode is silent.