optuna.study.Study

class optuna.study.Study(study_name, storage, sampler=None, pruner=None)[source]

一个 Study 对应一个优化任务，即一组 trials。

此对象提供运行新的 Trial、访问 trials 历史记录、设置/获取 Study 自身用户定义属性的接口。

注意，不建议直接使用此构造函数。要创建和加载 Study，请分别参考 create_study() 和 load_study() 的文档。

方法

`add_trial`(trial)	向 Study 添加 trial。
`add_trials`(trials)	向 Study 添加 trials。
`ask`([fixed_distributions])	创建一个新的 trial，可以从中建议超参数。
`enqueue_trial`(params[, user_attrs, ...])	使用给定参数值将 trial 排队。
`get_trials`([deepcopy, states])	返回 Study 中的所有 trials。
`optimize`(func[, n_trials, timeout, n_jobs, ...])	优化目标函数。
`set_metric_names`(metric_names)	设置指标名称。
`set_system_attr`(key, value)	为 Study 设置系统属性。
`set_user_attr`(key, value)	为 Study 设置用户属性。
`stop`()	在正在运行的 trials 完成后退出当前的优化循环。
`tell`(trial[, values, state, skip_if_finished])	完成使用 `ask()` 创建的 trial。
`trials_dataframe`([attrs, multi_index])	将 trials 导出为 pandas DataFrame。

属性

`best_params`	返回 Study 中最佳 trial 的参数。
`best_trial`	返回 Study 中的最佳 trial。
`best_trials`	返回 Study 中位于帕累托前沿的 trials。
`best_value`	返回 Study 中的最佳目标值。
`direction`	返回 Study 的优化方向。
`directions`	返回 Study 的优化方向列表。
`metric_names`	返回指标名称。
`system_attrs`	返回系统属性。
`trials`	返回 Study 中的所有 trials。
`user_attrs`	返回用户属性。

参数:

study_name (str)
storage (str | storages.BaseStorage)
sampler ('samplers.BaseSampler' | None)
pruner (pruners.BasePruner | None)

add_trial(trial)[source]

向 Study 添加 trial。

添加 trial 前会对其进行验证。

示例

import optuna
from optuna.distributions import FloatDistribution


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
assert len(study.trials) == 0

trial = optuna.trial.create_trial(
    params={"x": 2.0},
    distributions={"x": FloatDistribution(0, 10)},
    value=4.0,
)

study.add_trial(trial)
assert len(study.trials) == 1

study.optimize(objective, n_trials=3)
assert len(study.trials) == 4

other_study = optuna.create_study()

for trial in study.trials:
    other_study.add_trial(trial)
assert len(other_study.trials) == len(study.trials)

other_study.optimize(objective, n_trials=2)
assert len(other_study.trials) == len(study.trials) + 2

另请参见

此方法通常用于添加已评估的 trials（trial.state.is_finished() == True）。要将 trials 排队进行评估，请参考 enqueue_trial()。

另请参见

有关如何创建 trials，请参阅 create_trial()。

另请参见

有关如何手动指定带有评估值的超参数的教程，请参考第二种场景：让 Optuna 利用已评估的超参数。

参数:: trial (FrozenTrial) – 要添加的 Trial。
返回类型:: None

add_trials(trials)[source]

向 Study 添加 trials。

添加 trials 前会对其进行验证。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)
assert len(study.trials) == 3

other_study = optuna.create_study()
other_study.add_trials(study.trials)
assert len(other_study.trials) == len(study.trials)

other_study.optimize(objective, n_trials=2)
assert len(other_study.trials) == len(study.trials) + 2

另请参见

有关添加每个 trial 的信息，请参阅 add_trial()。

参数:: trials (Iterable[FrozenTrial]) – 要添加的 Trials。
返回类型:: None

ask(fixed_distributions=None)[source]

创建一个新的 trial，可以从中建议超参数。

此方法是 optimize() 的替代方案的一部分，允许在 func 范围之外控制 trial 的生命周期。每次调用此方法后，都应调用 tell() 来完成创建的 trial。

另请参见

Ask-and-Tell 接口教程提供了用例和示例。

示例

使用 ask() 方法获取 trial 对象。

import optuna

study = optuna.create_study()

trial = study.ask()

x = trial.suggest_float("x", -1, 1)

study.tell(trial, x**2)

示例

将先前定义的分布传递给 ask() 方法。

import optuna


study = optuna.create_study()

distributions = {
    "optimizer": optuna.distributions.CategoricalDistribution(["adam", "sgd"]),
    "lr": optuna.distributions.FloatDistribution(0.0001, 0.1, log=True),
}

