optuna.storages.JournalStorage

class optuna.storages.JournalStorage(log_storage)[source]

Journal 存储后端的存储类。

请注意，库用户可以实例化此类，但不应直接访问此类提供的属性。

Journal 存储会在每次操作执行时将其记录写入数据库，同时在内存中保留数据库的最新快照。如果数据库因任何原因崩溃，存储可以通过从头重放存储的操作来在内存中重建内容。

Journal 存储相对于传统的值日志存储具有以下几个优点。

由于日志粒度更大，可以减少 I/O 次数。
Journal 存储具有比值日志存储更简单的后端 API。
Journal 存储在内存中保留快照，因此无需添加更多缓存。

示例

import optuna

def objective(trial): ...

storage = optuna.storages.JournalStorage(
    optuna.storages.journal.JournalFileBackend("./optuna_journal_storage.log")
)

study = optuna.create_study(storage=storage)
study.optimize(objective)

在 Windows 环境中，可能会出现错误消息“客户端未持有所需的权限”。在这种情况下，您可以通过指定 JournalFileOpenLock 创建存储来解决此问题，如下所示。

file_path = "./optuna_journal_storage.log"
lock_obj = optuna.storages.journal.JournalFileOpenLock(file_path)

storage = optuna.storages.JournalStorage(
    optuna.storages.journal.JournalFileBackend(file_path, lock_obj=lock_obj),
)

方法

`check_trial_is_updatable`(trial_id, trial_state)	检查 trial 状态是否可更新。
`create_new_study`(directions[, study_name])	从名称创建一个新的 study。
`create_new_trial`(study_id[, template_trial])	创建新 trial 并将其添加到 study 中。
`delete_study`(study_id)	删除一个 study。
`get_all_studies`()	读取 `FrozenStudy` 对象的列表。
`get_all_trials`(study_id[, deepcopy, states])	读取 study 中的所有 trial。
`get_best_trial`(study_id)	返回 study 中具有最佳值的 trial。
`get_n_trials`(study_id[, state])	计算 study 中的 trial 数量。
`get_study_directions`(study_id)	读取 study 是最大化还是最小化目标。
`get_study_id_from_name`(study_name)	读取 study 的 ID。
`get_study_name_from_id`(study_id)	读取 study 的 study 名称。
`get_study_system_attrs`(study_id)	读取 study 的 optuna 内部属性。
`get_study_user_attrs`(study_id)	读取 study 的用户定义属性。
`get_trial`(trial_id)	读取一个 trial。
`get_trial_id_from_study_id_trial_number`(...)	读取 trial 的 trial ID。
`get_trial_number_from_id`(trial_id)	读取 trial 的 trial 编号。
`get_trial_param`(trial_id, param_name)	读取 trial 的参数。
`get_trial_params`(trial_id)	读取 trial 的参数字典。
`get_trial_system_attrs`(trial_id)	读取 trial 的 optuna 内部属性。
`get_trial_user_attrs`(trial_id)	读取 trial 的用户定义属性。
`remove_session`()	清理到数据库的所有连接。
`restore_replay_result`(snapshot)
`set_study_system_attr`(study_id, key, value)	向 study 注册 optuna 内部属性。
`set_study_user_attr`(study_id, key, value)	向 study 注册用户定义属性。
`set_trial_intermediate_value`(trial_id, step, ...)	报告目标函数的中间值。
`set_trial_param`(trial_id, param_name, ...)	为 trial 设置参数。
`set_trial_state_values`(trial_id, state[, values])	更新 trial 的状态和值。
`set_trial_system_attr`(trial_id, key, value)	为 trial 设置 optuna 内部属性。
`set_trial_user_attr`(trial_id, key, value)	为 trial 设置用户定义属性。

参数:: log_storage (BaseJournalBackend)

check_trial_is_updatable(trial_id, trial_state)

检查 trial 状态是否可更新。

参数:

trial_id (int) – trial 的 ID。仅用于错误消息。
trial_state (TrialState) – 要检查的 trial 状态。

抛出:

UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

None

create_new_study(directions, study_name=None)[source]

从名称创建一个新的 study。

如果未指定名称，则存储类将生成一个名称。返回的 study ID 在所有当前和已删除的 study 中是唯一的。

参数:

