optuna.study¶
-
class
optuna.study.
Study
(study_name, storage, sampler=None, pruner=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()
andload_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)[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=True)¶ 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 toFalse
, 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, n_trials=None, timeout=None, n_jobs=1, catch=(), callbacks=None, gc_after_trial=False, show_progress_bar=False)[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 alsoTPESampler
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. Iftimeout
is also set toNone
, 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. Ifn_trials
is also set toNone
, 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
andFrozenTrial
.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 callinggc.collect()
. If you see an increase in memory consumption over several trials, try setting this flag toTrue
.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 whenn_jobs
\(\ne 1\).
-
set_user_attr
(key, value)[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 theoptimize()
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='number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state', multi_index=False)[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 toparams_x
when set toFalse
.
- Returns
-
property
user_attrs
¶ Return user attributes.
- Returns
A dictionary containing all user attributes.
-
property
-
optuna.study.
create_study
(storage=None, sampler=None, pruner=None, study_name=None, direction='minimize', load_if_exists=False)[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 thestorage
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 alsosamplers
.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 andmaximize
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 thestorage
, aDuplicatedStudyError
is raised ifload_if_exists
is set toFalse
. 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, storage, sampler=None, pruner=None)[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 ofcreate_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 alsosamplers
.pruner – A pruner object that decides early stopping of unpromising trials. If
None
is specified,MedianPruner
is used as the default. See alsopruners
.
See also
The alias also exists as optuna.load_study()
.
-
optuna.study.
delete_study
(study_name, storage)[source]¶ Delete a
Study
object.- Parameters
study_name – Study’s name.
storage – Database URL such as
sqlite:///example.db
. Please see also the documentation ofcreate_study()
for further details.
See also
The alias also exists as optuna.delete_study()
.
-
optuna.study.
get_all_study_summaries
(storage)[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 ofcreate_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.
-
-
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()
.-
direction
¶ StudyDirection
of theStudy
.
-
user_attrs
¶ Dictionary that contains the attributes of the
Study
set withoptuna.study.Study.set_user_attr()
.
-