Run

class Run

A mutable run being recorded inside an unsealed Experiment.

A run represents one experimental condition or trial. Use log_parameter for scalar values that should appear in Experiment.run_parameters_df, and use attachment methods for payloads such as JSON, instances, solutions, sample sets, or raw bytes.

Runs are usually created with Experiment.run() and used as context managers. On normal context-manager exit the run is finished and added to the parent experiment. On exception the run is closed as failed and added with its partial state. KeyboardInterrupt is recorded separately as "interrupted". A run becomes immutable once it is closed.

__enter__() → Run

__exit__(exc_type: Optional[Any] = None, exc_value: Optional[Any] = None, traceback: Optional[Any] = None) → bool

__repr__() → str

finish() → None

Finish this run and append it to the parent Experiment.

After this method returns, the run handle can no longer be used. The context manager calls this automatically on normal exit. On exception, the context manager closes the run as failed or interrupted with its partial state.

log_attachment(name: str, media_type: str, bytes: bytes, compression: Literal["none", "zstd"] = 'none') → None

Attach arbitrary bytes with an explicit OCI media type in this run.

Use this for payloads that belong to this run but are not scalar run parameters, for example solver logs or derived files. Set compression="zstd" to compress the stored layer transparently.

log_file(name: str, path: str | PathLike | Path, media_type: Optional[str] = None, filename: Optional[str] = None, compression: Literal["none", "zstd"] = 'none') → None

Attach an existing filesystem file in this run.

The file bytes are copied into the Local Registry immediately. If media_type is omitted, the Rust SDK infers it from file contents and unknown types fall back to application/octet-stream. The original source path is not stored; only a basename for later export is stored as attachment metadata. The file is streamed into the Local Registry; set compression="zstd" to compress the stored layer transparently.

log_instance(name: str, instance: Instance) → None

Attach an Instance in this run.

This records an instance as a run-level attachment. Use log_solve when the instance is the input of a solver call and should be paired with the returned solution.

log_json(name: str, value: Any, compression: Literal["none", "zstd"] = 'none') → None

Attach a JSON-serializable value in this run.

The value is encoded with Python’s json.dumps and stored with media type application/json. Set compression="zstd" to compress the encoded JSON transparently.

log_parameter(name: str, value: bool | int | float | str) → None

Log a scalar parameter for this run.

Accepted value types are bool, int, float, and str. These values are intended for comparing runs and are exposed as columns in Experiment.run_parameters_df().

log_parametric_instance(name: str, pi: ParametricInstance) → None

Attach a ParametricInstance in this run.

log_sample(adapter: type[SamplerAdapter], instance: Instance, store_diagnostics: bool = False, kwargs: Any) → SampleSet

Sample an Instance with an OMMX SamplerAdapter and log a Sampling entry.

The original input is stored together with the returned SampleSet. A successful sampler call is recorded as finished even when none of its samples are feasible.

adapter must be a subclass of ommx.adapter.SamplerAdapter. Keyword arguments are passed to adapter.sample(...) and recorded as Sampling.adapter_options.

Set store_diagnostics=True to pass a diagnostics sink to the adapter. Diagnostics persistence is best-effort and does not change a successful sampler call into a failed Sampling.

log_sample_set(name: str, sample_set: SampleSet) → None

Attach a SampleSet in this run.

log_solution(name: str, solution: Solution) → None

Attach a Solution in this run.

This records a solution as a run-level attachment. Use log_solve when the solution is produced by a solver call and should be paired with the input instance.

log_solve(adapter: type[SolverAdapter], instance: Instance, store_diagnostics: bool = False, kwargs: Any) → Solution

Solve an Instance with an OMMX SolverAdapter and log a Solve entry.

The input Instance is cloned before calling the adapter, so adapter-side capability reductions do not mutate the caller’s object. The original input is always stored as the Solve input.

adapter must be a subclass of ommx.adapter.SolverAdapter. Keyword arguments are passed to adapter.solve(...) and recorded as Solve.adapter_options. The adapter class name is stored in Solve.adapter.

Adapter options are solve-scoped metadata, not run parameters. They do not appear in Experiment.run_parameters_df().

Adapter diagnostics are disabled by default. Set store_diagnostics=True to pass a diagnostics sink to the adapter and store recorded diagnostics with the Solve entry. Diagnostics persistence is best-effort. If diagnostics cannot be serialized or stored after the adapter returns a solution, the Solve entry is still recorded without diagnostics. store_diagnostics controls Experiment logging and is not recorded in Solve.adapter_options.

If the adapter raises before returning a Solution, this method records a failed Solve entry when possible, including diagnostics collected before the failure when store_diagnostics=True. Failed Solve entries have output=None.

log_with_codec(codec: type[AttachmentCodec[T]], name: str, value: T, compression: Literal["none", "zstd"] = 'none') → None

Encode a Python object with an attachment codec and attach it in this run.

The codec class must provide media_type, encode(value) -> bytes, and decode(bytes) -> object. OMMX owns only this protocol; concrete codecs should live in the package that owns the payload type. Set compression="zstd" to compress the encoded bytes transparently.

open_solve(adapter: type[SolverAdapter], instance: Instance, store_diagnostics: bool = False, kwargs: Any) → OpenSolve

Open a manual Solve scope for direct backend solver model access.

This returns a manual Solve context. Entering the context reserves a Solve ID, constructs the adapter with a cloned input Instance, and exposes the adapter’s solver_input. The caller can run backend-specific APIs, record adapter options that are set directly on the backend model, decode the backend output, and continue recording diagnostics until the context exits. The Solve entry is finalized on context exit. If adapter construction or the context body fails before decode succeeds, a failed or interrupted Solve is recorded when possible and the exception is re-raised.

property run_id: int

Read-only property.

Integer identifier of this run within its Experiment.