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) → 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.

log_file(name: str, path: str | PathLike | Path, media_type: Optional[str] = None, filename: Optional[str] = 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.

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) → 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.

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_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, 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().

log_with_codec(codec: type[AttachmentCodec[T]], name: str, value: T) → 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.

property run_id: int

Read-only property.

Integer identifier of this run within its Experiment.