# You can pass the distributions previously defined.
trial = study.ask(fixed_distributions=distributions)

# `optimizer` and `lr` are already suggested and accessible with `trial.params`.
assert "optimizer" in trial.params
assert "lr" in trial.params

参数:: fixed_distributions (dict[str, BaseDistribution] | None) – 包含参数名称和参数分布的字典。此字典中的每个参数都会自动建议给返回的 trial，即使用户未显式调用 suggest 方法。如果此参数设置为 None，则不会自动建议任何参数。
返回:: 一个 Trial。
返回类型:: Trial

property best_params: dict[str, Any]

返回 Study 中最佳 trial 的参数。

注意

此功能仅用于单目标优化。

返回:: 包含最佳 trial 参数的字典。

property best_trial: FrozenTrial

返回 Study 中的最佳 trial。

注意

此功能仅用于单目标优化。如果您的 Study 是多目标的，请改用 best_trials。

返回:: 最佳 trial 的 FrozenTrial 对象。

另请参见

重用最佳 trial 教程提供了如何使用此方法的详细示例。

property best_trials: list[FrozenTrial]

返回 Study 中位于帕累托前沿的 trials。

如果没有任何 trial 支配某个 trial，则该 trial 位于帕累托前沿。如果对于 v0, v1 in zip(t0.values, t1.values) 都满足 all(v0 <= v1) 并且对于 v0, v1 in zip(t0.values, t1.values) 有任意一个满足 any(v0 < v1)，则称 trial t0 支配另一个 trial t1。

返回:: FrozenTrial 对象的列表。

property best_value: float

返回 Study 中的最佳目标值。

注意

此功能仅用于单目标优化。

返回:: 表示最佳目标值的浮点数。

property direction: StudyDirection

返回 Study 的优化方向。

注意

此功能仅用于单目标优化。如果您的 Study 是多目标的，请改用 directions。

返回:: 一个 StudyDirection 对象。

property directions: list[StudyDirection]

返回 Study 的优化方向列表。

返回:: StudyDirection 对象的列表。

enqueue_trial(params, user_attrs=None, skip_if_exists=False)[source]

使用给定参数值将 trial 排队。

您可以固定将在您的目标函数中评估的下一个采样参数。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.enqueue_trial({"x": 5})
study.enqueue_trial({"x": 0}, user_attrs={"memo": "optimal"})
study.optimize(objective, n_trials=2)

assert study.trials[0].params == {"x": 5}
assert study.trials[1].params == {"x": 0}
assert study.trials[1].user_attrs == {"memo": "optimal"}

参数:

params (dict[str, Any]) – 要传递给目标函数的参数值。
user_attrs (dict[str, Any] | None) – 除了 params 之外的用户特定属性字典。
skip_if_exists (bool) –
当设置为 True 时，防止重复的 trials 再次排队。

注意

如果多个进程同时使用相同的 params 字典调用此方法，可能会产生重复的 trials。

返回类型:

None

另请参见

有关手动指定超参数的教程，请参考第一种场景：让 Optuna 评估您的超参数。

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

返回 Study 中的所有 trials。

返回的 trials 按 trial 编号排序。

另请参见

有关相关属性，请参阅 trials。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

trials = study.get_trials()
assert len(trials) == 3

参数:

deepcopy (bool) – 控制是否对 trials 应用 copy.deepcopy() 的标志。注意，如果您将此标志设置为 False，则不应修改返回的 trial 的任何字段。否则，Study 的内部状态可能会损坏并发生意外行为。
states (Container[TrialState] | None) – 要过滤的 Trial 状态。如果为 None，则包含所有状态。

返回:

FrozenTrial 对象的列表。

返回类型:

list[FrozenTrial]

property metric_names: list[str] | None

返回指标名称。

注意

请先使用 set_metric_names() 设置指标名称。

返回:: 包含目标函数返回值每个维度的名称列表。

optimize(func, n_trials=None, timeout=None, n_jobs=1, catch=(), callbacks=None, gc_after_trial=False, show_progress_bar=False)[source]

优化目标函数。

优化通过从给定范围中选择一组合适的超参数值来完成。使用采样器（sampler）来实现基于指定分布的值建议任务。采样器在 create_study() 中指定，采样器的默认选择是 TPE。有关 ‘TPE’ 的更多详细信息，另请参阅 TPESampler。

