PyPSA · FBumann · May 11, 2026 · May 11, 2026 · May 13, 2026 · May 13, 2026
diff --git a/doc/api.rst b/doc/api.rst
diff --git a/doc/benchmark.rst b/doc/benchmark.rst
@@ -1,7 +1,7 @@
 .. _benchmark:
 
-Benchmarks
-==========
+Performance comparison
+======================
 
 
 Linopy's performance scales well with the problem size. Its overall speed is comparable with the famous `JuMP <https://jump.dev/>`_ package written in `Julia <https://julialang.org/>`_. It even outperforms `JuMP` in total memory efficiency when it comes to large models. Compared to `Pyomo <https://pyomo.org>`_, the common optimization package in python, one can expect
@@ -13,9 +13,9 @@ for large problems. The following figure shows the memory usage and speed for so
 
 .. math::
 
-    & \min \;\; \sum_{i,j} 2 x_{i,j} \; y_{i,j} \\
+    & \min \;\; \sum_{i,j} 2 x_{i,j} + y_{i,j} \\
     s.t. & \\
-    & x_{i,j} - y_{i,j} \; \ge \; i \qquad \forall \; i,j \in \{1,...,N\} \\
+    & x_{i,j} - y_{i,j} \; \ge \; i-1 \qquad \forall \; i,j \in \{1,...,N\} \\
     & x_{i,j} + y_{i,j} \; \ge \; 0 \qquad \forall \; i,j \in \{1,...,N\}
 
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "linopy"
-copyright = "2021, Fabian Hofmann"
+copyright = "2021-2026, Fabian Hofmann"
 author = "Fabian Hofmann"
 
 # The full version, including alpha/beta/rc tags
@@ -72,6 +72,16 @@
 autosummary_generate = True
 autodoc_typehints = "none"
 
+# Intersphinx — resolve :class:`xarray.DataArray`, :func:`numpy.ndarray`, etc.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+    "xarray": ("https://docs.xarray.dev/en/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "dask": ("https://docs.dask.org/en/stable", None),
+}
+
 # Napoleon configurations
 
 napoleon_google_docstring = False

diff --git a/doc/contributing.rst b/doc/contributing.rst
@@ -13,14 +13,13 @@ You are invited to submit pull requests / issues to our
 Development Setup
 =================
 
-For linting, formatting and checking your code contributions
-against our guidelines (e.g. we use `Black <https://github.com/psf/black>`_ as code style
-and use `pre-commit <https://pre-commit.com/index.html>`_:
+For linting and formatting, we use `ruff <https://docs.astral.sh/ruff/>`_
+and run it via `pre-commit <https://pre-commit.com/index.html>`_:
 
 1. Installation ``conda install -c conda-forge pre-commit`` or ``pip install pre-commit``
 2. Usage:
     * To automatically activate ``pre-commit`` on every ``git commit``: Run ``pre-commit install``
-    * To manually run it: ``pre-commit run --all``
+    * To manually run it: ``pre-commit run --all-files``
 
 Running Tests
 =============
@@ -122,23 +121,25 @@ Then for every notebook:
       e.g. `Edit -> Clear all output` in JupyterLab.
 
 3. Provide a link to the documentation:
-   Include a file ``foo.nblink`` located in ``doc/examples/foo.nblink``
+   Include a file ``foo.nblink`` located in ``doc/foo.nblink``
    with this content
 
-   .. code-block:
-        {
-            'path' : '../../examples/foo.ipynb'
-        }
+   .. code-block:: json
+
+      {
+          "path": "../examples/foo.ipynb"
+      }
+
+   Adjust the path for your file's name.
+   This ``nblink`` allows us to link your notebook into the documentation.
 
-    Adjust the path for your file's name.
-    This ``nblink`` allows us to link your notebook into the documentation.
 4. Link your file in the documentation:
 
    Either
 
-    * Include your ``examples/foo.nblink`` directly into one of
-      the documentations toctrees; or
-    * Tell us where in the documentation you want your example to show up
+   * Include your ``foo.nblink`` directly into one of
+     the documentation's toctrees; or
+   * Tell us where in the documentation you want your example to show up
 
 5. Commit your changes.
    If the precommit hook you installed above kicks in, confirm

diff --git a/doc/coordinate-alignment.nblink b/doc/coordinate-alignment.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/coordinate-alignment.ipynb"
+}
diff --git a/doc/index.rst b/doc/index.rst
@@ -23,7 +23,7 @@ Main features
 `xarray <https://github.com/pydata/xarray>`__ which allows for many
 flexible data-handling features:
 
--  Define (arrays of) contnuous or binary variables with
+-  Define (arrays of) continuous or binary variables with
    **coordinates**, e.g. time, consumers, etc.
 -  Apply **arithmetic operations** on the variables like adding,
    subtracting, multiplying with all the **broadcasting** potentials of
