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)[source]

使用 TPE（树结构 Parzen 估计器）算法的采样器。

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

关于 TPE 算法的更多信息，请参考以下论文

对于多目标 TPE (MOTPE)，请参考以下论文

也请查看我们的文章

示例

单目标优化的示例如下

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 进行，但此计划可能会有所变动。参见 https://github.com/optuna/optuna/releases/tag/v4.3.0。
prior_weight (float) – 先验的权重。此参数用于 FloatDistribution、IntDistribution 和 CategoricalDistribution。
consider_magic_clip (bool) – 启用启发式方法，限制 Parzen 估计器中使用的 Gaussian 的最小方差。
consider_endpoints (bool) – 在计算 Parzen 估计器中 Gaussian 的方差时考虑域的端点。有关计算方差的启发式方法的详细信息，请参阅原始论文。
n_startup_trials (int) – 在同一 study 中，达到给定数量的试验完成之前，使用随机采样代替 TPE 算法。
n_ei_candidates (int) – 用于计算期望改进的候选样本数量。
gamma (Callable[[int], int]) – 一个函数，接受已完成试验的数量，并返回用于为具有低谷值的样本形成密度函数的试验数量。有关详细信息，请参阅原始论文。
weights (Callable[[int], np.ndarray]) –
一个函数，接受已完成试验的数量并返回它们的权重。有关详细信息，请参见模型搜索科学：用于视觉架构的数百维超参数优化。

注意

在多目标情况下，此参数仅用于计算差的试验的权重，即用于在论文中构建 g(x) 的试验。好的试验的权重，即用于构建 l(x) 的试验，由 MOTPE 论文中提出的基于超体积贡献的规则计算。
seed (int | None) – 随机数生成器的种子。
multivariate (bool) –
如果设置为 True，则在建议参数时使用多元 TPE。据报道，多元 TPE 优于独立的 TPE。有关详细信息，请参见 BOHB: 大规模稳健高效超参数优化和我们的文章。

注意

在 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 的记录。在后续采样期间，恒谎算法将避免这些“僵尸”试验参数。使用 RDBStorage 时，可以启用 heartbeat_interval 将异常终止的试验记录更改为 FAIL。

注意

在分布式优化期间，建议将此值设置为 True，以避免多个 worker 评估相似的参数配置。特别是当每次目标函数评估成本高昂、运行状态持续时间很长和/或 worker 数量很多时。

注意

在 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)[source]

试验后处理。

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

注意

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

参数:

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

返回类型:

None

before_trial(study, trial)[source]

试验预处理。

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

注意

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

参数:

study (Study) – 目标 study 对象。
trial (FrozenTrial) – 目标 trial 对象。

返回类型:

None

static hyperopt_parameters()[source]

返回 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)[source]

推断目标试验中相对采样将使用的搜索空间。

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

参数:

study (Study) – 目标 study 对象。
trial (FrozenTrial) – 目标 trial 对象。在修改此对象之前请先复制一份。

返回值:

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

返回类型:

dict[str, BaseDistribution]

另请参阅

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

reseed_rng()[source]

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

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

返回类型:: None

sample_independent(study, trial, param_name, param_distribution)[source]

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

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

注意

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

参数:

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

返回值:

一个参数值。

返回类型:

Any

sample_relative(study, trial, search_space)[source]

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

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

注意

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

参数:

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

返回值:

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

返回类型:

dict[str, Any]