optuna.samplers.TPESampler

class optuna.samplers.TPESampler(*, consider_prior=True, prior_weight=1.0, consider_magic_clip=True, consider_endpoints=False, n_startup_trials=10, n_ei_candidates=24, gamma=<function default_gamma>, weights=<function default_weights>, seed=None, multivariate=False, group=False, warn_independent_sampling=True, constant_liar=False, constraints_func=None, categorical_distance_func=None)[源代码]

使用 TPE（Tree-structured Parzen Estimator）算法的采样器。

在每次试验中，对于每个参数，TPE 会将一组与最佳目标值相关的参数值拟合到一个高斯混合模型 (GMM) l(x) 中，并将剩余的参数值拟合到另一个 GMM g(x) 中。它选择使比率 l(x)/g(x) 最大化的参数值 x。

有关 TPE 算法的更多信息，请参阅以下论文：

有关多目标 TPE (MOTPE) 的信息，请参阅以下论文：

有关 categorical_distance_func 的信息，请参阅以下论文：

Tree-Structured Parzen Estimator Can Solve Black-Box Combinatorial Optimization More Efficiently

请同时查看我们的文章：

示例

单目标优化的示例如下：

import optuna
from optuna.samplers import TPESampler


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


study = optuna.create_study(sampler=TPESampler())
study.optimize(objective, n_trials=10)

注意

TPESampler（在 v4.0.0 版本中速度显著提升，参见我们的文章）也能处理具有大量试验的多目标优化。请注意，多目标优化默认使用 NSGAIISampler，因此，如果用户希望将 TPESampler 用于多目标优化，则在创建 study 时必须显式指定 sampler。

参数:

consider_prior (bool) –
当设置为 True 时，通过施加高斯先验来增强 Parzen 估计器的稳定性。先验仅在采样分布为 FloatDistribution 或 IntDistribution 时有效。

警告

v4.3.0 中已弃用。consider_prior 参数将在未来版本中移除。此功能计划于 v6.0.0 移除，但此计划可能会更改。从 v4.3.0 开始，consider_prior 自动回退为 True。参见 https://github.com/optuna/optuna/releases/tag/v4.3.0。
prior_weight (float) – 先验的权重。此参数用于 FloatDistribution、IntDistribution 和 CategoricalDistribution。
consider_magic_clip (bool) – 启用一个启发式方法来限制 Parzen 估计器中使用的高斯分布的最小方差。
consider_endpoints (bool) – 在计算 Parzen 估计器中高斯分布的方差时，考虑域的端点。有关计算方差的启发式方法的详细信息，请参阅原始论文。
n_startup_trials (int) – 在同一 study 中，在给定的试验次数完成之前，使用随机采样而不是 TPE 算法。
n_ei_candidates (int) – 用于计算预期改进的候选样本数量。
gamma (Callable[[int], int]) – 一个函数，它接受已完成的试验数量并返回用于为具有低粒度的样本形成密度函数的试验数量。有关更多详细信息，请参阅原始论文。
weights (Callable[[int], np.ndarray]) –
一个函数，它接受已完成的试验数量并返回它们的权重。有关更多详细信息，请参阅 Making a Science of Model Search: Hyperparameter Optimization in Hundreds of Dimensions for Vision Architectures。

注意

在多目标情况下，此参数仅用于计算较差试验的权重，即用于构造 g(x) 的试验（参见论文）。较好试验的权重，即用于构造 l(x) 的试验，是根据 MOTPE 论文中提出的超体积贡献规则计算的。
seed (int | None) – 随机数生成器的种子。
multivariate (bool) –
如果为 True，则在建议参数时使用多变量 TPE。据报道，多变量 TPE 的性能优于独立 TPE。有关更多详细信息，请参阅 BOHB: Robust and Efficient Hyperparameter Optimization at Scale 和我们的文章。

注意

