pulp-lparray 2.0.0__tar.gz

pulp_lparray-2.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.env
+.ipynb_checkpoints/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.worktrees/
+*.png
+*.npy
+tags

pulp_lparray-2.0.0/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2019-2026 Evgeny Naumov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pulp_lparray-2.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: pulp-lparray
+Version: 2.0.0
+Summary: PuLP x NumPy
+License-Expression: MIT-0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2
+Requires-Dist: pulp>=4
+Description-Content-Type: text/markdown
+
+# pulp-lparray
+
+*PuLP x NumPy, a match made in heaven.*
+
+An `lparray` is a NumPy array of [PuLP](https://github.com/coin-or/pulp) variables, affine
+expressions or constraints. Broadcasting, indexing, sums and matrix products build whole
+families of expressions at once; `<=`, `>=` and `==` build families of constraints; and a
+handful of methods linearise abs, max, min, argmax, top-k, logic and piecewise-linear functions.
+Never see a `for` or an index variable again.
+
+It needs Python 3.12+ and PuLP 4. PuLP 4 ships no solver: `pip install "pulp[cbc]"` adds CBC.
+
+## Super Sudoku
+
+A Super Sudoku is a Sudoku in which the cells at the same position within their boxes also hold
+distinct digits.
+
+```python
+import numpy as np
+from pulp import LpBinary, LpProblem
+
+from pulp_lparray import lparray
+
+clues = np.array(
+    [
+        [0, 4, 0, 0, 1, 8, 0, 0, 0],
+        [0, 5, 0, 0, 0, 2, 0, 0, 0],
+        [2, 0, 8, 0, 0, 0, 7, 1, 4],
+        [1, 8, 2, 0, 0, 0, 5, 6, 0],
+        [0, 6, 0, 0, 0, 0, 0, 0, 0],
+        [4, 7, 0, 0, 0, 6, 0, 0, 2],
+        [0, 0, 5, 0, 9, 7, 0, 0, 1],
+        [0, 0, 4, 0, 0, 0, 0, 0, 0],
+        [9, 0, 0, 0, 0, 0, 3, 0, 0],
+    ]
+)  # 0 marks an empty cell
+
+prob = LpProblem("super_sudoku")
+# board[R, C, r, c, n] == 1: the cell in row 3R + r and column 3C + c holds digit n + 1
+board = lparray.create(prob, "board", (3, 3, 3, 3, 9), cat=LpBinary)
+(board.sum(axis=4) == 1).constrain(prob, "cell")
+(board.sum(axis=(1, 3)) == 1).constrain(prob, "row")
+(board.sum(axis=(0, 2)) == 1).constrain(prob, "column")
+(board.sum(axis=(2, 3)) == 1).constrain(prob, "box")
+(board.sum(axis=(0, 1)) == 1).constrain(prob, "position")
+cells = board.transpose(0, 2, 1, 3, 4).reshape(9, 9, 9)  # row, column, digit
+row, col = clues.nonzero()
+(cells[row, col, clues[row, col] - 1] == 1).constrain(prob, "clue")
+prob.solve()
+
+grid = cells.values.argmax(axis=2) + 1
+assert (grid[row, col] == clues[row, col]).all()
+assert all(sorted(line) == list(range(1, 10)) for line in [*grid, *grid.T])
+```
+
+## Portfolio allocation
+
+Whole numbers of shares whose values best match target weights within a budget, measured by
+relative error so that every position counts alike. Minimising `deviation` subject to
+`deviation >= error` and `deviation >= -error` makes it `|error|` without binaries; `abs` is for
+magnitudes that the objective does not push down.
+
+```python
+from pulp import LpInteger, LpMinimize
+
+price = np.array([31.0, 77.0, 12.5, 220.0])
+weight = np.array([0.4, 0.3, 0.2, 0.1])
+funds = 10_000
+
+prob = LpProblem("allocation", LpMinimize)
+shares = lparray.create(prob, "shares", 4, lowBound=0, cat=LpInteger)
+(shares @ price <= funds).constrain(prob, "budget")
+target = funds * weight / price
+error = (shares - target) / target
+deviation = lparray.create(prob, "deviation", 4)
+(deviation >= error).constrain(prob, "over")
+(deviation >= -error).constrain(prob, "under")
+prob += deviation.sum().item()
+prob.solve()
+```
+
+## Facility logistics
+
+Open exactly two facilities per region, ship every product to every customer, and pay an
+operating cost with a volume discount on each facility's throughput. The discount makes the cost
+concave, so `lp_interp` selects its segment with binaries.
+
+```python
+region = np.array([0, 0, 0, 1, 1, 1])
+capacity = np.array([12, 6, 6, 12, 6, 6])
+open_cost = np.array([10, 5, 7, 10, 5, 7])
+ship_cost = np.array(
+    [
+        [2, 2, 3, 9, 9],
+        [3, 1, 2, 9, 9],
+        [2, 3, 1, 9, 9],
+        [9, 9, 9, 2, 2],
+        [9, 9, 9, 3, 1],
+        [9, 9, 9, 2, 3],
+    ]
+)  # facility × customer
+demand = np.array([[4, 2, 1], [0, 3, 2], [1, 1, 0], [3, 0, 1], [2, 2, 2]])  # customer × product
+
+prob = LpProblem("logistics", LpMinimize)
+is_open = lparray.create(prob, "open", 6, cat=LpBinary)
+flow = lparray.create(prob, "flow", (6, 5, 3), lowBound=0)
+(flow.sum(axis=0) == demand).constrain(prob, "demand")
+throughput = flow.sum(axis=(1, 2))
+(throughput <= capacity * is_open).constrain(prob, "capacity")
+((region == np.arange(2)[:, None]) @ is_open == 2).constrain(prob, "two_per_region")
+# The first 5 units cost 3 each, and the rest 2 each.
+operating = throughput.lp_interp(prob, "operating", xp=[0, 5, 12], fp=[0, 15, 29])
+prob += ((ship_cost[:, :, None] * flow).sum() + open_cost @ is_open + operating.sum()).item()
+prob.solve()
+
+assert (is_open.values.reshape(2, 3).sum(axis=1) == 2).all()
+```
+
+## Formulations
+
+Methods taking `(prob, name)` add auxiliary variables and constraints named `{name}_{role}`.
+
+| method | result |
+| --- | --- |
+| `x.abs(prob, name, bigM=…)` | `\|x\|` |
+| `x.abs_decompose(prob, name, bigM=…)` | `(p, m)`: `p - m == x`, `p, m >= 0`, one of them zero |
+| `x.logical_clip(prob, name, bigM=…)` | binary `min(x, 1)` of integral `x >= 0` |
+| `x.lp_max(prob, name, axis=…, bigM=…)`, `lp_min` | maximum, minimum along `axis` |
+| `x.lp_argmax(prob, name, axis=…, bigM=…)`, `lp_argmin` | one-hot indicator of an extremum along `axis` |
+| `x.lp_topk(prob, name, k=…, axis=…, bigM=…)` | indicator of `k` largest entries along `axis` |
+| `b.lp_bin_max(prob, name, axis=…)`, `lp_bin_min` | logical OR, AND of binary `b` along `axis` |
+| `z.lp_bin_and(prob, name, *bs)`, `lp_bin_or` | constrains binary `z` to the AND, OR of `bs` |
+| `x.lp_interp(prob, name, xp=…, fp=…)` | `np.interp(x, xp, fp)`, breakpoints broadcasting against `x` |
+
+`bigM` must bound the spread of the values involved: `|x|` for `abs`, `x` for `logical_clip`,
+and the range along `axis` for the rest. Too small a `bigM` silently cuts off solutions.
+`lp_interp` constrains `x` to lie between the first and last breakpoints rather than clamping it.
+
+## Semantics
+
+`constrain(prob, name)` adds each constraint as `name(i,j,…)` and returns the array of
+`LpConstraint`s that the problem stores.
+
+Sums, `@` and `dot` take time linear in the contracted length. Other contractions, such as
+`np.einsum` and `np.inner`, run NumPy's object loops, which chain PuLP's `+` and take quadratic
+time. Reductions return 0-d lparrays, whose `item()` is the PuLP expression. Ufuncs that are not
+affine, such as `np.maximum` and `np.abs`, raise `TypeError`; the methods above linearise them.
+
+Keep the lparray on the left of `+` and `-` against a single PuLP variable or expression:
+PuLP treats an array on its right as an iterable and sums it into one expression.
+
+## Upgrading from 1.x
+
+| 1.x | 2.0 |
+| --- | --- |
+| `lparray.create(name, index_sets)`, `create_anon(name, shape)`, `create_like(name, a)` | `lparray.create(prob, name, shape)` |
+| `x.sumit()` | `x.sum().item()` |
+| `lp_int_max`, `lp_real_max`, `lp_int_min`, `lp_real_min` | `lp_max`, `lp_min` |
+| `lp_bin_argmax`, `lp_bin_argmin`, `lp_bin_topk` | `lp_argmax`, `lp_argmin`, `lp_topk` |
+| `piecewise_linear_sos2` | `lp_interp` |
+| `abs_clip` | `abs` |
+| `one_hot`, `constrain_one_hot`, `all_different`, `indicator_le`, `indicator_ge` | the sum or comparison each wrapped |
+| `soft_select_max`, `count_out` | removed |
+
+Every `bigM` is required, and `constrain` returns the stored constraints.

pulp_lparray-2.0.0/README.md

@@ -0,0 +1,165 @@
+# pulp-lparray
+
+*PuLP x NumPy, a match made in heaven.*
+
+An `lparray` is a NumPy array of [PuLP](https://github.com/coin-or/pulp) variables, affine
+expressions or constraints. Broadcasting, indexing, sums and matrix products build whole
+families of expressions at once; `<=`, `>=` and `==` build families of constraints; and a
+handful of methods linearise abs, max, min, argmax, top-k, logic and piecewise-linear functions.
+Never see a `for` or an index variable again.
+
+It needs Python 3.12+ and PuLP 4. PuLP 4 ships no solver: `pip install "pulp[cbc]"` adds CBC.
+
+## Super Sudoku
+
+A Super Sudoku is a Sudoku in which the cells at the same position within their boxes also hold
+distinct digits.
+
+```python
+import numpy as np
+from pulp import LpBinary, LpProblem
+
+from pulp_lparray import lparray
+
+clues = np.array(
+    [
+        [0, 4, 0, 0, 1, 8, 0, 0, 0],
+        [0, 5, 0, 0, 0, 2, 0, 0, 0],
+        [2, 0, 8, 0, 0, 0, 7, 1, 4],
+        [1, 8, 2, 0, 0, 0, 5, 6, 0],
+        [0, 6, 0, 0, 0, 0, 0, 0, 0],
+        [4, 7, 0, 0, 0, 6, 0, 0, 2],
+        [0, 0, 5, 0, 9, 7, 0, 0, 1],
+        [0, 0, 4, 0, 0, 0, 0, 0, 0],
+        [9, 0, 0, 0, 0, 0, 3, 0, 0],
+    ]
+)  # 0 marks an empty cell
+
+prob = LpProblem("super_sudoku")
+# board[R, C, r, c, n] == 1: the cell in row 3R + r and column 3C + c holds digit n + 1
+board = lparray.create(prob, "board", (3, 3, 3, 3, 9), cat=LpBinary)
+(board.sum(axis=4) == 1).constrain(prob, "cell")
+(board.sum(axis=(1, 3)) == 1).constrain(prob, "row")
+(board.sum(axis=(0, 2)) == 1).constrain(prob, "column")
+(board.sum(axis=(2, 3)) == 1).constrain(prob, "box")
+(board.sum(axis=(0, 1)) == 1).constrain(prob, "position")
+cells = board.transpose(0, 2, 1, 3, 4).reshape(9, 9, 9)  # row, column, digit
+row, col = clues.nonzero()
+(cells[row, col, clues[row, col] - 1] == 1).constrain(prob, "clue")
+prob.solve()
+
+grid = cells.values.argmax(axis=2) + 1
+assert (grid[row, col] == clues[row, col]).all()
+assert all(sorted(line) == list(range(1, 10)) for line in [*grid, *grid.T])
+```
+
+## Portfolio allocation
+
+Whole numbers of shares whose values best match target weights within a budget, measured by
+relative error so that every position counts alike. Minimising `deviation` subject to
+`deviation >= error` and `deviation >= -error` makes it `|error|` without binaries; `abs` is for
+magnitudes that the objective does not push down.
+
+```python
+from pulp import LpInteger, LpMinimize
+
+price = np.array([31.0, 77.0, 12.5, 220.0])
+weight = np.array([0.4, 0.3, 0.2, 0.1])
+funds = 10_000
+
+prob = LpProblem("allocation", LpMinimize)
+shares = lparray.create(prob, "shares", 4, lowBound=0, cat=LpInteger)
+(shares @ price <= funds).constrain(prob, "budget")
+target = funds * weight / price
+error = (shares - target) / target
+deviation = lparray.create(prob, "deviation", 4)
+(deviation >= error).constrain(prob, "over")
+(deviation >= -error).constrain(prob, "under")
+prob += deviation.sum().item()
+prob.solve()
+```
+
+## Facility logistics
+
+Open exactly two facilities per region, ship every product to every customer, and pay an
+operating cost with a volume discount on each facility's throughput. The discount makes the cost
+concave, so `lp_interp` selects its segment with binaries.
+
+```python
+region = np.array([0, 0, 0, 1, 1, 1])
+capacity = np.array([12, 6, 6, 12, 6, 6])
+open_cost = np.array([10, 5, 7, 10, 5, 7])
+ship_cost = np.array(
+    [
+        [2, 2, 3, 9, 9],
+        [3, 1, 2, 9, 9],
+        [2, 3, 1, 9, 9],
+        [9, 9, 9, 2, 2],
+        [9, 9, 9, 3, 1],
+        [9, 9, 9, 2, 3],
+    ]
+)  # facility × customer
+demand = np.array([[4, 2, 1], [0, 3, 2], [1, 1, 0], [3, 0, 1], [2, 2, 2]])  # customer × product
+
+prob = LpProblem("logistics", LpMinimize)
+is_open = lparray.create(prob, "open", 6, cat=LpBinary)
+flow = lparray.create(prob, "flow", (6, 5, 3), lowBound=0)
+(flow.sum(axis=0) == demand).constrain(prob, "demand")
+throughput = flow.sum(axis=(1, 2))
+(throughput <= capacity * is_open).constrain(prob, "capacity")
+((region == np.arange(2)[:, None]) @ is_open == 2).constrain(prob, "two_per_region")
+# The first 5 units cost 3 each, and the rest 2 each.
+operating = throughput.lp_interp(prob, "operating", xp=[0, 5, 12], fp=[0, 15, 29])
+prob += ((ship_cost[:, :, None] * flow).sum() + open_cost @ is_open + operating.sum()).item()
+prob.solve()
+
+assert (is_open.values.reshape(2, 3).sum(axis=1) == 2).all()
+```
+
+## Formulations
+
+Methods taking `(prob, name)` add auxiliary variables and constraints named `{name}_{role}`.
+
+| method | result |
+| --- | --- |
+| `x.abs(prob, name, bigM=…)` | `\|x\|` |
+| `x.abs_decompose(prob, name, bigM=…)` | `(p, m)`: `p - m == x`, `p, m >= 0`, one of them zero |
+| `x.logical_clip(prob, name, bigM=…)` | binary `min(x, 1)` of integral `x >= 0` |
+| `x.lp_max(prob, name, axis=…, bigM=…)`, `lp_min` | maximum, minimum along `axis` |
+| `x.lp_argmax(prob, name, axis=…, bigM=…)`, `lp_argmin` | one-hot indicator of an extremum along `axis` |
+| `x.lp_topk(prob, name, k=…, axis=…, bigM=…)` | indicator of `k` largest entries along `axis` |
+| `b.lp_bin_max(prob, name, axis=…)`, `lp_bin_min` | logical OR, AND of binary `b` along `axis` |
+| `z.lp_bin_and(prob, name, *bs)`, `lp_bin_or` | constrains binary `z` to the AND, OR of `bs` |
+| `x.lp_interp(prob, name, xp=…, fp=…)` | `np.interp(x, xp, fp)`, breakpoints broadcasting against `x` |
+
+`bigM` must bound the spread of the values involved: `|x|` for `abs`, `x` for `logical_clip`,
+and the range along `axis` for the rest. Too small a `bigM` silently cuts off solutions.
+`lp_interp` constrains `x` to lie between the first and last breakpoints rather than clamping it.
+
+## Semantics
+
+`constrain(prob, name)` adds each constraint as `name(i,j,…)` and returns the array of
+`LpConstraint`s that the problem stores.
+
+Sums, `@` and `dot` take time linear in the contracted length. Other contractions, such as
+`np.einsum` and `np.inner`, run NumPy's object loops, which chain PuLP's `+` and take quadratic
+time. Reductions return 0-d lparrays, whose `item()` is the PuLP expression. Ufuncs that are not
+affine, such as `np.maximum` and `np.abs`, raise `TypeError`; the methods above linearise them.
+
+Keep the lparray on the left of `+` and `-` against a single PuLP variable or expression:
+PuLP treats an array on its right as an iterable and sums it into one expression.
+
+## Upgrading from 1.x
+
+| 1.x | 2.0 |
+| --- | --- |
+| `lparray.create(name, index_sets)`, `create_anon(name, shape)`, `create_like(name, a)` | `lparray.create(prob, name, shape)` |
+| `x.sumit()` | `x.sum().item()` |
+| `lp_int_max`, `lp_real_max`, `lp_int_min`, `lp_real_min` | `lp_max`, `lp_min` |
+| `lp_bin_argmax`, `lp_bin_argmin`, `lp_bin_topk` | `lp_argmax`, `lp_argmin`, `lp_topk` |
+| `piecewise_linear_sos2` | `lp_interp` |
+| `abs_clip` | `abs` |
+| `one_hot`, `constrain_one_hot`, `all_different`, `indicator_le`, `indicator_ge` | the sum or comparison each wrapped |
+| `soft_select_max`, `count_out` | removed |
+
+Every `bigM` is required, and `constrain` returns the stored constraints.

pulp_lparray-2.0.0/pulp_lparray/__init__.py

@@ -0,0 +1,3 @@
+from .lparray import lparray
+
+__all__ = ["lparray"]

pulp_lparray-2.0.0/pulp_lparray/lparray.py

@@ -0,0 +1,373 @@
+"""NumPy arrays of PuLP variables, affine expressions and constraints."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any, Literal, Self
+
+import numpy as np
+from numpy.lib.array_utils import normalize_axis_tuple
+from pulp import (
+    LpAffineExpression,
+    LpBinary,
+    LpConstraint,
+    LpProblem,
+    LpVariable,
+    lpSum,
+    value,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Mapping
+
+    from numpy.typing import ArrayLike, NDArray
+
+type Category = Literal["Continuous", "Integer", "Binary"]
+type Axis = int | tuple[int, ...] | None
+
+
+class lparray(np.ndarray[tuple[int, ...], np.dtype[np.object_]]):
+    """An object ndarray of PuLP variables, affine expressions or constraints.
+
+    Arithmetic, indexing and broadcasting are NumPy's, applied elementwise, and NumPy functions
+    return lparrays; ufuncs that are not affine raise TypeError. `<=`, `>=` and `==` build arrays
+    of constraints, which `constrain` adds to a problem. Sums, ``@ and `dot` take time linear in
+    the contracted length. Reductions return 0-d lparrays, whose `item()` is the PuLP scalar.
+
+    Methods taking `(prob, name)` linearise nonlinear operations with auxiliary variables and
+    constraints named `{name}_{role}`. Those taking `bigM` require it to bound the spread of the
+    values involved; too small a bigM silently cuts off feasible solutions.
+
+    Keep the lparray on the left of `+` and `-` against a scalar PuLP operand: PuLP treats a
+    right-hand array as an iterable and sums it into a single expression.
+    """
+
+    __hash__ = None
+
+    # PuLP 4 scalars set __array_priority__ = 20, so a lower priority makes ndarray operators
+    # defer to the scalar's reflected method, which sums the whole array into one expression.
+    __array_priority__ = math.inf
+
+    if TYPE_CHECKING:
+        # NumPy's stubs type these as plain or boolean ndarrays; __array_ufunc__ returns lparrays.
+        def __getitem__(self, key: object, /) -> Any: ...  # noqa: ANN401
+        def __neg__(self) -> lparray: ...
+        def __add__(self, other: object, /) -> lparray: ...
+        def __radd__(self, other: ArrayLike, /) -> lparray: ...
+        def __sub__(self, other: object, /) -> lparray: ...
+        def __rsub__(self, other: ArrayLike, /) -> lparray: ...
+        def __mul__(self, other: object, /) -> lparray: ...
+        def __rmul__(self, other: ArrayLike, /) -> lparray: ...
+        def __truediv__(self, other: object, /) -> lparray: ...
+        def __matmul__(self, other: object, /) -> lparray: ...
+        def __rmatmul__(self, other: ArrayLike, /) -> lparray: ...
+        # Deliberately incompatible: comparisons build constraints, and the rest keep the subclass.
+        def __le__(self, other: object, /) -> lparray: ...  # ty: ignore[invalid-method-override]
+        def __ge__(self, other: object, /) -> lparray: ...  # ty: ignore[invalid-method-override]
+        def __eq__(self, other: object, /) -> lparray: ...  # ty: ignore[invalid-method-override]
+        def sum(self, axis: Axis = None, *, keepdims: bool = False) -> lparray: ...  # ty: ignore[invalid-method-override]
+        def reshape(self, *shape: Any, **kwargs: Any) -> lparray: ...  # ty: ignore[invalid-method-override]
+        def ravel(self, order: Literal["K", "A", "C", "F"] = "C") -> lparray: ...  # ty: ignore[invalid-method-override]
+        def flatten(self, order: Literal["K", "A", "C", "F"] = "C") -> lparray: ...  # ty: ignore[invalid-method-override]
+        def squeeze(self, axis: Axis = None) -> lparray: ...  # ty: ignore[invalid-method-override]
+
+    @classmethod
+    def create(
+        cls,
+        prob: LpProblem,
+        name: str,
+        shape: int | tuple[int, ...],
+        *,
+        lowBound: float | None = None,
+        upBound: float | None = None,
+        cat: Category = "Continuous",
+    ) -> Self:
+        """Variables of `prob` named `name(i,j,…)` by their indices."""
+        arr = np.empty(shape, dtype=object)
+        for ix in np.ndindex(arr.shape):
+            arr[ix] = prob.add_variable(_subscript(name, ix), lowBound, upBound, cat)
+        return arr.view(cls)
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs: Any, **kwargs: Any) -> object:
+        args = [x.view(np.ndarray) if isinstance(x, lparray) else _shield(x) for x in inputs]
+        if out := kwargs.get("out"):
+            kwargs["out"] = tuple(o.view(np.ndarray) for o in out)
+        match ufunc, method:
+            case np.add, "reduce":
+                result = _lpsum(*args, **kwargs)
+            case np.matmul, "__call__":
+                result = _matmul(*args, **kwargs)
+            case np.less_equal | np.greater_equal | np.equal, "__call__":
+                # PuLP 4 compares two variables by identity, yielding a bool. A difference is
+                # always an expression, and comparing an expression with 0 is a constraint.
+                difference = _shield(np.subtract(*args, dtype=object))
+                result = ufunc(difference, 0, **kwargs | {"dtype": object})
+            case np.add | np.subtract | np.multiply | np.true_divide | np.negative | np.positive, _:
+                result = getattr(ufunc, method)(*args, **kwargs)
+            case _:
+                raise TypeError(
+                    f"lparray supports affine ufuncs, <=, >= and ==, not np.{ufunc.__name__}."
+                    f"{method}; lp_max, lp_min and abs linearise extrema and magnitudes"
+                )
+        if out:
+            return out[0] if len(out) == 1 else out
+        return _wrap(result)
+
+    def __array_function__(
+        self,
+        func: Callable[..., Any],
+        types: Iterable[type],
+        args: Iterable[Any],
+        kwargs: Mapping[str, Any],
+    ) -> object:
+        args = tuple(map(_shield, args))
+        kwargs = {key: _shield(arg) for key, arg in kwargs.items()}
+        if func is np.dot:
+            return _wrap(_dot(*args, **kwargs))
+        return _wrap(super().__array_function__(func, types, args, kwargs))
+
+    def dot(self, b: ArrayLike, /) -> lparray:  # ty: ignore[invalid-method-override]
+        """`np.dot(self, b)`, which ndarray.dot would compute without dispatching to lparray."""
+        return np.dot(self, b)
+
+    if not TYPE_CHECKING:  # NumPy's stubs type assignment as it is
+
+        def __setitem__(self, key: object, value: object, /) -> None:
+            super().__setitem__(key, _shield(value))
+
+    @property
+    def values(self) -> NDArray[np.float64]:
+        """The solved value of each element."""
+        return np.fromiter(map(value, self.flat), np.float64, self.size).reshape(self.shape)
+
+    def constrain(self, prob: LpProblem, name: str) -> lparray:
+        """Add each constraint to `prob` as `name(i,j,…)`; return the stored constraints."""
+        stored = np.empty(self.shape, dtype=object)
+        for ix in np.ndindex(self.shape):
+            if not isinstance(c := self[ix], LpAffineExpression):
+                raise TypeError(f"{_subscript(name, ix)}: {c!r} is not a constraint")
+            stored[ix] = prob.addConstraint(c, _subscript(name, ix))
+        return stored.view(lparray)
+
+    def abs_decompose(self, prob: LpProblem, name: str, *, bigM: float) -> tuple[lparray, lparray]:
+        """The positive and negative parts `(p, m)` of self: `p - m == self`, `p, m >= 0`,
+        and at most one of them nonzero. Requires `|self| <= bigM`."""
+        neg = lparray.create(prob, f"{name}_neg", self.shape, cat=LpBinary)
+        p = lparray.create(prob, f"{name}_p", self.shape, lowBound=0)
+        m = lparray.create(prob, f"{name}_m", self.shape, lowBound=0)
+        (p - m == self).constrain(prob, f"{name}_split")
+        (p <= bigM * (1 - neg)).constrain(prob, f"{name}_p_off")
+        (m <= bigM * neg).constrain(prob, f"{name}_m_off")
+        return p, m
+
+    def abs(self, prob: LpProblem, name: str, *, bigM: float) -> lparray:
+        """`|self|`; requires `|self| <= bigM`."""
+        p, m = self.abs_decompose(prob, name, bigM=bigM)
+        return p + m
+
+    def logical_clip(self, prob: LpProblem, name: str, *, bigM: float) -> lparray:
+        """Binary `min(self, 1)` of integral `0 <= self <= bigM`."""
+        z = lparray.create(prob, f"{name}_z", self.shape, cat=LpBinary)
+        (self >= z).constrain(prob, f"{name}_lb")
+        (self <= bigM * z).constrain(prob, f"{name}_ub")
+        return z
+
+    def lp_max(self, prob: LpProblem, name: str, *, axis: Axis = None, bigM: float) -> lparray:
+        """Maximum along `axis`; requires the spread of self along it to be at most bigM."""
+        return self._extremum(prob, name, axis, bigM, 1)[0]
+
+    def lp_min(self, prob: LpProblem, name: str, *, axis: Axis = None, bigM: float) -> lparray:
+        """Minimum along `axis`; requires the spread of self along it to be at most bigM."""
+        return self._extremum(prob, name, axis, bigM, -1)[0]
+
+    def lp_argmax(self, prob: LpProblem, name: str, *, axis: Axis = None, bigM: float) -> lparray:
+        """Binary indicator, one-hot along `axis`, of an entry attaining the maximum."""
+        return self._extremum(prob, name, axis, bigM, 1)[1]
+
+    def lp_argmin(self, prob: LpProblem, name: str, *, axis: Axis = None, bigM: float) -> lparray:
+        """Binary indicator, one-hot along `axis`, of an entry attaining the minimum."""
+        return self._extremum(prob, name, axis, bigM, -1)[1]
+
+    def lp_bin_max(self, prob: LpProblem, name: str, *, axis: Axis = None) -> lparray:
+        """Logical OR of binary self along `axis`."""
+        axes, kept = self._reduction(axis)
+        z = lparray.create(prob, f"{name}_z", kept, lowBound=0, upBound=1)
+        _all(prob, name, 1 - z, 1 - self, axes)
+        return z
+
+    def lp_bin_min(self, prob: LpProblem, name: str, *, axis: Axis = None) -> lparray:
+        """Logical AND of binary self along `axis`."""
+        axes, kept = self._reduction(axis)
+        z = lparray.create(prob, f"{name}_z", kept, lowBound=0, upBound=1)
+        _all(prob, name, z, self, axes)
+        return z
+
+    def lp_bin_and(self, prob: LpProblem, name: str, *ins: ArrayLike) -> Self:
+        """Constrain binary self to the elementwise logical AND of `ins`; return self."""
+        _all(prob, name, self, _stacked(ins, self.shape), (0,))
+        return self
+
+    def lp_bin_or(self, prob: LpProblem, name: str, *ins: ArrayLike) -> Self:
+        """Constrain binary self to the elementwise logical OR of `ins`; return self."""
+        _all(prob, name, 1 - self, 1 - _stacked(ins, self.shape), (0,))
+        return self
+
+    def lp_topk(
+        self, prob: LpProblem, name: str, *, k: int, axis: Axis = None, bigM: float
+    ) -> lparray:
+        """Binary indicator of `k` entries along `axis`, none smaller than an unselected one."""
+        axes, kept = self._reduction(axis)
+        if not 0 <= k <= math.prod(self.shape[d] for d in axes):
+            raise ValueError(f"{name}: cannot select {k} of {self.shape} along {axes}")
+        threshold = lparray.create(prob, f"{name}_t", kept)
+        w = lparray.create(prob, f"{name}_w", self.shape, cat=LpBinary)
+        (w.sum(axis=axes) == k).constrain(prob, f"{name}_k")
+        gap = self - _expand(threshold, axes)
+        (gap >= -bigM * (1 - w)).constrain(prob, f"{name}_in")
+        (gap <= bigM * w).constrain(prob, f"{name}_out")
+        return w
+
+    def lp_interp(self, prob: LpProblem, name: str, *, xp: ArrayLike, fp: ArrayLike) -> lparray:
+        """`np.interp(self, xp, fp)`, constraining self to `[xp[..., 0], xp[..., -1]]`.
+
+        The breakpoints `xp` and values `fp` lie along their last axis; their leading axes
+        broadcast against self."""
+        xs, fs = np.broadcast_arrays(np.asarray(xp, dtype=float), np.asarray(fp, dtype=float))
+        if xs.ndim == 0 or xs.shape[-1] < 2 or np.any(np.diff(xs) <= 0):
+            raise ValueError("xp must increase strictly along its last axis, of length >= 2")
+        shape = np.broadcast_shapes(self.shape, xs.shape[:-1])
+        weight = lparray.create(prob, f"{name}_weight", (*shape, xs.shape[-1]), lowBound=0)
+        segment = lparray.create(prob, f"{name}_segment", (*shape, xs.shape[-1] - 1), cat=LpBinary)
+        (weight.sum(axis=-1) == 1).constrain(prob, f"{name}_weight_sum")
+        (segment.sum(axis=-1) == 1).constrain(prob, f"{name}_segment_sum")
+        # A weight may be positive only beside the chosen segment: SOS2 adjacency.
+        edge = np.zeros((*shape, 1), dtype=object)
+        flanks = np.concatenate([edge, segment, edge], axis=-1)
+        (weight <= flanks[..., :-1] + flanks[..., 1:]).constrain(prob, f"{name}_adjacent")
+        (self == (weight * xs).sum(axis=-1)).constrain(prob, f"{name}_x")
+        return (weight * fs).sum(axis=-1)
+
+    def _extremum(
+        self, prob: LpProblem, name: str, axis: Axis, bigM: float, sign: Literal[1, -1]
+    ) -> tuple[lparray, lparray]:
+        """`(t, w)`: `sign·t = max(sign·self)` along `axis`, `w` one-hot where attained."""
+        axes, kept = self._reduction(axis)
+        if not math.prod(self.shape[d] for d in axes):
+            raise ValueError(f"no extremum of an empty slice of {self.shape} along {axes}")
+        t = lparray.create(prob, f"{name}_t", kept)
+        w = lparray.create(prob, f"{name}_w", self.shape, cat=LpBinary)
+        (w.sum(axis=axes) == 1).constrain(prob, f"{name}_one")
+        gap = sign * (_expand(t, axes) - self)
+        (gap >= 0).constrain(prob, f"{name}_bound")
+        (gap <= bigM * (1 - w)).constrain(prob, f"{name}_attain")
+        return t, w
+
+    def _reduction(self, axis: Axis) -> tuple[tuple[int, ...], tuple[int, ...]]:
+        """The axes reduced over and the shape left."""
+        axes = normalize_axis_tuple(range(self.ndim) if axis is None else axis, self.ndim)
+        return axes, tuple(n for d, n in enumerate(self.shape) if d not in axes)
+
+
+def _subscript(name: str, ix: tuple[int, ...]) -> str:
+    return f"{name}({','.join(map(str, ix))})" if ix else name
+
+
+def _box(x: object) -> NDArray[np.object_]:
+    box = np.empty((), dtype=object)
+    box[()] = x
+    return box
+
+
+def _shield[T](x: T) -> T | NDArray[np.object_]:
+    """Box a PuLP 4 expression or constraint in a 0-d array, and those within lists and tuples:
+    both define __len__ and __getitem__, so NumPy would read one as the sequence of its
+    variables."""
+    match x:
+        case LpAffineExpression() | LpConstraint():
+            return _box(x)
+        case list() | tuple() if type(x) in (list, tuple):
+            return type(x)(map(_shield, x))
+        case _:
+            return x
+
+
+def _wrap(x: object) -> object:
+    """View the object ndarrays among a NumPy result as lparrays, and box the PuLP scalars that
+    NumPy returns for 0-d results into 0-d lparrays."""
+    match x:
+        case np.ndarray(dtype=np.object_):
+            return x.view(lparray)
+        case LpAffineExpression() | LpVariable() | LpConstraint():
+            return _box(x).view(lparray)
+        case tuple():
+            return tuple(map(_wrap, x))
+        case list():
+            return list(map(_wrap, x))
+        case _:
+            return x
+
+
+def _lpsum(
+    a: NDArray[np.object_],
+    *,
+    axis: Axis = 0,
+    dtype: object = None,
+    keepdims: bool = False,
+    where: object = True,
+) -> NDArray[np.object_]:
+    """`np.add.reduce` through `lpSum`. NumPy's object reduction chains `+`, and each PuLP `+`
+    copies its left operand, so it takes time quadratic in the length reduced."""
+    if dtype not in (None, object) or where is not True:
+        raise TypeError("lparray sums take only axis and keepdims")
+    if a.ndim == 0 and axis in (0, -1):
+        axis = ()  # NumPy reduces a 0-d array along axis 0 to itself
+    axes = normalize_axis_tuple(range(a.ndim) if axis is None else axis, a.ndim)
+    kept = [d for d in range(a.ndim) if d not in axes]
+    rows = a.transpose(*kept, *axes).reshape(
+        *(a.shape[d] for d in kept), math.prod(a.shape[d] for d in axes)
+    )
+    out = np.empty(rows.shape[:-1], dtype=object)
+    for ix in np.ndindex(out.shape):
+        out[ix] = lpSum(rows[ix])
+    return np.expand_dims(out, axes) if keepdims else out
+
+
+def _matmul(a: ArrayLike, b: ArrayLike) -> NDArray[np.object_]:
+    """`a @ b` as a sum of broadcast products, in time linear in the contracted length."""
+    lhs, rhs = np.asarray(a, dtype=object), np.asarray(b, dtype=object)
+    if not lhs.ndim or not rhs.ndim or lhs.shape[-1] != rhs.shape[-2 if rhs.ndim > 1 else 0]:
+        raise ValueError(f"matmul cannot contract {lhs.shape} with {rhs.shape}")
+    products = (lhs[None] if lhs.ndim == 1 else lhs)[..., :, :, None] * (
+        rhs[:, None] if rhs.ndim == 1 else rhs
+    )[..., None, :, :]
+    promoted = (-2,) * (lhs.ndim == 1) + (-1,) * (rhs.ndim == 1)
+    return _lpsum(products, axis=-2).squeeze(axis=promoted)
+
+
+def _dot(a: ArrayLike, b: ArrayLike) -> object:
+    """`np.dot(a, b)` through `_matmul`, which agrees with it when b has at most two axes."""
+    lhs, rhs = np.asarray(a, dtype=object), np.asarray(b, dtype=object)
+    if not lhs.ndim or not rhs.ndim:
+        return np.multiply(lhs, rhs)
+    if rhs.ndim <= 2:
+        return _matmul(lhs, rhs)
+    # dot contracts the last axis of a with the second-to-last of b; b's other axes follow a's.
+    flat = np.moveaxis(rhs, -2, 0).reshape(rhs.shape[-2], -1)
+    return _matmul(lhs, flat).reshape(*lhs.shape[:-1], *rhs.shape[:-2], rhs.shape[-1])
+
+
+def _expand(t: lparray, axes: tuple[int, ...]) -> lparray:
+    """A reduction's result with unit axes restored, to broadcast against its operand."""
+    return np.expand_dims(t, axes).view(lparray)
+
+
+def _stacked(ins: tuple[ArrayLike, ...], shape: tuple[int, ...]) -> NDArray[Any]:
+    """`ins` broadcast to `shape` and stacked along a new first axis."""
+    return np.stack([np.broadcast_to(_shield(x), shape, subok=True) for x in ins])
+
+
+def _all(prob: LpProblem, name: str, z: lparray, x: NDArray[Any], axes: tuple[int, ...]) -> None:
+    """Constrain `0 <= z <= 1` to the logical AND of binary `x` along `axes`."""
+    n = math.prod(x.shape[d] for d in axes)
+    (_expand(z, axes) <= x).constrain(prob, f"{name}_each")
+    (z >= x.sum(axis=axes) - (n - 1)).constrain(prob, f"{name}_sum")

pulp_lparray-2.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pulp-lparray"
+version = "2.0.0"
+description = "PuLP x NumPy"
+readme = "README.md"
+license = "MIT-0"
+requires-python = ">=3.12"
+dependencies = [
+  "numpy>=2",
+  "pulp>=4",
+]
+
+[dependency-groups]
+dev = [
+  "pulp[cbc]",
+  "pytest",
+  "ruff",
+  "ty",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib --strict-config --strict-markers"
+filterwarnings = ["error"]
+
+[tool.hatch.build]
+include = ["pulp_lparray"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "D",      # docstrings (intentionally not enforced)
+  "TRY",    # try/except micro-style (intentionally not enforced)
+  "COM",    # trailing commas (formatter handles)
+  "EM",     # exception message micro-style
+  "N",      # PuLP naming (lowBound, upBound, bigM) and the lowercase lparray class
+  "PLR0913",# keep high-arity internal helpers
+  "PLR2004",# magic numbers are fine
+  "TC",     # type-checking blocks
+  "CPY",    # no per-file copyright headers
+]
+
+[tool.ruff.format]
+quote-style = "preserve"
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true # forwarding NumPy's dynamically typed dispatch arguments
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["INP001", "S101"]
+
+[tool.ty.terminal]
+error-on-warning = true