optuna.samplers.GridSampler

class optuna.samplers.GridSampler(search_space, seed=None)[source]

使用网格搜索的采样器。

使用 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 不会处理由离散建议方法指定的参数量化，而只是从搜索空间中指定的值中采样一个。例如，在以下代码片段中，将采样 -0.5 或 0.5 作为 x，而不是整数点。

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

试验后处理。

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

注意

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

参数:

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

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

  • state (TrialState) – 结果试验状态。

  • values (Sequence[float] | None) – 结果试验值。如果试验成功，保证不是 None。

返回类型:

None

before_trial(study, trial)[source]

试验前处理。

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

注意

作为实验性功能在 v3.3.0 中添加。接口在更新版本中可能会更改，恕不另行通知。详见 https://github.com/optuna/optuna/releases/tag/v3.3.0。

参数:

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

  • trial (FrozenTrial) – 目标试验对象。

返回类型:

None

infer_relative_search_space(study, trial)[source]

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

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

参数:

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

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

返回:

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

返回类型:

dict[str, BaseDistribution]

另请参见

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

is_exhausted(study)[source]

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

参数:

study (Study)

返回类型:

bool

reseed_rng()[source]

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

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

返回类型:

None

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

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

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

注意

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

参数:

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

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

  • param_name (str) – 采样的参数名称。

  • param_distribution (BaseDistribution) – 指定采样算法的先验分布和/或尺度的分布对象。

返回:

一个参数值。

返回类型:

Any

sample_relative(study, trial, search_space)[source]

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

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

注意

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

参数:
返回:

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

返回类型:

dict[str, Any]