optuna.study.Study

class optuna.study.Study(study_name, storage, sampler=None, pruner=None)[source]

スタディは最適化タスク（すなわちトライアルの集合）に対応します。

このオブジェクトは、新しい Trial を実行するインターフェース、トライアルの履歴にアクセスするインターフェース、スタディ自体のユーザー定義属性を設定/取得するインターフェースを提供します。

このコンストラクタを直接使用することは推奨されません。スタディの作成と読み込みには、それぞれ create_study() と load_study() のドキュメントを参照してください。

メソッド

`add_trial`(trial)	Add trial to study.
`add_trials`(trials)	Add trials to study.
`ask`([fixed_distributions])	Create a new trial from which hyperparameters can be suggested.
`enqueue_trial`(params[, user_attrs, ...])	Enqueue a trial with given parameter values.
`get_trials`([deepcopy, states])	Return all trials in the study.
`optimize`(func[, n_trials, timeout, n_jobs, ...])	Optimize an objective function.
`set_metric_names`(metric_names)	Set metric names.
`set_system_attr`(key, value)	Set a system attribute to the study.
`set_user_attr`(key, value)	Set a user attribute to the study.
`stop`()	Exit from the current optimization loop after the running trials finish.
`tell`(trial[, values, state, skip_if_finished])	Finish a trial created with `ask()`.
`trials_dataframe`([attrs, multi_index])	Export trials as a pandas DataFrame.

属性

`best_params`	Return parameters of the best trial in the study.
`best_trial`	Return the best trial in the study.
`best_trials`	Return trials located at the Pareto front in the study.
`best_value`	Return the best objective value in the study.
`direction`	Return the direction of the study.
`directions`	Return the directions of the study.
`metric_names`	Return metric names.
`system_attrs`	Return system attributes.
`trials`	Return all trials in the study.
`user_attrs`	Return user attributes.

Parameters:

study_name (str)
storage (str | storages.BaseStorage)
sampler ('samplers.BaseSampler' | None)
pruner (pruners.BasePruner | None)

add_trial(trial)[source]

スタディにトライアルを追加します。

追加前にトライアルの検証が行われます。

使用例

import optuna
from optuna.distributions import FloatDistribution


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
assert len(study.trials) == 0

trial = optuna.trial.create_trial(
    params={"x": 2.0},
    distributions={"x": FloatDistribution(0, 10)},
    value=4.0,
)

study.add_trial(trial)
assert len(study.trials) == 1

study.optimize(objective, n_trials=3)
assert len(study.trials) == 4

other_study = optuna.create_study()

for trial in study.trials:
    other_study.add_trial(trial)
assert len(other_study.trials) == len(study.trials)

other_study.optimize(objective, n_trials=2)
assert len(other_study.trials) == len(study.trials) + 2

See also

このメソッドは通常、既に評価済みのトライアル（trial.state.is_finished() == True）を追加するために使用します。評価待ちのトライアルをキューに追加するには、enqueue_trial() を参照してください。

See also

トライアルの作成方法については、create_trial() を参照してください。

See also

評価済みの値を手動で指定してハイパーパラメータを定義するチュートリアルについては、第2のシナリオ: 既に評価済みのハイパーパラメータをOptunaに活用するを参照してください。

Parameters:: trial (FrozenTrial) – 追加するトライアル。
Return type:: None

add_trials(trials)[source]

スタディにトライアルを追加します。

追加前にトライアルの検証が行われます。

使用例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)
assert len(study.trials) == 3

other_study = optuna.create_study()
other_study.add_trials(study.trials)
assert len(other_study.trials) == len(study.trials)

other_study.optimize(objective, n_trials=2)
assert len(other_study.trials) == len(study.trials) + 2

See also

各トライアルの追加方法については、add_trial() を参照してください。

Parameters:: trials (Iterable[FrozenTrial]) – 追加するトライアル。
Return type:: None