@@ -81,7 +81,7 @@ A BibTeX entry for LaTeX users is
 License
 -------
 
-Copyright 2021-2023 Fabian Hofmann
+Copyright 2021-2026 Fabian Hofmann
 
 This package is published under MIT license.
 
@@ -112,31 +112,54 @@ This package is published under MIT license.
    creating-expressions
    creating-constraints
    coordinate-alignment
+   manipulating-models
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Examples
+
+   transport-tutorial
+   migrating-from-pyomo
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Advanced Features
+
    sos-constraints
    piecewise-linear-constraints
-   manipulating-models
    testing-framework
-   transport-tutorial
-   infeasible-model
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Solving
+
    solve-on-remote
    solve-on-oetc
    gpu-acceleration
-   migrating-from-pyomo
-   gurobi-double-logging
 
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Troubleshooting
+
+   infeasible-model
+   gurobi-double-logging
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: Benchmarking
+   :caption: Comparisons
 
    benchmark
    syntax
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: References
+   :caption: Reference
 
    api
    release_notes

diff --git a/doc/prerequisites.rst b/doc/prerequisites.rst
@@ -36,21 +36,26 @@ CPU-based solvers
 -  `Cbc <https://projects.coin-or.org/Cbc>`__ - open source, free, fast
 -  `GLPK <https://www.gnu.org/software/glpk/>`__ - open source, free, not very fast
 -  `HiGHS <https://highs.dev/>`__ - open source, free, fast
+-  `SCIP <https://www.scipopt.org/>`__ - open source (Apache-2.0), fast MIP solver
 -  `Gurobi <https://www.gurobi.com/>`__  - closed source, commercial, very fast
 -  `Xpress <https://www.fico.com/en/fico-xpress-trial-and-licensing-options>`__ - closed source, commercial, very fast (GPU acceleration available in v9.8+)
 -  `Cplex <https://www.ibm.com/de-de/analytics/cplex-optimizer>`__ - closed source, commercial, very fast
--  `MOSEK <https://www.mosek.com/>`__
--  `MindOpt <https://solver.damo.alibaba.com/doc/en/html/index.html>`__ -
+-  `MOSEK <https://www.mosek.com/>`__ - closed source, commercial, strong on conic/QP
+-  `MindOpt <https://solver.damo.alibaba.com/doc/en/html/index.html>`__ - closed source, commercial
 -  `COPT <https://www.shanshu.ai/copt>`__ - closed source, commercial, very fast
 
-For a subset of the solvers, Linopy provides a wrapper.
+The ``linopy[solvers]`` extra installs the Python clients for the
+supported solvers (HiGHS, SCIP, Gurobi, CPLEX, MOSEK, MindOpt, COPT,
+Xpress, Knitro). For the commercial ones a separate license is still
+required:
 
 .. code:: bash
 
     pip install linopy[solvers]
 
 
-We recommend to install the HiGHS solver if possible, which is free and open source but not yet available on all platforms.
+We recommend installing the HiGHS solver, which is free, open source, and
+fast across a wide range of problem sizes:
 
 .. code:: bash
 

diff --git a/doc/user-guide.rst b/doc/user-guide.rst
@@ -3,10 +3,58 @@
 Overview
 ========
 
-Welcome to the User Guide for Linopy. This guide is designed to help you understand and effectively use Linopy's features to solve your optimization problems, complementing the ``Getting Started`` section.
+In :doc:`Getting Started <prerequisites>` you installed linopy, built
+a first scalar model, and saw N-D variables on coordinates. The User
+Guide reopens each of those pieces in depth and adds the rest of the
+modelling surface.
 
-In the following sections, we will take a closer look at how to create and manipulate models, variables, and constraints, and how to solve these models to find optimal solutions. Each section includes detailed explanations and code examples to help you understand the concepts and apply them to your own projects.
+Each page is a runnable Jupyter notebook — read it top to bottom, or
+use it as a reference once you know what you're looking for.
 
-If you are completely new to Linopy, consider to first have a look at the `Getting Started` section.
 
