nimopt 0.1.0__py3-none-any.whl

nimopt/__init__.py

@@ -0,0 +1,55 @@
+"""An LP/MILP builder whose constraint blocks are labeled sparse arrays."""
+
+from nimopt.absence import Absence
+from nimopt.coefficient import Coefficient
+from nimopt.constraint import Constraint
+from nimopt.definition import Definition
+from nimopt.explanation import Explanation
+from nimopt.files import load, loads, save
+from nimopt.model import Assembled, Model
+from nimopt.names import COLUMN, ROW
+from nimopt.param import Param
+from nimopt.row import Row
+from nimopt.session import Diagnosis, Session
+from nimopt.sets import Alias, Set, product, subset, subset_of
+from nimopt.solution import Solution
+from nimopt.solvers import Option, available, capabilities, options
+from nimopt.term import Expression, Relation, Sum, Term
+from nimopt.variable import Variable
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "COLUMN",
+    "ROW",
+    "Absence",
+    "Alias",
+    "Assembled",
+    "Coefficient",
+    "Constraint",
+    "Definition",
+    "Diagnosis",
+    "Explanation",
+    "Expression",
+    "Model",
+    "Option",
+    "Param",
+    "Relation",
+    "Row",
+    "Session",
+    "Set",
+    "Solution",
+    "Sum",
+    "Term",
+    "Variable",
+    "__version__",
+    "available",
+    "capabilities",
+    "load",
+    "loads",
+    "options",
+    "product",
+    "save",
+    "subset",
+    "subset_of",
+]

nimopt/absence.py