ask(fixed_distributions=None)[source]

ハイパーパラメータを提案できる新しいトライアルを作成します。

このメソッドは、optimize() の代替手段の一部であり、 func のスコープ外でトライアルのライフタイムを制御できます。このメソッドを呼び出した後は、tell() を呼び出して作成したトライアルを終了する必要があります。

See also

Ask-and-Tell インターフェースチュートリアルでは、使用例とサンプルコードを提供しています。

使用例

ask() メソッドを使用してトライアルオブジェクトを取得する例。

import optuna

study = optuna.create_study()

trial = study.ask()

x = trial.suggest_float("x", -1, 1)

study.tell(trial, x**2)

使用例

ask() メソッドに事前に定義した分布を渡す例。

import optuna


study = optuna.create_study()

distributions = {
    "optimizer": optuna.distributions.CategoricalDistribution(["adam", "sgd"]),
    "lr": optuna.distributions.FloatDistribution(0.0001, 0.1, log=True),
}

# 事前に定義した分布を指定できます。
trial = study.ask(fixed_distributions=distributions)

# `optimizer` と `lr` はすでに提案され、`trial.params` でアクセス可能です。
assert "optimizer" in trial.params
assert "lr" in trial.params

Parameters:: fixed_distributions (dict[str, BaseDistribution] | None) – パラメータ名とその分布を含む辞書。この辞書の各パラメータは、ユーザーが明示的に提案メソッドを呼び出していない場合でも、返されるトライアルに自動的に提案されます。この引数を None に設定すると、どのパラメータも自動的に提案されません。
Returns:: Trial オブジェクト。
Return type:: Trial

property best_params: dict[str, Any]

スタディ内の最良トライアルのパラメータを返します。

Note

この機能は単一目的最適化でのみ使用できます。

Returns:: 最良トライアルのパラメータを含む辞書。

property best_trial: FrozenTrial

スタディ内の最良トライアルを返します。

Note

この機能は単一目的最適化でのみ使用できます。スタディが多目的最適化の場合、 best_trials を使用してください。

Returns:: 最良トライアルを表す FrozenTrial オブジェクト。

See also

最良のトライアルの再利用チュートリアルでは、このメソッドの詳細な使用例を提供しています。

property best_trials: list[FrozenTrial]

スタディ内のパレートフロントに位置するトライアルを返します。

トライアルがパレートフロントに位置するとは、他のトライアルが支配していない状態を指します。トライアル t0 がトライアル t1 を支配するとは、 all(v0 <= v1) for v0, v1 in zip(t0.values, t1.values) かつ any(v0 < v1) for v0, v1 in zip(t0.values, t1.values) が成り立つ場合です。

Returns:: FrozenTrial オブジェクトのリスト。

property best_value: float

スタディ内の最良目的値を返します。

Note

この機能は単一目的最適化でのみ使用できます。

Returns:: 最良目的値を表す浮動小数点数。

property direction: StudyDirection

スタディの方向を返します。

Note

この機能は単一目的最適化でのみ使用できます。スタディが多目的最適化の場合、 directions を使用してください。

Returns:: StudyDirection オブジェクト。

property directions: list[StudyDirection]

スタディの方向を返します。

Returns:: StudyDirection オブジェクトのリスト。

enqueue_trial(params, user_attrs=None, skip_if_exists=False)[source]

指定されたパラメータ値でトライアルをキューに追加します。

目的関数で評価する次のサンプリングパラメータを固定できます。

例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.enqueue_trial({"x": 5})
study.enqueue_trial({"x": 0}, user_attrs={"memo": "optimal"})
study.optimize(objective, n_trials=2)

assert study.trials[0].params == {"x": 5}
assert study.trials[1].params == {"x": 0}
assert study.trials[1].user_attrs == {"memo": "optimal"}

Parameters:

