feat: add active parameter to piecewise linear constraints

[FBumann]

Changes proposed in this Pull Request

Add an active parameter to piecewise() that accepts a binary variable to gate piecewise linear functions on/off. This enables unit commitment formulations where a commitment binary controls the operating range of a unit.

• When active=0, all auxiliary variables are forced to zero (x and y collapse to 0)
• When active=1, the normal PWL domain [x₀, xₙ] is active

Motivation

In energy dispatch optimization, units have a binary on/off status and a variable efficiency curve (heat rate). The piecewise linear approximation of this curve needs to be gated by the commitment binary: when the unit is off, both power output and fuel consumption must be zero — not just "unconstrained".

This zero-forcing behavior is the only option that can be expressed with pure linear constraints. The alternative — selectively relaxing the PWL constraint (letting x and y float freely when off) — would require big-M formulations or solver-native indicator constraints, both of which are outside the scope of this feature.

How it works per method

Method	Change	Why it works
Incremental	δ_i ≤ active + base terms × active	Deltas forced to 0 → reconstruction collapses
SOS2	Σλ_i = active (instead of = 1)	Lambdas forced to 0 → weighted sums collapse
Disjunctive	Σz_k = active (instead of = 1)	Segment binaries forced to 0 → lambdas collapse
LP	Not supported (raises ValueError)	See below

Why LP is excluded

The LP tangent-line formulation has no auxiliary variables — it directly constrains the x/y relationship via slope inequalities. This is its strength without active, but makes clean gating impossible:

1. Big-M would be needed to relax the tangent lines when active=0
2. Relaxing alone isn't enough — separate big-M constraints would also be needed to force x=0 and y=0
3. The result would be more constraints, M-dependent numerical conditioning, and no structural advantage over SOS2/incremental where zero-forcing is free

Why active lives on piecewise() not add_piecewise_constraints()

The active binary is a property of the piecewise function itself (the mapping is gated), not of the constraint method used to implement it. It belongs with the breakpoints.

Naming

active was chosen over alternatives:

• indicator — suggests constraint relaxation (Option B), not zero-forcing
• binary — describes the type, not the role
• commitment / on — too domain-specific for a general library

Open to discussion.

Usage

m = Model()
power = m.add_variables(lower=0, upper=100, name="power")
fuel = m.add_variables(name="fuel")
u = m.add_variables(binary=True, name="commit")

m.add_piecewise_constraints(
    piecewise(power, [20, 60, 100], [5, 20, 50], active=u) == fuel,
    method="incremental",
)

Checklist

• Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
• Unit tests for new features were added (if applicable).
• A note for the release notes doc/release_notes.rst of the upcoming release is included.
• I consent to the release of this PR's code under the MIT license.

Test plan

• Structural tests: verify correct constraints/variables are created for each method
• active=None (default) produces identical formulation to before
• active with method='lp' raises ValueError
• Multi-dimensional breakpoints with active work correctly
• Solver integration tests (active on/off, non-zero base, unit commitment pattern)
• All 122 piecewise tests pass

🤖 Generated with Claude Code

[FBumann]

Addition to #602

[FabianHofmann]

nice one, this is a great extension. found one issue. active is rejected for method="lp" explicitly, but it is still silently ignored when method="auto" resolves to the LP formulation for inequalities.

Concretely, something like

  m.add_piecewise_constraints(
      piecewise(x, [0, 50, 100], [0, 40, 60], active=u) >= y,
      method="auto",
  )

currently succeeds, but u is not used in the generated formulation at all.

Since auto is the default, this can lead to a model that appears gated but actually isn’t.

We probably want to raise here

[FabianHofmann]

mind if I quickly push this?