feat: add piecewise linear constraint API

[FBumann]

Add Piecewise Linear Constraint API

Summary

Add add_piecewise_constraints method to Model class for creating piecewise linear constraints using SOS2 formulation.

Features

• Single Variable or LinearExpression support
• Dict of Variables/Expressions for linking multiple quantities (e.g., power-efficiency curves)
• Auto-detection of link_dim from breakpoints coordinates
• NaN-based masking with skip_nan_check option for performance
• Counter-based name generation for efficiency

Design decision

Is this something the linopy package wants to add? And if, do you want to see this as a helper method, that adds variables and constraints itself, or store sth like a PWL-Constraint object?
This implementation adds variables and (sos-)constraints, which i prefer over adding other classes of constraints.
This kind of relies on #549 to be widely uses, as it uses sos2 internally

As a convention, we could establish that such internally added variables/constraints get a prefix starting with an double underscore. This would simplify filtering.

Usage

# Single variable
m.add_piecewise_constraints(x, breakpoints, dim='bp')

# Expression
m.add_piecewise_constraints(x + y, breakpoints, dim='bp')

# Multiple linked variables (e.g., power-efficiency curve)
m.add_piecewise_constraints(
    {'power': power, 'efficiency': efficiency},
    breakpoints,
    link_dim='var',
    dim='bp'
)

SOS2 Formulation

The method creates:

1. Lambda (λ) variables with bounds [0, 1] for each breakpoint
2. SOS2 constraint ensuring at most two adjacent λ values are non-zero
3. Convexity constraint: Σλ = 1
4. Linking constraints: expr = Σ(λ × breakpoint) for each expression

Known Limitations

• No binary variable fallback for solvers without SOS2 support (feat: add sos reformulations into linopy to simplify adoption of new sos features #549)
• Continuous PWL only - discontinuous functions need binary formulation (See https://github.com/FBumann/linopy/tree/feat/add-discontinous-pwl)

Supported (continuous):     NOT supported (discontinuous):
      /\                          /\
     /  \                        /  \
    /    \____                  /    \       ____
                                           gap

• Returns only convexity constraint; access lambda via model.variables[f"{name}_lambda"]
• No removal/modification support after creation
• Single breakpoint dimension for all linked expressions

Future Work

• Binary variable formulation for non-SOS2 solvers (feat: add sos reformulations into linopy to simplify adoption of new sos features #549)
• Discontinuous PWL support (gaps/steps)
• Minimum breakpoint count validation (need at least 2)

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.

[RobbieKiwi]

It could be nice to have a linear formulation as well to cover the strictly monotonic case

[FBumann]

@RobbieKiwi Yes why not?
But id like to add this quickly, together with the sos reformulation, and then build on top of it :).
What formulation do you have in mind?
continuous δᵢ ∈ [0,1] with filling-order constraints δᵢ₊₁ ≤ δᵢ ?
Or just skipping the sos2 and relying on convexity ?

[RobbieKiwi]

Yeah makes more sense for a future PR. I was thinking continuous with filling-order constraints, I don't like relying on the objective to make the mapping work correctly

[FBumann]

Yeah makes more sense for a future PR. I was thinking continuous with filling-order constraints, I don't like relying on the objective to make the mapping work correctly

Ok perfect. We should bundle those under a "method" or sth. Just to have it linked here: FBumann#10

[FBumann]

@RobbieKiwi @FabianHofmann Is there a blocker to this PR? Or is the blocker in #549 ?
It would really make my own library much simpler.
I also already prepared follow ups FBumann#10 and FBumann#20

[FBumann]

I added some docs. If you want to, we can also merge all 3 as a single new feature. WOuld add full generalized support for piecewise linear formulation, both for linear, sos2 and dicontinous formulations

[RobbieKiwi]

By the way there is an issue with readthedocs, nothing to do with your changes, I am fixing it here #574

[RobbieKiwi]

What is the purpose of a single variable piecewise constraint?

[FBumann]

I thought fording a variable into such bounds would be useful to someone.
Im not completely sure about the actual use case. But i don't see why we should strip it.

[FBumann]

@RobbieKiwi if you prefer, we can make a bigger combined feature PR: #576

[RobbieKiwi]

@RobbieKiwi if you prefer, we can make a bigger combined feature PR: #576

This PR looks good to me, but I can't approve PRs you need to check with the others