optuna.samplers.CmaEsSampler

class optuna.samplers.CmaEsSampler(x0=None, sigma0=None, n_startup_trials=1, independent_sampler=None, warn_independent_sampling=True, seed=None, *, consider_pruned_trials=False, restart_strategy=None, popsize=None, inc_popsize=-1, use_separable_cma=False, with_margin=False, lr_adapt=False, source_trials=None)[源代码]

一个使用 cmaes 作为后端的采样器。

示例

使用 CmaEsSampler 来优化一个简单的二次函数。

$ pip install cmaes

import optuna


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


sampler = optuna.samplers.CmaEsSampler()
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=20)

请注意，此采样器不支持 CategoricalDistribution。但是，支持带 step 的 FloatDistribution（suggest_float()）和 IntDistribution（suggest_int()）。

如果您的搜索空间包含类别参数，我建议您改用 TPESampler。此外，在并行优化设置中还有性能改进的空间。此采样器不能使用某些 trial 来更新多元正态分布的参数。

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

另请参阅

您还可以使用 optuna_integration.PyCmaSampler，这是一个使用 cma 库作为后端的采样器。

参数:

x0 (dict[str, Any] | None) – CMA-ES 的初始参数值字典。默认情况下，使用每个分布的 low 和 high 的均值。请注意，如果您指定了 restart_strategy 参数，则 x0 会在每次重新启动时在搜索空间域内均匀采样。
sigma0 (float | None) – CMA-ES 的初始标准差。默认情况下，sigma0 设置为 min_range / 6，其中 min_range 表示搜索空间中分布的最小范围。
seed (int | None) – CMA-ES 的随机种子。
n_startup_trials (int) – 在同一研究中完成给定数量的 trial 之前，将使用独立采样而不是 CMA-ES 算法。
independent_sampler (BaseSampler | None) –
用于独立采样的 BaseSampler 实例。不包含在相对搜索空间中的参数由该采样器采样。CmaEsSampler 的搜索空间由 intersection_search_space() 确定。

如果指定了 None，则默认使用 RandomSampler。

另请参阅

optuna.samplers 模块提供了内置的独立采样器，如 RandomSampler 和 TPESampler。
warn_independent_sampling (bool) –
如果为 True，则在通过独立采样器对参数值进行采样时会发出警告消息。

请注意，研究中第一个 trial 的参数始终通过独立采样器进行采样，因此在这种情况下不会发出警告消息。
restart_strategy (str | None) –
CMA-ES 优化收敛到局部最小值时重新启动的策略。如果给定 None，CMA-ES 将不会重新启动（默认）。如果给定 'ipop'，CMA-ES 将以增加的种群大小重新启动。如果给定 'bipop'，CMA-ES 将以增加或减少的种群大小重新启动。另请参阅 inc_popsize 参数。

警告

v4.4.0 中已弃用。`restart_strategy` 参数将在未来版本中移除。此功能的原定移除时间为 v6.0.0，但可能会发生变化。从 v4.4.0 开始，`restart_strategy` 会自动回退到 `None`，并且 `restart_strategy` 将在 OptunaHub 中得到支持。请参阅 https://github.com/optuna/optuna/releases/tag/v4.4.0。
popsize (int | None) – CMA-ES 的种群大小。
inc_popsize (int) –
每次重新启动前增加种群大小的乘数。当指定 restart_strategy = 'ipop' 或 restart_strategy = 'bipop' 时，将使用此参数。

警告

v4.4.0 中已弃用。`inc_popsize` 参数将在未来版本中移除。此功能的原定移除时间为 v6.0.0，但可能会发生变化。从 v4.4.0 开始，Optuna 不再使用 `inc_popsize`，`inc_popsize` 将在 OptunaHub 中得到支持。请参阅 https://github.com/optuna/optuna/releases/tag/v4.4.0。
consider_pruned_trials (bool) –
如果为 True，则在采样时考虑 PRUNED 的 trial。

注意

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

注意

建议在使用 MedianPruner 时将此标志设置为 False。另一方面，在使用 HyperbandPruner 时，建议将其设置为 True。有关详细信息，请参阅基准测试结果。
use_separable_cma (bool) –
如果为 True，则协方差矩阵被限制为对角矩阵。为了降低模型复杂度，协方差矩阵的学习率会增加。因此，该算法在可分离函数上的表现优于 CMA-ES。

注意

作为实验性功能于 v2.6.0 添加。界面可能在后续版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v2.6.0。
with_margin (bool) –
如果为 True，则使用带边距的 CMA-ES。此算法可防止每个离散分布（带 step 的 FloatDistribution 和 IntDistribution）中的样本固定为单个点。当前，此选项不能与 use_separable_cma=True 一起使用。

注意

作为实验性功能于 v3.1.0 添加。界面可能在后续版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v3.1.0。
lr_adapt (bool) –
如果为 True，则使用带学习率自适应的 CMA-ES。此算法侧重于在多峰和/或有噪声的问题上使用默认设置就能取得良好效果。当前，此选项不能与 use_separable_cma=True 或 with_margin=True 一起使用。

注意

作为实验性功能于 v3.3.0 或更高版本添加。界面可能在后续版本中更改，恕不另行通知。请参阅 https://github.com/optuna/optuna/releases/tag/v3.3.0。
source_trials (list[FrozenTrial] | None) –
此选项用于 CMA-ES 的热启动，这是一种通过初始化 CMA-ES 来转移对相似 HPO 任务的先验知识的方法。此方法从 source_trials 估计一个有前景的分布，并生成多元高斯分布的参数。请注意，禁止同时使用 x0、sigma0 或 use_separable_cma 参数。

注意

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

方法

`after_trial`(study, trial, state, values)	试验后处理。
`before_trial`(study, trial)	试验预处理。
`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) – 目标 study 对象。
trial (FrozenTrial) – 目标 trial 对象。在修改此对象之前，先复制一份。
state (TrialState) – 结果 trial 状态。
values (Sequence[float] | None) – 结果 trial 值。如果 trial 成功，则保证不为 None。

返回类型:

无

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

试验预处理。

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

注意

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

参数:

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

返回类型:

无

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

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

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

参数:

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

返回:

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

返回类型:

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) – 目标 study 对象。
trial (FrozenTrial) – 目标 trial 对象。在修改此对象之前，先复制一份。
param_name (str) – 采样参数的名称。
param_distribution (BaseDistribution) – 指定采样算法先验和/或尺度的分布对象。

返回:

参数值。

返回类型:

Any

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

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

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

注意

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

参数:

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

返回:

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

返回类型:

dict[str, Any]