optuna.study.Study

class optuna.study.Study(study_name, storage, sampler=None, pruner=None)[源代码]

A study corresponds to an optimization task, i.e., a set of trials.

This object provides interfaces to run a new Trial, access trials’ history, set/get user-defined attributes of the study itself.

Note that the direct use of this constructor is not recommended. To create and load a study, please refer to the documentation of create_study() and load_study() respectively.

Methods

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)

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_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])

Finish a trial created with ask().

trials_dataframe([attrs, multi_index])

Export trials as a pandas DataFrame.

Attributes

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.

system_attrs

Return system attributes.

trials

Return all trials in the study.

user_attrs

Return user attributes.

参数
返回类型

None

add_trial(trial)[源代码]

Add trial to study.

The trial is validated before being added.

示例

import optuna
from optuna.distributions import UniformDistribution


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": UniformDistribution(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

参见

This method should in general be used to add already evaluated trials (trial.state.is_finished() == True). To queue trials for evaluation, please refer to enqueue_trial().

参见

See create_trial() for how to create trials.

参数

trial (optuna.trial._frozen.FrozenTrial) – Trial to add.

引发

ValueError – If trial is an invalid state.

返回类型

None

注解

Added in v2.0.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.0.0.

add_trials(trials)[源代码]

Add trials to study.

The trials are validated before being added.

示例

import optuna
from optuna.distributions import UniformDistribution


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 add_trial() for addition of each trial.

参数

trials (Iterable[optuna.trial._frozen.FrozenTrial]) – Trials to add.

引发

ValueError – If trials include invalid trial.

返回类型

None

注解

Added in v2.5.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.5.0.

ask(fixed_distributions=None)[源代码]

Create a new trial from which hyperparameters can be suggested.

This method is part of an alternative to optimize() that allows controlling the lifetime of a trial outside the scope of func. Each call to this method should be followed by a call to tell() to finish the created trial.

参见

The Ask-and-Tell 接口 tutorial provides use-cases with examples.

示例

Getting the trial object with the ask() method.

import optuna


study = optuna.create_study()

trial = study.ask()

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

study.tell(trial, x ** 2)

示例

Passing previously defined distributions to the ask() method.

import optuna


study = optuna.create_study()

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

# You can pass the distributions previously defined.
trial = study.ask(fixed_distributions=distributions)

# `optimizer` and `lr` are already suggested and accessible with `trial.params`.
assert "optimizer" in trial.params
assert "lr" in trial.params
参数

fixed_distributions (Optional[Dict[str, optuna.distributions.BaseDistribution]]) – A dictionary containing the parameter names and parameter’s distributions. Each parameter in this dictionary is automatically suggested for the returned trial, even when the suggest method is not explicitly invoked by the user. If this argument is set to None, no parameter is automatically suggested.

返回

A Trial.

返回类型

optuna.trial._trial.Trial

property best_params: Dict[str, Any]

Return parameters of the best trial in the study.

返回

A dictionary containing parameters of the best trial.

引发

RuntimeError – If the study has more than one direction.

property best_trial: optuna.trial._frozen.FrozenTrial

Return the best trial in the study.

返回

A FrozenTrial object of the best trial.

引发

RuntimeError – If the study has more than one direction.

property best_trials: List[optuna.trial._frozen.FrozenTrial]

Return trials located at the Pareto front in the study.

A trial is located at the Pareto front if there are no trials that dominate the trial. It’s called that a trial t0 dominates another trial t1 if all(v0 <= v1) for v0, v1 in zip(t0.values, t1.values) and any(v0 < v1) for v0, v1 in zip(t0.values, t1.values) are held.

返回

A list of FrozenTrial objects.

property best_value: float

Return the best objective value in the study.

返回

A float representing the best objective value.

引发

RuntimeError – If the study has more than one direction.

property direction: optuna._study_direction.StudyDirection

Return the direction of the study.

返回

A StudyDirection object.

引发

RuntimeError – If the study has more than one direction.

property directions: List[optuna._study_direction.StudyDirection]

Return the directions of the study.

返回

A list of StudyDirection objects.

enqueue_trial(params)[源代码]

Enqueue a trial with given parameter values.

You can fix the next sampling parameters which will be evaluated in your objective function.

示例

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})
study.optimize(objective, n_trials=2)

assert study.trials[0].params == {"x": 5}
assert study.trials[1].params == {"x": 0}
参数

params (Dict[str, Any]) – Parameter values to pass your objective function.

返回类型

None

注解

Added in v1.2.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v1.2.0.

get_trials(deepcopy=True, states=None)

Return all trials in the study.

The returned trials are ordered by trial number.

示例

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
参数
  • deepcopy (bool) – Flag to control whether to apply copy.deepcopy() to the trials. Note that if you set the flag to False, you shouldn’t mutate any fields of the returned trial. Otherwise the internal state of the study may corrupt and unexpected behavior may happen.

  • states (Optional[Tuple[optuna.trial._state.TrialState, ...]]) – Trial states to filter on. If None, include all states.

返回

A list of FrozenTrial objects.

返回类型

List[optuna.trial._frozen.FrozenTrial]

optimize(func, n_trials=None, timeout=None, n_jobs=1, catch=(), callbacks=None, gc_after_trial=False, show_progress_bar=False)[源代码]

Optimize an objective function.

