solverpilot 0.1__py3-none-any.whl

solverpilot/plan/selective_lp.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+from dataclasses import dataclass
+import math
+from typing import Mapping, Any
+from solverpilot.inspect import ProblemFingerprint
+
+FEATURE_NAMES=('log1p_n','log1p_m','log1p_nnz','log_density','log1p_m_over_n')
+
+@dataclass(frozen=True, slots=True)
+class SelectiveLPDecision:
+    backend: str
+    default_backend: str
+    alternate_backend: str
+    switched: bool
+    leaf: int
+    predicted_saving_s: float
+    lower_saving_s: float
+    support_passed: bool
+    reason: str
+
+
+def _features(fp: ProblemFingerprint) -> tuple[float,...]:
+    if fp.problem_class != 'lp':
+        raise ValueError(f'M27 LP selector only supports continuous LP fingerprints, got {fp.problem_class!r}')
+    n=max(int(fp.n_variables),0); m=max(int(fp.n_constraints),0); nnz=max(int(fp.nnz_a),0)
+    return (
+        math.log1p(n), math.log1p(m), math.log1p(nnz),
+        math.log(max(float(fp.density_a),1e-12)), math.log1p(m/max(n,1)),
+    )
+
+
+def _traverse(nodes: list[Mapping[str,Any]], x: tuple[float,...]) -> int:
+    by_id={int(n['node']):n for n in nodes}; node=0
+    while True:
+        row=by_id[node]
+        if bool(row['is_leaf']): return node
+        f=int(row['feature']); thr=float(row['threshold'])
+        node=int(row['left'] if x[f] <= thr else row['right'])
+
+
+def decide_selective_lp_backend(fingerprint: ProblemFingerprint, model: Mapping[str,Any]) -> SelectiveLPDecision:
+    if str(model.get('schema')) != 'solverpilot.m27.selective_absolute_saving_tree.v1':
+        raise ValueError('unsupported M27 selector schema')
+    if bool(model.get('test_outcomes_seen_during_fit')):
+        raise ValueError('selector artifact is contaminated: test outcomes seen during fit')
+    if not bool(model.get('development_gate_passed')):
+        raise ValueError('selector development gate did not pass')
+    x=_features(fingerprint); nodes=list(model['tree_nodes']); leaf=_traverse(nodes,x)
+    stats=model['leaf_stats'][str(leaf)]; rule=model['selective_rule']; margin=float(rule['switch_margin_s'])
+    mean=float(stats['mean_saving_s']); lower=float(stats['bootstrap_one_sided_90_lower_mean_s']); samples=int(stats['samples'])
+    support=True
+    for key,bounds in stats.get('support_used_features',{}).items():
+        f=int(key); v=x[f]
+        if v < float(bounds['min'])-1e-12 or v > float(bounds['max'])+1e-12:
+            support=False; break
+    switch=bool(mean>margin and lower>margin and samples>=int(rule['require_leaf_samples_at_least']) and support)
+    default=str(model['default_backend']); alternate=str(model['alternate_backend']); backend=alternate if switch else default
+    reasons=[]
+    if switch: reasons.append('alternate selected: leaf mean and one-sided empirical lower saving exceed margin within observed leaf support')
+    else:
+        if mean<=margin: reasons.append('fallback: predicted leaf mean saving does not exceed margin')
+        if lower<=margin: reasons.append('fallback: empirical lower saving does not exceed margin')
+        if not support: reasons.append('fallback: query extrapolates outside observed leaf support')
+        if samples<int(rule['require_leaf_samples_at_least']): reasons.append('fallback: insufficient leaf support count')
+    return SelectiveLPDecision(backend,default,alternate,switch,leaf,mean,lower,support,'; '.join(reasons))

solverpilot/problem/__init__.py

@@ -0,0 +1,16 @@
+from .enums import ConvexityStatus, ObjectiveSense, VariableDomain
+from .linear import LinearProblem
+from .mps import MPSParseError, MPSUnsupportedFeatureError, parse_mps, read_mps
+from .quadratic import QuadraticProblem
+
+__all__ = [
+    "ConvexityStatus",
+    "LinearProblem",
+    "MPSParseError",
+    "MPSUnsupportedFeatureError",
+    "ObjectiveSense",
+    "parse_mps",
+    "read_mps",
+    "QuadraticProblem",
+    "VariableDomain",
+]

solverpilot/problem/enums.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ObjectiveSense(str, Enum):
+    MINIMIZE = "minimize"
+    MAXIMIZE = "maximize"
+
+
+class VariableDomain(str, Enum):
+    CONTINUOUS = "continuous"
+    INTEGER = "integer"
+    BINARY = "binary"
+
+
+class ConvexityStatus(str, Enum):
+    CONFIRMED = "confirmed"
+    REJECTED = "rejected"
+    UNKNOWN = "unknown"

