optuna.study.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.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
Return parameters of the best trial in the study.
Return the best trial in the study.
Return trials located at the Pareto front in the study.
Return the best objective value in the study.
Return the direction of the study.
Return the directions of the study.
Return system attributes.
Return all trials in the study.
Return user attributes.
-
add_trial
(trial)[source]¶ Add trial to study.
The trial is validated before being added.
Example
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
See also
This method should in general be used to add already evaluated trials (
trial.state.is_finished() == True
). To queue trials for evaluation, please refer toenqueue_trial()
.See also
See
create_trial()
for how to create trials.- Parameters
trial (optuna.trial._frozen.FrozenTrial) – Trial to add.
- Raises
ValueError – If trial is an invalid state.
- Return type
Note
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)[source]¶ Add trials to study.
The trials are validated before being added.
Example
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 also
See
add_trial()
for addition of each trial.- Parameters
trials (Iterable[optuna.trial._frozen.FrozenTrial]) – Trials to add.
- Raises
ValueError – If
trials
include invalid trial.- Return type
Note
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)[source]¶ 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 offunc
. Each call to this method should be followed by a call totell()
to finish the created trial.See also
The Ask-and-Tell Interface tutorial provides use-cases with examples.
Example
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)
Example
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
- Parameters
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.- Returns
A
Trial
.- Return type
optuna.trial._trial.Trial
-
property
best_params
¶ Return parameters of the best trial in the study.
- Returns
A dictionary containing parameters of the best trial.
- Raises
RuntimeError – If the study has more than one direction.
-
property
best_trial
¶ Return the best trial in the study.
- Returns
A
FrozenTrial
object of the best trial.- Raises
RuntimeError – If the study has more than one direction.
-
property
best_trials
¶ 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 trialt1
ifall(v0 <= v1) for v0, v1 in zip(t0.values, t1.values)
andany(v0 < v1) for v0, v1 in zip(t0.values, t1.values)
are held.- Returns
A list of
FrozenTrial
objects.
-
property
best_value
¶ Return the best objective value in the study.
- Returns
A float representing the best objective value.
- Raises
RuntimeError – If the study has more than one direction.
-
property
direction
¶ Return the direction of the study.
- Returns
A
StudyDirection
object.- Raises
RuntimeError – If the study has more than one direction.
-
property
directions
¶ Return the directions of the study.
- Returns
A list of
StudyDirection
objects.
-
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_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}
- Parameters
params (Dict[str, Any]) – Parameter values to pass your objective function.
- Return type
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, states=None)¶ Return all trials in the study.
The returned trials are ordered by trial number.
Example
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) – 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.states (Optional[Tuple[optuna.trial._state.TrialState, ..]]) – Trial states to filter on. If
None
, include all states.
- Returns
A list of
FrozenTrial
objects.- Return type
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)[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’.Example
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 (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. Iftimeout
is also set toNone
, 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. 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 (int) –
The number of parallel jobs. If this argument is set to
-1
, the number is set to CPU count.Note
n_jobs
allows parallelization usingthreading
and may suffer from Python’s GIL. It is recommended to use process-based parallelization iffunc
is CPU bound.Warning
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.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
andFrozenTrial
.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 callinggc.collect()
. If you see an increase in memory consumption over several trials, try setting this flag toTrue
.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 whenn_jobs
\(\ne 1\).
- Raises
RuntimeError – If nested invocation of this method occurs.
- Return type
-
set_system_attr
(key, value)[source]¶ 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.
-
set_user_attr
(key, value)[source]¶ Set a user attribute to the study.
See also
See
user_attrs
for related attribute.Example
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"], }
-
stop
()[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.Example
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
- Raises
RuntimeError – If this method is called outside an objective function or callback.
- Return type
-
property
system_attrs
¶ Return system attributes.
- Returns
A dictionary containing all system attributes.
-
tell
(trial, values=None, state=TrialState.COMPLETE)[source]¶ Finish a trial created with
ask()
.See also
The Ask-and-Tell Interface tutorial provides use-cases with examples.
Example
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)
- Parameters
trial (Union[optuna.trial._trial.Trial, int]) – A
Trial
object or a trial number.values (Optional[Union[float, Sequence[float]]]) – Optional objective value or a sequence of such values in case the study is used for multi-objective optimization. Argument must be provided if
state
isCOMPLETE
and should beNone
ifstate
isFAIL
orPRUNED
.state (optuna.trial._state.TrialState) – State to be reported. Must be
COMPLETE
,FAIL
orPRUNED
.
- Raises
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
isCOMPLETE
butvalues
isNone
.state
isFAIL
orPRUNED
butvalues
is notNone
.state
is notCOMPLETE
,FAIL
orPRUNED
.trial
is a trial number but no trial exists with that number.
- Return type
-
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, states=None)
.- 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_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.
- Parameters
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 toparams_x
when set toFalse
.
- Returns
- Return type
pandas.core.frame.DataFrame
Note
If
value
is inattrs
during multi-objective optimization, it is implicitly replaced withvalues
.
-
property
user_attrs
¶ Return user attributes.
See also
See
set_user_attr()
for related method.Example
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
A dictionary containing all user attributes.
-