experiment - MINTO - Management and Insight Tool for Optimization

minto.experiment

Module for managing optimization experiments.

This module provides the Experiment class for managing optimization experiments. The Experiment class handles experiment-level data (problems, instances, global parameters) while the Run class handles run-specific data (solutions, run parameters). This explicit separation replaces the previous implicit with-clause behavior.

Classes¶

Experiment¶

Experiment(name: str = (lambda: str(uuid.uuid4().hex[:8]))(), savedir: str | pathlib.Path = DEFAULT_RESULT_DIR, auto_saving: bool = True, collect_environment: bool = True, verbose_logging: bool = (lambda: _get_default_verbose_logging())(), log_config: minto.logging_config.LogConfig = LogConfig())

Class to manage optimization experiments.

This class provides a structured way to manage optimization experiments, handling experiment-level data (problems, instances, global parameters). Run-specific data is handled by the Run class through explicit run creation.

This design eliminates the previous implicit with-clause behavior where the storage location depended on context. Now, experiment-level and run-level operations are explicitly separated.

Methods¶

run¶

run()

Create a new run for this experiment.

This method explicitly creates a new Run object for logging run-specific data. Unlike the previous implicit with-clause behavior, this makes it clear that data logged to the returned Run object will be stored at the run level.

Returns:

Type	Description
``	A new Run instance for logging run-specific data.

finish_experiment¶

finish_experiment()

Finish the experiment and log completion information.

This method should be called when the experiment is complete to log the final statistics and elapsed time.

save¶

save(path: typing.Optional = None)

Save the experiment data to disk.

Parameters:

Name	Type	Description
`path`	`typing.Optional`	Optional path to save to. If None, uses default savedir.

log_global_problem¶

log_global_problem(problem_name: str | jm.Problem, problem: typing.Optional = None)

Log an optimization problem to the experiment (experiment-level data).

This is the preferred method for logging problems at the experiment level. Problems logged here are shared across all runs in the experiment.

Parameters:

Name	Type	Description
`problem_name`	`str	jm.Problem`
`problem`	`typing.Optional`	Problem object (if problem_name is a string).

log_global_instance¶

log_global_instance(instance_name: str | ommx_v1.Instance, instance: typing.Optional = None)

Log an optimization problem instance to the experiment.

This logs to experiment-level data.

This is the preferred method for logging instances at the experiment level. Instances logged here are shared across all runs in the experiment.

Parameters:

Name	Type	Description
`instance_name`	`str	ommx_v1.Instance`
`instance`	`typing.Optional`	Instance object (if instance_name is a string).

log_global_parameter¶

log_global_parameter(name: str, value: float | int | str | np.ndarray)

Log a parameter to the experiment (experiment-level data).

This is the preferred method for logging parameters at the experiment level. These parameters apply to the entire experiment, such as global configuration, dataset properties, or experiment setup. For run-specific parameters, use Run.log_parameter() method.

Parameters:

Name	Type	Description
`name`	`str`	Name of the parameter.
`value`	`float	int

log_global_params¶

log_global_params(params: dict)

Log multiple parameters to the experiment (experiment-level data).

This is the preferred method for logging multiple parameters at the experiment level.

Parameters:

Name	Type	Description
`params`	`dict`	Dictionary of parameter names and values. None values are automatically skipped.

log_global_config¶

log_global_config(name: str, value: dict)

Log a configuration object to the experiment (experiment-level data).

This is the preferred method for logging configuration objects at the experiment level. Use this for experiment-wide settings, metadata, or complex configuration objects.

Parameters:

Name	Type	Description
`name`	`str`	Name of the configuration object
`value`	`dict`	Dictionary containing the configuration data

log_global_object¶

log_global_object(name: str, value: dict)

Log a global object to the experiment (experiment-level data).

This is an alias for log_global_config() for consistency with the notebook API. Use this for experiment-wide objects that should be accessible across all runs.

Parameters:

Name	Type	Description
`name`	`str`	Name of the object
`value`	`dict`	Dictionary containing the object data

log_problem¶

log_problem(problem_name: str | jm.Problem, problem: typing.Optional = None)

.. deprecated:: Calling log_problem() on Experiment is deprecated. Use run.log_problem() directly for clearer semantics.

Parameters:

Name	Type	Description
`problem_name`	`str	jm.Problem`
`problem`	`typing.Optional`	Problem object (if problem_name is a string).

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.

log_instance¶

log_instance(instance_name: str | ommx_v1.Instance, instance: typing.Optional = None)

.. deprecated:: Calling log_instance() on Experiment is deprecated. Use run.log_instance() directly for clearer semantics.

Parameters:

Name	Type	Description
`instance_name`	`str	ommx_v1.Instance`
`instance`	`typing.Optional`	Instance object (if instance_name is a string).

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.

log_parameter¶

log_parameter(name: str, value: float | int | str | list | dict | np.ndarray)

.. deprecated:: Calling log_parameter() on Experiment is deprecated. Use run.log_parameter() directly for clearer semantics.

Parameters:

Name	Type	Description
`name`	`str`	Name of the parameter.
`value`	`float	int

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.

log_params¶

log_params(params: dict)

Log multiple parameters to the experiment (experiment-level data).