solverpilot/problem/hashing.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable
+
+import numpy as np
+from scipy import sparse
+
+
+def _hash_parts(parts: Iterable[bytes]) -> str:
+    h = hashlib.sha256()
+    for part in parts:
+        h.update(len(part).to_bytes(8, byteorder="little", signed=False))
+        h.update(part)
+    return h.hexdigest()
+
+
+def _array_bytes(arr: np.ndarray) -> bytes:
+    c = np.ascontiguousarray(arr)
+    return b"|".join(
+        [
+            str(c.dtype).encode(),
+            repr(tuple(c.shape)).encode(),
+            c.tobytes(order="C"),
+        ]
+    )
+
+
+def hash_array(arr: np.ndarray) -> str:
+    return _hash_parts([_array_bytes(arr)])
+
+
+def hash_sparse_matrix(matrix: sparse.spmatrix) -> str:
+    csr = sparse.csr_matrix(matrix, dtype=np.float64, copy=True)
+    csr.sum_duplicates()
+    csr.sort_indices()
+    return _hash_parts(
+        [
+            repr(csr.shape).encode(),
+            _array_bytes(csr.indptr.astype(np.int64, copy=False)),
+            _array_bytes(csr.indices.astype(np.int64, copy=False)),
+            _array_bytes(csr.data.astype(np.float64, copy=False)),
+        ]
+    )
+
+
+def structural_hash_linear(
+    A: sparse.spmatrix,
+    domains: np.ndarray,
+) -> str:
+    csr = sparse.csr_matrix(A, dtype=np.float64, copy=True)
+    csr.sum_duplicates()
+    csr.sort_indices()
+    # Structural hash intentionally excludes numerical matrix values.
+    return _hash_parts(
+        [
+            repr(csr.shape).encode(),
+            _array_bytes(csr.indptr.astype(np.int64, copy=False)),
+            _array_bytes(csr.indices.astype(np.int64, copy=False)),
+            _array_bytes(np.asarray(domains, dtype="U16")),
+        ]
+    )
+
+
+def data_hash_linear(
+    A: sparse.spmatrix,
+    c: np.ndarray,
+    variable_lower: np.ndarray,
+    variable_upper: np.ndarray,
+    constraint_lower: np.ndarray,
+    constraint_upper: np.ndarray,
+    domains: np.ndarray,
+    objective_sense: str,
+    objective_offset: float,
+) -> str:
+    return _hash_parts(
+        [
+            hash_sparse_matrix(A).encode(),
+            _array_bytes(c),
+            _array_bytes(variable_lower),
+            _array_bytes(variable_upper),
+            _array_bytes(constraint_lower),
+            _array_bytes(constraint_upper),
+            _array_bytes(np.asarray(domains, dtype="U16")),
+            objective_sense.encode(),
+            np.float64(objective_offset).tobytes(),
+        ]
+    )