当收到 SIGINT 和 SIGTERM 等终止信号时，优化将停止。与其他信号不同，当收到 SIGINT (Ctrl+C) 时，trial 会自动干净地失败。如果 n_jobs 大于 1，或者使用了 SIGINT 以外的其他信号，则被中断的 trial 状态将无法正确更新。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

参数:

func (ObjectiveFuncType) – 实现目标函数的可调用对象。
n_trials (int | None) –
每个进程的 trial 数量。None 表示 trials 数量没有限制。Study 继续创建 trials，直到 trials 数量达到 n_trials，timeout 期限到期，调用 stop()，或者收到 SIGTERM 或 Ctrl+C 等终止信号。

另请参见

optuna.study.MaxTrialsCallback 可以确保在所有进程中执行 trials 的次数。
timeout (float | None) – 在给定秒数后停止 Study。None 表示经过时间没有限制。Study 继续创建 trials，直到 trials 数量达到 n_trials，timeout 期限到期，调用 stop()，或者收到 SIGTERM 或 Ctrl+C 等终止信号。
n_jobs (int) –
并行作业的数量。如果此参数设置为 -1，则数量设置为 CPU 核心数。

注意

n_jobs 允许使用 threading 进行并行化，并可能受到 Python 的 GIL 的影响。如果 func 是 CPU 密集型的，建议使用基于进程的并行化。
catch (Iterable[type[Exception]] | type[Exception]) – 即使 trial 引发此参数中指定的异常之一，Study 也会继续运行。默认为空元组，即除了 TrialPruned 外，Study 将因任何异常而停止。
callbacks (Iterable[Callable[[Study, FrozenTrial], None]] | None) –
在每个 trial 结束时调用的回调函数列表。每个函数必须按以下顺序接受两个参数，其类型分别为：Study 和 FrozenTrial。

另请参见

有关如何使用和实现回调函数，请参阅 Study.optimize 的回调教程。
gc_after_trial (bool) –
一个标志，用于确定是否在每次 trial 后自动运行垃圾回收。设置为 True 以运行垃圾回收，否则设置为 False。当它运行时，通过内部调用 gc.collect() 执行完全回收。如果您发现经过多次 trial 后内存消耗增加，请尝试将此标志设置为 True。

另请参见

在优化 Study 时，如何避免内存不足 (OOM)？
show_progress_bar (bool) – 显示或不显示进度条的标志。要显示进度条，请将其设置为 True。注意，当 n_trials 为 None，timeout 不为 None 且 n_jobs \(\ne 1\) 时，此选项被禁用。

抛出:

RuntimeError – 如果发生此方法的嵌套调用。

返回类型:

None

set_metric_names(metric_names)[source]

设置指标名称。

此方法命名目标函数返回值的每个维度。这在多目标优化中特别有用。指标名称主要由可视化函数引用。

示例

import optuna
import pandas


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2, x + 1


study = optuna.create_study(directions=["minimize", "minimize"])
study.set_metric_names(["x**2", "x+1"])
study.optimize(objective, n_trials=3)

df = study.trials_dataframe(multi_index=True)
assert isinstance(df, pandas.DataFrame)
assert list(df.get("values").keys()) == ["x**2", "x+1"]

另请参见

此方法设置的名称用于 trials_dataframe() 和 plot_pareto_front()。

参数:: metric_names (list[str]) – 目标函数的指标名称列表。
返回类型:: None

注意

作为实验性功能在 v3.2.0 中添加。未来版本中接口可能会发生变化，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v3.2.0。

set_system_attr(key, value)[source]

为 Study 设置系统属性。

请注意，Optuna 内部使用此方法保存系统消息。请使用 set_user_attr() 设置用户属性。

参数:

key (str) – 属性的键字符串。
value (Any) – 属性的值。该值应可 JSON 序列化。

返回类型:

None

警告

在 v3.1.0 中已弃用。此功能将来会被移除。目前计划在 v5.0.0 中移除此功能，但此计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.1.0。

set_user_attr(key, value)[source]

为 Study 设置用户属性。

另请参见

有关相关属性，请参阅 user_attrs。

另请参见

请参阅用户属性的秘籍。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 1)
    y = trial.suggest_float("y", 0, 1)
    return x**2 + y**2


study = optuna.create_study()

study.set_user_attr("objective function", "quadratic function")
study.set_user_attr("dimensions", 2)
study.set_user_attr("contributors", ["Akiba", "Sano"])

assert study.user_attrs == {
    "objective function": "quadratic function",
    "dimensions": 2,
    "contributors": ["Akiba", "Sano"],
}

参数:

key (str) – 属性的键字符串。
value (Any) – 属性的值。该值应可 JSON 序列化。

返回类型:

