optuna

optuna.create_study(storage=None, sampler=None, pruner=None, study_name=None, direction='minimize', load_if_exists=False)

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

This is an alias for optuna.study.create_study().

optuna.load_study(study_name, storage, sampler=None, pruner=None)

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

This is an alias for optuna.study.load_study().

optuna.delete_study(study_name, storage)

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

This is an alias for optuna.study.delete_study().

optuna.get_all_study_summaries(storage)

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

This is an alias for optuna.study.get_all_study_summaries().

class optuna.TrialPruned

Exception for pruned trials.

This error tells a trainer that the current Trial was pruned. It is supposed to be raised after optuna.trial.Trial.should_prune() as shown in the following example.

Example

import numpy as np
from sklearn.datasets import load_iris
from sklearn.linear_model import SGDClassifier
from sklearn.model_selection import train_test_split

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)
classes = np.unique(y)

def objective(trial):
    alpha = trial.suggest_uniform('alpha', 0.0, 1.0)
    clf = SGDClassifier(alpha=alpha)
    n_train_iter = 100

    for step in range(n_train_iter):
        clf.partial_fit(X_train, y_train, classes=classes)

        intermediate_value = clf.score(X_valid, y_valid)
        trial.report(intermediate_value, step)

        if trial.should_prune():
            raise optuna.TrialPruned()

    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=20)

See also

This is an alias for optuna.exceptions.TrialPruned.