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.
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.
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.
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.
- 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.
state –
TrialState
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.
- 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 orNOT_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 ofRUNNING
trial toRUNNING
.- 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.