solverpilot/problem/linear.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+import numpy as np
+from scipy import sparse
+
+from .enums import ObjectiveSense, VariableDomain
+from .hashing import data_hash_linear, structural_hash_linear
+
+
+def _readonly_f64(values: Sequence[float] | np.ndarray, *, name: str) -> np.ndarray:
+    arr = np.array(values, dtype=np.float64, copy=True)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional")
+    if np.isnan(arr).any():
+        raise ValueError(f"{name} must not contain NaN")
+    arr.flags.writeable = False
+    return arr
+
+
+def _require_finite(values: np.ndarray, *, name: str) -> None:
+    if not np.all(np.isfinite(values)):
+        raise ValueError(f"{name} must contain only finite values")
+
+
+def _require_bound_directions(lower: np.ndarray, upper: np.ndarray, *, label: str) -> None:
+    if np.isposinf(lower).any():
+        idx = int(np.flatnonzero(np.isposinf(lower))[0])
+        raise ValueError(f"{label} lower bound at index {idx} cannot be +infinity")
+    if np.isneginf(upper).any():
+        idx = int(np.flatnonzero(np.isneginf(upper))[0])
+        raise ValueError(f"{label} upper bound at index {idx} cannot be -infinity")
+
+
+def _normalize_domains(domains: Iterable[VariableDomain | str], n: int) -> np.ndarray:
+    vals = []
+    for value in domains:
+        try:
+            vals.append(VariableDomain(value).value)
+        except ValueError as exc:
+            raise ValueError(f"unknown variable domain: {value!r}") from exc
+    if len(vals) != n:
+        raise ValueError(f"domains must have length {n}, got {len(vals)}")
+    arr = np.asarray(vals, dtype="U16")
+    arr.flags.writeable = False
+    return arr
+
+
+def _readonly_csr(A: sparse.spmatrix | np.ndarray) -> sparse.csr_matrix:
+    matrix = sparse.csr_matrix(A, dtype=np.float64, copy=True)
+    if matrix.ndim != 2:
+        raise ValueError("A must be two-dimensional")
+    if np.isnan(matrix.data).any() or np.isinf(matrix.data).any():
+        raise ValueError("A coefficients must be finite")
+    matrix.sum_duplicates()
+    if not np.isfinite(matrix.data).all():
+        raise ValueError("A coefficients must be finite after summing duplicates")
+    matrix.eliminate_zeros()
+    matrix.sort_indices()
+    matrix.data.flags.writeable = False
+    matrix.indices.flags.writeable = False
+    matrix.indptr.flags.writeable = False
+    return matrix
+
+
+@dataclass(frozen=True, slots=True)
+class LinearProblem:
+    A: sparse.csr_matrix
+    c: np.ndarray
+    variable_lower: np.ndarray
+    variable_upper: np.ndarray
+    constraint_lower: np.ndarray
+    constraint_upper: np.ndarray
+    domains: np.ndarray
+    objective_sense: ObjectiveSense = ObjectiveSense.MINIMIZE
+    objective_offset: float = 0.0
+    name: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict, compare=False, repr=False)
+    structural_hash: str = field(init=False)
+    data_hash: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        A = _readonly_csr(self.A)
+        c = _readonly_f64(self.c, name="c")
+        vl = _readonly_f64(self.variable_lower, name="variable_lower")
+        vu = _readonly_f64(self.variable_upper, name="variable_upper")
+        cl = _readonly_f64(self.constraint_lower, name="constraint_lower")
+        cu = _readonly_f64(self.constraint_upper, name="constraint_upper")
+        sense = ObjectiveSense(self.objective_sense)
+
+        m, n = A.shape
+        if c.shape != (n,):
+            raise ValueError(f"c must have shape ({n},), got {c.shape}")
+        _require_finite(c, name="c")
+        if vl.shape != (n,) or vu.shape != (n,):
+            raise ValueError("variable bounds must match number of variables")
+        if cl.shape != (m,) or cu.shape != (m,):
+            raise ValueError("constraint bounds must match number of constraints")
+        _require_bound_directions(vl, vu, label="variable")
+        _require_bound_directions(cl, cu, label="constraint")
+        if np.any(vl > vu):
+            idx = int(np.flatnonzero(vl > vu)[0])
+            raise ValueError(f"inconsistent variable bounds at index {idx}: lower > upper")
+        if np.any(cl > cu):
+            idx = int(np.flatnonzero(cl > cu)[0])
+            raise ValueError(f"inconsistent constraint bounds at index {idx}: lower > upper")
+
+        domains = _normalize_domains(self.domains, n)
+        for j, domain in enumerate(domains):
+            if domain == VariableDomain.BINARY.value:
+                if vl[j] < 0.0 or vu[j] > 1.0:
+                    raise ValueError(
+                        f"binary variable {j} must have bounds inside [0, 1], "
+                        f"got [{vl[j]}, {vu[j]}]"
+                    )
+
+        if not np.isfinite(float(self.objective_offset)):
+            raise ValueError("objective_offset must be finite")
+
+        object.__setattr__(self, "A", A)
+        object.__setattr__(self, "c", c)
+        object.__setattr__(self, "variable_lower", vl)
+        object.__setattr__(self, "variable_upper", vu)
+        object.__setattr__(self, "constraint_lower", cl)
+        object.__setattr__(self, "constraint_upper", cu)
+        object.__setattr__(self, "domains", domains)
+        object.__setattr__(self, "objective_sense", sense)
+        object.__setattr__(self, "objective_offset", float(self.objective_offset))
+        object.__setattr__(self, "metadata", dict(self.metadata))
+        object.__setattr__(self, "structural_hash", structural_hash_linear(A, domains))
+        object.__setattr__(
+            self,
+            "data_hash",
+            data_hash_linear(
+                A,
+                c,
+                vl,
+                vu,
+                cl,
+                cu,
+                domains,
+                sense.value,
+                float(self.objective_offset),
+            ),
+        )
+
+    @property
+    def n_variables(self) -> int:
+        return self.A.shape[1]
+
+    @property
+    def n_constraints(self) -> int:
+        return self.A.shape[0]
+
+    @property
+    def nnz(self) -> int:
+        return int(self.A.nnz)
+
+    @property
+    def has_integer_variables(self) -> bool:
+        return bool(np.any(self.domains != VariableDomain.CONTINUOUS.value))
+
+    @classmethod
+    def from_data(
+        cls,
+        *,
+        A: sparse.spmatrix | np.ndarray,
+        c: Sequence[float] | np.ndarray,
+        variable_lower: Sequence[float] | np.ndarray,
+        variable_upper: Sequence[float] | np.ndarray,
+        constraint_lower: Sequence[float] | np.ndarray,
+        constraint_upper: Sequence[float] | np.ndarray,
+        domains: Iterable[VariableDomain | str] | None = None,
+        objective_sense: ObjectiveSense | str = ObjectiveSense.MINIMIZE,
+        objective_offset: float = 0.0,
+        name: str | None = None,
+        metadata: dict[str, object] | None = None,
+    ) -> "LinearProblem":
+        n = sparse.csr_matrix(A).shape[1]
+        if domains is None:
+            domains = [VariableDomain.CONTINUOUS] * n
+        return cls(
+            A=A,
+            c=np.asarray(c),
+            variable_lower=np.asarray(variable_lower),
+            variable_upper=np.asarray(variable_upper),
+            constraint_lower=np.asarray(constraint_lower),
+            constraint_upper=np.asarray(constraint_upper),
+            domains=list(domains),
+            objective_sense=ObjectiveSense(objective_sense),
+            objective_offset=objective_offset,
+            name=name,
+            metadata={} if metadata is None else metadata,
+        )