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 (Tree-structured Parzen Estimator) アルゴリズムを使用するサンプラー。

各トライアルにおいて、各パラメータに対して、TPE は最適な目的値に関連付けられたパラメータ値の集合に対して1つのガウス混合モデル (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)

Note

v4.0.0 で大幅に高速化された TPESampler (記事参照) は、多数のトライアルを用いた多目的最適化にも対応しています。ただし、多目的最適化ではデフォルトで NSGAIISampler が使用されるため、 TPESampler を多目的最適化で使用する場合は、 sampler を明示的に指定する必要があります。

Parameters:

consider_prior (bool) –
True の場合、ガウス事前分布を課すことでパーゼン推定器の安定性を向上させます。事前分布は、サンプリング分布が FloatDistribution または IntDistribution の場合にのみ有効です。

Warning

v4.3.0 で非推奨となりました。consider_prior 引数は将来のバージョンで削除予定です。この機能の削除は v6.0.0 で予定されていますが、変更される可能性があります。 v4.3.0 以降、consider_prior は True に自動設定されます。詳細は https://github.com/optuna/optuna/releases/tag/v4.3.0 を参照してください。
prior_weight (float) – 事前分布の重み。この引数は FloatDistribution、 IntDistribution、 CategoricalDistribution で使用されます。
consider_magic_clip (bool) – パーゼン推定器で使用するガウス分布の最小分散を制限するヒューリスティックを有効にします。
consider_endpoints (bool) – パーゼン推定器でガウス分布の分散を計算する際に、ドメインの端点を考慮します。分散計算のヒューリスティックの詳細については原論文を参照してください。
n_startup_trials (int) – 指定されたトライアル数に達するまで、TPE アルゴリズムではなくランダムサンプリングを使用します。
n_ei_candidates (int) – 期待改善度を計算する際に使用する候補サンプル数。
gamma (Callable[[int], int]) – 終了したトライアル数を受け取り、低粒度サンプルの密度関数を形成するトライアル数を返す関数。詳細は原論文を参照してください。
weights (Callable[[int], np.ndarray]) –
終了したトライアル数を受け取り、それらの重みを返す関数。詳細は Making a Science of Model Search: Hyperparameter Optimization in Hundreds of Dimensions for Vision Architectures を参照してください。

Note

多目的最適化の場合、この引数は不良試行（g(x) 構築用試行）の重み計算にのみ使用されます。一方、良好試行（l(x) 構築用試行）の重み計算は、MOTPE 論文で提案されたハイパーボリューム寄与に基づくルールによって行われます。
seed (int | None) – 乱数生成器のシード値
multivariate (bool) –
これが True の場合、パラメータ提案時に多変量 TPE が使用されます。多変量 TPE は独立 TPE よりも優れた性能を示すことが報告されています。詳細は BOHB: Robust and Efficient Hyperparameter Optimization at Scale および当社記事を参照してください。

Note

v2.2.0 で実験的機能として追加されました。インターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v2.2.0 を参照してください。
group (bool) –
multivariate が True の場合、グループ分割された探索空間を用いた多変量 TPE が使用されます。サンプリングアルゴリズムは過去の試行に基づいて探索空間を分割し、各分割空間から結合分布に従ってサンプルを抽出します。分割空間は全体の探索空間の分割であり、各サブスペースは以下の条件を満たす全体の最大部分集合です：完了した試行のサブスペースと探索空間の共通部分がサブスペース自身または空集合であること。サブスペース上の結合分布からのサンプリングは多変量 TPE によって実現されます。 group が True の場合、multivariate も True でなければなりません。

Note

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 の場合、近傍のパラメータ構成を提案しないように実行中の試行をペナルティします。

Note

異常終了した試行はストレージに RUNNING 状態の記録が残ることがあります。このような「ゾンビ」試行パラメータは、constant liar アルゴリズムによって後続のサンプリング時に回避されます。 RDBStorage を使用する場合、heartbeat_interval を設定して異常終了した試行の記録を FAIL に変更することが可能です。

Note

分散最適化を行う場合、この値を True に設定することをお勧めします。特に、各目的関数評価が高価で実行状態の持続時間が長い場合や、ワーカー数が多い場合に有効です。

Note

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 は各成功トライアルの後に評価されます。トライアルが失敗した場合やプルーニングされた場合は呼び出されませんが、この動作は将来のリリースで変更される可能性があります。

Note

v3.0.0 で実験的機能として追加されました。インターフェースは予告なく変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.0.0 を参照してください。
categorical_distance_func (dict[str, Callable[[CategoricalChoiceType, CategoricalChoiceType], float]] | None) –
カテゴリカルパラメータの距離関数辞書。キーはカテゴリカルパラメータ名、値は2つの CategoricalChoiceType を受け取り float を返す距離関数です。距離関数は非負の値を返す必要があります。

デフォルトではカテゴリカル選択は均等に扱われますが、このオプションによりカテゴリカルパラメータの構造に関する事前知識を指定できます。指定すると、現在の最良選択に近いカテゴリカル選択が優先的にサンプリングされます。

Note

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

メソッド

`after_trial`(study, trial, state, values)	Trial post-processing.
`before_trial`(study, trial)	Trial pre-processing.
`hyperopt_parameters`()	Return the the default parameters of hyperopt (v0.1.2).
`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

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)

Returns:: hyperopt のデフォルトパラメータを含む辞書。
Return type:: dict[str, Any]

infer_relative_search_space(study, trial)[source]

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

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

Parameters:

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

Returns:

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

Return type:

dict[str, BaseDistribution]