PyPSA
diff --git a/‎.pre-commit-config.yaml‎
Lines changed: 1 addition & 0 deletions b/‎.pre-commit-config.yaml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎doc/api.rst‎
Lines changed: 18 additions & 0 deletions b/‎doc/api.rst‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎doc/release_notes.rst‎
Lines changed: 17 additions & 1 deletion b/‎doc/release_notes.rst‎
Lines changed: 17 additions & 1 deletion
diff --git a/‎examples/creating-constraints.ipynb‎
Lines changed: 3 additions & 3 deletions b/‎examples/creating-constraints.ipynb‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎examples/manipulating-models.ipynb‎
Lines changed: 26 additions & 11 deletions b/‎examples/manipulating-models.ipynb‎
Lines changed: 26 additions & 11 deletions
@@ -30,6 +30,7 @@ repos:
     rev: v2.4.2
     hooks:
     -   id: codespell
+        args: ['--ignore-words-list=coo']
         types_or: [python, rst, markdown]
         files: ^(linopy|doc)/
 -   repo: https://github.com/kynan/nbstripout
 
@@ -136,9 +136,14 @@ Attributes
 Modification
 ------------
 
+``Variable.update`` is the canonical mutation API. The legacy ``lower`` /
+``upper`` setters still forward to ``update`` but emit a
+``DeprecationWarning`` and will be removed in a future release.
+
 .. autosummary::
    :toctree: generated/
 
+   variables.Variable.update
    variables.Variable.fix
    variables.Variable.unfix
    variables.Variable.relax
@@ -332,6 +337,19 @@ Structure
    constraints.Constraint.coeffs
    constraints.Constraint.vars
 
+Modification
+------------
+
+``Constraint.update`` is the canonical mutation API. The legacy ``lhs`` /
+``sign`` / ``rhs`` / ``coeffs`` / ``vars`` setters still forward to
+``update`` but emit a ``DeprecationWarning`` and will be removed in a
+future release.
+
+.. autosummary::
+   :toctree: generated/
+
+   constraints.Constraint.update
+
 Post-solve access
 -----------------
 
 
@@ -4,12 +4,28 @@ Release Notes
 Upcoming Version
 ----------------
 
+**Features**
+
+
+*In-place solver updates (persistent re-solve)*
+
+* A built solver can now be re-solved against a mutated ``Model`` without a full rebuild. Construct with ``Solver.from_name(..., track_updates=True)`` and re-call ``solver.solve(model)`` after edits — the diff against the previous build is applied in place when the backend supports it, falling back to a rebuild otherwise. Supported on HiGHS, Gurobi, Xpress, and Mosek (``io_api="direct"``).
+* Pass ``disallow_rebuild=True`` to ``solve(model, ...)`` to guarantee an in-place update or raise ``RebuildRequiredError``. Inspect ``solver._last_rebuild_reason`` (a ``RebuildReason``, or ``None`` after an in-place update) to understand why a rebuild was triggered.
+* New ``linopy.persistent`` module exposes ``ModelSnapshot``, ``ModelDiff``, and ``RebuildReason`` for users who want to introspect or build the diff themselves. ``ModelDiff.from_snapshot`` / ``from_models`` return the ``RebuildReason`` directly when the change cannot be applied in place.
+
+*Improved IO*
+
 * ``Model.to_netcdf`` now records the writing linopy version in the ``_linopy_version`` dataset attribute. Files written by older versions (without the attribute) continue to read unchanged.
 