Optimization is done by choosing a suitable set of hyperparameter values from a given range. Uses a sampler which implements the task of value suggestion based on a specified distribution. The sampler is specified in create_study() and the default choice for the sampler is TPE. See also TPESampler for more details on ‘TPE’.

示例

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)
参数
  • func (Callable[[optuna.trial._trial.Trial], Union[float, Sequence[float]]]) – A callable that implements objective function.

  • n_trials (Optional[int]) – The number of trials. If this argument is set to None, there is no limitation on the number of trials. If timeout is also set to None, the study continues to create trials until it receives a termination signal such as Ctrl+C or SIGTERM.

  • timeout (Optional[float]) – Stop study after the given number of second(s). If this argument is set to None, the study is executed without time limitation. If n_trials is also set to None, the study continues to create trials until it receives a termination signal such as Ctrl+C or SIGTERM.

  • n_jobs (int) –

    The number of parallel jobs. If this argument is set to -1, the number is set to CPU count.

    注解

    n_jobs allows parallelization using threading and may suffer from Python’s GIL. It is recommended to use process-based parallelization if func is CPU bound.

    警告

    Deprecated in v2.7.0. This feature will be removed in the future. It is recommended to use process-based parallelization. The removal of this feature is currently scheduled for v4.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v2.7.0.

  • catch (Tuple[Type[Exception], ...]) – A study continues to run even when a trial raises one of the exceptions specified in this argument. Default is an empty tuple, i.e. the study will stop for any exception except for TrialPruned.

  • callbacks (Optional[List[Callable[[optuna.study.Study, optuna.trial._frozen.FrozenTrial], None]]]) – List of callback functions that are invoked at the end of each trial. Each function must accept two parameters with the following types in this order: Study and FrozenTrial.

  • gc_after_trial (bool) –

    Flag to determine whether to automatically run garbage collection after each trial. Set to True to run the garbage collection, False otherwise. When it runs, it runs a full collection by internally calling gc.collect(). If you see an increase in memory consumption over several trials, try setting this flag to True.

  • show_progress_bar (bool) – Flag to show progress bars or not. To disable progress bar, set this False. Currently, progress bar is experimental feature and disabled when n_jobs \(\ne 1\).

引发

RuntimeError – If nested invocation of this method occurs.

返回类型

None

set_system_attr(key, value)[源代码]

Set a system attribute to the study.

Note that Optuna internally uses this method to save system messages. Please use set_user_attr() to set users’ attributes.

参数
  • key (str) – A key string of the attribute.

  • value (Any) – A value of the attribute. The value should be JSON serializable.

返回类型

None

set_user_attr(key, value)[源代码]

Set a user attribute to the study.

参见

See user_attrs for related attribute.

示例

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"],
}
参数
  • key (str) – A key string of the attribute.

  • value (Any) – A value of the attribute. The value should be JSON serializable.

返回类型

None

stop()[源代码]

Exit from the current optimization loop after the running trials finish.

This method lets the running optimize() method return immediately after all trials which the optimize() method spawned finishes. This method does not affect any behaviors of parallel or successive study processes.

示例

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
引发

RuntimeError – If this method is called outside an objective function or callback.

返回类型

None

property system_attrs: Dict[str, Any]

Return system attributes.

返回

A dictionary containing all system attributes.

tell(trial, values=None, state=TrialState.COMPLETE)[源代码]

Finish a trial created with ask().

参见

The Ask-and-Tell 接口 tutorial provides use-cases with examples.

示例

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)

    # Iterative gradient descent objective function.
    x = 3  # Initial value.
    for step in range(128):
        y = f(x)

        trial.report(y, step=step)

        if trial.should_prune():
            # Finish the trial with the pruned state.
            study.tell(trial, state=TrialState.PRUNED)
            break

        gy = df(x)
        x -= gy * lr
    else:
        # Finish the trial with the final value after all iterations.
        study.tell(trial, y)
参数
引发
  • TypeError – If trial is not a Trial or an int.

  • ValueError – If any of the following. values is a sequence but its length does not match the number of objectives for its associated study. state is COMPLETE but values is None. state is FAIL or PRUNED but values is not None. state is not COMPLETE, FAIL or PRUNED. trial is a trial number but no trial exists with that number.

返回类型

None

property trials: List[optuna.trial._frozen.FrozenTrial]

Return all trials in the study.

The returned trials are ordered by trial number.

This is a short form of self.get_trials(deepcopy=True, states=None).

返回

A list of FrozenTrial objects.

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

Export trials as a pandas DataFrame.

The DataFrame provides various features to analyze studies. It is also useful to draw a histogram of objective values and to export trials as a CSV file. If there are no trials, an empty DataFrame is returned.

示例

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)

# Create a dataframe from the study.
df = study.trials_dataframe()
assert isinstance(df, pandas.DataFrame)
assert df.shape[0] == 3  # n_trials.
参数
  • attrs (Tuple[str, ...]) – Specifies field names of FrozenTrial to include them to a DataFrame of trials.

  • multi_index (bool) – Specifies whether the returned DataFrame employs MultiIndex or not. Columns that are hierarchical by nature such as (params, x) will be flattened to params_x when set to False.

返回

A pandas DataFrame of trials in the Study.

返回类型

pandas.core.frame.DataFrame

注解

If value is in attrs during multi-objective optimization, it is implicitly replaced with values.

property user_attrs: Dict[str, Any]

Return user attributes.

参见

See set_user_attr() for related method.

示例

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"],
}
返回

A dictionary containing all user attributes.