directions (Sequence[StudyDirection]) – 方向序列，其元素为 MAXIMIZE 或 MINIMIZE。
study_name (str | None) – 要创建的新 study 的名称。

返回:

创建的 study 的 ID。

抛出:

optuna.exceptions.DuplicatedStudyError – 如果具有相同 study_name 的 study 已存在。

返回类型:

int

create_new_trial(study_id, template_trial=None)[source]

创建新 trial 并将其添加到 study 中。

返回的 trial ID 在所有当前和已删除的 trial 中是唯一的。

参数:

study_id (int) – study 的 ID。
template_trial (FrozenTrial | None) – 具有默认用户属性、系统属性、中间值和状态的 FrozenTrial 模板。

返回:

创建的 trial 的 ID。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。

返回类型:

int

delete_study(study_id)[source]

删除一个 study。

参数:: study_id (int) – study 的 ID。
抛出:: KeyError – 如果不存在匹配 study_id 的 study。
返回类型:: None

get_all_studies()[source]

读取 FrozenStudy 对象的列表。

返回:: 一个 FrozenStudy 对象列表，按 study_id 排序。
返回类型:: list[FrozenStudy]

get_all_trials(study_id, deepcopy=True, states=None)[source]

读取 study 中的所有 trial。

参数:

study_id (int) – study 的 ID。
deepcopy (bool) – 返回前是否复制 trial 列表。如果您打算更新列表或列表中的元素，请设置为 True。
states (Container[TrialState] | None) – 用于过滤的 trial 状态。如果为 None，则包含所有状态。

返回:

study 中的 trial 列表，按 trial_id 排序。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。

返回类型:

list[FrozenTrial]

get_best_trial(study_id)

返回 study 中具有最佳值的 trial。

此方法仅在单目标优化期间有效。

参数:

study_id (int) – study 的 ID。

返回:

study 中所有已完成 trial 中具有最佳目标值的 trial。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。
RuntimeError – 如果 study 具有多个方向。
ValueError – 如果没有 trial 已完成。

返回类型:

FrozenTrial

get_n_trials(study_id, state=None)

计算 study 中的 trial 数量。

参数:

study_id (int) – study 的 ID。
state (tuple[TrialState, ...] | TrialState | None) – 用于过滤的 trial 状态。如果为 None，则包含所有状态。

返回:

study 中的 trial 数量。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。

返回类型:

int

get_study_directions(study_id)[source]

读取 study 是最大化还是最小化目标。

参数:: study_id (int) – study 的 ID。
返回:: study 的优化方向列表。
抛出:: KeyError – 如果不存在匹配 study_id 的 study。
返回类型:: list[StudyDirection]

get_study_id_from_name(study_name)[source]

读取 study 的 ID。

参数:: study_name (str) – study 的名称。
返回:: study 的 ID。
抛出:: KeyError – 如果不存在匹配 study_name 的 study。
返回类型:: int

get_study_name_from_id(study_id)[source]

读取 study 的 study 名称。

参数:: study_id (int) – study 的 ID。
返回:: study 的名称。
抛出:: KeyError – 如果不存在匹配 study_id 的 study。
返回类型:: str

get_study_system_attrs(study_id)[source]

读取 study 的 optuna 内部属性。

参数:: study_id (int) – study 的 ID。
返回:: 包含 study 的 optuna 内部属性的字典。
抛出:: KeyError – 如果不存在匹配 study_id 的 study。
返回类型:: dict[str, Any]

get_study_user_attrs(study_id)[source]

读取 study 的用户定义属性。

参数:: study_id (int) – study 的 ID。
返回:: 包含 study 的用户属性的字典。
抛出:: KeyError – 如果不存在匹配 study_id 的 study。
返回类型:: dict[str, Any]

get_trial(trial_id)[source]

读取一个 trial。

参数:: trial_id (int) – trial 的 ID。
返回:: 具有匹配 trial ID 的 trial。
抛出:: KeyError – 如果不存在匹配 trial_id 的 trial。
返回类型:: FrozenTrial

get_trial_id_from_study_id_trial_number(study_id, trial_number)[source]

读取 trial 的 trial ID。

参数:

study_id (int) – study 的 ID。
trial_number (int) – trial 的编号。

返回:

trial 的 ID。

抛出:

KeyError – 如果不存在匹配 study_id 和 trial_number 的 trial。

