optuna.storages.RedisStorage

class optuna.storages.RedisStorage(url: str)[source]

Storage class for Redis backend.

Note that library users can instantiate this class, but the attributes provided by this class are not supposed to be directly accessed by them.

Example

We create an RedisStorage instance using the given redis database URL.

>>> import optuna
>>>
>>> def objective(trial):
>>>     ...
>>>
>>> storage = optuna.storages.RedisStorage(
>>>     url='redis://passwd@localhost:port/db',
>>> )
>>>
>>> study = optuna.create_study(storage=storage)
>>> study.optimize(objective)
Parameters

url – URL of the redis storage, password and db are optional. (ie: redis://localhost:6379)

Note

If you use plan to use Redis as a storage mechanism for optuna, make sure Redis in installed and running. Please execute $ pip install -U redis to install redis python library.

Note

Added in v1.4.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v1.4.0.

__init__(url: str) None[source]

Methods

__init__(url)

check_trial_is_updatable(trial_id, trial_state)

Check whether a trial state is updatable.

create_new_study([study_name])

Create a new study from a name.

create_new_trial(study_id[, template_trial])

Create and add a new trial to a study.

delete_study(study_id)

Delete a study.

get_all_study_summaries()

Read a list of StudySummary objects.

get_all_trials(study_id[, deepcopy])

Read all trials in a study.

get_best_trial(study_id)

Return the trial with the best value in a study.

get_n_trials(study_id[, state])

Count the number of trials in a study.

get_study_direction(study_id)

Read whether a study maximizes or minimizes an objective.

get_study_id_from_name(study_name)

Read the ID of a study.

get_study_id_from_trial_id(trial_id)

Read the ID of a study to which a trial belongs.

get_study_name_from_id(study_id)

Read the study name of a study.

get_study_system_attrs(study_id)

Read the optuna-internal attributes of a study.

get_study_user_attrs(study_id)

Read the user-defined attributes of a study.

get_trial(trial_id)

Read a trial.

get_trial_number_from_id(trial_id)

Read the trial number of a trial.

get_trial_param(trial_id, param_name)

Read the parameter of a trial.

get_trial_params(trial_id)

Read the parameter dictionary of a trial.

get_trial_system_attrs(trial_id)

Read the optuna-internal attributes of a trial.

get_trial_user_attrs(trial_id)

Read the user-defined attributes of a trial.

read_trials_from_remote_storage(study_id)

Make an internal cache of trials up-to-date.

remove_session()

Clean up all connections to a database.

set_study_direction(study_id, direction)

Register an optimization problem direction to a study.

set_study_system_attr(study_id, key, value)

Register an optuna-internal attribute to a study.

set_study_user_attr(study_id, key, value)

Register a user-defined attribute to a study.

set_trial_intermediate_value(trial_id, step, ...)

Report an intermediate value of an objective function.

set_trial_param(trial_id, param_name, ...)

Set a parameter to a trial.

set_trial_state(trial_id, state)

Update the state of a trial.

set_trial_system_attr(trial_id, key, value)

Set an optuna-internal attribute to a trial.

set_trial_user_attr(trial_id, key, value)

Set a user-defined attribute to a trial.

set_trial_value(trial_id, value)

Set a return value of an objective function.

check_trial_is_updatable(trial_id: int, trial_state: optuna.trial._state.TrialState) None

Check whether a trial state is updatable.

Parameters
  • trial_id – ID of the trial. Only used for an error message.

  • trial_state – Trial state to check.

Raises

RuntimeError – If the trial is already finished.

create_new_study(study_name: Optional[str] = None) int[source]

Create a new study from a name.

If no name is specified, the storage class generates a name. The returned study ID is unique among all current and deleted studies.

Parameters

study_name – Name of the new study to create.

Returns

ID of the created study.

Raises

optuna.exceptions.DuplicatedStudyError – If a study with the same study_name already exists.

create_new_trial(study_id: int, template_trial: Optional[FrozenTrial] = None) int[source]

Create and add a new trial to a study.

The returned trial ID is unique among all current and deleted trials.

Parameters
  • study_id – ID of the study.

  • template_trial – Template FronzenTrial with default user-attributes, system-attributes, intermediate-values, and a state.

Returns

ID of the created trial.

Raises

KeyError – If no study with the matching study_id exists.

delete_study(study_id: int) None[source]

Delete a study.

Parameters

study_id – ID of the study.

Raises

KeyError – If no study with the matching study_id exists.

get_all_study_summaries() List[StudySummary][source]

Read a list of StudySummary objects.

Returns

A list of StudySummary objects.

get_all_trials(study_id: int, deepcopy: bool = True) List[FrozenTrial][source]

Read all trials in a study.

Parameters
  • study_id – ID of the study.

  • deepcopy – Whether to copy the list of trials before returning. Set to True if you intend to update the list or elements of the list.

Returns

List of trials in the study.

Raises

KeyError – If no study with the matching study_id exists.

get_best_trial(study_id: int) optuna.trial._frozen.FrozenTrial[source]

Return the trial with the best value in a study.

Parameters

study_id – ID of the study.

Returns

The trial with the best objective value among all finished trials in the study.

Raises
  • KeyError – If no study with the matching study_id exists.

  • ValueError – If no trials have been completed.

get_n_trials(study_id: int, state: Optional[TrialState] = None) int[source]

Count the number of trials in a study.

Parameters
  • study_id – ID of the study.

  • stateTrialState to filter trials.

Returns

Number of trials in the study.

Raises

KeyError – If no study with the matching study_id exists.

get_study_direction(study_id: int) optuna._study_direction.StudyDirection[source]

Read whether a study maximizes or minimizes an objective.

Parameters

study_id – ID of a study.

Returns

Optimization direction of the study.

Raises

KeyError – If no study with the matching study_id exists.

get_study_id_from_name(study_name: str) int[source]

Read the ID of a study.

Parameters

study_name – Name of the study.

Returns

ID of the study.

Raises

KeyError – If no study with the matching study_name exists.

get_study_id_from_trial_id(trial_id: int) int[source]

Read the ID of a study to which a trial belongs.

Parameters

trial_id – ID of the trial.

Returns

ID of the study.

Raises

KeyError – If no trial with the matching trial_id exists.

get_study_name_from_id(study_id: int) str[source]

Read the study name of a study.

Parameters

study_id – ID of the study.

Returns

Name of the study.

Raises

KeyError – If no study with the matching study_id exists.

get_study_system_attrs(study_id: int) Dict[str, Any][source]

Read the optuna-internal attributes of a study.

Parameters

study_id – ID of the study.

Returns

Dictionary with the optuna-internal attributes of the study.

Raises

KeyError – If no study with the matching study_id exists.

get_study_user_attrs(study_id: int) Dict[str, Any][source]

Read the user-defined attributes of a study.

Parameters

study_id – ID of the study.

Returns

Dictionary with the user attributes of the study.

Raises

KeyError – If no study with the matching study_id exists.

get_trial(trial_id: int) optuna.trial._frozen.FrozenTrial[source]

Read a trial.

Parameters

trial_id – ID of the trial.

Returns

Trial with a matching trial ID.

Raises

KeyError – If no trial with the matching trial_id exists.

get_trial_number_from_id(trial_id: int) int[source]

Read the trial number of a trial.

Note

The trial number is only unique within a study, and is sequential.

Parameters

trial_id – ID of the trial.

Returns

Number of the trial.

Raises

KeyError – If no trial with the matching trial_id exists.

get_trial_param(trial_id: int, param_name: str) float[source]

Read the parameter of a trial.

Parameters
  • trial_id – ID of the trial.

  • param_name – Name of the parameter.

Returns

Internal representation of the parameter.

Raises

KeyError – If no trial with the matching trial_id exists. If no such parameter exists.

get_trial_params(trial_id: int) Dict[str, Any]

Read the parameter dictionary of a trial.

Parameters

trial_id – ID of the trial.

Returns

Dictionary of a parameters. Keys are parameter names and values are internal representations of the parameter values.

Raises

KeyError – If no trial with the matching trial_id exists.

get_trial_system_attrs(trial_id: int) Dict[str, Any]

Read the optuna-internal attributes of a trial.

Parameters

trial_id – ID of the trial.

Returns

Dictionary with the optuna-internal attributes of the trial.

Raises

KeyError – If no trial with the matching trial_id exists.

get_trial_user_attrs(trial_id: int) Dict[str, Any]

Read the user-defined attributes of a trial.

Parameters

trial_id – ID of the trial.

Returns

Dictionary with the user-defined attributes of the trial.

Raises

KeyError – If no trial with the matching trial_id exists.

read_trials_from_remote_storage(study_id: int) None[source]

Make an internal cache of trials up-to-date.

Parameters

study_id – ID of the study.

Raises

KeyError – If no study with the matching study_id exists.

remove_session() None

Clean up all connections to a database.

set_study_direction(study_id: int, direction: optuna._study_direction.StudyDirection) None[source]

Register an optimization problem direction to a study.

Parameters
Raises
  • KeyError – If no study with the matching study_id exists.

  • ValueError – If the direction is already set and the passed direction is the opposite direction or NOT_SET.

set_study_system_attr(study_id: int, key: str, value: Any) None[source]

Register an optuna-internal attribute to a study.

This method overwrites any existing attribute.

Parameters
  • study_id – ID of the study.

  • key – Attribute key.

  • value – Attribute value. It should be JSON serializable.

Raises

KeyError – If no study with the matching study_id exists.

set_study_user_attr(study_id: int, key: str, value: Any) None[source]

Register a user-defined attribute to a study.

This method overwrites any existing attribute.

Parameters
  • study_id – ID of the study.

  • key – Attribute key.

  • value – Attribute value. It should be JSON serializable.

Raises

KeyError – If no study with the matching study_id exists.

set_trial_intermediate_value(trial_id: int, step: int, intermediate_value: float) None[source]

Report an intermediate value of an objective function.

This method overwrites any existing intermediate value associated with the given step.

Parameters
  • trial_id – ID of the trial.

  • step – Step of the trial (e.g., the epoch when training a neural network).

  • intermediate_value – Intermediate value corresponding to the step.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

set_trial_param(trial_id: int, param_name: str, param_value_internal: float, distribution: optuna.distributions.BaseDistribution) None[source]

Set a parameter to a trial.

Parameters
  • trial_id – ID of the trial.

  • param_name – Name of the parameter.

  • param_value_internal – Internal representation of the parameter value.

  • distribution – Sampled distribution of the parameter.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

set_trial_state(trial_id: int, state: optuna.trial._state.TrialState) bool[source]

Update the state of a trial.

Parameters
  • trial_id – ID of the trial.

  • state – New state of the trial.

Returns

True if the state is successfully updated. False if the state is kept the same. The latter happens when this method tries to update the state of RUNNING trial to RUNNING.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

set_trial_system_attr(trial_id: int, key: str, value: Any) None[source]

Set an optuna-internal attribute to a trial.

This method overwrites any existing attribute.

Parameters
  • trial_id – ID of the trial.

  • key – Attribute key.

  • value – Attribute value. It should be JSON serializable.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

set_trial_user_attr(trial_id: int, key: str, value: Any) None[source]

Set a user-defined attribute to a trial.

This method overwrites any existing attribute.

Parameters
  • trial_id – ID of the trial.

  • key – Attribute key.

  • value – Attribute value. It should be JSON serializable.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

set_trial_value(trial_id: int, value: float) None[source]

Set a return value of an objective function.

This method overwrites any existing trial value.

Parameters
  • trial_id – ID of the trial.

  • value – Value of the objective function.

Raises
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.