solverpilot 0.1__py3-none-any.whl

solverpilot/session/session.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+import numpy as np
+from scipy import sparse
+
+from solverpilot.backends import Backend, BackendRegistry
+from solverpilot.plan import PlannerContext, SolveBudget, SolveIntent
+from solverpilot.problem import LinearProblem, QuadraticProblem
+from solverpilot.runtime import SolveResult, solve as runtime_solve
+
+from .mutations import MutationRecord, classify_mutations
+from .reuse import ReuseAssessment, assess_reuse
+
+
+class Session:
+    """Versioned repeated-solve session with explicit mutation tracking.
+
+    M1 tracks and assesses reuse safely but does not pretend to apply native solver
+    state. Actual basis/factorization/incumbent injection is reserved for native
+    backend adapters that expose a stateful contract.
+    """
+
+    def __init__(
+        self,
+        problem: LinearProblem | QuadraticProblem,
+        *,
+        registry: BackendRegistry | None = None,
+    ) -> None:
+        self._problem = problem
+        if registry is None:
+            from solverpilot.runtime import default_registry
+            registry = default_registry()
+        self._registry = registry
+        self._revision = 0
+        self._history: list[MutationRecord] = []
+        self._last_result: SolveResult | None = None
+        self._last_solve_revision: int | None = None
+        self._last_reuse_assessment: ReuseAssessment | None = None
+
+    @property
+    def problem(self) -> LinearProblem | QuadraticProblem:
+        return self._problem
+
+    @property
+    def revision(self) -> int:
+        return self._revision
+
+    @property
+    def history(self) -> tuple[MutationRecord, ...]:
+        return tuple(self._history)
+
+    @property
+    def last_result(self) -> SolveResult | None:
+        return self._last_result
+
+    @property
+    def last_reuse_assessment(self) -> ReuseAssessment | None:
+        return self._last_reuse_assessment
+
+    def update(self, **changes: Any) -> MutationRecord:
+        old = self._problem
+        new = _updated_problem(old, changes)
+        next_revision = self._revision if old.data_hash == new.data_hash else self._revision + 1
+        record = classify_mutations(
+            old,
+            new,
+            revision_before=self._revision,
+            revision_after=next_revision,
+        )
+        # Descriptive updates do not change the mathematical hash/revision,
+        # but must still be visible to the caller.
+        self._problem = new
+        if not record.is_noop:
+            self._revision = next_revision
+            self._history.append(record)
+        return record
+
+    def solve(
+        self,
+        *,
+        backend: str | Backend | None = None,
+        intent: SolveIntent | str = SolveIntent.BALANCED,
+        budget: SolveBudget | None = None,
+        diagnose_infeasible: bool = False,
+    ) -> SolveResult:
+        previous_backend = None if self._last_result is None else self._last_result.trace.backend
+        context = PlannerContext(
+            previous_backend=previous_backend,
+            session_revision=self._revision,
+        )
+        result = runtime_solve(
+            self._problem,
+            registry=self._registry,
+            backend=backend,
+            intent=intent,
+            budget=budget,
+            context=context,
+            diagnose_infeasible=diagnose_infeasible,
+        )
+        result = replace(result, session_revision=self._revision)
+
+        if self._last_result is not None and result.trace.backend is not None:
+            since = self._mutations_since_last_solve()
+            if backend is not None and not isinstance(backend, str):
+                manifest = backend.manifest
+            else:
+                manifest = self._registry.get(result.trace.backend).manifest
+            assessment = assess_reuse(self._problem, manifest, since)
+            if result.trace.reuse_applied is True:
+                mode = result.trace.reuse_mode or "backend-reported reuse"
+                assessment = replace(
+                    assessment,
+                    applied=True,
+                    safe_candidate=True,
+                    reason=f"backend reported applied reuse: {mode}",
+                )
+            self._last_reuse_assessment = assessment
+        else:
+            self._last_reuse_assessment = None
+
+        self._last_result = result
+        self._last_solve_revision = self._revision
+        return result
+
+    def _mutations_since_last_solve(self) -> tuple[MutationRecord, ...]:
+        if self._last_solve_revision is None:
+            return ()
+        return tuple(
+            record for record in self._history if record.revision_after > self._last_solve_revision
+        )
+
+
+def _updated_problem(
+    problem: LinearProblem | QuadraticProblem,
+    changes: dict[str, Any],
+) -> LinearProblem | QuadraticProblem:
+    allowed_linear = {
+        "A",
+        "c",
+        "variable_lower",
+        "variable_upper",
+        "constraint_lower",
+        "constraint_upper",
+        "domains",
+        "objective_sense",
+        "objective_offset",
+        "name",
+        "metadata",
+    }
+    allowed_qp = {
+        "P",
+        "A",
+        "q",
+        "variable_lower",
+        "variable_upper",
+        "constraint_lower",
+        "constraint_upper",
+        "objective_sense",
+        "objective_offset",
+        "metadata",
+    }
+
+    if isinstance(problem, LinearProblem):
+        unknown = set(changes) - allowed_linear
+        if unknown:
+            raise TypeError(f"unknown LinearProblem update fields: {sorted(unknown)}")
+        data = {
+            "A": problem.A,
+            "c": problem.c,
+            "variable_lower": problem.variable_lower,
+            "variable_upper": problem.variable_upper,
+            "constraint_lower": problem.constraint_lower,
+            "constraint_upper": problem.constraint_upper,
+            "domains": problem.domains,
+            "objective_sense": problem.objective_sense,
+            "objective_offset": problem.objective_offset,
+            "name": problem.name,
+            "metadata": problem.metadata,
+        }
+        data.update(changes)
+        return LinearProblem.from_data(**data)
+
+    if isinstance(problem, QuadraticProblem):
+        unknown = set(changes) - allowed_qp
+        if unknown:
+            raise TypeError(f"unknown QuadraticProblem update fields: {sorted(unknown)}")
+        linear = problem.linear
+        P = changes.get("P", problem.P)
+        A = changes.get("A", linear.A)
+        q = changes.get("q", linear.c)
+        vl = changes.get("variable_lower", linear.variable_lower)
+        vu = changes.get("variable_upper", linear.variable_upper)
+        cl = changes.get("constraint_lower", linear.constraint_lower)
+        cu = changes.get("constraint_upper", linear.constraint_upper)
+        sense = changes.get("objective_sense", linear.objective_sense)
+        offset = changes.get("objective_offset", linear.objective_offset)
+        metadata = changes.get("metadata", problem.metadata)
+
+        # Avoid an unnecessary eigenvalue calculation when P is unchanged.
+        if "P" not in changes:
+            new_linear = LinearProblem.from_data(
+                A=A,
+                c=q,
+                variable_lower=vl,
+                variable_upper=vu,
+                constraint_lower=cl,
+                constraint_upper=cu,
+                objective_sense=sense,
+                objective_offset=offset,
+                metadata=metadata,
+            )
+            return QuadraticProblem(
+                linear=new_linear,
+                P=problem.P,
+                convexity_status=problem.convexity_status,
+                metadata=metadata,
+            )
+
+        return QuadraticProblem.from_data(
+            P=P,
+            A=A,
+            q=q,
+            variable_lower=vl,
+            variable_upper=vu,
+            constraint_lower=cl,
+            constraint_upper=cu,
+            objective_sense=sense,
+            objective_offset=offset,
+            verify_convexity=True,
+            metadata=metadata,
+        )
+
+    raise TypeError(f"unsupported problem type: {type(problem)!r}")

