refactor(piecewise): per-tuple sign + categorized internal flow

doc/release_notes.rst

@@ -11,11 +11,11 @@ Upcoming Version
   - Comparison operators (``==``, ``<=``, ``>=``) fill missing RHS coords with NaN (no constraint created)
   - Fixes crash on ``subset + var`` / ``subset + expr`` reverse addition
   - Fixes superset DataArrays expanding result coords beyond the variable's coordinate space
-* Add ``add_piecewise_formulation()`` for piecewise linear equality constraints with SOS2, incremental, and disjunctive formulations: ``m.add_piecewise_formulation((power, x_pts), (fuel, y_pts))``.  Supports N-variable linking (e.g. CHP with fuel/power/heat) and per-entity breakpoints.  ``method="auto"`` picks the cheapest correct formulation automatically.  The API is newly added and emits an :class:`linopy.EvolvingAPIWarning` to signal that details (e.g. the ``sign``/first-tuple convention, ``active`` + non-equality sign semantics) may be refined in minor releases — feedback and use cases at https://github.com/PyPSA/linopy/issues shape what stabilises.  Silence with ``warnings.filterwarnings("ignore", category=linopy.EvolvingAPIWarning)``.
-* Add one-sided piecewise bounds via the ``sign`` parameter on ``add_piecewise_formulation``: ``sign="<="`` / ``">="`` applies the bound to the first tuple (first-tuple convention).  On convex/concave curves with a matching sign, ``method="auto"`` dispatches to a pure-LP chord formulation (``method="lp"``) with no auxiliary variables and automatic domain bounds on the input.  Mismatched curvature+sign is detected and falls back to SOS2/incremental with an explanatory info log.
+* Add ``add_piecewise_formulation()`` for piecewise linear constraints with SOS2, incremental, and disjunctive formulations: ``m.add_piecewise_formulation((power, x_pts), (fuel, y_pts))``.  Supports N-variable linking (e.g. CHP with fuel/power/heat) and per-entity breakpoints.  ``method="auto"`` picks the cheapest correct formulation automatically.  The API is newly added and emits an :class:`linopy.EvolvingAPIWarning` to signal that details (e.g. the per-tuple sign convention, ``active`` + non-equality sign semantics) may be refined in minor releases — feedback and use cases at https://github.com/PyPSA/linopy/issues shape what stabilises.  Silence with ``warnings.filterwarnings("ignore", category=linopy.EvolvingAPIWarning)``.
+* Add one-sided piecewise bounds via a per-tuple sign on ``add_piecewise_formulation``: append ``"<="`` or ``">="`` as a third tuple element — e.g. ``(fuel, y_pts, "<=")`` — to mark that expression as bounded by the curve while the others remain pinned.  At most one tuple may carry a non-equality sign; with 3 or more tuples all signs must be ``"=="``.  On convex/concave curves with a matching sign, ``method="auto"`` dispatches to a pure-LP chord formulation (``method="lp"``) with no auxiliary variables and automatic domain bounds on the input.  Mismatched curvature+sign is detected and falls back to SOS2/incremental with an explanatory info log.
 * Add unit-commitment gating via the ``active`` parameter on ``add_piecewise_formulation``: a binary variable that, when zero, forces all auxiliary variables (and thus the linked expressions) to zero.  Works with the SOS2, incremental, and disjunctive methods.
 * Surface formulation metadata on the returned ``PiecewiseFormulation``: ``.method`` (resolved method name) and ``.convexity`` (``"convex"`` / ``"concave"`` / ``"linear"`` / ``"mixed"`` when well-defined).  Both persist across netCDF round-trip.
-* Add ``tangent_lines()`` as a low-level helper that returns per-segment chord expressions as a ``LinearExpression`` — no variables created.  Most users should prefer ``add_piecewise_formulation(..., sign="<=")``, which builds on this helper and adds domain bounds and curvature validation.
+* Add ``tangent_lines()`` as a low-level helper that returns per-segment chord expressions as a ``LinearExpression`` — no variables created.  Most users should prefer ``add_piecewise_formulation`` with a bounded tuple ``(y, y_pts, "<=")``, which builds on this helper and adds domain bounds and curvature validation.
 * Add ``linopy.breakpoints()`` factory for convenient breakpoint construction from lists, Series, DataFrames, DataArrays, or dicts. Supports slopes mode.
 * Add ``linopy.segments()`` factory for disjunctive (disconnected) breakpoints.
 * Add ``slopes_to_points()`` utility for converting segment slopes to breakpoint y-coordinates.