Add a `mask` parameter to `add_piecewise_formulation`

[FBumann]

This is not needed explicitly by anyone yet, but should be added for consistency with add_variables etc

Note

The following content was generated by AI.

Summary

Add a mask parameter to add_piecewise_formulation, matching the add_variables(mask=…) / add_constraints(mask=…) convention: where mask=False, no piecewise formulation is built for that entry (no auxiliary variables, no link/convexity constraints). It answers a structural question — does this entity have a piecewise relationship at all? — and takes priority over active.

Motivation

Heterogeneous sets where only some entities have a piecewise curve. Today you either split into several add_piecewise_formulation calls or rely on NaN-breakpoint tricks. A mask is the declarative, convention-aligned way to say "this entity has no curve here."

Relationship to active / active_fill (#796, #797, #798)

mask is orthogonal to gating and does not overlap with the #796 work:

state	how to express
entity has no curve	mask=False
curve, gated on/off (unit commitment)	active=status
curve, always on (ungated)	active_fill=1 (or full active=1)

• mask: structural / compile-time — does the constraint exist here?
• active: solve-time decision — is it engaged?

They compose: mask filters which entries get a formulation, active gates the survivors. A masked entry has no constraint, so active/active_fill for it is moot — hence mask priority. mask does not solve #796: masking the non-committable units would delete their curve, but those units still dispatch on it.

Relationship to .sel()

For a clean label-subset along one dimension, .sel() on the operands already achieves "no constraint elsewhere", so no parameter is needed there. mask earns its place for:

1. Ragged / multi-dim holes that no rectangular .sel() can express (scattered (gen, time) pairs, not whole labels along an axis).
2. Full-index output — .sel() returns reduced-index objects that must be realigned to the full coordinate afterwards; mask keeps everything on the full index with holes.
3. One declarative argument instead of slicing every operand (and keeping breakpoint arrays consistent).

Notes

• Not urgent and not a blocker for the add_piecewise_formulation: support a partial active gate (treat missing/null entries as always-active) #796 gating fix; filed separately so the two designs don't get tangled.
• Originally raised by @fneum in review of feat(piecewise): partial active gate support via active_gate helper (#796) #797.

🤖 Generated with Claude Code