params (dict[str, Any]) – 目的関数に渡すパラメータ値。
user_attrs (dict[str, Any] | None) – params 以外のユーザー定義属性の辞書。
skip_if_exists (bool) –
True の場合、重複トライアルの再キューイングを防止します。

Note

このメソッドは、同じ params 辞書を使用して複数のプロセスから同時に呼び出された場合、重複トライアルを生成する可能性があります。

Return type:

None

See also

ハイパーパラメータを手動で指定するチュートリアルについては、最初のシナリオ：Optunaにハイパーパラメータを評価させるを参照してください。

get_trials(deepcopy=True, states=None)[source]

スタディ内のすべてのトライアルを返します。

返されるトライアルはトライアル番号順にソートされます。

See also

関連プロパティについては trials を参照してください。

例

import optuna


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

trials = study.get_trials()
assert len(trials) == 3

Parameters:

deepcopy (bool) – トライアルに copy.deepcopy() を適用するかどうかを制御するフラグ。このフラグを False に設定した場合、返されたトライアルのフィールドを変更しないでください。そうしないと、スタディの内部状態が破損し、予期しない動作が発生する可能性があります。
states (Container[TrialState] | None) – フィルタリングするトライアル状態。None の場合、すべての状態を含めます。

Returns:

FrozenTrial オブジェクトのリスト。

Return type:

list[FrozenTrial]

property metric_names: list[str] | None

メトリック名を返します。

Note

メトリック名を設定するには set_metric_names() を最初に呼び出してください。

Returns:: 目的関数の戻り値の各次元の名前のリスト。

optimize(func, n_trials=None, timeout=None, n_jobs=1, catch=(), callbacks=None, gc_after_trial=False, show_progress_bar=False)[source]

目的関数を最適化します。

最適化は、指定された範囲から適切なハイパーパラメータ値のセットを選択することで行われます。指定された分布に基づいて値を提案するタスクを実装するサンプラーを使用します。サンプラーは create_study() で指定され、デフォルトのサンプラーは TPE です。 ‘TPE’ の詳細については、TPESampler も参照してください。

最適化は、SIGINT や SIGTERM などの終了シグナルを受信すると停止します。他のシグナルとは異なり、SIGINT (Ctrl+C) を受信するとトライアルは自動的かつクリーンに失敗します。 n_jobs が 1 より大きい場合、または SIGINT 以外のシグナルが使用される場合、中断されたトライアル状態は適切に更新されません。

例

import optuna


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

Parameters:

func (ObjectiveFuncType) – 目的関数を実装する呼び出し可能オブジェクト。
n_trials (int | None) – 各プロセスのトライアル数。None はトライアル数に制限がないことを表します。スタディは、トライアル数が n_trials に達するか、timeout 期間が経過するか、 stop() が呼び出されるか、SIGTERM や Ctrl+C などの終了シグナルが受信されるまで、トライアルを作成し続けます。
timeout (float | None) – 指定された秒数後にスタディを停止します。None は経過時間に制限がないことを表します。スタディは、トライアル数が n_trials に達するか、timeout 期間が経過するか、 stop() が呼び出されるか、SIGTERM や Ctrl+C などの終了シグナルが受信されるまで、トライアルを作成し続けます。
n_jobs (int) –
並列ジョブの数。この引数を -1 に設定すると、CPU 数に設定されます。

Note

n_jobs は threading を使用した並列化を可能にしますが、 Python の GIL の影響を受ける可能性があります。 func が CPU バウンドの場合、プロセスベースの並列化の使用が推奨されます。
catch (Iterable[type[Exception]] | type[Exception]) – この引数で指定された例外のいずれかをトライアルが発生させても、スタディは実行を続けます。デフォルトは空のタプルで、TrialPruned 以外の例外が発生した場合にスタディが停止します。
callbacks (Iterable[Callable[[Study, FrozenTrial], None]] | None) –
各トライアルの終了時に呼び出されるコールバック関数のリスト。各関数は、以下の順序で2つのパラメータを受け取る必要があります: Study と FrozenTrial。