None

stop()[source]

在正在运行的 trials 完成后退出当前的优化循环。

此方法允许正在运行的 optimize() 方法在其启动的所有 trials 完成后立即返回。此方法不影响并行或后续 Study 进程的任何行为。此方法仅在目标函数或回调函数内部调用时才有效。

示例

import optuna


def objective(trial):
    if trial.number == 4:
        trial.study.stop()
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=10)
assert len(study.trials) == 5

返回类型:: None

property system_attrs: dict[str, Any]

返回系统属性。

返回:: 包含所有系统属性的字典。

警告

在 v3.1.0 中已弃用。此功能将来会被移除。目前计划在 v5.0.0 中移除此功能，但此计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.1.0。

tell(trial, values=None, state=None, skip_if_finished=False)[source]

完成使用 ask() 创建的 trial。

另请参见

Ask-and-Tell 接口教程提供了用例和示例。

示例

import optuna
from optuna.trial import TrialState


def f(x):
    return (x - 2) ** 2


def df(x):
    return 2 * x - 4


study = optuna.create_study()

n_trials = 30

for _ in range(n_trials):
    trial = study.ask()

    lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True)

    # Iterative gradient descent objective function.
    x = 3  # Initial value.
    for step in range(128):
        y = f(x)

        trial.report(y, step=step)

        if trial.should_prune():
            # Finish the trial with the pruned state.
            study.tell(trial, state=TrialState.PRUNED)
            break

        gy = df(x)
        x -= gy * lr
    else:
        # Finish the trial with the final value after all iterations.
        study.tell(trial, y)

参数:

trial (Trial | int) – 一个 Trial 对象或 trial 编号。
values (float | Sequence[float] | None) – 可选的目标值或一组目标值，用于多目标优化。如果 state 是 COMPLETE，则必须提供此参数；如果 state 是 FAIL 或 PRUNED，则应为 None。
state (TrialState | None) – 要报告的状态。必须是 None、COMPLETE、FAIL 或 PRUNED。如果 state 是 None，它将更新为 COMPLETE 或 FAIL，具体取决于报告的 values 验证是否成功。
skip_if_finished (bool) – 控制当已完成的 trial 的值被告知时是否应引发异常的标志。如果为 True，则在 trial 已完成时，tell 会跳过而不会出现任何错误。

返回:

表示结果 trial 的 FrozenTrial。返回的 trial 是深拷贝的，因此用户可以根据需要修改它。

返回类型:

FrozenTrial

property trials: list[FrozenTrial]

返回 Study 中的所有 trials。

返回的 trials 按 trial 编号排序。

这是 self.get_trials(deepcopy=True, states=None) 的简写形式。

返回:

FrozenTrial 对象的列表。

另请参见

有关相关方法，请参阅 get_trials()。

trials_dataframe(attrs=('number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state'), multi_index=False)[source]

将 trials 导出为 pandas DataFrame。

DataFrame 提供了多种功能来分析 studies。它也常用于绘制目标值的直方图以及将 trials 导出为 CSV 文件。如果没有 trials，则返回一个空的 DataFrame。

示例

import optuna
import pandas


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

# Create a dataframe from the study.
df = study.trials_dataframe()
assert isinstance(df, pandas.DataFrame)
assert df.shape[0] == 3  # n_trials.

参数:

attrs (tuple[str, ...]) – 指定 FrozenTrial 的字段名称，以便将其包含在 trials 的 DataFrame 中。
multi_index (bool) – 指定返回的 DataFrame 是否使用 MultiIndex。本质上是分层的列（例如 (params, x)）在设置为 False 时将被展平为 params_x。

返回:

Study 中 trials 的 pandas DataFrame。

返回类型:

pd.DataFrame

注意

如果在多目标优化期间 attrs 中包含 value，则它会被隐式替换为 values。

注意

如果调用了 set_metric_names()，则 value 或 values 会被隐式替换为一个字典，其中键为目标名称，值为目标值。

property user_attrs: dict[str, Any]

返回用户属性。

另请参见

有关相关方法，请参阅 set_user_attr()。

示例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 1)
    y = trial.suggest_float("y", 0, 1)
    return x**2 + y**2


study = optuna.create_study()

study.set_user_attr("objective function", "quadratic function")
study.set_user_attr("dimensions", 2)
study.set_user_attr("contributors", ["Akiba", "Sano"])

assert study.user_attrs == {
    "objective function": "quadratic function",
    "dimensions": 2,
    "contributors": ["Akiba", "Sano"],
}

返回:: 包含所有用户属性的字典。