于 v2.2.0 添加为实验性功能。接口可能在未来版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v2.2.0。
group (bool) –
如果此参数和 multivariate 都为 True，则在建议参数时使用具有分组分解搜索空间的多变量 TPE。采样算法根据过去的试验分解搜索空间，并在每个分解的子空间中从联合分布进行采样。分解的子空间是整个搜索空间的一个分区。每个子空间是整个搜索空间的一个最大子集，它满足以下条件：对于已完成试验中的一个试验，子空间与该试验的搜索空间的交集是子空间本身或一个空集。通过多变量 TPE 实现从子空间上的联合分布进行采样。如果 group 为 True，则 multivariate 也必须为 True。

注意

在 v2.8.0 中作为实验性功能添加。接口在后续版本中可能在没有事先通知的情况下发生更改。请参阅 https://github.com/optuna/optuna/releases/tag/v2.8.0。

示例
```
import optuna


def objective(trial):
    x = trial.suggest_categorical("x", ["A", "B"])
    if x == "A":
        return trial.suggest_float("y", -10, 10)
    else:
        return trial.suggest_int("z", -10, 10)


sampler = optuna.samplers.TPESampler(multivariate=True, group=True)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
```
warn_independent_sampling (bool) – 如果此参数为 True 且 multivariate=True，则在使用独立采样器采样参数值时会发出警告消息。如果 multivariate=False，则此标志无效。
constant_liar (bool) –
如果为 True，则会惩罚正在运行的试验，以避免建议附近的参数配置。

注意

异常终止的试验通常会在存储中留下状态为 RUNNING 的记录。在后续采样过程中，常量 liar 算法会避免这些“僵尸”试验参数。当使用 RDBStorage 时，可以启用 heartbeat_interval 将异常终止试验的记录更改为 FAIL。

注意

建议在分布式优化期间将此值设置为 True，以避免多个工作器评估相似的参数配置。特别是，如果每个目标函数评估的成本很高，并且正在运行状态的持续时间很长，并且/或者工作器的数量很多。

注意

在 v2.8.0 中作为实验性功能添加。接口在后续版本中可能在没有事先通知的情况下发生更改。请参阅 https://github.com/optuna/optuna/releases/tag/v2.8.0。
constraints_func (Callable[[FrozenTrial], Sequence[float]] | None) –
一个可选函数，用于计算目标约束。它必须接受一个 FrozenTrial 并返回约束。返回值必须是一个 float 序列。大于 0 的值表示约束被违反。等于或小于 0 的值被视为可行的。如果 constraints_func 为试验返回多个值，则仅当所有值都等于 0 或更小时，该试验才被视为可行。

constraints_func 将在每次成功试验后进行评估。当试验失败或被剪枝时，该函数不会被调用，但此行为可能会在未来的版本中发生更改。

注意

在 v3.0.0 中作为实验性功能添加。接口在后续版本中可能在没有事先通知的情况下发生更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.0.0。
categorical_distance_func (dict[str, Callable[[CategoricalChoiceType, CategoricalChoiceType], float]] | None) –
分类参数的距离函数字典。键是分类参数的名称，值是一个距离函数，该函数接受两个 CategoricalChoiceType 并返回一个 float 值。距离函数必须返回非负值。

虽然默认情况下分类选择的处理方式相同，但此选项允许用户指定分类参数的结构的先验知识。指定后，更可能采样到比当前最佳选择更接近的分类选择。

注意

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

方法

`after_trial`(study, trial, state, values)	试验后处理。
`before_trial`(study, trial)	试验预处理。
`hyperopt_parameters`()	返回 hyperopt (v0.1.2) 的默认参数。
`infer_relative_search_space`(study, trial)	为目标试验推断将使用的搜索空间。
`reseed_rng`()	重新设置采样器的随机数生成器。
`sample_independent`(study, trial, param_name, ...)	为给定的分布采样一个参数。
`sample_relative`(study, trial, search_space)	在给定的搜索空间中采样参数。

