optuna.samplers.GridSampler

class optuna.samplers.GridSampler(search_space, seed=None)[源代码]

使用网格搜索的采样器。

使用 GridSampler，试验会在研究中建议给定搜索空间中所有参数的组合。

示例

import optuna


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


search_space = {"x": [-50, 0, 50], "y": [-99, 0, 99]}
study = optuna.create_study(sampler=optuna.samplers.GridSampler(search_space))
study.optimize(objective)

注意

此采样器配合 Ask-and-Tell 接口，在评估完最后一个网格后会引发 RuntimeError。这是因为 GridSampler 会在传递的 search_space 中的所有组合都已评估完毕后自动停止优化，内部调用 stop() 方法。作为一种变通方法，我们需要像在 https://github.com/optuna/optuna/issues/4121#issuecomment-1305289910 中那样手动处理错误。

注意

GridSampler 不会处理离散建议方法指定的参数量化，而是仅从搜索空间中指定的某一个值进行采样。例如，在下面的代码片段中，x 将被采样为 -0.5 或 0.5，而不是一个整数点。

import optuna


def objective(trial):
    # The following suggest method specifies integer points between -5 and 5.
    x = trial.suggest_float("x", -5, 5, step=1)
    return x**2


# Non-int points are specified in the grid.
search_space = {"x": [-0.5, 0.5]}
study = optuna.create_study(sampler=optuna.samplers.GridSampler(search_space))
study.optimize(objective, n_trials=2)

注意

网格中的参数配置在试验完成之前不被视为完成。因此，在试验并发运行的分布式优化期间，不同的工作进程有时会建议相同的参数配置。因此，实际试验的总数可能会超过网格的大小。

注意

在使用 GridSampler 和 enqueue_trial() 时，必须指定所有参数。

参数:

  • search_space (Mapping[str, Sequence[GridValueType]]) – 一个字典，其键是参数名，值是相应的候选值列表。

  • seed (int | None) – 一个种子，用于固定试验顺序，因为网格是随机打乱的。当网格数量大于 optimize() 中的 n_trials 时，这种打乱是有益的，可以减少建议相似网格的情况。请注意，在分布式优化中，强烈建议为每个进程固定 seed 以避免重复建议。

方法

after_trial(study, trial, state, values)

试验后处理。

before_trial(study, trial)

试验预处理。

infer_relative_search_space(study, trial)

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

is_exhausted(study)

如果所有可能的参数都已评估，则返回 True，否则返回 False。

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) – 目标试验对象。

返回类型:

无

infer_relative_search_space(study, trial)[源代码]

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

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

参数:

  • study (Study) – 目标研究对象。

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

返回:

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

返回类型:

dict[str, BaseDistribution]

另请参阅

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

is_exhausted(study)[源代码]

如果所有可能的参数都已评估，则返回 True，否则返回 False。

参数:

study (Study)

返回类型:

bool

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。

注意

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

参数:
返回:

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

返回类型:

dict[str, Any]