optuna.study

class optuna.study.Study(study_name: str, storage: Union[str, storages.BaseStorage], sampler: samplers.BaseSampler = None, pruner: pruners.BasePruner = None)[source]

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.

property best_params

Return parameters of the best trial in the study.

Returns

A dictionary containing parameters of the best trial.

property best_trial

Return the best trial in the study.

Returns

A FrozenTrial object of the best trial.

property best_value

Return the best objective value in the study.

Returns

A float representing the best objective value.

property direction

Return the direction of the study.

Returns

A StudyDirection object.

enqueue_trial(params: Dict[str, Any]) → None[source]

Enqueue a trial with given parameter values.

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

Example

import optuna

def objective(trial):
    x = trial.suggest_uniform('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}
Parameters

params – Parameter values to pass your objective function.

Note

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: bool = True) → List[FrozenTrial]

Return all trials in the study.

The returned trials are ordered by trial number.

For library users, it’s recommended to use more handy trials property to get the trials instead.

Parameters

deepcopy – 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.

Returns

A list of FrozenTrial objects.

optimize(func: ObjectiveFuncType, n_trials: Optional[int] = None, timeout: Optional[float] = None, n_jobs: int = 1, catch: Union[Tuple[()], Tuple[Type[Exception]]] = (), callbacks: Optional[List[Callable[[Study, FrozenTrial], None]]] = None, gc_after_trial: bool = False, show_progress_bar: bool = False) → None[source]

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’.

Parameters

  • func – A callable that implements objective function.

  • n_trials – 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 – 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 – The number of parallel jobs. If this argument is set to -1, the number is set to CPU count.

  • catch – 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 – 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 –

    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.

    See also

    How do I avoid running out of memory (OOM) when optimizing studies?

  • show_progress_bar – 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\).

set_user_attr(key: str, value: Any) → None[source]

Set a user attribute to the study.

Parameters

  • key – A key string of the attribute.

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

stop() → None[source]

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.

Raises

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

Note

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

property trials

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).

Returns

A list of FrozenTrial objects.

trials_dataframe(attrs: Tuple[str, …] = 'number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state', multi_index: bool = False) → pd.DataFrame[source]

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.

Example

import optuna
import pandas

def objective(trial):
    x = trial.suggest_uniform('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.
Parameters

  • attrs – Specifies field names of FrozenTrial to include them to a DataFrame of trials.

  • multi_index – 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.

Returns

A pandas DataFrame of trials in the Study.

property user_attrs

Return user attributes.

Returns

A dictionary containing all user attributes.

optuna.study.create_study(storage: Union[None, str, storages.BaseStorage] = None, sampler: samplers.BaseSampler = None, pruner: pruners.BasePruner = None, study_name: Optional[str] = None, direction: str = 'minimize', load_if_exists: bool = False) → Study[source]

Create a new Study.

Parameters

  • storage –

    Database URL. If this argument is set to None, in-memory storage is used, and the Study will not be persistent.

    Note

    When a database URL is passed, Optuna internally uses SQLAlchemy to handle the database. Please refer to SQLAlchemy’s document for further details. If you want to specify non-default options to SQLAlchemy Engine, you can instantiate RDBStorage with your desired options and pass it to the storage argument instead of a URL.

  • sampler – A sampler object that implements background algorithm for value suggestion. If None is specified, TPESampler is used as the default. See also samplers.

  • pruner – A pruner object that decides early stopping of unpromising trials. See also pruners.

  • study_name – Study’s name. If this argument is set to None, a unique name is generated automatically.

  • direction – Direction of optimization. Set minimize for minimization and maximize for maximization.

  • load_if_exists – Flag to control the behavior to handle a conflict of study names. In the case where a study named study_name already exists in the storage, a DuplicatedStudyError is raised if load_if_exists is set to False. Otherwise, the creation of the study is skipped, and the existing one is returned.

Returns

A Study object.

See also

The alias also exists as optuna.create_study().

optuna.study.load_study(study_name: str, storage: Union[str, storages.BaseStorage], sampler: samplers.BaseSampler = None, pruner: pruners.BasePruner = None) → Study[source]

Load the existing Study that has the specified name.

Parameters

  • study_name – Study’s name. Each study has a unique name as an identifier.

  • storage – Database URL such as sqlite:///example.db. Please see also the documentation of create_study() for further details.

  • sampler – A sampler object that implements background algorithm for value suggestion. If None is specified, TPESampler is used as the default. See also samplers.

  • pruner – A pruner object that decides early stopping of unpromising trials. If None is specified, MedianPruner is used as the default. See also pruners.

See also

The alias also exists as optuna.load_study().

optuna.study.delete_study(study_name: str, storage: Union[str, storages.BaseStorage]) → None[source]

Delete a Study object.

Parameters

  • study_name – Study’s name.

  • storage – Database URL such as sqlite:///example.db. Please see also the documentation of create_study() for further details.

See also

The alias also exists as optuna.delete_study().

optuna.study.get_all_study_summaries(storage: Union[str, storages.BaseStorage]) → List[StudySummary][source]

Get all history of studies stored in a specified storage.

Parameters

storage – Database URL such as sqlite:///example.db. Please see also the documentation of create_study() for further details.

Returns

List of study history summarized as StudySummary objects.

See also

The alias also exists as optuna.get_all_study_summaries().

class optuna.study.StudyDirection[source]

Direction of a Study.

NOT_SET

Direction has not been set.

MINIMIZE

Study minimizes the objective function.

MAXIMIZE

Study maximizes the objective function.

class optuna.study.StudySummary(study_name: str, direction: optuna._study_direction.StudyDirection, best_trial: Optional[optuna.trial._frozen.FrozenTrial], user_attrs: Dict[str, Any], system_attrs: Dict[str, Any], n_trials: int, datetime_start: Optional[datetime.datetime], study_id: int)[source]

Basic attributes and aggregated results of a Study.

See also optuna.study.get_all_study_summaries().

study_name

Name of the Study.

direction

StudyDirection of the Study.

best_trial

FrozenTrial with best objective value in the Study.

user_attrs

Dictionary that contains the attributes of the Study set with optuna.study.Study.set_user_attr().

system_attrs

Dictionary that contains the attributes of the Study internally set by Optuna.

n_trials

The number of trials ran in the Study.

datetime_start

Datetime where the Study started.