ommx.experiment

ommx.experiment records an optimization experiment as one OMMX Artifact. Use it when a single source problem produces several runs, for example different formulations, decomposition strategies, disabled constraints, or solver settings, and you want the resulting Artifact to answer:

• which shared dataset or baseline configuration was used,

• which run-level parameters should be compared as a table,

• which input ommx.Instance was actually solved or sampled, and

• which output ommx.Solution or ommx.SampleSet and adapter options came from each solver or sampler call.

An Experiment is a mutable session until it is committed. Experiment-level attachments store shared context, while each Run stores scalar parameters, run-level attachments, and zero or more Solve and Sampling records. Use Run.log_parameter(...) for values that should become columns in Experiment.run_parameters_df(), and use attachment methods for payloads such as JSON, instances, solutions, sample sets, logs, or caller-defined media types. Run.log_solve(...) calls an ommx.adapter.SolverAdapter, stores the original input instance and returned solution, and records adapter keyword arguments as solve metadata rather than run parameters. Run.log_sample(...) similarly records a sampler call as a separate Sampling whose output is the complete SampleSet.

Use Run as a context manager so closing the block records whether that trial finished, failed, or was interrupted. Experiment may also be used as a context manager for batch scripts, but interactive workflows often keep one Experiment open across notebook cells and call commit() explicitly after reviewing the closed runs. Run-close draft checkpoints are written after every Run by default; AutosavePolicy can batch, rate-limit, or disable them for large sweeps. On exceptional with Experiment(...) exit, OMMX publishes a checkpoint instead of advancing the success ref. A committed experiment is read-only. To add runs to a committed experiment, create a child session with Experiment.fork(...). Use Experiment.rename(...) to choose or update the local registry image reference before saving or pushing.

Classes

Name	Description
AutosavePolicy	Policy controlling rolling draft checkpoints after a Run closes.
Experiment	A collection of optimization experiment records stored as one OMMX Artifact.
ExperimentCheckpointRef	A Local Registry checkpoint that can restore an uncommitted Experiment.
ExperimentRef	A local-registry image reference that points to an Experiment artifact.
OpenSolve	Context manager for a manually executed Solve inside a Run.
Run	A mutable run being recorded inside an unsealed Experiment.
Sampling	Immutable record of one sampler call.
SealedRun	Immutable view of a closed Run in an Experiment.
Solve	Immutable record of one solver call.

Functions

Name	Description
list_experiment_checkpoints	List internal Experiment checkpoints by requested image name and lifecycle
list_experiments	List Experiment refs using the Local Registry's digest-addressed JSON cache.