minto

minto#

Submodules#

Classes#

Experiment

Class to manage optimization experiments.

Package Contents#

class Experiment#

Class to manage optimization experiments.

This class provides a structured way to manage optimization experiments, including logging of problems, instances, solutions, and parameters. It supports both experiment-wide data and run-specific data, with automatic saving capabilities and artifact creation.

name#

Name of the experiment.

Type:

str

savedir#

Directory path for saving experiment data.

Type:

pathlib.Path

auto_saving#

Flag to enable automatic saving of experiment data.

Type:

bool

timestamp#

Timestamp of the experiment creation.

Type:

datetime

_running#

Flag to track the current run status.

Type:

bool

_run_id#

ID of the current run.

Type:

int

Properties:

experiment_name (str): Full name of the experiment with timestamp. database (Database): Database instance for storing experiment data.

name: str = ''#
savedir: pathlib.Path#
auto_saving: bool = True#
timestamp: datetime.datetime#
run() → Experiment#

Start a new experiment run.

Returns:

Instance of the current experiment run.

Return type:

Experiment

close_run()#

Close the current experiment run.

This method should be called to properly end the current run.

save(path: str | pathlib.Path | None = None)#

Save the experiment database to the disk.

get_current_datastore() → minto.v1.datastore.DataStore#

Get the current DataStore object.

log_data(name: str, data: Any, storage_name: str)#

Log data to the experiment database.

This method is not intended to be called directly by the user. Instead, users should use other log_* methods. Other log_* methods wrap this method to save data to the dataspace. If the current experiment is not running, the data is saved to .dataspace.experiment_datastore. If the current experiment is running, the data is saved to .dataspace.run_datastores[self._run_id].

Parameters:

  • name – Name of the data

  • data – Data object to be saved

  • storage_name – Name of the storage object

log_problem(problem_name: str | jijmodeling.Problem, problem: jijmodeling.Problem | None = None)#

Log an optimization problem to the experiment database.

Parameters:

  • problem_name – Name of the problem, or the problem object itself.

  • problem – Problem object (if problem_name is a string).

If a run is active, the problem is saved with the current run ID.

log_instance(instance_name: str | ommx.v1.Instance, instance: ommx.v1.Instance | None = None)#

Log an optimization problem instance to the experiment database.

Logs an ommx.v1.Instance to the experiment database. If instance_name is not specified, it will be named sequentially as “0”, “1”, “2”, etc.

Parameters:

  • instance_name – Name of the instance, or the instance object itself.

  • instance – Instance object (if instance_name is a string).

Examples

>>> import minto
>>> exp = minto.Experiment("exp1")
>>> instance = ommx_v1.Instance()
>>> exp.log_instance("instance1", instance)
log_solution(solution_name: str | ommx.v1.Solution, solution: ommx.v1.Solution | None = None)#

Log an optimization solution to the experiment database.

Parameters:

  • solution_name – Name of the solution, or the solution object itself.

  • solution – Solution object (if solution_name is a string).

If a run is active, the solution is saved with the current run ID.

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

Log a parameter to the experiment database.

This method allows logging of both simple scalar values (float, int, str) and complex data structures (list, dict, numpy.ndarray) as parameters. Complex data structures are first checked for JSON serializability and then stored as objects with a “parameter_” prefix to distinguish them from regular parameters.

Parameters:

  • name (str) – Name of the parameter. Must be a string that uniquely identifies the parameter within the experiment.

  • value (Union[float, int, str, list, dict, numpy.ndarray]) – Value of the parameter. Can be one of the following types: - float: Floating point numbers - int: Integer numbers - str: String values - list: Python lists (must be JSON serializable) - dict: Python dictionaries (must be JSON serializable) - numpy.ndarray: NumPy arrays (must be JSON serializable)

Raises:

  • ValueError – If a complex data structure (list, dict, numpy.ndarray) is not JSON serializable. This can happen if the structure contains objects that cannot be converted to JSON (e.g., custom objects, functions).

  • TypeError – If the name is not a string or if the value is not one of the supported types.

Note

  • For complex data structures (list, dict, numpy.ndarray), the value is stored both as a parameter and as an object with a “parameter_” prefix.

  • If the experiment is running (i.e., within a run context), the parameter is saved with the current run ID. Otherwise, it is saved as experiment-wide data.

  • NumPy arrays are converted to nested lists when serialized to JSON.

Examples

>>> exp = Experiment("example")
>>> # Logging simple scalar values
>>> exp.log_parameter("learning_rate", 0.001)
>>> exp.log_parameter("batch_size", 32)