@@ -0,0 +1,191 @@
+"""Which coordinates fell out of a constraint, and by which rule."""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from nimblend import Domain, SparseArray
+
+from nimopt.names import COLUMN
+
+
+@dataclass(frozen=True)
+class DroppedRow:
+    """A row a constraint did not state, and what removed it."""
+
+    coordinate: dict[str, Any]
+    rule: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class DroppedTerm:
+    """A term missing from a row that stands, and what removed it."""
+
+    coordinate: dict[str, Any]
+    variable: str
+    rule: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class Absence:
+    """What a constraint set out to state, what it states, and what fell.
+
+    `stated_by` is `"terms"` where the rows are derived from what the terms
+    reach and `"over"` where they are stated outright. Under `"over"` nothing
+    is dropped and an empty `dropped_rows` is structural rather than a
+    constraint that happened to lose nothing.
+
+    A coefficient absent inside a sum removes a term and leaves the row
+    standing; a term absent along a free dimension removes the row, because a
+    row missing one of its terms states something that was not written.
+    """
+
+    constraint: str
+    stated_by: str
+    expected: int
+    standing: int
+    dropped_rows: tuple[DroppedRow, ...]
+    dropped_terms: tuple[DroppedTerm, ...]
+
+    def __repr__(self) -> str:
+        lines = [
+            f"{self.constraint}  {self.standing} of {self.expected} rows  "
+            f"stated by {self.stated_by}"
+        ]
+        for dropped in self.dropped_rows:
+            lines.append(
+                f"  row absent  {_at(dropped.coordinate)}  "
+                f"{dropped.rule} ({dropped.detail})"
+            )
+        for dropped in self.dropped_terms:
+            lines.append(
+                f"  term absent {_at(dropped.coordinate)}  {dropped.variable}  "
+                f"{dropped.rule} ({dropped.detail})"
+            )
+        return "\n".join(lines)
+
+
+def _at(coordinate: Mapping[str, Any]) -> str:
+    return ", ".join(f"{d}={v!r}" for d, v in coordinate.items())
+
+
+def _coordinates(domain: Domain) -> list[dict[str, Any]]:
+    """One dict of dimension to label per member of a domain.
+
+    A label is handed over as the Python value it stands for, so a caller
+    comparing one against a literal, and a rendering of it, both read plainly.
+    """
+    labels = domain.labels()
+    return [{d: labels[d][k].item() for d in domain.dims} for k in range(domain.size)]
+
+
+def _absent_terms(
+    rows: Domain, term: Any, before: SparseArray, after: SparseArray
+) -> list[DroppedTerm]:
+    """Terms a coefficient removed from rows that still stand.
+
+    A term is identified by the coordinate it carries once its coefficient has
+    placed it. Every such coordinate is the entries the variable brought,
+    crossed with each member of a dimension the coefficient introduced; the
+    ones the coefficient does not carry are the terms that are gone.
+    """
+    if not term.summed:
+        return []
+    keep = tuple(d for d in after.dims if d != COLUMN)
+    carried = after.domain(keep)
+    brought = tuple(d for d in before.dims if d != COLUMN)
+    entries = before.domain(brought)
+    introduced = tuple(d for d in keep if d not in brought)
+    whole = entries.expand(introduced, carried.coords).transpose(*keep)
+    lost = whole.difference(carried)
+    at = lost.coordinates()[[keep.index(d) for d in rows.dims]]
+    standing = rows.positions_of_coordinates(at) >= 0
+    variable = term.variable.name
+    detail = term.coefficient.name
+    return [
+        DroppedTerm(coordinate, variable, "absent-coefficient", detail)
+        for coordinate, keeping in zip(_coordinates(lost), standing)
+        if keeping
+    ]
+
+
+class Recorder:
+    """What a constraint's shape pass dropped, gathered as it narrows.
+
+    A dropped row leaves no trace in the matrix, so it is attributed while the
+    narrowing runs rather than read back from it. Each narrowing sees only what
+    survived the one before, so a coordinate is attributed to one rule.
+    """
+
+    def __init__(self) -> None:
+        self.stated_by = "terms"
+        self.expected: int | None = None
+        self.rows = []
+        self.terms = []
+        self._reached = []
+        self._coefficients = []
+        self._standing: Domain | None = None
+
+    def term_rows(self, term: Any, domain: Domain) -> None:
+        """The rows one term of the expression reaches."""
+        self._reached.append((term, domain))
+
+    def reached(self, frame: Sequence[str], rows: Domain) -> None:
+        """The rows the terms reach, against the product the frame spans.
+
+        A coordinate no term reaches is attributed to the first term that
+        misses it, so each is named once and by the term that lost it.
+        """
+        whole = Domain.full(frame, rows.coords)
+        self.expected = whole.size
+        standing = whole
+        for term, domain in self._reached:
+            reduced = standing.intersect(domain)
+            self._record_rows(
+                standing, reduced, "term-does-not-reach", term.variable.name
+            )
+            standing = reduced
+
+    def stated(self, rows: Domain) -> None:
+        """The rows an `over=` states outright, which drops nothing."""
+        self.stated_by = "over"
+        self.expected = rows.size
+        self.rows = []
+
+    def dropped(self, before: Domain, after: Domain, rule: str, detail: str) -> None:
+        """The rows one narrowing removed."""
+        self._record_rows(before, after, rule, detail)
+
+    def _record_rows(
+        self, before: Domain, after: Domain, rule: str, detail: str
+    ) -> None:
+        lost = before.difference(after)
+        self.rows.extend(DroppedRow(at, rule, detail) for at in _coordinates(lost))
+
+    def coefficient(self, term: Any, before: SparseArray, after: SparseArray) -> None:
+        """A term's entries either side of the coefficient that multiplied it."""
+        self._coefficients.append((term, before, after))
+
+    def settled(self, rows: Domain) -> None:
+        """The rows the constraint states, once every narrowing has run."""
+        self._standing = rows
+        for held in self._coefficients:
+            self.terms.extend(_absent_terms(rows, *held))
+
+    def absence(self, name: str) -> Absence:
+        """What this recorder gathered, as the answer a caller reads."""
+        if self.expected is None or self._standing is None:
+            raise ValueError(
+                f"constraint {name!r} has not settled its rows; an absence is "
+                f"read once the shape pass has run"
+            )
+        return Absence(
+            constraint=name,
+            stated_by=self.stated_by,
+            expected=self.expected,
+            standing=self._standing.size,
+            dropped_rows=tuple(self.rows),
+            dropped_terms=tuple(self.terms),
+        )

