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

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
@@ -529,7 +596,10 @@ 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 +608,7 @@ Types returned by or compared against :attr:`Model.status`,
    constants.TerminationCondition
    constants.Status
    constants.Solution
+   constants.SolverReport
    constants.Result
 
 

doc/index.rst

@@ -136,6 +136,7 @@ This package is published under MIT license.
    :maxdepth: 2
    :caption: Solving
 
+   using-solvers
    solve-on-remote
    solve-on-oetc
    gpu-acceleration

doc/sos-constraints.rst

@@ -268,12 +268,13 @@ as binary + linear constraints using the Big-M method.
 
 .. code-block:: python
 
-    # Automatic reformulation during solve
+    # Automatic reformulation during solve (apply / undo bracketed by Model.solve)
     m.solve(solver_name="highs", reformulate_sos=True)
 
-    # Or reformulate manually
-    m.reformulate_sos_constraints()
+    # Or stage the reformulation manually — e.g. to inspect or export the MILP
+    m.apply_sos_reformulation()
     m.solve(solver_name="highs")
+    m.undo_sos_reformulation()
 
 **Requirements:**
 

doc/using-solvers.nblink

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

examples/create-a-model.ipynb

@@ -30,11 +30,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "dramatic-cannon",
    "metadata": {},
+   "source": [],
    "outputs": [],
-   "source": []
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -49,15 +49,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "technical-conducting",
    "metadata": {},
-   "outputs": [],
    "source": [
     "from linopy import Model\n",
     "\n",
     "m = Model()"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -83,14 +83,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "protecting-power",
    "metadata": {},
-   "outputs": [],
    "source": [
     "x = m.add_variables(lower=0, name=\"x\")\n",
     "y = m.add_variables(lower=0, name=\"y\");"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -103,13 +103,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "virtual-anxiety",
    "metadata": {},
-   "outputs": [],
    "source": [
     "x"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -127,13 +127,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "fbb46cad",
    "metadata": {},
-   "outputs": [],
    "source": [
     "3 * x + 7 * y >= 10"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -146,13 +146,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "60f41b76",
    "metadata": {},
-   "outputs": [],
    "source": [
     "3 * x + 7 * y - 10 >= 0"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -167,14 +167,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "hollywood-production",
    "metadata": {},
-   "outputs": [],
    "source": [
     "m.add_constraints(3 * x + 7 * y >= 10)\n",
     "m.add_constraints(5 * x + 2 * y >= 3);"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -189,13 +189,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "overall-exhibition",
    "metadata": {},
-   "outputs": [],
    "source": [
     "m.add_objective(x + 2 * y)"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -210,13 +210,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "pressing-copying",
    "metadata": {},
-   "outputs": [],
    "source": [
     "m.solve(solver_name=\"highs\", output_flag=False)"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -229,23 +229,23 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "electric-duration",
    "metadata": {},
-   "outputs": [],
    "source": [
     "x.solution"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "cell_type": "code",
-   "execution_count": null,
    "id": "e6d31751",
    "metadata": {},
-   "outputs": [],
    "source": [
     "y.solution"
-   ]
+   ],
+   "outputs": [],
+   "execution_count": null
   },
   {
    "attachments": {},
@@ -255,6 +255,59 @@
    "source": [
     "Well done! You solved your first linopy model!"
    ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "f2dc93fa",
+   "metadata": {},
+   "source": [
+    "After solving, the solver instance stays attached to the model as `model.solver`, including a small report (runtime, MIP gap, dual bound, iterations) on solvers that populate it:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "21edcd3f",
+   "metadata": {},
+   "source": [
+    "m.solver"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "91a26989",
+   "metadata": {},
+   "source": [
+    "m.solver.report"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "58965d32",
+   "source": "Some solvers hold a license while the underlying handle is alive. Release it with `solver.close()` (or `model.solver = None` to also detach the wrapper):",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "d9c736c6",
+   "source": "m.solver.close()",
+   "metadata": {},
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "513277f1",
+   "metadata": {},
+   "source": [
+    "For more on choosing a solver, the construct-then-solve API, and querying solver capabilities, see [Using solvers](using-solvers.ipynb)."
+   ]
   }
  ],
  "metadata": {