>>> # Logging complex data structures
>>> exp.log_parameter("layer_sizes", [64, 128, 64])
>>> exp.log_parameter("model_config", {"activation": "relu", "dropout": 0.5})
>>> exp.log_parameter("weights", np.array([1.0, 2.0, 3.0]))
log_params(params: dict[str, float | int])#

Log multiple parameters to the experiment database.

Parameters:

params – Dictionary of parameter names and values.

If a run is active, the parameters are saved with the current run ID. Else, they are saved as experiment-wide data.

log_object(name: str, value: dict[str, Any])#

Log a custom object to the experiment database.

Parameters:

  • name – Name of the object

  • value – Dictionary containing the object data

If a run is active, the object is saved with the current run ID.

log_sampleset(name: str | ommx.v1.SampleSet | jijmodeling.SampleSet | jijmodeling.experimental.SampleSet, value: ommx.v1.SampleSet | None = None)#

Log a SampleSet to the experiment or run database.

log_solver(solver_name: str | Callable[P, R], solver: Callable[P, R] | None = None, *, exclude_params: list[str] | None = None) → Callable[P, R]#

Log solver name and parameters to the dataspace.

When the wrapped solver function is called, the following actions are performed:

  • The solver name is logged as a parameter with .log_parameter(“solver_name”, solver_name).

  • Each keyword argument passed to the solver function is logged as a parameter if it is of type int, float, or str.

  • If a keyword argument is of type jm.Problem, it is logged as a problem.

  • If a keyword argument is of type ommx_v1.Instance, it is logged as an instance.

  • After the solver function executes, the result is logged as a sampleset if it is of type ommx_v1.SampleSet, jm.SampleSet, or jm.experimental.SampleSet.

  • If the result is of type ommx_v1.Solution, it is logged as a solution.

Parameters:

solver – Solver function to be logged.

Returns:

Wrapped solver function.

Return type:

typ.Callable[P, R]

Example

`python import minto exp = minto.Experiment("exp1") result = exp.log_solver(solver)(parameter=1) exp.dataspace.experiment_datastore.parameters # {'solver_name': 'solver', 'parameter': 1} `

classmethod load_from_dir(savedir: str | pathlib.Path) → Experiment#

Load an experiment from a directory containing saved data.

Parameters:

savedir – Directory path containing the saved experiment data.

Returns:

Instance of the loaded experiment.

Return type:

Experiment

save_as_ommx_archive(savefile: str | pathlib.Path | None = None) → ommx.artifact.Artifact#

Save the experiment data as an OMMX artifact.

Parameters:

savefile – Path to save the OMMX artifact. If None, a default name is generated.

classmethod load_from_ommx_archive(savefile: str | pathlib.Path) → Experiment#

Load an experiment from an OMMX artifact file.

Parameters:

savefile – Path to the OMMX artifact file.

Returns:

Instance of the loaded experiment.

Return type:

Experiment

get_run_table() → pandas.DataFrame#

Get the run data as a table.

Returns:

DataFrame containing the run data.

Return type:

pd.DataFrame

get_experiment_tables() → dict[str, pandas.DataFrame]#

Get the experiment data as a table.

Returns:

DataFrame containing the experiment data.

Return type:

pd.DataFrame

push_github(org: str, repo: str, name: str | None = None, tag: str | None = None) → ommx.artifact.Artifact#

Push the experiment data to a GitHub repository.

Returns:

OMMX artifact containing the experiment data.

Return type:

ox_artifact.Artifact

property runs: list[minto.v1.datastore.DataStore]#

Get the list of run datastores in the experiment.

This property is a syntax sugar for accessing the run datastores in the experiment. Returns the same result as self.dataspace.run_datastores.

Returns:

List of run datastores in the experiment.

Return type:

list[DataStore]

classmethod load_from_registry(imagename: str) → Experiment#

Load an experiment from a Docker registry.

Parameters:

imagename – Name of the Docker image containing the experiment data.

Returns:

Instance of the loaded experiment.

Return type:

Experiment

classmethod concat(experiments: list[Experiment], name: str | None = None, savedir: str | pathlib.Path = DEFAULT_RESULT_DIR, auto_saving: bool = True) → Experiment#

Concatenate multiple experiments into a single experiment.

Parameters:

  • experiments – List of Experiment instances to concatenate.

  • name – Name of the concatenated experiment.

  • savedir – Directory path for saving the concatenated experiment data.

  • auto_saving – Flag to enable automatic saving of the concatenated experiment

Example

`python import minto exp1 = minto.Experiment("exp1") exp2 = minto.Experiment("exp2") exp3 = minto.Experiment("exp3") new_exp = minto.Experiment.concat([exp1, exp2, exp3]) `

Returns:

Instance of the concatenated experiment.

Return type:

Experiment

Contents