docs: add working-with-solvers notebook for the stateful Solver API

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

doc/conf.py

@@ -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

doc/index.rst

@@ -112,31 +112,55 @@ 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
+
+   using-solvers
    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

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.

doc/using-solvers.nblink

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

examples/create-a-model-with-coordinates.ipynb

@@ -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": {