Base

Generic Storage Protocol

Implement a generic protocol to allow Orion to communicate using different storage backend.

class orion.storage.base.BaseStorageProtocol[source]

Implement a generic protocol to allow Orion to communicate using different storage backend

Attributes:
instance

Methods

count_broken_trials(experiment) Count the number of broken trials
count_completed_trials(experiment) Count the number of completed trials
create_benchmark(config) Insert a new benchmark inside the database
create_experiment(config) Insert a new experiment inside the database
delete_experiment([experiment, uid]) Delete matching experiments from the database
delete_trials([experiment, uid, where]) Delete matching trials from the database
fetch_benchmark(query[, selection]) Fetch all benchmarks that match the query
fetch_experiments(query[, selection]) Fetch all experiments that match the query
fetch_lost_trials(experiment) Fetch all trials that have a heartbeat older than some given time delta (2 minutes by default)
fetch_noncompleted_trials(experiment) Fetch all non completed trials
fetch_pending_trials(experiment) Fetch all trials that are available to be executed by a worker, this includes new, suspended and interrupted trials
fetch_trials([experiment, uid, where]) Fetch all the trials of an experiment in the database
fetch_trials_by_status(experiment, status) Fetch all trials with the given status
get_trial([trial, uid]) Fetch a single trial
push_trial_results(trial) Push the trial’s results to the database
register_lie(trial) Register a fake trial created by the strategist.
register_trial(trial) Create a new trial to be executed
reserve_trial(experiment) Select a pending trial and reserve it for the worker
retrieve_result(trial, *args, **kwargs) Fetch the result from a given medium (file, db, socket, etc..) for a given trial and insert it into the trial object
set_trial_status(trial, status[, heartbeat, was]) Update the trial status and the heartbeat
update_experiment([experiment, uid, where]) Update the fields of a given experiment
update_heartbeat(trial) Update trial’s heartbeat
update_trial([trial, uid, where]) Update fields of a given trial
update_trials([experiment, uid, where]) Update trials of a given experiment matching a query
count_broken_trials(experiment)[source]

Count the number of broken trials

count_completed_trials(experiment)[source]

Count the number of completed trials

create_benchmark(config)[source]

Insert a new benchmark inside the database

create_experiment(config)[source]

Insert a new experiment inside the database

delete_experiment(experiment=None, uid=None)[source]

Delete matching experiments from the database

Parameters:
experiment: Experiment, optional

experiment object to retrieve from the database

uid: str, optional

experiment id used to retrieve the trial object

Returns:
Number of experiments deleted.
Raises:
UndefinedCall

if both experiment and uid are not set

AssertionError

if both experiment and uid are provided and they do not match

delete_trials(experiment=None, uid=None, where=None)[source]

Delete matching trials from the database

Parameters:
experiment: Experiment, optional

experiment object to retrieve from the database

uid: str, optional

experiment id used to retrieve the trial object

where: Optional[dict]

constraint trials must respect

Returns:
Number of trials deleted.
Raises:
UndefinedCall

if both experiment and uid are not set

AssertionError

if both experiment and uid are provided and they do not match

fetch_benchmark(query, selection=None)[source]

Fetch all benchmarks that match the query

fetch_experiments(query, selection=None)[source]

Fetch all experiments that match the query

fetch_lost_trials(experiment)[source]

Fetch all trials that have a heartbeat older than some given time delta (2 minutes by default)

fetch_noncompleted_trials(experiment)[source]

Fetch all non completed trials

fetch_pending_trials(experiment)[source]

Fetch all trials that are available to be executed by a worker, this includes new, suspended and interrupted trials

fetch_trials(experiment=None, uid=None, where=None)[source]

Fetch all the trials of an experiment in the database

Parameters:
experiment: Experiment, optional

experiment object to retrieve from the database

uid: str, optional

experiment id used to retrieve the trial object

where: Optional[dict]

constraint trials must respect

Returns:
return none if the experiment is not found,
Raises:
UndefinedCall

if both experiment and uid are not set

AssertionError

if both experiment and uid are provided and they do not match

fetch_trials_by_status(experiment, status)[source]

Fetch all trials with the given status

get_trial(trial=None, uid=None)[source]

Fetch a single trial

Parameters:
trial: Trial, optional

trial object to retrieve from the database

uid: str, optional

trial id used to retrieve the trial object

Returns:
return none if the trial is not found,
Raises:
UndefinedCall

if both trial and uid are not set

AssertionError

if both trial and uid are provided and they do not match

push_trial_results(trial)[source]

Push the trial’s results to the database

register_lie(trial)[source]

