feat(piecewise): partial active gate support via active_gate helper (#796)

[FBumann]

(placeholder — Felix to rewrite)

Closes #796. See the design discussion in the issue.

Note

The following content was generated by AI.

Problem

add_piecewise_formulation(active=...) assumed the gate spanned the formulation's full indexed dimension. A gate defined over only a subset of coordinate labels — or with masked entries — silently forced the uncovered entries to zero, instead of leaving them ungated. This broke formulations that mix gated and ungated entities (e.g. committable + non-committable units sharing a unit-commitment status), surfaced in PyPSA/PyPSA#1755.

Approach

Per the issue discussion, this does not make the function silently accept misaligned coords (that would mask genuine coverage bugs and clashes with v1 alignment semantics). Instead:

1. Validate, don't auto-fix. add_piecewise_formulation now rejects an under-defined active (strict subset or masked) with an actionable error. A lower-dimensional gate still broadcasts and is accepted.
2. linopy.active_gate(active, coords, fill_value=1) pads a partial gate to full coverage — missing/masked entries become always-active (1) or always-off (0). The signature mirrors active.reindex(coords).fillna(fill_value) so migration is mechanical.

active_gate is a temporary legacy stopgap, isolated in linopy/_active_gate.py: under the planned v1 arithmetic semantics (#717) the bare reindex().fillna() idiom is correct on its own, so the helper is expected to be deprecated and that file removed. The validation guard stays.

Why a helper is needed today (legacy footgun)

The "always-on" pad is conceptually just reindex(coords).fillna(1). Today that idiom is shape- and cast-dependent: a bare Variable.fillna resolves a gap to always-off, fillna can't add absent labels (a strict subset needs reindex), and a masked entry has no NaN for fillna to fill (needs .where). There is no single correct one-liner across both shapes. active_gate encapsulates a .where-on-term-labels recipe that is correct for both shapes; under v1 it collapses to the bare idiom. Full per-shape/per-regime table in the issue comment.

Changes

• linopy/_active_gate.py (new) — active_gate helper.
• linopy/piecewise.py — _validate_active_coverage + wiring; active docstring.
• linopy/__init__.py — export active_gate.
• test/test_piecewise_active_gate.py (new) — parametrized over both partial shapes × helper/validation/solver (incremental, sos2, disjunctive), plus broadcast and full/scalar acceptance.
• Docs: api.rst, piecewise guide (partial-gates section), release notes.

Tests

test_piecewise_active_gate.py + test_piecewise_constraints.py: 247 passed. mypy and ruff clean.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 138 untouched benchmarks
⏩ 138 skipped benchmarks¹

---

_{Comparing fix/796-partial-active-gate (16fc4a2) with master (1dbde37)}

Footnotes

1. 138 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[FabianHofmann]

thanks @FBumann ; the exposure of the new active_gate function is not ideal as this will be a throw-away in v1. but I definitely see the point. a potentiially cleaner solution would be adding a explicit boolean mask that has prio and active can be a subset. then we have a clear split on masking and gating and align the signature with the other add_* functions. what do you think?

[FBumann]

thanks @FBumann ; the exposure of the new active_gate function is not ideal as this will be a throw-away in v1. but I definitely see the point. a potentiially cleaner solution would be adding a explicit boolean mask that has prio and active can be a subset. then we have a clear split on masking and gating and align the signature with the other add_* functions. what do you think?

A mask parameter is indeed a good idea. But it should mask the whole constraint, not just active! So its not a fix to this use case.

And yes, the helper isnt ideal, but as you can see from the tests and the AI comment, under legacy, there are many edge cases, and scoping them in a helper keeps add_piecewise_formulation clean. Else we need parameters purely scoped to active (which we could do...), and deprecate them gracefully. Maybe this is the right call from a user perspective though...

[FBumann]

I'll do another branch with inline parameters, so we can decide from seeing the api!

[FabianHofmann]

closed via #798