release: v4.0.0b21 — Benders in-out stabilization + polar-high>=3.4.0 floor

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jkiviluo

CHANGELOG.md

@@ -1,3 +1,36 @@
+## Release 4.0.0b21 (1.7.2026) — Benders in-out stabilization (degeneracy tail-off)
+
+No database migration (schema stays **v62**). Dependency floor raised to
+**`polar-high>=3.4.0`** (`polars>=1.40`, `highspy<=1.14.0` unchanged). Opt-in and
+OFF by default — the converged solution is unchanged on every model.
+
+### Decomposition (Benders)
+
+- **Optional in-out separation to speed up a slowly-converging (tailing-off)
+  spatial-Benders solve.** When storage (or any inter-temporal coupling) makes
+  timesteps fungible, the region recourse is flat in the per-timestep coupling
+  flow and the cut slopes become basis-dependent; the master then wanders among
+  cost-equivalent flow schedules and the lower bound closes very slowly even
+  though the best feasible solution is near-optimal early. In-out separation
+  (Ben-Ameur & Neto 2007) generates each cut at an interior point
+  `f_sep = λ·centre + (1-λ)·f_out` instead of the extreme master vertex — better-
+  centred cuts, no wandering, faster bound closure, at **zero extra subproblem
+  solves** (the region is solved once per iteration either way, just at a better
+  point). Enabled per solve via the environment variable
+  `FLEXTOOL_BENDERS_IN_OUT_WEIGHT` (the weight `λ`): **`0.0` (the default) is OFF**
+  and byte-identical to before; `λ ∈ (0, 1)` turns it on, larger = more
+  stabilisation. On a hydrogen-trade tail-off benchmark, `λ ≈ 0.3–0.7` reached the
+  practical optimality gaps about 30% faster and closed the bound tighter than the
+  un-stabilised run (which plateaued above the gap it could otherwise reach). The
+  stabilisation math is the domain-free `polar_high.decomposition.InOutStabilizer`
+  (3.4.0); FlexTool drives one instance per node group. Correctness is preserved
+  regardless of `λ`: a cut generated at any point is a valid supporting hyperplane
+  (valid lower bound), the interior point is clamped to the chosen capacity (valid
+  upper bound), and the moment a region's cut fails to separate the master vertex
+  the method falls back to an exact-Benders step for that region — so the optimum
+  is unchanged and convergence is guaranteed. A future release will promote the
+  knob to a `solve` database parameter once a default is settled.
+
 ## Release 4.0.0b20 (1.7.2026) — Benders stall guard (fail fast with a diagnostic)
 
 No database migration (schema stays **v62**). Dependency floor raised to

pyproject.toml

@@ -7,7 +7,7 @@ name = "flextool"
 # restructure are in.  4.0.0 final follows after the remaining
 # minor-functionality additions, cleanup and testing land.  PEP 440
 # pre-release suffix: 4.0.0a1, 4.0.0a2, ... 4.0.0b1, 4.0.0rc1, then 4.0.0.
-version = "4.0.0b20"
+version = "4.0.0b21"
 description = "IRENA FlexTool is an energy and power systems model for understanding the role of variable power generation in future energy systems."
 readme = "README.md"
 license = { file = "LICENSE.txt" }
@@ -54,9 +54,10 @@ dependencies = [
     # self-check reads to size its tolerance.  3.2.0 makes autoscale Layer 3
     # centre the objective over HiGHS' cost comfort zone (clearing the
     # "excessively small costs" warning that the legacy 1e-6 scale_the_objective
-    # provokes).  3.3.0 adds polar_high.decomposition.StallMonitor, the generic
-    # tail-off detector the Benders stall guard drives — so it is the hard floor.
-    "polar-high>=3.3.0",
+    # provokes).  3.3.0 adds polar_high.decomposition.StallMonitor (the Benders
+    # stall guard).  3.4.0 adds decomposition.InOutStabilizer, the generic in-out
+    # separation picker the Benders in-out stabilization drives — the hard floor.
+    "polar-high>=3.4.0",
     # Cap pins the install default to 1.14.0 (the highest tested
     # version) while leaving room for users to downgrade to older
     # 1.x releases that have been validated against their setup.