discopt.decomposition.learning.record

Telemetry schema for the Decomposition Advisor (design §8, §10.2).

The advisor improves over time only if every solve is recorded. This module defines the immutable record written after a solve — the instance’s features, the method the advisor chose, what it predicted, and what was observed. Recording predicted next to observed is the whole point: it makes the advisor’s own error measurable, which is what later calibrates the scoring weights and confidences (design §10.2).

Everything here is dependency-light and JSON-serializable so the store (discopt.decomposition.learning.store) can be a plain append-only file — no database required, nothing leaves the machine unless the user exports it.

Classes

Outcome	Terminal status of a solve.
InstanceFeatures	Cheap scalar features describing an instance (design §10.3).
ObservedPerformance	What actually happened when the chosen method ran.
SolveRecord	One solve's telemetry (design §10.2), the unit the store persists.

Module Contents

class discopt.decomposition.learning.record.Outcome(*args, **kwds)

Bases: enum.Enum

Terminal status of a solve.

OPTIMAL = 'optimal'

FEASIBLE = 'feasible'

TIMEOUT = 'timeout'

INFEASIBLE = 'infeasible'

UNBOUNDED = 'unbounded'

ERROR = 'error'

UNKNOWN = 'unknown'

class discopt.decomposition.learning.record.InstanceFeatures

Cheap scalar features describing an instance (design §10.3).

These feed the instance-based / portfolio learners. Graph embeddings for the neural options are a later addition; the scalar features come straight from the StructureReport with no extra passes.

num_vars: int

num_constraints: int

num_incidences: int

integer_fraction: float

coupling_density: float

num_blocks: int

blocks_after_integer_projection: int

nonlinear: bool

static names() → list[str]

Names of the numeric feature-vector components, in order.

vector() → list[float]

Numeric feature vector for distance/retrieval.

Counts are log1p-scaled so a large model does not dominate the distance; fractions and the nonlinear flag are already in [0, 1].

to_dict() → dict

JSON-serializable form.

classmethod from_dict(d: dict) → InstanceFeatures

Reconstruct from to_dict().

class discopt.decomposition.learning.record.ObservedPerformance

What actually happened when the chosen method ran.

wall_clock_s: float

iterations: int | None = None

converged: bool = True

gap: float | None = None

peak_mem_mb: float | None = None

master_time_s: float | None = None

subproblem_time_s: float | None = None

to_dict() → dict

JSON-serializable form.

classmethod from_dict(d: dict) → ObservedPerformance

Reconstruct from to_dict().

class discopt.decomposition.learning.record.SolveRecord

One solve’s telemetry (design §10.2), the unit the store persists.

Variables:

• instance_fingerprint (str) – Stable hash of the instance’s structure, for grouping re-solves.

• features (InstanceFeatures) – The instance’s scalar features.

• chosen (str) – MethodKind.value the advisor recommended / that was run.

• considered (list[tuple[str, float]]) – (method, aggregate) for every scored candidate — the runners-up too, so a learner can see what was not picked.

• predicted_confidence (predicted_speedup,) – What the advisor forecast for the chosen method.

• observed (ObservedPerformance | None) – Measured performance (None if only the prediction is being logged).

• solver_config (dict) – Tolerances / threads / backend in effect.

• outcome (str) – Outcome.value.

• timestamp (float) – Unix seconds; supplied by the caller (kept out of the record builder so results stay reproducible in tests).

instance_fingerprint: str

features: InstanceFeatures

chosen: str

considered: list[tuple[str, float]] = []

predicted_speedup: float | None = None

predicted_confidence: float | None = None

observed: ObservedPerformance | None = None

solver_config: dict

outcome: str = 'unknown'

timestamp: float = 0.0

to_dict() → dict

JSON-serializable form.

classmethod from_dict(d: dict) → SolveRecord

Reconstruct from to_dict().