Piecewise linear constraints: follow-up improvements

[FabianHofmann]

Changes proposed in this Pull Request

Strongly needed follow-up improvements to the piecewise linear constraints feature:

• Introduce piecewise function to create a PiecewiseExpression which can be used in operations like y == piecewise(x, x_pts, y_pts)
• Make use case breakpoints and segments (new) clearer.
• Apply convexity checks where needed (LP formulation)
• Documentation: Expanded doc/piecewise-linear-constraints.rst and updated notebook

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.

[coroa]

I'd have liked to review this: I still have questions about the use of breakpoints for x and y or why they are used at all. I would prefer we remove add_piecewise_constraints and merge its code into add_constraints.

I don't understand the docs in regards to inequalities. They are slightly misleading, it's probably easiest to discuss once more

[FabianHofmann]

Hey @coroa, please do the review anyway. This will likely need another follow up. I mostly wanted to avoid the misleading state in the master branch and resolve that asap. and as it is a bit more sorted now, there is no need to pressure you on the review (I know that you are on a workshop this week).

[FBumann]

@FabianHofmann This PR improved the code quality pf the feature a lot i think.
But it also made some simplifications that are a real deal breaker for me. I think your intend with this follow up was to make the case of linking 2 variables via piecewise simpler, but this came at the cost of less universal usage and other potential issues.

1. The formulation now only allows to link exactly 2 variables. This is a fundamental limitation and will prevent users (including me) from using the api. I often need to link 1,2,3 or more variables (like a chp plant with fuel in, heat and power out = 3 vars with nonlinear efficiencies)
2. This API hides the complexity of piecewise constraints. the constraint is now captured as a new class/state and abstraction layer. This complicates inspection and interoperability with regular expressions and constraints. Also, this goes against the principle of exposing only variables and constraints. I would rather have a construction layer which convers everything into regular expressions/constraints instead of a State/object. Like we had in Feat/add piecewise linear #558

A bit more Insight with examples:

What changed

PR #602 replaced the old dict[str, LinExprLike] + link_dim API with a simpler piecewise(expr, x_points, y_points) function that only supports 2-variable relationships (y = f(x)).

What was lost

The old API could link 3+ variables through shared SOS2 lambda weights:

# OLD API
m.add_piecewise_constraints(
    expr={"x": x_var, "y": y_var, "z": z_var},
    breakpoints=bp,  # link_dim matched dict keys
)

This is no longer possible. The new API is strictly x → y:

# NEW API
m.add_piecewise_constraints(piecewise(x, x_pts, y_pts) == y)

Workarounds

1. Chain piecewise constraints

Works when the relationship decomposes (e.g. z = g(x) + h(y)). Use two separate piecewise() calls and sum the results. Only applicable for separable functions.

2. Manual lambda formulation (essentially constructing the piecewise function yourselves)

For true multi-variable linking, reproduce the SOS2 lambda formulation manually. All required operations (Variable * DataArray, .sum(), add_sos_constraints) are supported:

import numpy as np
import pandas as pd

bp_idx = pd.Index(np.arange(n_breakpoints), name="breakpoint")

lam = m.add_variables(lower=0, upper=1, coords=[bp_idx], name="lambda")
m.add_constraints(lam.sum("breakpoint") == 1)          # convexity
m.add_constraints(x == (lam * x_pts).sum("breakpoint")) # link x
m.add_constraints(y == (lam * y_pts).sum("breakpoint")) # link y
m.add_constraints(z == (lam * z_pts).sum("breakpoint")) # link z
m.add_sos_constraints(lam, sos_type=2, sos_dim="breakpoint")  # adjacency

Summary

The current state is not usable for me. I would really like to bring back the more generic #558 approach.
I would keep the distinction between segments/piecewise and think about adding a simple constructur method for your x-->y case

What do you think about this?
@FabianHofmann @coroa

[FabianHofmann]

@FBumann this makes totally sense and this use case was not on my radar at all, sorry for this. there were so many new aspects to think about. so let's bring it back. can we find a compromise that allows the piecewise function to be applied on 2+ variables? or do you think we should directly go for the dict approach?

[FBumann]

@FabianHofmann I'm not entirely sure we need to choose between the two approaches. If we go for a construction layer (no dedicated Piecewise class/state), there's no issue with supporting different use cases through method overloading or shared internal helpers.

The key architectural decision is: should piecewise constraints introduce new state (PiecewiseConstraintDescriptor) or should they be a pure construction layer that produces regular Variables, Constraints, and Expressions?

I'd argue strongly for the construction layer, for a few reasons:

1. API surface stays minimal. linopy's strength is that the entire API is just Model, Variables, Constraints, Expression. Adding PiecewiseExpression and PiecewiseConstraintDescriptor as user-facing types breaks this. Users now need to understand a new concept that doesn't exist in the optimization domain — it's an implementation artifact.

2. No loss of functionality. Everything the descriptor does can be done by a single add_piecewise_constraints() call that directly creates the auxiliary variables, SOS constraints, and linking constraints. The descriptor is a detour, not a necessity.

3. Multi-variable linking becomes natural. The current descriptor pattern is structurally tied to 2-variable x → y relationships. A construction function with a dict-based API (like pre-Piecewise linear constraints: follow-up improvements #602) supports N-variable linking without any contortion — CHP plants with fuel/power/heat are a first-class use case, not a workaround.

4. Interoperability. When piecewise constraints produce regular linopy objects, they compose with everything else — .dual, .to_matrix(), IO, inspection. A descriptor is opaque until it's expanded.

A single overloaded method could cover both the simple and the complex case:

# Simple 2-variable case
m.add_piecewise_constraints(power, fuel, x_pts, y_pts, sign="==")

# N-variable case (shared lambdas)
m.add_piecewise_constraints(
    exprs={"power": power, "fuel": fuel, "heat": heat},
    breakpoints=bp,
    sign="==",
)

Proposed first step: Agree that piecewise constraints should not introduce stored state (PiecewiseConstraintDescriptor, PiecewiseExpression). Once we align on that, we can list the use cases to cover and design the API signature together.