solverpilot/trace/__init__.py

@@ -0,0 +1,3 @@
+from .schema import TRACE_SCHEMA_VERSION, PhaseTimings, SolveTrace
+
+__all__ = ["TRACE_SCHEMA_VERSION", "PhaseTimings", "SolveTrace"]

solverpilot/trace/schema.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+TRACE_SCHEMA_VERSION = "0.3"
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseTimings:
+    inspect_s: float = 0.0
+    plan_s: float = 0.0
+    backend_build_s: float = 0.0
+    solve_s: float = 0.0
+    validate_s: float = 0.0
+    diagnose_s: float = 0.0
+    total_s: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class SolveTrace:
+    problem_structural_hash: str
+    problem_data_hash: str
+    problem_class: str
+    backend: str | None = None
+    backend_version: str | None = None
+    parameters: dict[str, Any] = field(default_factory=dict)
+    fingerprint: dict[str, Any] | None = None
+    planner_selected_backend: str | None = None
+    planner_evidence_level: str | None = None
+    planner_health_policy: str | None = None
+    transformations: tuple[str, ...] = ()
+    seed: int | None = None
+    threads: int | None = None
+    timings: PhaseTimings = field(default_factory=PhaseTimings)
+    termination: str | None = None
+    validation_valid: bool | None = None
+    reuse_applied: bool | None = None
+    reuse_mode: str | None = None
+    warnings: tuple[str, ...] = ()
+    schema_version: str = TRACE_SCHEMA_VERSION
+    created_at_utc: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