after_trial(study, trial, state, values)[源代码]

试验后处理。

此方法在目标函数返回后、试验完成并存储其状态之前调用。

注意

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

参数:

study (Study) – 目标研究对象。
trial (FrozenTrial) – 目标试验对象。修改此对象前请先复制。
state (TrialState) – 结果试验状态。
values (Sequence[float] | None) – 结果试验值。如果试验成功，则保证不为 None。

返回类型:

无

before_trial(study, trial)[源代码]

试验预处理。

此方法在调用目标函数之前、试验实例化之后调用。更准确地说，此方法在试验初始化期间调用，就在调用 infer_relative_search_space() 调用之前。换句话说，它负责在推断搜索空间之前应执行的预处理。

注意

于 v3.3.0 作为实验性功能添加。界面可能会在较新版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v3.3.0。

参数:

study (Study) – 目标研究对象。
trial (FrozenTrial) – 目标试验对象。

返回类型:

无

static hyperopt_parameters()[源代码]

返回 hyperopt (v0.1.2) 的默认参数。

TPESampler 可以使用此方法返回的参数进行实例化。

示例

使用 hyperopt 的默认参数创建 TPESampler 实例。

import optuna
from optuna.samplers import TPESampler


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


sampler = TPESampler(**TPESampler.hyperopt_parameters())
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)

返回:: 包含 hyperopt 默认参数的字典。
返回类型:: dict[str, Any]

infer_relative_search_space(study, trial)[源代码]

为目标试验推断将使用的搜索空间。

此方法在调用 sample_relative() 方法之前调用，并且此方法返回的搜索空间将传递给它。未包含在搜索空间中的参数将使用 sample_independent() 方法进行采样。

参数:

study (Study) – 目标研究对象。
trial (FrozenTrial) – 目标试验对象。修改此对象前请先复制。

返回:

包含参数名称和参数分布的字典。

返回类型:

dict[str, BaseDistribution]

另请参阅

请参阅 intersection_search_space() 作为 infer_relative_search_space() 的实现。

reseed_rng()[源代码]

重新设置采样器的随机数生成器。

如果试验与 n_jobs>1 选项并行执行，则 Study 实例将调用此方法。在这种情况下，采样器实例将被复制，包括随机数生成器的状态，并且它们可能会建议相同的值。为防止此问题，此方法为每个随机数生成器分配不同的种子。

返回类型:: 无

sample_independent(study, trial, param_name, param_distribution)[源代码]

为给定的分布采样一个参数。

此方法仅对未包含在 sample_relative() 方法返回的搜索空间中的参数进行调用。此方法适用于不使用参数之间关系的采样算法，例如随机采样和 TPE。

注意

任何内置采样器在采样新参数时都会忽略失败的试验。因此，在采样器看来，失败的试验被视为已删除。

参数:

study (Study) – 目标研究对象。
trial (FrozenTrial) – 目标试验对象。修改此对象前请先复制。
param_name (str) – 采样参数的名称。
param_distribution (BaseDistribution) – 指定采样算法先验和/或尺度的分布对象。

返回:

参数值。

返回类型:

Any

sample_relative(study, trial, search_space)[源代码]

在给定的搜索空间中采样参数。

此方法在每次试验开始时调用一次，即在评估目标函数之前。此方法适用于使用参数之间关系的采样算法，例如高斯过程和 CMA-ES。

注意

任何内置采样器在采样新参数时都会忽略失败的试验。因此，在采样器看来，失败的试验被视为已删除。

参数:

study (Study) – 目标研究对象。
trial (FrozenTrial) – 目标试验对象。修改此对象前请先复制。
search_space (dict[str, BaseDistribution]) – 由 infer_relative_search_space() 返回的搜索空间。

返回:

包含参数名称和值的字典。

返回类型:

dict[str, Any]