See also

Study.optimize 用のコールバックのチュートリアルを参照して、コールバック関数の使用方法と実装方法を確認してください。
gc_after_trial (bool) –
各トライアル後に自動的にガベージコレクションを実行するかどうかを決定するフラグ。 True に設定するとガベージコレクションが実行され、False に設定すると実行されません。実行時には、内部で gc.collect() を呼び出して完全なコレクションを実行します。複数のトライアルでメモリ消費量が増加する場合は、このフラグを True に設定してみてください。

See also

スタディの最適化時にメモリ不足（OOM）を回避する方法は？
show_progress_bar (bool) – 進捗バーを表示するかどうかを決定するフラグ。進捗バーを表示するには、 True に設定します。ただし、n_trials が None の場合や、 timeout が None の場合、または n_jobs が $\neq 1$ の場合は無効になります。

Raises:

RuntimeError – このメソッドがネストして呼び出された場合。

Return type:

None

set_metric_names(metric_names)[source]

メトリック名を設定します。

このメソッドは、目的関数の戻り値の各次元に名前を付けます。特に多目的最適化において有用です。メトリック名は主に可視化関数で参照されます。

例

import optuna
import pandas


def objective(trial):
    x = trial.suggest_float("x", 0, 10)
    return x**2, x + 1


study = optuna.create_study(directions=["minimize", "minimize"])
study.set_metric_names(["x**2", "x+1"])
study.optimize(objective, n_trials=3)


df = study.trials_dataframe(multi_index=True)
assert isinstance(df, pandas.DataFrame)
assert list(df.get("values").keys()) == ["x**2", "x+1"]

See also

このメソッドで設定された名前は、trials_dataframe() と plot_pareto_front() で使用されます。

Parameters:: metric_names (list[str]) – 目的関数のメトリック名のリスト。
Return type:: None

Note

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

set_system_attr(key, value)[source]

スタディにシステム属性を設定します。

Optuna はこのメソッドを内部的に使用してシステムメッセージを保存します。ユーザー属性を設定するには、 set_user_attr() を使用してください。

Parameters:

key (str) – 属性のキー文字列。
value (Any) – 属性の値。値は JSON シリアライズ可能である必要があります。

Return type:

None

Warning

v3.1.0 で非推奨となりました。この機能は将来的に削除される予定です。削除時期は v5.0.0 を予定していますが、変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.1.0 を参照してください。

set_user_attr(key, value)[source]

スタディにユーザー属性を設定します。

See also

関連属性については user_attrs を参照してください。

ユーザー属性のレシピも参照してください。

例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 1)
    y = trial.suggest_float("y", 0, 1)
    return x**2 + y**2


study = optuna.create_study()

study.set_user_attr("objective function", "quadratic function")
study.set_user_attr("dimensions", 2)
study.set_user_attr("contributors", ["Akiba", "Sano"])

assert study.user_attrs == {
    "objective function": "quadratic function",
    "dimensions": 2,
    "contributors": ["Akiba", "Sano"],
}

Parameters:

key (str) – 属性のキー文字列。
value (Any) – 属性の値。値は JSON シリアライズ可能である必要があります。

Return type:

None

stop()[source]

現在の最適化ループを、実行中のトライアルが終了した時点で終了します。

このメソッドは、optimize() メソッドが生成したすべてのトライアルが終了した時点で、 optimize() メソッドを直ちに終了させます。このメソッドは並列または連続的なスタディプロセスの動作には影響しません。このメソッドは目的関数またはコールバック内でのみ有効です。

例

import optuna


def objective(trial):
    if trial.number == 4:
        trial.study.stop()
    x = trial.suggest_float("x", 0, 10)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=10)
assert len(study.trials) == 5

Return type:: None

property system_attrs: dict[str, Any]

システム属性を取得します。

