PyPSA · FBumann · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.github/workflows/test-notebooks.yml b/.github/workflows/test-notebooks.yml
@@ -40,8 +40,8 @@ jobs:
 
           # Skip notebooks that require credentials or special setup
           case "$name" in
-            solve-on-oetc.ipynb|solve-on-remote.ipynb)
-              echo "Skipping $name (requires credentials or special setup)"
+            remote-machines.ipynb)
+              echo "Skipping $name (requires credentials or remote machine)"
               continue
               ;;
           esac

diff --git a/doc/api.rst b/doc/api.rst
@@ -70,6 +70,8 @@ Modifying a model
    model.Model.remove_objective
    model.Model.remove_sos_constraints
    model.Model.copy
+   model.Model.apply_sos_reformulation
+   model.Model.undo_sos_reformulation
    model.Model.reformulate_sos_constraints
 
 Solving
@@ -498,10 +500,75 @@ Type aliases
 Solvers
 ========
 
+The stateful :class:`~linopy.solvers.Solver` instance owns the solver-side
+model and exposes a two-step :meth:`~linopy.solvers.Solver.from_name` /
+:meth:`~linopy.solvers.Solver.solve` workflow. :meth:`Model.solve` is a
+thin wrapper around it.
+
+.. autosummary::
+   :toctree: generated/
+
+   solvers.Solver
+
+Construction
+------------
+
+.. autosummary::
+   :toctree: generated/
+
+   solvers.Solver.from_name
+   solvers.Solver.from_model
+
+Solving
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   solvers.Solver.solve
+   solvers.Solver.update_solver_model
+   solvers.Solver.close
+
+Post-solve state
+----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   solvers.Solver.status
+   solvers.Solver.solution
+   solvers.Solver.report
+   solvers.Solver.solver_model
+
+Capabilities
+------------
+
+.. autosummary::
+   :toctree: generated/
+
+   solvers.Solver.is_available
+   solvers.Solver.license_status
+   solvers.Solver.supports
+   solvers.Solver.supported_features
+   solvers.Solver.runtime_features
+
+Discovery
+---------
+
 .. autosummary::
    :toctree: generated/
 
    solvers.available_solvers
+   solvers.licensed_solvers
+   solvers.SolverFeature
+   solvers.LicenseStatus
+
+Implementations
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
    solvers.CBC
    solvers.COPT
    solvers.Cplex
@@ -519,17 +586,29 @@ Solvers
 Remote solving
 ==============
 
+Solve a model on a remote machine via SSH or on the OET Cloud (OETC).
+See :doc:`remote-machines` for usage.
+
 .. autosummary::
    :toctree: generated/
 
+   remote.SSH
+   remote.SshSettings
+   remote.Oetc
+   remote.OetcSettings
    remote.RemoteHandler
+   remote.OetcHandler
+   remote.OetcCredentials
 
 
 Solver status and result types
 ==============================
 
 Types returned by or compared against :attr:`Model.status`,
-:attr:`Model.termination_condition`, and :attr:`Model.solution`.
+:attr:`Model.termination_condition`, and :attr:`Model.solution`, plus
+:class:`~linopy.constants.SolverReport` surfaced on
+:attr:`Solver.report <linopy.solvers.Solver.report>` and
+:attr:`Result.report <linopy.constants.Result.report>`.
 
 .. autosummary::
    :toctree: generated/
@@ -538,6 +617,7 @@ Types returned by or compared against :attr:`Model.status`,
    constants.TerminationCondition
    constants.Status
    constants.Solution
+   constants.SolverReport
    constants.Result
 
 

diff --git a/doc/benchmark.rst b/doc/benchmark.rst
diff --git a/doc/conf.py b/doc/conf.py
@@ -123,6 +123,7 @@
 html_theme_options = {
     "repository_url": "https://github.com/pypsa/linopy",
     "use_repository_button": True,
+    "show_toc_level": 2,
 }
 
 

diff --git a/doc/create-a-model-with-coordinates.nblink b/doc/create-a-model-with-coordinates.nblink
diff --git a/doc/create-a-model.nblink b/doc/create-a-model.nblink
diff --git a/doc/first-real-model.nblink b/doc/first-real-model.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/first-real-model.ipynb"
+}
diff --git a/doc/gpu-acceleration.rst b/doc/gpu-acceleration.rst
@@ -1,14 +1,14 @@
-========================
-GPU-Accelerated Solving
-========================
+================
+GPU acceleration
+================
 
 .. warning::
 
    This feature is **experimental** and not tested in CI due to the lack of GPU-enabled machines. Use with caution and please report any issues.
 
 Linopy supports GPU-accelerated optimization solvers that can significantly speed up solving large-scale linear programming problems by leveraging the parallel processing capabilities of modern GPUs.
 
-Supported GPU Solvers
+Supported GPU solvers
 =====================
 
 cuPDLPx
@@ -42,7 +42,7 @@ To install it, you have to have the `CUDA Toolkit <https://developer.nvidia.com/
 
 For a complete list of cuPDLPx parameters, see the `cuPDLPx documentation <https://github.com/MIT-Lu-Lab/cuPDLPx/tree/main/python#parameters>`_.
 
-Xpress with GPU Acceleration
+Xpress with GPU acceleration
 -----------------------------
 
 `FICO Xpress <https://www.fico.com/en/fico-xpress-trial-and-licensing-options>`_ version 9.8 and later includes GPU acceleration support for certain operations.
@@ -56,7 +56,7 @@ Xpress with GPU Acceleration
 Prerequisites
 =============
 
-Hardware Requirements
+Hardware requirements
 ---------------------
 
 GPU solvers require:
@@ -65,13 +65,13 @@ GPU solvers require:
 - Sufficient GPU memory for your problem size (varies by problem)
 - PCIe 3.0 or higher for optimal data transfer
 
-Software Requirements
+Software requirements
 ---------------------
 
 1. **CUDA Toolkit**: Most GPU solvers require CUDA 11.0 or later
 2. **Compatible GPU drivers**: Match your CUDA version
 
-Verifying Installation
+Verifying installation
 ======================
 
 To verify that the GPU solvers are properly installed and detected:

diff --git a/doc/gurobi-double-logging.rst b/doc/gurobi-double-logging.rst
diff --git a/doc/index.rst b/doc/index.rst
@@ -98,69 +98,61 @@ This package is published under MIT license.
    :maxdepth: 2
    :caption: Getting Started
 
-   prerequisites
-   create-a-model
-   create-a-model-with-coordinates
+   installation
+   quick-start
+   first-real-model
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: User Guide
+   :caption: Creating a Model
 
-   user-guide
    creating-variables
    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
+   :caption: Solving a Model
 
-   sos-constraints
-   piecewise-linear-constraints
-   testing-framework
+   solving
+   solver-api
+   remote-machines
+   gpu-acceleration
+   solving-troubleshooting
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: Solving
+   :caption: Modifying a Model
 
-   solve-on-remote
-   solve-on-oetc
-   gpu-acceleration
+   manipulating-models
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: Troubleshooting
+   :caption: Advanced Formulations
 
-   infeasible-model
-   gurobi-double-logging
+   sos-constraints
+   piecewise-linear-constraints
 
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: Comparisons
+   :caption: Coming from Other Tools
 
-   benchmark
-   syntax
+   tool-comparison
+   migrating-from-pyomo
+   transport-tutorial
 
 .. toctree::
    :hidden:
    :maxdepth: 2
    :caption: Reference
 
+   testing-framework
    api
    release_notes
    contributing
diff --git a/doc/infeasible-model.nblink b/doc/infeasible-model.nblink