optuna.samplers.QMCSampler

class optuna.samplers.QMCSampler(*, qmc_type='sobol', scramble=False, seed=None, independent_sampler=None, warn_asynchronous_seeding=True, warn_independent_sampling=True)[source]

低不一致性列を生成する準モンテカルロサンプラー。

準モンテカルロ（QMC）列は、標準的な乱数列よりも低い不一致性を持つように設計されています。 ハイパーパラメータ最適化において、標準的な乱数列よりも優れた性能を発揮することが知られています。

ハイパーパラメータ最適化におけるQMC列の使用に関する詳細については、以下の論文を参照してください：

本実装ではScipyのQMC実装を使用しています。QMCアルゴリズムの詳細については、 scipy.stats.qmc のAPIドキュメントを参照してください。

Note

サンプラーの探索空間は、スタディ内の過去のトライアルまたは このサンプラーが最初にサンプリングするトライアルによって決定されます。

スタディに過去のトライアルが存在する場合、 QMCSampler は スタディ内で最初に作成されたトライアルを使用して探索空間を推定します。

それ以外の場合（スタディに過去のトライアルが存在しない場合）、 QMCSampler は 最初のトライアルを independent_sampler でサンプリングし、2番目のトライアルで 探索空間を推定します。

前述の通り、 QMCSampler の探索空間はスタディの最初のトライアルによって決定されます。 一度決定された探索空間は後から変更できません。

Parameters:

  • qmc_type (str) –

    サンプリングするQMC列のタイプ。 “halton”`または”sobol”` のいずれかを指定します。 デフォルトは “sobol” です。

    Note

    Sobol’列は、各正の整数 \(m\) に対してサンプル数 \(n=2^m\) の場合に 低不一致性特性を持つように設計されています。 QMCSampler が提案するトライアル数を 事前に指定できる場合、トライアル数は2のべき乗に設定することが推奨されます。

  • scramble (bool) – このオプションが True の場合、QMC列に乱数化（スクランブリング）が適用されます。

  • seed (int | None) –

    QMCSampler のシード値。この引数は scramble が True の場合にのみ使用されます。 値が None の場合、ランダムなシードが初期化されます。デフォルトは None です。

    Note

    複数の QMCSampler を並列または分散環境で最適化する場合、 scrambling が有効になっている場合、すべてのサンプラーは同じシードを共有する必要があります。 そうでない場合、サンプルの低不一致性特性が劣化する可能性があります。

  • independent_sampler (BaseSampler | None) –

    独立サンプリングに使用する BaseSampler のインスタンス。 スタディの最初のトライアルおよび相対探索空間に含まれないパラメータはこのサンプラーでサンプリングされます。

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

    See also

    samplers モジュールには、 RandomSampler や TPESampler などの組み込み独立サンプラーが用意されています。

  • warn_independent_sampling (bool) –

    これが True の場合、独立サンプラーを使用してパラメータ値がサンプリングされたときに警告メッセージが表示されます。

    スタディの最初のトライアルのパラメータは通常独立サンプラーでサンプリングされるため、このような場合に警告メッセージは表示されません。

  • warn_asynchronous_seeding (bool) –

    これが True の場合、QMCシーケンスにscrambling（乱数化）が適用され、サンプラーのランダムシードが手動で設定されていない場合に警告メッセージが表示されます。

    Note

    手動でシードを設定せずに並列または分散最適化を行う場合、 QMCSampler の各ワーカーインスタンスごとにランダムにシードが設定されるため、 最適化に使用される複数のサンプラー間で非同期的なシード設定が行われることになります。

    See also

    QMCSampler のパラメータ seed を参照してください。

使用例

QMCSampler を使用して単純な二次関数を最適化します。

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.QMCSampler()
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=8)

Note

v3.0.0で実験的機能として追加されました。インターフェースは予告なく変更される可能性があります。 詳細は https://github.com/optuna/optuna/releases/tag/v3.0.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 (optuna.trial.FrozenTrial) – 対象のトライアルオブジェクト。 このオブジェクトを変更する前にコピーを作成してください。

  • state (TrialState) – トライアルの最終状態。

  • values (Sequence[float] | None) – トライアルの最終値。トライアルが成功した場合、:obj:`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]

See also

intersection_search_space() は infer_relative_search_space() の実装例です。

reseed_rng()[source]

サンプラーの乱数生成器のシードをリセットします。

このメソッドは Study インスタンスが並列実行( n_jobs>1 オプション)される場合に 呼び出されます。この場合、乱数生成器の状態を含むサンプラーインスタンスが複製され、 同じ値を提案する可能性があります。この問題を防ぐため、各乱数生成器に異なるシードを割り当てます。

Return type:

None

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

指定された分布からパラメータをサンプリングします。

このメソッドは sample_relative() メソッドで返される探索空間に含まれない パラメータに対してのみ呼び出されます。ランダムサンプリングやTPEなど、パラメータ間の関係を使用しない サンプリングアルゴリズムに適しています。

Note

組み込みサンプラーは失敗したトライアルを無視して新しいパラメータをサンプリングします。 したがって、失敗したトライアルはサンプラーの観点では削除されたものとみなされます。

Parameters:

  • study (Study) – 対象のスタディオブジェクト。

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

  • param_name (str) – サンプリングするパラメータの名前。

  • param_distribution (BaseDistribution) – サンプリングアルゴリズムの事前分布とスケールを指定する分布オブジェクト。

Returns:

パラメータ値。

Return type:

Any

sample_relative(study, trial, search_space)[source]

指定された探索空間からパラメータをサンプリングします。

このメソッドは各トライアルの開始時(目的関数評価の直前)に1回呼び出されます。 ガウス過程やCMA-ESなど、パラメータ間の関係を利用するサンプリングアルゴリズムに適しています。

Note

組み込みサンプラーは失敗したトライアルを無視して新しいパラメータをサンプリングします。 したがって、失敗したトライアルはサンプラーの観点では削除されたものとみなされます。

Parameters:

  • study (Study) – 対象のスタディオブジェクト。

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

  • search_space (dict[str, BaseDistribution]) – infer_relative_search_space() で返される探索空間。

Returns:

パラメータ名と値を含む辞書。

Return type:

dict[str, Any]