linopy.model.Model.add_piecewise_formulation

linopy.model.Model.add_piecewise_formulation#

Model.add_piecewise_formulation(*pairs, sign='==', method='auto', active=None, name=None)#

Add piecewise linear constraints.

Each positional argument is a (expression, breakpoints) tuple. All expressions are linked through shared interpolation weights so that every operating point lies on the same segment of the piecewise curve.

Example — 2 variables:

m.add_piecewise_formulation(
    (power, [0, 30, 60, 100]),
    (fuel,  [0, 36, 84, 170]),
)

Example — 3 variables (CHP plant):

m.add_piecewise_formulation(
    (power, [0, 30, 60, 100]),
    (fuel,  [0, 40, 85, 160]),
    (heat,  [0, 25, 55, 95]),
)

Sign — inequality bounds:

The sign parameter follows the first-tuple convention:

  • sign="==" (default): all expressions must lie exactly on the piecewise curve (joint equality).

  • sign="<=": the first tuple’s expression is bounded above by its interpolated value; all other tuples are forced to equality (inputs on the curve). Reads as “first expression ≤ f(the rest)”.

  • sign=">=": same but the first is bounded below.

For 2-variable inequality on convex/concave curves, method="auto" automatically selects a pure-LP tangent-line formulation (no auxiliary variables). Non-convex curves fall back to SOS2/incremental with the sign applied to the first tuple’s link constraint.

Example — fuel ≤ f(power) on a concave curve:

m.add_piecewise_formulation(
    (fuel,  y_pts),    # bounded output, listed first
    (power, x_pts),    # input, always equality
    sign="<=",
)
Parameters:

  • *pairs (tuple of (expression, breakpoints)) – Each pair links an expression (Variable or LinearExpression) to its breakpoint values. At least two pairs are required. With sign != EQUAL the first pair is the bounded output; all later pairs are treated as inputs forced to equality.

  • sign ({"==", "<=", ">="}, default "==") – Constraint sign applied to the first tuple’s link constraint. Later tuples always use equality. See description above.

  • method ({"auto", "sos2", "incremental", "lp"}, default "auto") – Formulation method. "lp" uses tangent lines (pure LP, no variables) and requires sign != EQUAL plus a matching-convexity curve with exactly two tuples. "auto" picks "lp" when applicable, otherwise "incremental" (monotonic breakpoints) or "sos2".

  • active (Variable or LinearExpression, optional) – Binary variable that gates the piecewise function. When active=0, all auxiliary variables are forced to zero. Not supported with method="lp".

    With sign="==" (the default), the output is then pinned to 0. With sign="<=" / ">=", deactivation only pushes the signed bound to 0 (the output is ≤ 0 or ≥ 0 respectively) — the complementary bound still comes from the output variable’s own lower/upper. In the common case where the output is naturally non-negative (fuel, cost, heat, …), just set lower=0 on that variable: combined with the y ≤ 0 constraint from deactivation, this forces y = 0 automatically. For outputs that genuinely need both signs you must add the complementary bound yourself (e.g., a big-M coupling y with active).

  • name (str, optional) – Base name for generated variables/constraints.

Returns:

PiecewiseFormulation

Warns:

EvolvingAPIWarning – add_piecewise_formulation is a newly-added API; details such as the sign/first-tuple convention and active + non-equality sign semantics may be refined based on user feedback. Silence with warnings.filterwarnings("ignore", category=linopy.EvolvingAPIWarning).