返回类型:

int

get_trial_number_from_id(trial_id)

读取 trial 的 trial 编号。

注意

trial 编号在 study 中是唯一的，并且是连续的。

参数:: trial_id (int) – trial 的 ID。
返回:: trial 的编号。
抛出:: KeyError – 如果不存在匹配 trial_id 的 trial。
返回类型:: int

get_trial_param(trial_id, param_name)

读取 trial 的参数。

参数:

trial_id (int) – trial 的 ID。
param_name (str) – 参数的名称。

返回:

参数的内部表示。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。如果不存在此参数。

返回类型:

float

get_trial_params(trial_id)

读取 trial 的参数字典。

参数:: trial_id (int) – trial 的 ID。
返回:: 参数字典。键是参数名称，值是参数值的外部表示。
抛出:: KeyError – 如果不存在匹配 trial_id 的 trial。
返回类型:: dict[str, Any]

get_trial_system_attrs(trial_id)

读取 trial 的 optuna 内部属性。

参数:: trial_id (int) – trial 的 ID。
返回:: 包含 trial 的 optuna 内部属性的字典。
抛出:: KeyError – 如果不存在匹配 trial_id 的 trial。
返回类型:: dict[str, Any]

get_trial_user_attrs(trial_id)

读取 trial 的用户定义属性。

参数:: trial_id (int) – trial 的 ID。
返回:: 包含 trial 的用户定义属性的字典。
抛出:: KeyError – 如果不存在匹配 trial_id 的 trial。
返回类型:: dict[str, Any]

remove_session()

清理到数据库的所有连接。

返回类型:: None

set_study_system_attr(study_id, key, value)[source]

向 study 注册 optuna 内部属性。

此方法将覆盖任何现有属性。

参数:

study_id (int) – study 的 ID。
key (str) – 属性键。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性值。它应该是 JSON 可序列化的。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。

返回类型:

None

set_study_user_attr(study_id, key, value)[source]

向 study 注册用户定义属性。

此方法将覆盖任何现有属性。

参数:

study_id (int) – study 的 ID。
key (str) – 属性键。
value (Any) – 属性值。它应该是 JSON 可序列化的。

抛出:

KeyError – 如果不存在匹配 study_id 的 study。

返回类型:

None

set_trial_intermediate_value(trial_id, step, intermediate_value)[source]

报告目标函数的中间值。

此方法将覆盖与给定步骤关联的任何现有中间值。

参数:

trial_id (int) – trial 的 ID。
step (int) – trial 的步骤（例如，训练神经网络时的 epoch）。
intermediate_value (float) – 与该步骤对应的中间值。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。
UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

None

set_trial_param(trial_id, param_name, param_value_internal, distribution)[source]

为 trial 设置参数。

参数:

trial_id (int) – trial 的 ID。
param_name (str) – 参数的名称。
param_value_internal (float) – 参数值的内部表示。
distribution (BaseDistribution) – 参数的采样分布。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。
UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

None

set_trial_state_values(trial_id, state, values=None)[source]

更新 trial 的状态和值。

将目标函数的返回值设置为 values 参数。如果 values 参数不是 None，则此方法将覆盖任何现有 trial 值。

参数:

trial_id (int) – trial 的 ID。
state (TrialState) – trial 的新状态。
values (Sequence[float] | None) – 目标函数的值。

返回:

如果状态成功更新，则为 True。如果状态保持不变，则为 False。后一种情况发生在此方法尝试将 RUNNING trial 的状态更新为 RUNNING 时。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。
UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

bool

set_trial_system_attr(trial_id, key, value)[source]

为 trial 设置 optuna 内部属性。

此方法将覆盖任何现有属性。

参数:

trial_id (int) – trial 的 ID。
key (str) – 属性键。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性值。它应该是 JSON 可序列化的。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。
UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

None

set_trial_user_attr(trial_id, key, value)[source]

为 trial 设置用户定义属性。

此方法将覆盖任何现有属性。

参数:

trial_id (int) – trial 的 ID。
key (str) – 属性键。
value (Any) – 属性值。它应该是 JSON 可序列化的。

抛出:

KeyError – 如果不存在匹配 trial_id 的 trial。
UpdateFinishedTrialError – 如果 trial 已完成。

返回类型:

None