-Let's get started!
+Core building blocks
+--------------------
+
+The four notebooks below cover the model object you'll interact with
+most. Read them in order the first time; come back to them whenever
+you're unsure what a particular operator or argument does.
+
+- :doc:`creating-variables` — declaring decision variables, with bounds
+  and coordinates. Continuous, integer, binary, and semi-continuous.
+- :doc:`creating-expressions` — combining variables into linear (and
+  quadratic) expressions; arithmetic, broadcasting, ``sum``,
+  ``groupby``, ``rolling``, ``where``.
+- :doc:`creating-constraints` — turning expressions into ``≤`` / ``≥``
+  / ``==`` constraints, and the ``CSRConstraint`` memory-efficient
+  alternative.
+- :doc:`coordinate-alignment` — how linopy lines up operands that live
+  on different coordinates, and how to control it with ``join``.
+
+After these four you can build any LP/MIP/QP linopy supports.
+
+
+Working with an existing model
+------------------------------
+
+Once you've built a model, you'll often want to inspect it, change a
+bound, swap a constraint, or copy it for what-if analysis.
+
+- :doc:`manipulating-models` — modifying or removing variables and
+  constraints in place; ``Model.copy()``; ``fix`` / ``relax`` for
+  variables.
+
+
+Where to go next
+----------------
+
+- **Examples** — end-to-end problem walkthroughs:
+  :doc:`transport-tutorial`, :doc:`migrating-from-pyomo`.
+- **Advanced features** — :doc:`sos-constraints`,
+  :doc:`piecewise-linear-constraints`, and the
+  :doc:`testing-framework` for asserting structural properties of a
+  model.
+- **Solving** — :doc:`solve-on-remote` (SSH),
+  :doc:`solve-on-oetc` (OET Cloud), :doc:`gpu-acceleration` (cuPDLPx).
+- **Troubleshooting** — :doc:`infeasible-model` (diagnosing infeasible
+  problems), :doc:`gurobi-double-logging` (and other solver quirks).
+- **Reference** — the full :doc:`api` listing.
diff --git a/examples/create-a-model-with-coordinates.ipynb b/examples/create-a-model-with-coordinates.ipynb
@@ -150,7 +150,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")"
+    "m.solve(solver_name=\"highs\", output_flag=False)"
    ]
   },
   {
@@ -178,6 +178,16 @@
    "source": [
     "Alright! Now you learned how to set up linopy variables and expressions with coordinates. In the User Guide, which follows, we are going to see, how the representation of variables with coordinates allows us to formulate more advanced operations."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4db583af",
+   "metadata": {},
+   "source": [
+    "## Where to next\n",
+    "\n",
+    "You've now seen the full path from declaring variables on coordinates to solving the model. The [User Guide overview](user-guide.rst) reopens each piece in depth and points you at every topic from here."
+   ]
   }
  ],
  "metadata": {

diff --git a/examples/create-a-model.ipynb b/examples/create-a-model.ipynb
@@ -215,7 +215,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")"
+    "m.solve(solver_name=\"highs\", output_flag=False)"
    ]
   },
   {

diff --git a/examples/creating-expressions.ipynb b/examples/creating-expressions.ipynb
@@ -160,7 +160,10 @@
    "cell_type": "markdown",
    "id": "f7578221",
    "metadata": {},
-   "source": ".. important::\n\n\tWhen combining variables or expression with dimensions of the same name and size, the first object will determine the coordinates of the resulting expression. For example:"
+   "source": [
+    ".. important::\n",
+    "   When combining variables or expressions with dimensions of the same name and size, the first object determines the coordinates of the resulting expression. For example:"
+   ]
   },
   {
    "cell_type": "code",
@@ -196,7 +199,10 @@
   {
    "cell_type": "markdown",
    "id": "a8xsfdqrcrn",
-   "source": ".. tip::\n\n\tFor explicit control over how coordinates are aligned during arithmetic, use the `.add()`, `.sub()`, `.mul()`, and `.div()` methods with a ``join`` parameter (``\"inner\"``, ``\"outer\"``, ``\"left\"``, ``\"right\"``). See the :doc:`coordinate-alignment` guide for details.",
+   "source": [
+    ".. tip::\n",
+    "   For explicit control over how coordinates are aligned during arithmetic, use the ``.add()``, ``.sub()``, ``.mul()``, and ``.div()`` methods with a ``join`` parameter (``\"inner\"``, ``\"outer\"``, ``\"left\"``, ``\"right\"``). See the :doc:`coordinate-alignment` guide for details."
+   ],
    "metadata": {}
   },
   {

diff --git a/examples/creating-variables.ipynb b/examples/creating-variables.ipynb
@@ -31,6 +31,12 @@
     "m = Model()"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "",
+   "id": "46c4f2824a2ed8aa"
+  },
   {
    "cell_type": "markdown",
    "id": "6c6420a7",
@@ -465,9 +471,12 @@
   },
   {
    "cell_type": "markdown",
-   "id": "77e264e2",
+   "id": "e8249281",
    "metadata": {},
-   "source": ".. important::\n\n    **New in version 0.3.6**\n\n    As pandas objects always have indexes, the `coords` argument is not required and is ignored is passed. Before, it was used to overwrite the indexes of the pandas objects. A warning is raised if `coords` is passed and if these are not aligned with the pandas object."
+   "source": [
+    ".. note::\n",
+    "   As pandas objects already carry indexes, the ``coords`` argument is ignored when supplied alongside them. A warning is raised if a ``coords`` value is passed that does not align with the pandas object."
+   ]
   },
   {
    "cell_type": "code",