feat: PiecewiseFormulation return type, model repr, rename to add_piecewise_formulation

[FBumann]

I thought a bit about user ergonomics after creation for the piecewise stuff. I would like to keep the improvements surgical and only for inspecting, not for storage or behaviour. I decided that adding some sort of filtering in __repr__ methods and a basic registry on Model is probably the most surgical solution. I also added a dataclass PiecewiseFormulation as a return time for the renamed add_piecewise_formulation(), which makes it more prominent whats actually happening: Adding a complex formulation, not a regular constraint!.

This allows the user to inspect the created variables and constraints through a higher level object/view. This also feels quite usable for other Formulation concepts, like the existing internal SOS-Reformulations or others to come. One issue i see is that we categorize variables/constraints into 2 levels - the user defined one and the one created internally through Formulations. I like the concept and dont think there is anything wrong with it, but i think its an important sidenote.

Happy to hear your thoughts on it!

Summary

• Add PiecewiseFormulation class as return type of add_piecewise_formulation() (renamed from add_piecewise_constraints)
• Groups all auxiliary variables and constraints; variables/constraints properties return live views
• Add _piecewise_formulations registry on Model with IO persistence (netcdf round-trip)
• Model repr hides piecewise artifacts and shows a dedicated "Piecewise Formulations" section
• Notebook updated to show reprs (last statement = add_piecewise_formulation)
• Export PiecewiseFormulation from linopy

PiecewiseFormulation repr:

PiecewiseFormulation `pwl` [time: 3, gen: 2] — incremental
  Variables:
    * pwl_delta (time, gen, _breakpoint_seg)
    * pwl_order_binary (time, gen, _breakpoint_seg)
  Constraints:
    * pwl_delta_bound (time, gen, _breakpoint_seg)
    * pwl_fill_order (time, gen, _breakpoint_seg)
    * pwl_binary_order (time, gen, _breakpoint_seg)
    * pwl_link (_breakpoint, _pwl_var, gen, time)

Model repr:

Variables:
 * power (gen, time)
 * fuel (gen, time)

Piecewise Formulations:
 * pwl (time, gen) — incremental, 2 vars, 4 cons

Access:

pwl = m.add_piecewise_formulation(
    (power, [0, 30, 60, 100]),
    (fuel,  [0, 36, 84, 170]),
)
pwl.variables            # Variables view
pwl.constraints          # Constraints view
pwl.variables['pwl_delta']  # individual Variable
pwl.method               # "incremental" or "sos2"

Suffix renames

Internal PWL suffix constants renamed for clarity:

Old	New	What it does
_x_link / _y_link	_link	expr = weighted sum (N-var, single constraint)
_binary	_segment_binary	disjunctive segment selection
_inc_binary	_order_binary	incremental fill-ordering binary
_inc_link	_delta_bound	δ ≤ binary
_inc_order	_binary_order	binary_{i+1} ≤ δ_i
_fill	_fill_order	δ_{i+1} ≤ δ_i

Unchanged: _lambda, _convex, _delta, _select, _active_bound

Test plan

• pytest test/test_piecewise_constraints.py — 108 passed
• pytest test/test_model.py — 18 passed
• mypy . --exclude build — clean
• ruff check — clean

🤖 Generated with Claude Code

[FBumann]

More thoughts about the Formulation concept

On the Formulation concept

A Formulation in linopy is a modeling-layer concept: it decomposes a high-level mathematical relationship into standard variables and constraints. The solver layer never sees the formulation — it only sees the flat collection of variables, constraints, and objectives it already knows how to handle.

This is intentional. Solvers don't speak "formulations" — they speak variables, constraints, bounds. Even Gurobi's addGenConstrPWL is just a convenience that internally creates the same underlying structures. By decomposing once at the modeling layer, every solver backend works automatically without per-solver formulation code.

It also means formulations are composable: piecewise with active=commit works because commit is just a regular variable. And formulations are inspectable: users can examine the generated constraints, modify bounds, or add extra constraints on top.

Key design point: Formulation classes are never constructed by the user. They are result views returned by model.add_*() methods. The user calls model.add_piecewise_formulation(...) and gets back a PiecewiseFormulation — a lightweight object holding names and a model reference. All the actual work (creating variables, constraints, registering in the model) happens inside the add_* method. The formulation object is purely for inspection and access.

This pattern could generalize naturally to other model.add_*() methods that create auxiliary variables + constraints from a higher-level intent: absolute value, min/max, indicator constraints, etc. The question for each would be whether the complexity justifies a named Formulation return type, or whether a simpler return suffices. Piecewise clearly earns it (5+ aux vars/cons per call). Something like abs(x) (1 var, 2 cons) might not.