docs: fix broken toctree, refresh API reference, and clean up references

doc/api.rst

@@ -18,6 +18,7 @@ Creating a model
     model.Model.add_variables
     model.Model.add_constraints
     model.Model.add_objective
+    model.Model.add_sos_constraints
     model.Model.add_piecewise_formulation
     piecewise.PiecewiseFormulation
     piecewise.Slopes
@@ -26,10 +27,26 @@ Creating a model
     piecewise.tangent_lines
     model.Model.linexpr
     model.Model.remove_constraints
+    model.Model.reformulate_sos_constraints
+    model.Model.compute_infeasibilities
+    model.Model.format_infeasibilities
     model.Model.copy
 
 
-Classes under the hook
+Top-level helpers
+=================
+
+.. autosummary::
+    :toctree: generated/
+
+    align
+    merge
+    options
+    EvolvingAPIWarning
+    PerformanceWarning
+
+
+Classes under the hood
 ======================
 
 Variable
@@ -46,7 +63,11 @@ Variable
     variables.Variable.sum
     variables.Variable.where
     variables.Variable.sanitize
-    variables.Variables
+    variables.Variable.to_linexpr
+    variables.Variable.fix
+    variables.Variable.unfix
+    variables.Variable.relax
+    variables.Variable.unrelax
     variables.ScalarVariable
 
 Variables
@@ -61,7 +82,6 @@ Variables
     variables.Variables.add
     variables.Variables.remove
     variables.Variables.continuous
-    variables.Variables.integers
     variables.Variables.binaries
     variables.Variables.integers
     variables.Variables.flat
@@ -82,6 +102,24 @@ LinearExpressions
     expressions.merge
     expressions.ScalarLinearExpression
 
+
+QuadraticExpressions
+--------------------
+
+.. autosummary::
+    :toctree: generated/
+
+    expressions.QuadraticExpression
+
+
+Objective
+---------
+
+.. autosummary::
+    :toctree: generated/
+
+    objective.Objective
+
 Constraint
 ----------
 
@@ -167,13 +205,27 @@ Solvers
     :toctree: generated/
 
     solvers.CBC
+    solvers.COPT
     solvers.Cplex
     solvers.GLPK
     solvers.Gurobi
     solvers.Highs
+    solvers.Knitro
+    solvers.MindOpt
     solvers.Mosek
+    solvers.PIPS
     solvers.SCIP
     solvers.Xpress
+    solvers.cuPDLPx
+
+
+Remote solving
+==============
+
+.. autosummary::
+    :toctree: generated/
+
+    remote.RemoteHandler
 
 
 Solving

doc/benchmark.rst

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

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

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

doc/coordinate-alignment.nblink

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

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.
 

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
 

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)"
    ]
   },
   {

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)"
    ]
   },
   {

examples/manipulating-models.ipynb

@@ -48,9 +48,9 @@
     "con2 = m.add_constraints(5 * x + 2 * y >= 3 * factor, name=\"con2\")\n",
     "\n",
     "m.add_objective(x + 2 * y)\n",
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "\n",
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -95,7 +95,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -137,7 +137,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -190,7 +190,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -242,7 +242,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -276,7 +276,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "sol = m.solution.to_dataframe()\n",
     "sol.plot(grid=True, ylabel=\"Optimal Value\")"
    ]
@@ -326,7 +326,7 @@
     "# Penalize activation of z in the objective\n",
     "m.objective = x + 3 * y + 10 * z\n",
     "\n",
-    "m.solve(solver_name=\"highs\")"
+    "m.solve(solver_name=\"highs\", output_flag=False)"
    ]
   },
   {
@@ -346,7 +346,7 @@
    "source": [
     "m.variables.binaries.fix()\n",
     "m.variables.binaries.relax()\n",
-    "m.solve(solver_name=\"highs\")\n",
+    "m.solve(solver_name=\"highs\", output_flag=False)\n",
     "\n",
     "# Dual values are now available on the constraints\n",
     "m.constraints[\"con1\"].dual"

examples/transport-tutorial.ipynb

@@ -417,7 +417,7 @@
    "outputs": [],
    "source": [
     "# Solve the model\n",
-    "m.solve(solver_name=\"highs\")"
+    "m.solve(solver_name=\"highs\", output_flag=False)"
    ]
   },
   {