solverpilot/validate/__init__.py

@@ -0,0 +1,10 @@
+from .core import validate_solution
+from .result import CandidateSolution, PublicStatus, ValidationReport, ValidationTolerances
+
+__all__ = [
+    "CandidateSolution",
+    "PublicStatus",
+    "ValidationReport",
+    "ValidationTolerances",
+    "validate_solution",
+]

solverpilot/validate/core.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import numpy as np
+
+from solverpilot.problem import LinearProblem, QuadraticProblem, VariableDomain
+
+from .result import CandidateSolution, ValidationReport, ValidationTolerances
+
+_FEASIBILITY_REL = 1e-9
+
+
+def _max_violation(values: np.ndarray, lower: np.ndarray, upper: np.ndarray) -> float:
+    if not np.isfinite(values).all():
+        return float("inf")
+    below = np.maximum(lower - values, 0.0)
+    above = np.maximum(values - upper, 0.0)
+    v = np.maximum(below, above)
+    return float(np.max(v)) if v.size else 0.0
+
+
+def _scaled_feasibility(
+    values: np.ndarray,
+    lower: np.ndarray,
+    upper: np.ndarray,
+    *,
+    atol: float,
+    rtol: float,
+    extra_scale: np.ndarray | None = None,
+) -> tuple[float, bool]:
+    """Return max normalized violation and whether every row is within tolerance.
+
+    The absolute tolerance remains the numerical floor.  The relative term scales
+    against the magnitude of the candidate, finite bounds and (for constraints)
+    an independently supplied row/activity scale.
+    """
+    if not np.isfinite(values).all():
+        return float("inf"), False
+    scale = np.maximum(1.0, np.abs(values))
+    if extra_scale is not None:
+        if not np.isfinite(extra_scale).all():
+            return float("inf"), False
+        scale = np.maximum(scale, np.asarray(extra_scale, dtype=np.float64))
+    max_normalized = 0.0
+    ok = True
+    # Each side uses its own bound: a distant upper bound must not relax a
+    # violated lower bound (or vice versa).
+    for bound, direction in ((lower, -1.0), (upper, 1.0)):
+        mask = np.isfinite(bound)
+        with np.errstate(over="ignore", invalid="ignore", divide="ignore"):
+            violation = np.maximum(direction * (values[mask] - bound[mask]), 0.0)
+            allowed = float(atol) + float(rtol) * np.maximum(scale[mask], np.abs(bound[mask]))
+            normalized = np.divide(violation, allowed, out=np.full_like(violation, np.inf), where=allowed > 0)
+        normalized[violation == 0] = 0.0
+        if normalized.size:
+            max_normalized = max(max_normalized, float(np.max(normalized)))
+        ok = ok and bool(np.all(np.isfinite(violation) & np.isfinite(allowed) & (violation <= allowed)))
+    return max_normalized, ok
+
+
+def _linear_objective(problem: LinearProblem, x: np.ndarray) -> float:
+    return float(problem.c @ x + problem.objective_offset)
+
+
+def _quadratic_objective(problem: QuadraticProblem, x: np.ndarray) -> float:
+    return float(0.5 * x @ (problem.P @ x) + problem.linear.c @ x + problem.linear.objective_offset)
+
+
+def validate_solution(
+    problem: LinearProblem | QuadraticProblem,
+    solution: CandidateSolution,
+    *,
+    tolerances: ValidationTolerances | None = None,
+) -> ValidationReport:
+    tol = ValidationTolerances() if tolerances is None else tolerances
+    linear = problem.linear if isinstance(problem, QuadraticProblem) else problem
+    x = np.asarray(solution.x, dtype=np.float64)
+
+    if x.shape != (linear.n_variables,):
+        raise ValueError(f"solution x must have shape ({linear.n_variables},), got {x.shape}")
+    if not np.isfinite(x).all():
+        return ValidationReport(
+            valid=False,
+            max_bound_violation=float("inf"),
+            max_constraint_violation=float("inf"),
+            max_integrality_violation=float("inf") if linear.has_integer_variables else None,
+            objective_recomputed=None,
+            objective_reported=solution.objective_reported,
+            objective_difference=None,
+            objective_consistent=False if solution.objective_reported is not None else None,
+            warnings=("solution contains NaN or infinity",),
+        )
+
+    bound_v = _max_violation(x, linear.variable_lower, linear.variable_upper)
+    bound_scaled_v, bounds_ok = _scaled_feasibility(
+        x,
+        linear.variable_lower,
+        linear.variable_upper,
+        atol=tol.feasibility,
+        rtol=_FEASIBILITY_REL,
+    )
+
+    activity = np.asarray(linear.A @ x, dtype=np.float64).reshape(-1)
+    constraint_v = _max_violation(activity, linear.constraint_lower, linear.constraint_upper)
+    row_scale = np.asarray(np.abs(linear.A) @ np.abs(x), dtype=np.float64).reshape(-1)
+    constraint_scaled_v, constraints_ok = _scaled_feasibility(
+        activity,
+        linear.constraint_lower,
+        linear.constraint_upper,
+        atol=tol.feasibility,
+        rtol=_FEASIBILITY_REL,
+        extra_scale=row_scale,
+    )
+
+    integer_mask = np.isin(
+        linear.domains,
+        [VariableDomain.INTEGER.value, VariableDomain.BINARY.value],
+    )
+    if np.any(integer_mask):
+        int_v = float(np.max(np.abs(x[integer_mask] - np.rint(x[integer_mask]))))
+    else:
+        int_v = None
+
+    objective = (
+        _quadratic_objective(problem, x)
+        if isinstance(problem, QuadraticProblem)
+        else _linear_objective(problem, x)
+    )
+
+    reported = solution.objective_reported
+    if not np.isfinite(objective):
+        objective_diff = None if reported is None else float("inf")
+        objective_ok = False
+    elif reported is None:
+        objective_diff = None
+        objective_ok = None
+    elif not np.isfinite(reported):
+        objective_diff = float("inf")
+        objective_ok = False
+    else:
+        objective_diff = float(abs(objective - reported))
+        objective_ok = bool(
+            objective_diff
+            <= tol.objective_abs + tol.objective_rel * max(abs(objective), abs(reported))
+        )
+
+    valid = (
+        bounds_ok
+        and constraints_ok
+        and (int_v is None or int_v <= tol.integrality)
+        and (objective_ok is not False)
+    )
+
+    warnings: list[str] = []
+    if not np.isfinite(objective):
+        warnings.append("canonical objective is non-finite")
+    if not bounds_ok:
+        warnings.append("variable bound violation")
+    elif bound_v > tol.feasibility:
+        warnings.append("variable bound residual accepted by scale-aware feasibility tolerance")
+    if not constraints_ok:
+        warnings.append("constraint violation")
+    elif constraint_v > tol.feasibility:
+        warnings.append("constraint residual accepted by scale-aware feasibility tolerance")
+    if int_v is not None and int_v > tol.integrality:
+        warnings.append("integrality violation")
+    if objective_ok is False:
+        warnings.append("reported objective is inconsistent with canonical objective")
+
+    return ValidationReport(
+        valid=valid,
+        max_bound_violation=bound_v,
+        max_constraint_violation=constraint_v,
+        max_integrality_violation=int_v,
+        objective_recomputed=objective,
+        objective_reported=reported,
+        objective_difference=objective_diff,
+        objective_consistent=objective_ok,
+        warnings=tuple(warnings),
+    )

