refac(piecewise): introduce Slopes class, remove breakpoints(slopes=) mode

doc/api.rst

@@ -20,9 +20,9 @@ Creating a model
     model.Model.add_objective
     model.Model.add_piecewise_formulation
     piecewise.PiecewiseFormulation
+    piecewise.Slopes
     piecewise.breakpoints
     piecewise.segments
-    piecewise.slopes_to_points
     piecewise.tangent_lines
     model.Model.linexpr
     model.Model.remove_constraints

doc/piecewise-linear-constraints.rst

@@ -96,7 +96,9 @@ Two factories with distinct geometric meaning:
 
     linopy.breakpoints([0, 50, 100])  # connected
     linopy.breakpoints({"gen1": [0, 50], "gen2": [0, 80]}, dim="gen")  # per-entity
-    linopy.breakpoints(slopes=[1.2, 1.4], x_points=[0, 30, 60], y0=0)  # from slopes
+    linopy.Slopes(
+        [1.2, 1.4], y0=0
+    )  # from slopes (deferred — pairs with a sibling tuple)
     linopy.segments([(0, 10), (50, 100)])  # two disjoint regions
     linopy.segments({"gen1": [(0, 10)], "gen2": [(0, 80)]}, dim="gen")
 
@@ -240,21 +242,23 @@ Equivalent, but explicit about the DataArray construction:
 From slopes
 ~~~~~~~~~~~
 
-When you know marginal costs (slopes) rather than absolute values:
+When you know marginal costs (slopes) rather than absolute values, wrap
+them in :class:`linopy.Slopes`.  The x grid is borrowed from the sibling
+tuple — no need to repeat it:
 
 .. code-block:: python
 
     m.add_piecewise_formulation(
         (power, [0, 50, 100, 150]),
-        (
-            cost,
-            linopy.breakpoints(
-                slopes=[1.1, 1.5, 1.9], x_points=[0, 50, 100, 150], y0=0
-            ),
-        ),
+        (cost, linopy.Slopes([1.1, 1.5, 1.9], y0=0)),
     )
     # cost breakpoints: [0, 55, 130, 225]
 
+For standalone resolution outside of ``add_piecewise_formulation``, call
+:meth:`linopy.Slopes.to_breakpoints` with an explicit x grid::
+
+    bp = linopy.Slopes([1.1, 1.5, 1.9], y0=0).to_breakpoints([0, 50, 100, 150])
+
 Per-entity breakpoints
 ~~~~~~~~~~~~~~~~~~~~~~
 

doc/release_notes.rst

@@ -16,7 +16,8 @@ Upcoming Version
 * 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-piece 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()`` (lists/Series/DataFrame/DataArray/dict, plus a slopes-mode constructor), ``linopy.segments()`` (disjunctive operating regions), and ``slopes_to_points()`` (per-piece slopes → breakpoint y-coordinates) as breakpoint-construction helpers.
+* Add ``linopy.breakpoints()`` (lists/Series/DataFrame/DataArray/dict) and ``linopy.segments()`` (disjunctive operating regions) as breakpoint-construction helpers.
+* Add ``linopy.Slopes`` for specifying a piecewise curve by marginal costs / per-piece slopes instead of absolute y-values — ``(fuel, Slopes([1.2, 1.4, 1.7], y0=0))`` borrows the x grid from a sibling tuple in ``add_piecewise_formulation``.
 * Add the `sphinx-copybutton` to the documentation
 * Add SOS1 and SOS2 reformulations for solvers not supporting them.
 * Add semi-continous variables for solvers that support them

examples/piecewise-linear-constraints.ipynb

@@ -391,6 +391,36 @@
     "m.solve(reformulate_sos=\"auto\")\n",
     "m.solution[[\"power\", \"fuel\"]].to_dataframe()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. Specifying with slopes — `Slopes`\n",
+    "\n",
+    "When marginal costs (slopes) are more natural than absolute y-values, wrap them in `linopy.Slopes`. The x grid is borrowed from the sibling tuple — no need to repeat it. Same curve as section 1:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = linopy.Model()\n",
+    "power = m.add_variables(name=\"power\", lower=0, upper=100, coords=[time])\n",
+    "fuel = m.add_variables(name=\"fuel\", lower=0, coords=[time])\n",
+    "\n",
+    "m.add_piecewise_formulation(\n",
+    "    (power, [0, 30, 60, 100]),\n",
+    "    (fuel, linopy.Slopes([1.2, 1.6, 2.15], y0=0)),\n",
+    ")\n",
+    "m.add_constraints(power == demand, name=\"demand\")\n",
+    "m.add_objective(fuel.sum())\n",
+    "m.solve(reformulate_sos=\"auto\")\n",
+    "\n",
+    "m.solution[[\"power\", \"fuel\"]].to_pandas()"
+   ]
   }
  ],
  "metadata": {

linopy/__init__.py

@@ -27,9 +27,9 @@
 from linopy.objective import Objective
 from linopy.piecewise import (
     PiecewiseFormulation,
+    Slopes,
     breakpoints,
     segments,
-    slopes_to_points,
     tangent_lines,
 )
 from linopy.remote import RemoteHandler
@@ -53,6 +53,7 @@
     "PiecewiseFormulation",
     "QuadraticExpression",
     "RemoteHandler",
+    "Slopes",
     "Variable",
     "Variables",
     "align",
@@ -62,6 +63,5 @@
     "options",
     "read_netcdf",
     "segments",
-    "slopes_to_points",
     "tangent_lines",
 )