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

バックエンドとして 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 をサポートしていません。ただし、FloatDistribution の step オプション、 (suggest_float()) および IntDistribution (suggest_int()) はサポートされています。

探索空間にカテゴリカルパラメータが含まれる場合は、 TPESampler の使用を推奨します。また、並列最適化設定ではパフォーマンス改善の余地があります。このサンプラーでは、多変量正規分布のパラメータ更新に一部のトライアルを使用できません。

CMA-ES アルゴリズムの詳細については、以下の論文を参照してください:

See also

cma ライブラリをバックエンドとして使用するサンプラー optuna_integration.PyCmaSampler も利用可能です。

Parameters:

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) – 指定された数のトライアルが完了するまで、CMA-ES アルゴリズムの代わりに独立サンプリングが使用されます。
independent_sampler (BaseSampler | None) –
独立サンプリングに使用される BaseSampler インスタンス。相対探索空間に含まれないパラメータはこのサンプラーによってサンプリングされます。 CmaEsSampler の探索空間は intersection_search_space() によって決定されます。

None が指定された場合、RandomSampler がデフォルトとして使用されます。

See also

optuna.samplers モジュールには、RandomSampler や TPESampler などの組み込み独立サンプラーが用意されています。
warn_independent_sampling (bool) –
これが True の場合、独立サンプラーを使用してパラメータ値がサンプリングされたときに警告メッセージが出力されます。

注意: スタディの最初のトライアルは常に独立サンプラーによってサンプリングされるため、この場合警告メッセージは出力されません。
restart_strategy (str | None) –
局所最小値に収束した際の CMA-ES 最適化の再起動戦略。 None が指定された場合、CMA-ES は再起動しません (デフォルト)。 ‘ipop’ が指定された場合、CMA-ES は人口サイズを増加させて再起動します。 ‘bipop’ が指定された場合、CMA-ES は人口サイズを増加または減少させて再起動します。 inc_popsize パラメータも参照してください。

Warning

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' が指定された場合に使用されます。

Warning

v4.4.0 で非推奨。inc_popsize 引数は将来削除される予定です。この機能の削除は現在 v6.0.0 で予定されていますが、このスケジュールは変更される可能性があります。 v4.4.0 以降、inc_popsize は Optuna 内で使用されなくなり、 inc_popsize は OptunaHub でサポートされます。詳細は https://github.com/optuna/optuna/releases/tag/v4.4.0 を参照してください。
consider_pruned_trials (bool) –
これが True の場合、PRUNED トライアルがサンプリングの対象となります。

Note

v2.0.0 で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v2.0.0 を参照してください。

Note

MedianPruner を使用する場合は False に設定することが推奨されます。一方、HyperbandPruner を使用する場合は True に設定することが推奨されます。詳細はベンチマーク結果を参照してください。
use_separable_cma (bool) –
これが True の場合、共分散行列は対角行列に制約されます。モデルの複雑さを軽減するため、共分散行列の学習率が増加します。その結果、このアルゴリズムは分離可能な関数において CMA-ES よりも優れた性能を発揮します。

Note

v2.6.0 で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v2.6.0 を参照してください。
with_margin (bool) –
これが True の場合、マージン付き CMA-ES が使用されます。このアルゴリズムは、各離散分布 (FloatDistribution で step を指定し、 IntDistribution を使用する場合) において、サンプルが単一の点に固定されるのを防ぎます。現在、このオプションは use_separable_cma=True と併用できません。

Note

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 と併用できません。

Note

v3.3.0 以降で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.3.0 を参照してください。
source_trials (list[FrozenTrial] | None) –
このオプションは、類似の HPO タスクにおける事前知識を CMA-ES の初期化を通じて転送する Warm Starting CMA-ES 用です。この手法は source_trials から有望な分布を推定し、多変量ガウス分布のパラメータを生成します。 x0、sigma0、または use_separable_cma 引数と併用することは禁止されています。

Note

v2.6.0 で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v2.6.0 を参照してください。

メソッド

`after_trial`(study, trial, state, values)	Trial post-processing.
`before_trial`(study, trial)	Trial pre-processing.
`infer_relative_search_space`(study, trial)	Infer the search space that will be used by relative sampling in the target trial.
`reseed_rng`()	Reseed sampler's random number generator.
`sample_independent`(study, trial, param_name, ...)	Sample a parameter for a given distribution.
`sample_relative`(study, trial, search_space)	Sample parameters in a given search space.

after_trial(study, trial, state, values)[source]

トライアルの事後処理。

このメソッドは、目的関数が返された後、トライアルが終了して状態が保存される直前に呼び出されます。

Note

v2.4.0 で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v2.4.0 を参照してください。

Parameters:

study (Study) – 対象のスタディオブジェクト。
trial (FrozenTrial) – 対象のトライアルオブジェクト。このオブジェクトを変更する前にコピーを作成してください。
state (TrialState) – 結果のトライアル状態。
values (Sequence[float] | None) – 結果のトライアル値。トライアルが成功した場合、None にはなりません。

Return type:

None

before_trial(study, trial)[source]

トライアルの事前処理。

このメソッドは、目的関数が呼び出される前、トライアルがインスタンス化された直後に呼び出されます。より正確には、トライアルの初期化中、 infer_relative_search_space() の呼び出し直前に呼び出されます。つまり、探索空間を推論する前に行うべき事前処理を担当します。

Note

v3.3.0 で実験的機能として追加されました。このインターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.3.0 を参照してください。

Parameters:

study (Study) – 対象のスタディオブジェクト。
trial (FrozenTrial) – 対象のトライアルオブジェクト。

Return type:

None

infer_relative_search_space(study, trial)[source]

対象のトライアルで相対サンプリングに使用する探索空間を推論します。

このメソッドは sample_relative() メソッドの直前に呼び出され、このメソッドが返す探索空間が渡されます。探索空間に含まれないパラメータは、 sample_independent() メソッドを使用してサンプリングされます。

Parameters:

study (Study) – 対象のスタディオブジェクト。
trial (FrozenTrial) – 対象のトライアルオブジェクト。このオブジェクトを変更する前にコピーを作成してください。

Returns:

パラメータ名とパラメータの分布を含む辞書。

Return type:

dict[str, BaseDistribution]