solverpilot/validate/result.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+import numpy as np
+
+
+class PublicStatus(str, Enum):
+    VALID_OPTIMAL = "valid_optimal"
+    VALID_FEASIBLE = "valid_feasible"
+    FEASIBLE_LIMIT = "feasible_limit"
+    INFEASIBLE = "infeasible"
+    UNBOUNDED = "unbounded"
+    INFEASIBLE_OR_UNBOUNDED = "infeasible_or_unbounded"
+    INVALID_SOLUTION = "invalid_solution"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationTolerances:
+    feasibility: float = 1e-7
+    integrality: float = 1e-6
+    objective_abs: float = 1e-7
+    objective_rel: float = 1e-7
+
+    def __post_init__(self) -> None:
+        for name in ("feasibility", "integrality", "objective_abs", "objective_rel"):
+            raw = getattr(self, name)
+            if isinstance(raw, bool) or type(raw) not in (int, float):
+                raise ValueError(f"{name} tolerance must be a finite number")
+            value = float(raw)
+            if not np.isfinite(value) or value < 0:
+                raise ValueError(f"{name} tolerance must be finite and non-negative")
+            object.__setattr__(self, name, value)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationReport:
+    valid: bool
+    max_bound_violation: float
+    max_constraint_violation: float
+    max_integrality_violation: float | None
+    objective_recomputed: float | None
+    objective_reported: float | None
+    objective_difference: float | None
+    objective_consistent: bool | None
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateSolution:
+    x: np.ndarray
+    objective_reported: float | None = None