optuna.study.Study

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

一个 study 代表一个优化任务，即一组 trials。

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

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

方法

`add_trial`(trial)	将 trial 添加到 study。
`add_trials`(trials)	将 trials 添加到 study。
`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 中位于 Pareto 前沿的 trials。
`best_value`	返回 study 中最佳的客观函数值。
`direction`	返回 study 的方向。
`directions`	返回 study 的方向。
`metric_names`	返回指标名称。
`系统属性`	返回系统属性。
`trials`	返回 study 中的所有 trials。
`user_attrs`	返回用户属性。

参数:

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

add_trial(trial)[源代码]

将 trial 添加到 study。

在添加 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。
返回类型:: 无

add_trials(trials)[源代码]

将 trials 添加到 study。

在添加 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。
返回类型:: 无

ask(fixed_distributions=None)[源代码]

创建一个新的 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 建议，即使用户未显式调用建议方法。如果此参数设置为 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 中位于 Pareto 前沿的 trials。

如果不存在支配该 trial 的其他 trials，则该 trial 位于 Pareto 前沿。如果对于两个 trial t0 和 t1，满足 all(v0 <= v1) for v0, v1 in zip(t0.values, t1.values) 且 any(v0 < v1) for v0, v1 in zip(t0.values, t1.values)，则称 t0 支配 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)[源代码]

使用给定的参数值入队一个 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。

返回类型:

无

另请参阅

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

get_trials(deepcopy=True, states=None)[源代码]

返回 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)[源代码]

优化目标函数。

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

当收到终止信号（如 SIGINT 和 SIGTERM）时，优化将停止。与其他信号不同，当收到 SIGINT (Ctrl+C) 时，trial 会自动且干净地失败。如果 `n_jobs` 大于一或使用了 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) – 实现目标函数的 callable。
n_trials (int | None) –
每个进程的 trial 数量。 None 表示在 trial 数量上没有限制。study 会继续创建 trials，直到 trial 数量达到 `n_trials`、`timeout` 时期结束、调用 stop() 或收到终止信号（如 SIGTERM 或 Ctrl+C）。

另请参阅

optuna.study.MaxTrialsCallback 可以确保在所有进程中执行 trials 的次数。
timeout (float | None) – 在给定的秒数后停止 study。 None 表示在时间流逝上没有限制。study 会继续创建 trials，直到 trial 数量达到 `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。

另请参阅

在优化研究时，如何避免内存不足 (OOM)？
show_progress_bar (bool) – 控制是否显示进度条的标志。要显示进度条，请将其设置为 True。请注意，当 `n_trials` 为 None、`timeout` 不为 None 且 `n_jobs` \(\ne 1\) 时，它将被禁用。

引发:

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

返回类型:

无

set_metric_names(metric_names)[源代码]

设置指标名称。

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

示例

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]) – 目标函数的指标名称列表。
返回类型:: 无

注意

在 v3.2.0 中添加为实验性功能。接口可能在更高版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v3.2.0。

set_system_attr(key, value)[源代码]

将系统属性设置为 study。

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

参数:

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

返回类型:

无

警告

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

set_user_attr(key, value)[源代码]

将用户属性设置为 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 可序列化。

返回类型:

无

stop()[源代码]

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

此方法允许正在运行的 optimize() 方法在 `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

返回类型:: 无

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)[源代码]

完成由 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) – 可选的目标函数值或一系列目标函数值（如果 study 用于多目标优化）。如果 `state` 为 COMPLETE，则必须提供此参数；如果 `state` 为 FAIL 或 PRUNED，则应为 None。
state (TrialState | None) – 要报告的状态。必须是 None、COMPLETE、FAIL 或 PRUNED。如果 `state` 为 None，它将根据 `values` 报告的验证是否成功而更新为 COMPLETE 或 FAIL。
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)[源代码]

将 trials 导出为 pandas DataFrame。

DataFrame 提供了各种分析 study 的功能。它也有助于绘制目标函数值直方图以及将 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

注意

如果 `value` 在多目标优化期间出现在 `attrs` 中，它将被隐式替换为 `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"],
}

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