nimopt/coefficient.py

@@ -0,0 +1,345 @@
+"""A coefficient: a parameter read at its sets, or a combination of them."""
+
+from typing import Any
+
+import numpy as np
+from nimblend import combined_dims
+
+from nimopt.sets import check_members, reference
+from nimopt.symbol import Symbol, read_bare
+
+NOT_A_COEFFICIENT = (
+    "a coefficient is a parameter; build one with `Param.from_dense` or "
+    "`Param.from_long` and read it at its sets. A product of two expressions "
+    "is not linear."
+)
+
+_BINARY = {
+    "+": lambda a, b: a + b,
+    "-": lambda a, b: a - b,
+    "*": lambda a, b: a * b,
+    "**": lambda a, b: a**b,
+}
+
+
+def _rendered(operand: Any) -> str:
+    """How an operand reads inside a combination's name."""
+    return operand.name if isinstance(operand, Coefficient) else str(operand)
+
+
+def _finite_divisor(divisor: Any, named: str) -> None:
+    """Refuse a divisor that is zero, naming what is divided.
+
+    A numpy scalar divides to infinity where a Python number raises, so the
+    rule is stated rather than left to the arithmetic: a coefficient reaching
+    a solver is finite.
+    """
+    if float(divisor) == 0.0:
+        raise ZeroDivisionError(
+            f"{named} is divided by zero; a divisor of zero states a "
+            f"coefficient no solver can read, so it is prepared before it "
+            f"reaches an expression"
+        )
+
+
+def _finite_quotient(array: Any, name: str) -> None:
+    """Refuse a divisor carrying a zero, naming the first coordinate it sits at."""
+    at = np.flatnonzero(array.values() == 0.0)
+    if at.size:
+        where = {
+            d: labels[at[0]].item() for d, labels in array.domain().labels().items()
+        }
+        raise ZeroDivisionError(
+            f"divisor {name} carries a zero at {at.size} coordinate(s), the "
+            f"first at {where}; a quotient there states a coefficient no "
+            f"solver can read"
+        )
+
+
+class Coefficient:
+    """What a term reads as its coefficient.
+
+    A `name` to report, the `dims` it carries, the array it `materialise()`s
+    to, and a reading at its sets. A parameter's reference and a combination
+    of coefficients both answer that surface, so a verb reporting a
+    coefficient reads one thing whichever it is handed.
+
+    The arithmetic is here because both answer it alike: a coefficient
+    meeting an expression multiplies its terms, one meeting another
+    coefficient or a number states a combination that computes where the
+    matrix is built, and everything else is declined so the operand on the
+    right is offered its turn.
+    """
+
+    __array_ufunc__ = None
+    __hash__ = None
+
+    @property
+    def name(self) -> str:
+        """What this coefficient is called where it is reported."""
+        raise NotImplementedError
+
+    @property
+    def dims(self) -> tuple[str, ...]:
+        """The dimensions this coefficient carries."""
+        raise NotImplementedError
+
+    def materialise(self) -> Any:
+        """The array this coefficient computes to."""
+        raise NotImplementedError
+
+    def held(self) -> Any:
+        """The array this coefficient already holds, or None where it holds none.
+
+        A parameter that is bound holds its array, so a fact about its values
+        is in hand where the arithmetic is written. A combination holds none:
+        computing one to read a fact off it is the build, done early.
+        """
+        return None
+
+    def parameters(self) -> tuple[Any, ...]:
+        """The parameters this coefficient reads, in order of appearance."""
+        raise NotImplementedError
+
+    def __getitem__(self, sets: Any) -> Any:
+        """Refuse a second reading of a coefficient already read."""
+        raise TypeError(
+            f"coefficient {self.name} is already read at {self.dims}; a "
+            f"coefficient is read at its sets once"
+        )
+
+    def _read(self, sets: Any, holder: Any) -> dict[str, Any]:
+        """The members `sets` fixes, checked against the dimensions carried."""
+        given, shifts, fixed = reference(sets, self.dims)
+        if shifts:
+            raise ValueError(
+                f"coefficient {self.name} is read at a lag {sorted(shifts)}; "
+                f"state the lag at the variable's reference, where a "
+                f"coefficient multiplies the row it lands on"
+            )
+        if given != self.dims:
+            raise ValueError(
+                f"coefficient {self.name} is over {self.dims}; got {given}"
+            )
+        check_members(holder.sets, fixed, f"coefficient {self.name}")
+        return fixed
+
+    def _combine(self, other: Any, symbol: str, flip: bool = False) -> Any:
+        if isinstance(other, np.ndarray):
+            raise TypeError(NOT_A_COEFFICIENT)
+        if not isinstance(other, (Coefficient, int, float, np.number)):
+            return NotImplemented
+        return Derived(other, self, symbol) if flip else Derived(self, other, symbol)
+
+    def _applied(self, other: Any) -> Any:
+        from nimopt.term import Expression
+
+        other = read_bare(other)
+        if isinstance(other, Expression):
+            return Expression([t.with_coefficient(self) for t in other.terms])
+        return None
+
+    def __mul__(self, other: Any) -> Any:
+        applied = self._applied(other)
+        return self._combine(other, "*") if applied is None else applied
+
+    def __rmul__(self, other: Any) -> Any:
+        applied = self._applied(other)
+        if applied is not None:
+            return applied
+        if isinstance(other, (int, float, np.number)):
+            return Derived(self, other, "*")
+        return self._combine(other, "*", flip=True)
+
+    def __add__(self, other: Any) -> Any:
+        return self._combine(other, "+")
+
+    def __radd__(self, other: Any) -> Any:
+        return self._combine(other, "+", flip=True)
+
+    def __sub__(self, other: Any) -> Any:
+        return self._combine(other, "-")
+
+    def __rsub__(self, other: Any) -> Any:
+        return self._combine(other, "-", flip=True)
+
+    def __truediv__(self, other: Any) -> Any:
+        other = read_bare(other)
+        if isinstance(other, (int, float, np.number)):
+            _finite_divisor(other, f"coefficient {self.name}")
+        elif isinstance(other, Coefficient):
+            in_hand = other.held()
+            if in_hand is not None:
+                _finite_quotient(in_hand, other.name)
+        return self._combine(other, "/")
+
+    def __rtruediv__(self, other: Any) -> Any:
+        return self._combine(other, "/", flip=True)
+
+    def __neg__(self) -> Any:
+        return Derived(self, None, "-")
+
+    def __rpow__(self, other: Any) -> Any:
+        raise TypeError(
+            f"a power takes a number, and {_rendered(other)} raised to "
+            f"coefficient {self.name} varies by coordinate; nimopt expresses a "
+            f"linear term, and such a value is data a caller prepares"
+        )
+
+    def __pow__(self, other: Any) -> Any:
+        if not isinstance(other, (int, float, np.number)):
+            raise TypeError(
+                f"a power takes a number, and {_rendered(other)} carries "
+                f"dimensions; an exponent that varies by coordinate is data a "
+                f"caller prepares before a parameter exists"
+            )
+        return Derived(self, other, "**")
+
+    def __abs__(self) -> Any:
+        raise TypeError(
+            f"coefficient {self.name} has no absolute value here; nimopt "
+            f"reduces with `Sum` over its sets, and a magnitude is prepared "
+            f"before a parameter exists"
+        )
+
+    def _no_row(self, other: Any) -> Any:
+        """Refuse a comparison of two coefficients, declining one that states a row.
+
+        An expression or a symbol answers the comparison itself, so this
+        declines and Python offers it the reflected operator, which reverses
+        the sense: `capacity[G, T] >= gen[G, T]` is the row
+        `gen[G, T] <= capacity[G, T]`.
+        """
+        from nimopt.term import Expression
+
+        if isinstance(other, (Expression, Symbol)):
+            return NotImplemented
+        raise TypeError(
+            f"coefficient {self.name} compared with {_rendered(other)} states "
+            f"no row; an equation needs a variable on one side of it"
+        )
+
+    __le__ = _no_row
+    __ge__ = _no_row
+    __lt__ = _no_row
+    __gt__ = _no_row
+    __eq__ = _no_row
+
+
+class Derived(Coefficient):
+    """Two coefficients and an operator, or one coefficient and a number.
+
+    The combination holds handles: it states its dimensions from its
+    operands' and computes once, where the term it multiplies materialises.
+    A coefficient is therefore written in a definition before any data
+    exists.
+    """
+
+    def __init__(self, left: Any, right: Any, symbol: str) -> None:
+        self.left = left
+        self.right = right
+        self.symbol = symbol
+        carried = [
+            operand.dims
+            for operand in (left, right)
+            if isinstance(operand, Coefficient)
+        ]
+        self._dims = combined_dims(*carried) if len(carried) == 2 else carried[0]
+
+    @property
+    def name(self) -> str:
+        """The arithmetic this combination states, as it was written."""
+        if self.right is None:
+            return f"({self.symbol}{self.left.name})"
+        return f"({_rendered(self.left)} {self.symbol} {_rendered(self.right)})"
+
+    @property
+    def dims(self) -> tuple[str, ...]:
+        """The dimensions the combination carries, read from its operands'.
+
+        They are settled where the combination is written, so two operands
+        sharing no dimension are refused there rather than at build.
+        """
+        return self._dims
+
+    @property
+    def sets(self) -> tuple[Any, ...]:
+        """The sets the dimensions this carries are declared over."""
+        held = {s.name: s for p in self.parameters() for s in p.sets}
+        return tuple(held[d] for d in self.dims)
+
+    def parameters(self) -> tuple[Any, ...]:
+        """The parameters this combination reads, in order of appearance."""
+        found = {}
+        for operand in (self.left, self.right):
+            if isinstance(operand, Coefficient):
+                for parameter in operand.parameters():
+                    found.setdefault(parameter.name, parameter)
+        return tuple(found.values())
+
+    def __repr__(self) -> str:
+        return f"Derived({self.name!r}, {self.dims})"
+
+    def materialise(self) -> Any:
+        """The array this combination computes to, over the frame it states."""
+        left = self.left
+        if isinstance(left, Coefficient):
+            left = left.materialise()
+        if self.right is None:
+            return -left
+        right = self.right
+        if isinstance(right, Coefficient):
+            right = right.materialise()
+        if self.symbol == "/":
+            if isinstance(right, (int, float, np.number)):
+                _finite_divisor(right, f"coefficient {_rendered(self.left)}")
+            else:
+                _finite_quotient(right, self.right.name)
+            return left / right
+        return _BINARY[self.symbol](left, right)
+
+    def __getitem__(self, sets: Any) -> "DerivedRef":
+        """This combination read at its sets, as a parameter is read at its.
+
+        The reading is checked against the dimensions the combination
+        carries, so a transposed or short spelling is refused where it is
+        written rather than a layer away.
+        """
+        return DerivedRef(self, self._read(sets, self))
+
+
+class DerivedRef(Coefficient):
+    """A derived coefficient read at its sets, and at the members fixed."""
+
+    def __init__(self, derived: Any, fixed: dict[str, Any] | None = None) -> None:
+        self.derived = derived
+        self.fixed = dict(fixed) if fixed else {}
+
+    @property
+    def name(self) -> str:
+        """The arithmetic the combination this reads states."""
+        return self.derived.name
+
+    @property
+    def dims(self) -> tuple[str, ...]:
+        """The dimensions the reference carries, without those it fixes."""
+        return tuple(d for d in self.derived.dims if d not in self.fixed)
+
+    @property
+    def sets(self) -> tuple[Any, ...]:
+        """The sets the dimensions this carries are declared over."""
+        return self.derived.sets
+
+    def parameters(self) -> tuple[Any, ...]:
+        """The parameters the combination this reads carries."""
+        return self.derived.parameters()
+
+    def __repr__(self) -> str:
+        return f"DerivedRef({self.name!r}, {self.dims})"
+
+    def materialise(self) -> Any:
+        """The combination's array, read at the members this reference fixes."""
+        array = self.derived.materialise()
+        if not self.fixed:
+            return array
+        return array.sel(self.fixed)