docs: document the sparse expression path

doc/api.rst

@@ -60,6 +60,7 @@ Inspecting a model
    model.Model.type
    model.Model.is_linear
    model.Model.is_quadratic
+   model.Model.sparse
 
 Modifying a model
 -----------------
@@ -292,6 +293,7 @@ Structure
    expressions.LinearExpression.const
    expressions.LinearExpression.nterm
    expressions.LinearExpression.has_terms
+   expressions.LinearExpression.is_sparse
 
 Conversion
 ----------
@@ -413,7 +415,7 @@ CSRConstraint
 Memory-efficient, immutable constraint representation backed by a scipy
 CSR sparse matrix. Opt in via ``Model(sparse=True)`` or
 ``Model.add_constraints(..., freeze=True)``. See the
-:doc:`creating-constraints` guide for usage.
+:doc:`creating-constraints` and :doc:`sparse-models` guides for usage.
 
 .. autosummary::
    :toctree: generated/
@@ -449,6 +451,8 @@ Conversion
    :toctree: generated/
 
    constraints.CSRConstraint.to_polars
+   constraints.CSRConstraint.to_dense
+   constraints.CSRConstraint.mutable
 
 
 Constraints
@@ -684,6 +688,17 @@ Utilities
    options
    ABSENT
 
+``options`` holds these keys:
+
+- ``display_max_rows``, ``display_max_terms``: size of the printed repr.
+- ``semantics``: ``"legacy"`` (default) or ``"v1"``, see
+  :doc:`migrating-to-v1`.
+- ``warn_on_densify``: emit a ``PerformanceWarning`` when a sparse (CSR)
+  backing is converted to dense. ``None`` (default) warns in a sparse model
+  on implicit conversions only, ``True`` always warns, ``False`` never
+  warns. See :doc:`sparse-models`.
+- ``sparse_groupby``: deprecated, use ``Model(sparse=True)``.
+
 
 Warnings
 ========

doc/index.rst

@@ -135,6 +135,7 @@ This package is published under MIT license.
    sos-constraints
    piecewise-linear-constraints
    numerical-scaling
+   sparse-models
    testing-framework
 
 .. toctree::

doc/release_notes.rst

@@ -48,6 +48,7 @@ Upcoming Version
 * ``linopy.merge(..., dim=<grid dimension>)`` keeps CSR-backed operands sparse: the rows are stacked in input order and the coordinates are what the dense path's ``xr.concat`` yields, so overlapping and duplicate labels along ``dim``, the ``join`` of the other dimensions (cells the join creates are absent), the v1 label check of the auto-detected join and auxiliary coordinates behave as on the dense path. The operands are left sparse, too. A merge along a new dimension, with extra ``xr.concat`` arguments or over non-unique labels that need aligning still densifies, with a notice. (`#1011 <https://github.com/PyPSA/linopy/issues/1011>`__)
 * ``linopy.options["warn_on_densify"]`` now defaults to ``None``, which means: on in a sparse model (``Model(sparse=True)``), off otherwise. Every operation that implicitly drops a sparse backing in a sparse model, e.g. ``.data`` or an operation without a sparse path, emits a ``PerformanceWarning`` naming the reason. Explicit conversions (``CSRConstraint.mutable()``/``to_dense()``, ``add_constraints(..., freeze=False)``) only warn when the option is ``True``. Set the option to ``False`` to silence it, or to ``True`` to see it in a dense model and on explicit conversions as well. (`#969 <https://github.com/PyPSA/linopy/issues/969>`__)
 * A merge of operands over different dimensions, e.g. ``bal + s`` with ``s`` over a subset of the dimensions of ``bal``, still densifies and now warns in a sparse model. (`#969 <https://github.com/PyPSA/linopy/issues/969>`__)
+* New :doc:`sparse-models` guide and API entries for ``LinearExpression.is_sparse`` and ``Model.sparse``: how to opt in, which operations keep the sparse backing and which densify, and the ``warn_on_densify`` option. (`#971 <https://github.com/PyPSA/linopy/issues/971>`__)
 
 *Other*
 

doc/sparse-models.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../examples/sparse-models.ipynb"
+}

doc/user-guide.rst

@@ -72,6 +72,26 @@ For a worked example that builds a badly-scaled model and applies each of the
 three variants step by step, see the :doc:`numerical-scaling` tutorial.
 
 
+Sparse models
+-------------
+
+Models that aggregate many entities into few rows, such as generators
+into buses, can store their expressions as sparse matrices instead of
+padded dense arrays. Opt in with ``Model(sparse=True)`` under the v1
+semantics. ``groupby(...).sum()`` and ``@`` then return sparse-backed
+expressions, and by default every constraint is stored as a frozen
+``CSRConstraint``. Operations without a sparse path convert an
+expression to dense and emit a ``PerformanceWarning``.
+
+.. code-block:: python
+
+    linopy.options["semantics"] = "v1"
+    m = linopy.Model(sparse=True)
+
+See :doc:`sparse-models` for the operations that keep the sparse
+backing, the ones that densify, and the ``warn_on_densify`` option.
+
+
 Working with an existing model
 ------------------------------