.. deprecated:: Use log_global_params() instead for clearer experiment-level data handling.

Parameters:

Name	Type	Description
`params`	`dict`	Dictionary of parameter names and values.

log_object¶

log_object(name: str, value: dict)

.. deprecated:: Calling log_object() on Experiment is deprecated. Use run.log_object() directly for clearer semantics.

Parameters:

Name	Type	Description
`name`	`str`	Name of the object
`value`	`dict`	Dictionary containing the object data

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.

log_solver¶

log_solver(solver_name: str | typ.Callable, solver: typing.Optional = None, exclude_params: typing.Optional = None) -> typing.Callable

Log solver name and parameters to the experiment.

This method creates a wrapped version of a solver function that automatically logs solver parameters and results. This is maintained for backward compatibility with the old interface, but the new explicit interface using Run.log_solver() is recommended for run-specific operations.

Parameters:

Name	Type	Description
`solver_name`	`str	typ.Callable`
`solver`	`typing.Optional`	Solver function (if solver_name is a string).
`exclude_params`	`typing.Optional`	List of parameter names to exclude from logging.

Returns:

Type	Description
`typing.Callable`	Wrapped solver function.

Raises:

Exception	Description
`TypeError`	If solver_name or solver have incorrect types.

load_from_dir¶

classmethod

load_from_dir(savedir: str | pathlib.Path) -> minto.experiment.Experiment

Load an experiment from a directory containing saved data.

Parameters:

Name	Type	Description
`savedir`	`str	pathlib.Path`

Returns:

Type	Description
`minto.experiment.Experiment`	Instance of the loaded experiment.

save_as_ommx_archive¶

save_as_ommx_archive(savefile: typing.Optional = None) -> ommx.artifact.Artifact

Save the experiment data as an OMMX artifact.

Parameters:

Name	Type	Description
`savefile`	`typing.Optional`	Path to save the OMMX artifact. If None, a default name is generated.

load_from_ommx_archive¶

classmethod

load_from_ommx_archive(savefile: str | pathlib.Path) -> minto.experiment.Experiment

Load an experiment from an OMMX artifact file.

Parameters:

Name	Type	Description
`savefile`	`str	pathlib.Path`

Returns:

Type	Description
`minto.experiment.Experiment`	Instance of the loaded experiment.

get_run_table¶

get_run_table() -> pandas.DataFrame

Get the run data as a table.

Returns:

Type	Description
`pandas.DataFrame`	pd.DataFrame: DataFrame containing the run data.

get_experiment_tables¶

get_experiment_tables() -> dict

Get the experiment data as a table.

Returns:

Type	Description
`dict`	dict[str, pd.DataFrame]: Dictionary containing the experiment data tables.

push_github¶

push_github(org: str, repo: str, name: typing.Optional = None, tag: typing.Optional = None) -> ommx.artifact.Artifact

Push the experiment data to a GitHub repository.

Returns:

Type	Description
`ommx.artifact.Artifact`	ox_artifact.Artifact: OMMX artifact containing the experiment data.

load_from_registry¶

classmethod

load_from_registry(imagename: str) -> minto.experiment.Experiment

Load an experiment from a Docker registry.

Parameters:

Name	Type	Description
`imagename`	`str`	Name of the Docker image containing the experiment data.

Returns:

Type	Description
`minto.experiment.Experiment`	Instance of the loaded experiment.

concat¶

classmethod

concat(experiments: list, name: typing.Optional = None, savedir: str | pathlib.Path = DEFAULT_RESULT_DIR, auto_saving: bool = True) -> minto.experiment.Experiment

Concatenate multiple experiments into a single experiment.

Parameters:

Name	Type	Description
`experiments`	`list`	List of Experiment instances to concatenate.
`name`	`typing.Optional`	Name of the concatenated experiment.
`savedir`	`str	pathlib.Path`
`auto_saving`	`bool`	Flag to enable automatic saving of the concatenated experiment

Returns:

Type	Description
`minto.experiment.Experiment`	Instance of the concatenated experiment.

get_environment_info¶

get_environment_info() -> typing.Optional

Get experiment environment metadata.

Returns:

Type	Description
`typing.Optional`	Environment metadata dictionary, or None if not collected.

print_environment_summary¶

print_environment_summary()

Print a summary of environment information.

log_solution¶

log_solution(solution_name: str | ommx_v1.Solution, solution: typing.Optional = None)

.. deprecated:: Calling log_solution() on Experiment is deprecated. Use run.log_solution() directly for clearer semantics.

Parameters:

Name	Type	Description
`solution_name`	`str	ommx_v1.Solution`
`solution`	`typing.Optional`	Solution object (if solution_name is a string).

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.

log_sampleset¶

log_sampleset(name: str | ommx_v1.SampleSet | jm.SampleSet | jm.experimental.SampleSet, value: typing.Optional = None)

.. deprecated:: Calling log_sampleset() on Experiment is deprecated. Use run.log_sampleset() directly for clearer semantics.

Parameters:

Name	Type	Description
`name`	`str	ommx_v1.SampleSet
`value`	`typing.Optional`	SampleSet object (if name is a string).

Raises:

Exception	Description
`RuntimeError`	If called outside of a run context.