discopt.debug.context#

The state snapshot handed to the debugger at each checkpoint.

DebugContext is a superset of discopt.callbacks.CallbackContext: it carries the aggregate tree state that is always available, plus the per-node batch arrays that exist only at the batch-level checkpoints. It is built lazily — only when a debugger is actually attached — so a detached solve pays nothing (see discopt.debug.fire()).

Classes#

NodeLineage

Where a set of nodes sits in the tree and how each got there (#2043).

DebugContext

Read-mostly view of solver state at a checkpoint.

Functions#

flat_variable_names(model[, n]) → Optional[list[str]]

Display name of each flat variable index of model, or None.

Module Contents#

class discopt.debug.context.NodeLineage#

Where a set of nodes sits in the tree and how each got there (#2043).

Arrays are aligned with ids. The root has parent == -1, branch_var == -1, branch_side == "" and branch_value NaN. A child was created by x[branch_var] <= branch_value (side "down") or x[branch_var] >= branch_value (side "up"); the record is taken when the child is made, so a later tightening of its box does not change it. status is one of pending, evaluated, branched, pruned, fathomed at the moment of the checkpoint; pruned covers both a bound prune and an infeasible relaxation.

ids: numpy.ndarray#
parent: numpy.ndarray#
depth: numpy.ndarray#
branch_var: numpy.ndarray#
branch_side: tuple[str, ...]#
branch_value: numpy.ndarray#
status: tuple[str, ...]#
classmethod from_dict(d: dict) → NodeLineage#

From the dict PyTreeManager.node_lineage and the Rust MILP hook emit.

branch_text(k: int, names: list[str] | None = None) → str#

The branch that created node k as text: root, x3 <= 0, …

names maps a flat variable index to a display name; without it (or for an index it does not cover) the variable shows as x[j].

to_dict() → dict[str, list]#

Columnar, JSON-ready form (the batch/created pause fields, #2049).

row(k: int, names: list[str] | None = None) → dict[str, Any]#

Node k as one record, with the creating branch rendered as text.

discopt.debug.context.flat_variable_names(model: Any, n: int | None = None) → list[str] | None#

Display name of each flat variable index of model, or None.

Indices follow model._variables flattened in order, the layout the B&B tree is built from (solver._extract_variable_info). Returns None when the model has no variable list, or when n (the width of the boxes the tree reports) disagrees with the model’s size: then the indices belong to some other variable space and naming them from this model would mislabel them.

class discopt.debug.context.DebugContext#

Read-mostly view of solver state at a checkpoint.

Aggregate fields are always populated. Batch fields (batch_* and result_*) are present only at AFTER_SELECT and later within an iteration; they are None at ITER_START and TERMINATED.

checkpoint: discopt.debug.checkpoints.Checkpoint#
iteration: int#
elapsed: float#
node_count: int#
open_nodes: int#
incumbent_obj: float | None#
best_bound: float#
gap: float | None#
batch_lb: numpy.ndarray | None = None#
batch_ub: numpy.ndarray | None = None#
batch_ids: numpy.ndarray | None = None#
result_lbs: numpy.ndarray | None = None#
result_sols: numpy.ndarray | None = None#
result_feas: numpy.ndarray | None = None#
batch_lineage: NodeLineage | None = None#
created: NodeLineage | None = None#
event: str | None = None#
steer: discopt.debug.steer.DebugSteer | None = None#
model: Any = None#
extra: dict[str, Any]#
property n_batch: int#

Number of nodes in the current batch (0 if no batch is live).

property batch_parent: numpy.ndarray | None#

Parent id of each batch node (-1 for the root), or None.

property batch_depth: numpy.ndarray | None#

Depth of each batch node (root = 0), or None.

property batch_branch_var: numpy.ndarray | None#

Branching variable that created each batch node (-1 for the root).

property batch_branch_side: tuple[str, ...] | None#

"down"/"up" for each batch node ("" for the root).

property batch_branch_value: numpy.ndarray | None#

Bound the creating branch imposed on each batch node (NaN for the root).

metrics() → dict[str, float]#

Scalar metrics addressable by conditional breakpoints and print.

classmethod build(checkpoint: discopt.debug.checkpoints.Checkpoint, *, tree: Any, model: Any = None, iteration: int = 0, elapsed: float = 0.0, batch_lb: Any = None, batch_ub: Any = None, batch_ids: Any = None, result_lbs: Any = None, result_sols: Any = None, result_feas: Any = None, event: str | None = None, validator: Any = None) → DebugContext#

Construct a context by reading aggregate state from the Rust tree.

Only pure reads (tree.stats() / tree.incumbent()) are performed, so building a context never perturbs the search — a no-op debugger is bound-neutral. validator is the solve loop’s candidate-validation closure (see discopt.debug.steer.Validator); the inject steer is available only at checkpoints that wire one.

classmethod from_rust(state: dict) → DebugContext#

Build a context from the pure-Rust MILP hook’s state dict.

The Rust solve_milp fast-path has no PyTreeManager (so no steer handle — inspection and flow control only), but at the after_select checkpoint the hook marshals the batch’s per-node boxes/ids, so print node <i> / print nodes work here too. The Rust hook carries no final status, so extra["error"] is never set and "on-error" sessions do not trigger on this path (documented in Model.solve).