optuna.storages.JournalStorage
- class optuna.storages.JournalStorage(log_storage)[source]
Storage class for Journal storage 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.
Journal storage writes a record of every operation to the database as it is executed and at the same time, keeps a latest snapshot of the database in-memory. If the database crashes for any reason, the storage can re-establish the contents in memory by replaying the operations stored from the beginning.
Journal storage has several benefits over the conventional value logging storages.
The number of IOs can be reduced because of larger granularity of logs.
Journal storage has simpler backend API than value logging storage.
Journal storage keeps a snapshot in-memory so no need to add more cache.
Example
import optuna def objective(trial): ... storage = optuna.storages.JournalStorage( optuna.storages.JournalFileStorage("./journal.log"), ) study = optuna.create_study(storage=storage) study.optimize(objective)
In a Windows environment, an error message “A required privilege is not held by the client” may appear. In this case, you can solve the problem with creating storage by specifying
JournalFileOpenLock
as follows.file_path = "./journal.log" lock_obj = optuna.storages.JournalFileOpenLock(file_path) storage = optuna.storages.JournalStorage( optuna.storages.JournalFileStorage(file_path, lock_obj=lock_obj), )
Note
Added in v3.1.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.1.0.
Methods
check_trial_is_updatable
(trial_id, trial_state)Check whether a trial state is updatable.
create_new_study
(directions[, 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
FrozenStudy
objects.get_all_trials
(study_id[, deepcopy, states])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_directions
(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_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.
Read the trial ID of 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.
Clean up all connections to a database.
restore_replay_result
(snapshot)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_values
(trial_id, state[, values])Update the state and values 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.
- Parameters
log_storage (BaseJournalLogStorage) –
- check_trial_is_updatable(trial_id, trial_state)
Check whether a trial state is updatable.
- Parameters
trial_id (int) – ID of the trial. Only used for an error message.
trial_state (TrialState) – Trial state to check.
- Raises
RuntimeError – If the trial is already finished.
- Return type
None
- create_new_study(directions, study_name=None)[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
- Returns
ID of the created study.
- Raises
optuna.exceptions.DuplicatedStudyError – If a study with the same
study_name
already exists.- Return type
- create_new_trial(study_id, template_trial=None)[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 (int) – ID of the study.
template_trial (Optional[FrozenTrial]) – Template
FrozenTrial
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.- Return type
- get_all_studies()[source]
Read a list of
FrozenStudy
objects.- Returns
A list of
FrozenStudy
objects.- Return type
List[FrozenStudy]
- get_all_trials(study_id, deepcopy=True, states=None)[source]
Read all trials in a study.
- Parameters
- Returns
List of trials in the study.
- Raises
KeyError – If no study with the matching
study_id
exists.- Return type
- get_best_trial(study_id)
Return the trial with the best value in a study.
This method is valid only during single-objective optimization.
- Parameters
study_id (int) – 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.RuntimeError – If the study has more than one direction.
ValueError – If no trials have been completed.
- Return type
- get_n_trials(study_id, state=None)
Count the number of trials in a study.
- Parameters
study_id (int) – ID of the study.
state (Optional[Union[Tuple[TrialState, ...], TrialState]]) – Trial states to filter on. If
None
, include all states.
- Returns
Number of trials in the study.
- Raises
KeyError – If no study with the matching
study_id
exists.- Return type
- get_study_directions(study_id)[source]
Read whether a study maximizes or minimizes an objective.
- get_trial(trial_id)[source]
Read a trial.
- get_trial_id_from_study_id_trial_number(study_id, trial_number)[source]
Read the trial ID of a trial.
- get_trial_number_from_id(trial_id)
Read the trial number of a trial.
Note
The trial number is only unique within a study, and is sequential.
- 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.
- remove_session()
Clean up all connections to a database.
- Return type
None
- set_study_system_attr(study_id, key, value)[source]
Register an optuna-internal attribute to a study.
This method overwrites any existing attribute.
- set_study_user_attr(study_id, key, value)[source]
Register a user-defined attribute to a study.
This method overwrites any existing attribute.
- set_trial_intermediate_value(trial_id, step, intermediate_value)[source]
Report an intermediate value of an objective function.
This method overwrites any existing intermediate value associated with the given step.
- Parameters
- Raises
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type
None
- set_trial_param(trial_id, param_name, param_value_internal, distribution)[source]
Set a parameter to a trial.
- Parameters
- Raises
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type
None
- set_trial_state_values(trial_id, state, values=None)[source]
Update the state and values of a trial.
Set return values of an objective function to values argument. If values argument is not
None
, this method overwrites any existing trial values.- Parameters
trial_id (int) – ID of the trial.
state (TrialState) – New state of the trial.
values (Optional[Sequence[float]]) – Values of the objective function.
- 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.
- Return type
- set_trial_system_attr(trial_id, key, value)[source]
Set an optuna-internal attribute to a trial.
This method overwrites any existing attribute.
- Parameters
- Raises
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type
None
- set_trial_user_attr(trial_id, key, value)[source]
Set a user-defined attribute to a trial.
This method overwrites any existing attribute.
- Parameters
- Raises
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type
None