feat(piecewise): active_fill for partial active gates (alt. to #797, #796)

[FBumann]

(placeholder — Felix to rewrite)

Note

The following content was generated by AI.

Alternative to #797. Closes #796. Same goal (partial active gate), but exposes the fix as an active_fill parameter on add_piecewise_formulation instead of a standalone active_gate helper. The first two commits are #797's helper approach; the third refactors it into the parameter, so the evolution is visible in history while the net diff is just the parameter design.

What

add_piecewise_formulation(..., active=status, active_fill=1):

• active_fill=None (default) → a partial active (subset of the indexed dim, or masked) raises — the function stays strict.
• active_fill=0|1 → opt in to gating the missing entries as always-off / always-on.

The function derives its own coordinate, so the caller supplies nothing extra (no coords, no helper, no import).

Why a parameter instead of the active_gate helper (#797)

• No caller boilerplate — the helper needed an explicit coords argument; the function already knows its coordinate.
• Strict by default — active_fill=None rejects a partial gate, so accidental partial coverage surfaces as an error rather than a silent always-on/off.
• Transitional, and honestly scoped — active_fill is documented as slated for removal once v1 arithmetic semantics make active.reindex(coords).fillna(value) correct on its own. It's a parameter whose implementation is legacy-specific, not throwaway public surface elsewhere.

Changes (net)

• linopy/piecewise.py — active_fill parameter; _resolve_active folds the coverage guard (raise when None) and the padding (where(has_terms, fill) when set) into one place.
• test/test_piecewise_active_fill.py — parametrized over both gap shapes (strict-subset, masked) × resolution/validation/solver (incremental, sos2, disjunctive); covers active_fill=0/1, None-raises, active_fill without active, and lower-dimensional broadcast.
• Docs: piecewise guide + release notes.

Tests

test_piecewise_active_fill.py + test_piecewise_constraints.py: 248 passed. ruff / blackdoc / mypy clean.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 138 untouched benchmarks
⏩ 138 skipped benchmarks¹

---

_{Comparing feat/piecewise-active-fill (feed36e) 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. ↩

[FBumann]

@FabianHofmann Id argue this is more ergonomic than #797. And handling the removal of this isn't harder...
Its probably easier...

[FabianHofmann]

let's pull that in. I spent some time with trying to find a way without the active_fill. but in the end this is fail fast and explicit. just as we want.