-**Features**
+*Other*
 
 * ``add_variables(binary=True, ...)`` now accepts ``lower``/``upper`` bounds, as long as they are 0 or 1. Previously binary bounds could only be set via the ``.lower``/``.upper`` setters after creation. (https://github.com/PyPSA/linopy/issues/776)
 
+**Deprecations**
+
+* Mutation via assignment to ``Variable.lower`` / ``Variable.upper`` / ``Constraint.coeffs`` / ``Constraint.vars`` / ``Constraint.lhs`` / ``Constraint.sign`` / ``Constraint.rhs`` is deprecated and emits a ``DeprecationWarning``. Use ``Variable.update(...)`` / ``Constraint.update(...)`` instead — the canonical mutation API with one validation path and one place that flips the persistent-solver dirty flag. Read access to these properties is unchanged. The setters will be removed in a future release.
+* Passing a raw ``DataArray`` of integer labels to ``Constraint.vars = ...`` setter is deprecated and emits a ``FutureWarning``. Pass a ``Variable`` to ``Constraint.update()`` instead — it is the supported input. The ``DataArray`` path will be removed in a future release.
+
 **Bug fixes**
 
 * LP file export now honors bounds tightened below ``[0, 1]`` on a binary variable via the ``.lower``/``.upper`` setters after creation (e.g. ``upper = 0``). Previously such bounds were written only by ``io_api="direct"`` and dropped by ``io_api="lp"``. (https://github.com/PyPSA/linopy/issues/776)
 
@@ -348,16 +348,16 @@
     "\n",
     "`CSRConstraint` deliberately exposes a narrower API than the xarray-backed `Constraint`:\n",
     "\n",
-    "- **No in-place mutation.** Setters such as `con.coeffs = ...`, `con.vars = ...`, `con.sign = ...`, `con.rhs = ...`, and `con.lhs = ...` are only available on `Constraint`.\n",
+    "- **No in-place mutation.** `Constraint.update(...)` is only available on `Constraint`. (The legacy setters — `con.coeffs = ...`, `con.vars = ...`, `con.sign = ...`, `con.rhs = ...`, `con.lhs = ...` — still forward to `update` on `Constraint` but emit a `DeprecationWarning` and will be removed in a future release.)\n",
     "- **No label-based indexing.** `con.loc[...]` is only available on `Constraint`.\n",
     "- **Accessing `.coeffs` / `.vars` triggers reconstruction.** On a `CSRConstraint` these properties rebuild the full xarray `Dataset` on demand and emit a `PerformanceWarning`. For solver-oriented workflows prefer `con.to_matrix()` or work with the CSR data directly.\n",
     "\n",
     "If you need any of the above, call `.mutable()` first to get a `Constraint`:\n",
     "\n",
     "```python\n",
     "con = m.constraints[\"my_constraint\"].mutable()\n",
-    "con.loc[{\"time\": 0}]  # label-based indexing now available\n",
-    "con.rhs = 5           # mutation now available\n",
+    "con.loc[{\"time\": 0}]      # label-based indexing now available\n",
+    "con.update(rhs=5)         # mutation now available\n",
     "```"
    ]
   },
 
@@ -74,7 +74,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "x.lower = 1"
+    "x.update(lower=1)"
    ]
   },
   {
@@ -83,7 +83,10 @@
    "metadata": {},
    "source": [
     ".. note::\n",
-    "   The same could have been achieved by calling `m.variables.x.lower = 1`\n",
+    "   Assignment via the ``x.lower = 1`` setter still works but is\n",
+    "   deprecated and will be removed in a future release. Use\n",
+    "   ``Variable.update`` instead — it is the canonical mutation API\n",
+    "   with a single validation path.\n",
     "\n",
     "Let's solve it again!"
    ]
@@ -127,7 +130,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "x.lower = xr.DataArray(range(10, 0, -1), coords=(time,))"
+    "x.update(lower=xr.DataArray(range(10, 0, -1), coords=(time,)))"
    ]
   },
   {
@@ -157,9 +160,12 @@
    "source": [
     "## Varying Constraints\n",
     "\n",
-    "A similar functionality is implemented for constraints. Here we can modify the left-hand-side, the sign and the right-hand-side.\n",
+    "A similar functionality is implemented for constraints. We use\n",
+    "``Constraint.update`` to change the left-hand-side, the sign,\n",
+    "and the right-hand-side.\n",
     "\n",
-    "Assume we want to relax the right-hand-side of the first constraint `con1` to `8 * factor`. This would translate to:"
+    "Assume we want to relax the right-hand-side of the first constraint\n",
+    "``con1`` to ``8 * factor``. This translates to:"
    ]
   },
   {
@@ -169,7 +175,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "con1.rhs = 8 * factor"
+    "con1.update(rhs=8 * factor)"
    ]
   },
   {
@@ -178,7 +184,10 @@
    "metadata": {},
    "source": [
     ".. note::\n",
-    "   The same could have been achieved by calling `m.constraints.con1.rhs = 8 * factor`\n",
+    "   Assignment via the ``con1.rhs = 8 * factor`` setter still works\n",
+    "   but is deprecated and will be removed in a future release. Use\n",
+    "   ``Constraint.update`` instead — it is the canonical mutation API\n",
+    "   with a single validation path.\n",
     "\n",
     "Let's solve it again!"
    ]
@@ -212,7 +221,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "con1.lhs = 3 * x + 8 * y"
+    "con1.update(lhs=3 * x + 8 * y)"
    ]
   },
   {
@@ -221,9 +230,15 @@
    "metadata": {},
    "source": [
     "**Note:**\n",
-    "The same could have been achieved by calling \n",
-    "```python \n",
-    "m.constraints['con1'].lhs = 3 * x + 8 * y\n",
+    "Assignment via the ``con1.lhs = 3 * x + 8 * y`` setter still works\n",
+    "but is deprecated and will be removed in a future release. Use\n",
+    "``Constraint.update`` instead — it is the canonical mutation API\n",
+    "with a single validation path.\n",
+    "\n",
+    "``Constraint.update`` also accepts a full constraint expression in one call:\n",
+    "\n",
+    "```python\n",
+    "con1.update(3 * x + 8 * y <= 8 * factor)   # replaces lhs / sign / rhs at once\n",
     "```"
    ]
   },