Register a fake trial created by the strategist.

The main difference between fake trial and orignal ones is the addition of a fake objective result, and status being set to completed. The id of the fake trial is different than the id of the original trial, but the original id can be computed using the hashcode on parameters of the fake trial. See mod:orion.core.worker.strategy for more information and the Strategist object and generation of fake trials.

Parameters:
trial: `Trial` object

Fake trial to register in the database

register_trial(trial)[source]

Create a new trial to be executed

reserve_trial(experiment)[source]

Select a pending trial and reserve it for the worker

Returns:
Returns the reserved trial or None if no trials were found
retrieve_result(trial, *args, **kwargs)[source]

Fetch the result from a given medium (file, db, socket, etc..) for a given trial and insert it into the trial object

set_trial_status(trial, status, heartbeat=None, was=None)[source]

Update the trial status and the heartbeat

Parameters:
trial: `Trial` object

Trial object to update in the database.

status: str

Status to be set to the trial

heartbeat: datetime, optional

New heartbeat to update simultaneously with status

was: str, optional

The status the trial should be set to in the database. If None, current trial.status will be used. This is used to ensure coherence in the database, protecting against race conditions for instance.

Raises:
FailedUpdate

The exception is raised if the status of the trial object does not match the status in the database

update_experiment(experiment=None, uid=None, where=None, **kwargs)[source]

Update the fields of a given experiment

Parameters:
experiment: Experiment, optional

experiment object to retrieve from the database

uid: str, optional

experiment id used to retrieve the trial object

where: Optional[dict]

constraint experiment must respect

**kwargs: dict

a dictionary of fields to update

Returns:
returns true if the underlying storage was updated
Raises:
UndefinedCall

if both experiment and uid are not set

AssertionError

if both experiment and uid are provided and they do not match

update_heartbeat(trial)[source]

Update trial’s heartbeat

update_trial(trial=None, uid=None, where=None, **kwargs)[source]

Update fields of a given trial

Parameters:
trial: Trial, optional

trial object to update in the database

uid: str, optional

id of the trial to update in the database

where: Optional[dict]

constraint trials must respect. Note: useful to handle race conditions.

**kwargs: dict

a dictionary of fields to update

Raises:
UndefinedCall

if both trial and uid are not set

AssertionError

if both trial and uid are provided and they do not match

update_trials(experiment=None, uid=None, where=None, **kwargs)[source]

Update trials of a given experiment matching a query

Parameters:
experiment: Experiment, optional

experiment object to retrieve from the database

uid: str, optional

experiment id used to retrieve the trial object

where: Optional[dict]

constraint trials must respect

**kwargs: dict

a dictionary of fields to update

Raises:
UndefinedCall

if both experiment and uid are not set

AssertionError

if both experiment and uid are provided and they do not match

exception orion.storage.base.FailedUpdate[source]

Exception raised when we are unable to update a trial’ status

exception orion.storage.base.MissingArguments[source]

Raised when calling a function without the minimal set of parameters

class orion.storage.base.ReadOnlyStorageProtocol(protocol)[source]

Read-only interface from a storage protocol.

class orion.storage.base.Storage[source]

Storage protocol is a generic way of allowing Orion to interface with different storage. MongoDB, track, cometML, MLFLow, etc…

Notes

When retrieving an already initialized Storage object you should use get_storage. Storage() should only be used for initialization purposes as get_storage raises more granular error messages.

Examples

>>> Storage('track', uri='file://orion_test.json')
>>> Storage('legacy', experiment=...)
Attributes:
instance
orion.storage.base.get_storage()[source]

Return current storage

This is a wrapper around the Storage Singleton object to provide better error message when it is used without being initialized.

Raises:
RuntimeError

If the underlying storage was not initialized prior to calling this function

Notes

To initialize the underlying storage you must first call Storage(…) with the appropriate arguments for the chosen backend

orion.storage.base.get_uid(item=None, uid=None, force_uid=True)[source]

Return uid either from item or directly uid.

Parameters:
item: Experiment or Trial, optional

Object with .id attribute

uid: str, optional

str id representation

force_uid: bool, optional

If True, at least one of item or uid must be passed.

Raises:
UndefinedCall

if both item and uid are not set and force_uid is True

AssertionError

if both item and uid are provided and they do not match

orion.storage.base.setup_storage(storage=None, debug=False)[source]

Create the storage instance from a configuration.

Parameters:
config: dict, optional

Configuration for the storage backend. If not defined, global configuration is used.

debug: bool, optional

If using in debug mode, the storage config is overrided with legacy:EphemeralDB. Defaults to False.