Returns:: すべてのシステム属性を含む辞書。

Warning

v3.1.0 で非推奨となりました。この機能は将来的に削除される予定です。削除時期は v5.0.0 を予定していますが、変更される可能性があります。詳細は https://github.com/optuna/optuna/releases/tag/v3.1.0 を参照してください。

tell(trial, values=None, state=None, skip_if_finished=False)[source]

ask() で作成されたトライアルを終了します。

See also

Ask-and-Tell インターフェースチュートリアルには使用例が記載されています。

例

import optuna
from optuna.trial import TrialState


def f(x):
    return (x - 2) ** 2


def df(x):
    return 2 * x - 4

study = optuna.create_study()

n_trials = 30

for _ in range(n_trials):
    trial = study.ask()

    lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True)

    # 反復勾配降下法の目的関数
    x = 3  # 初期値
    for step in range(128):
        y = f(x)

        trial.report(y, step=step)

        if trial.should_prune():
            # プルーニングされた状態でトライアルを終了
            study.tell(trial, state=TrialState.PRUNED)
            break

        gy = df(x)
        x -= gy * lr
    else:
        # 全反復終了後の最終値でトライアルを終了
        study.tell(trial, y)

Parameters:

trial (Trial | int) – Trial オブジェクトまたはトライアル番号
values (float | Sequence[float] | None) – 目的値またはマルチ目的最適化時の値のシーケンス（オプション）
state (TrialState | None) – 報告する状態（None, COMPLETE, FAIL, PRUNED のいずれか）
skip_if_finished (bool) – 終了済みトライアルに値を報告する際の例外制御フラグ（True でスキップ）

Return type:

FrozenTrial

property trials: list[FrozenTrial]

スタディ内のすべてのトライアルを取得します。

トライアルはトライアル番号順にソートされています。

self.get_trials(deepcopy=True, states=None) の簡易版です。

Returns:: FrozenTrial オブジェクトのリスト

trials_dataframe(attrs=('number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state'), multi_index=False)[source]

トライアルを pandas DataFrame としてエクスポートします。

この DataFrame はスタディの分析や目的値のヒストグラム作成、CSV ファイルへのエクスポートに便利です。トライアルが存在しない場合は空の DataFrame が返されます。

使用例

import optuna
import pandas


def objective(trial):
    x = trial.suggest_float("x", -1, 1)
    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

# スタディから DataFrame を作成
df = study.trials_dataframe()
assert isinstance(df, pandas.DataFrame)
assert df.shape[0] == 3  # n_trials に相当

Parameters:

attrs (tuple[str, ...]) – 取得するフィールド名を指定（デフォルト: (‘number’, ‘value’, ‘datetime_start’, ‘datetime_complete’, ‘duration’, ‘params’, ‘user_attrs’, ‘system_attrs’, ‘state’)）
multi_index (bool) – マルチインデックスを使用するかどうか（デフォルト: False）

Returns:

トライアル情報を含む pandas DataFrame

Return type:

pd.DataFrame

Note

マルチ目的最適化時に attrs に value が含まれている場合、values に置き換えられます。

Note

set_metric_names() が呼び出されている場合、value または values は目的名をキーとする辞書に置き換えられます。

property user_attrs: dict[str, Any]

ユーザー属性を取得します。

See also

set_user_attr() を参照してください。

使用例

import optuna


def objective(trial):
    x = trial.suggest_float("x", 0, 1)
    y = trial.suggest_float("y", 0, 1)
    return x**2 + y**2


study = optuna.create_study()

study.set_user_attr("objective function", "quadratic function")
study.set_user_attr("dimensions", 2)
study.set_user_attr("contributors", ["Akiba", "Sano"])

assert study.user_attrs == {
    "objective function": "quadratic function",
    "dimensions": 2,
    "contributors": ["Akiba", "Sano"],
}

Returns:: すべてのユーザー属性を含む辞書