optuna.trial.FrozenTrial

class optuna.trial.FrozenTrial(number, state, value, datetime_start, datetime_complete, params, distributions, user_attrs, system_attrs, intermediate_values, trial_id, *, values=None)[source]

Status and results of a Trial.

An object of this class has the same methods as Trial, but is not associated with, nor has any references to a Study.

It is therefore not possible to make persistent changes to a storage from this object by itself, for instance by using set_user_attr().

It will suggest the parameter values stored in params and will not sample values from any distributions.

It can be passed to objective functions (see optimize()) and is useful for deploying optimization results.

Example

Re-evaluate an objective function with parameter values optimized study.

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)

assert objective(study.best_trial) == study.best_value

Note

Instances are mutable, despite the name. For instance, set_user_attr() will update user attributes of objects in-place.

Example:

Overwritten attributes.

import copy
import datetime

import optuna


def objective(trial):
    x = trial.suggest_float("x", -1, 1)

    # this user attribute always differs
    trial.set_user_attr("evaluation time", datetime.datetime.now())

    return x**2


study = optuna.create_study()
study.optimize(objective, n_trials=3)

best_trial = study.best_trial
best_trial_copy = copy.deepcopy(best_trial)

# re-evaluate
objective(best_trial)

# the user attribute is overwritten by re-evaluation
assert best_trial.user_attrs != best_trial_copy.user_attrs

Note

Please refer to Trial for details of methods and properties.

Parameters:
number

Unique and consecutive number of Trial for each Study. Note that this field uses zero-based numbering.

state

TrialState of the Trial.

value

Objective value of the Trial. value and values must not be specified at the same time.

values

Sequence of objective values of the Trial. The length is greater than 1 if the problem is multi-objective optimization. value and values must not be specified at the same time.

datetime_start

Datetime where the Trial started.

datetime_complete

Datetime where the Trial finished.

params

Dictionary that contains suggested parameters.

distributions

Dictionary that contains the distributions of params.

user_attrs

Dictionary that contains the attributes of the Trial set with optuna.trial.Trial.set_user_attr().

system_attrs

Dictionary that contains the attributes of the Trial set with optuna.trial.Trial.set_system_attr().

intermediate_values

Intermediate objective values set with optuna.trial.Trial.report().

Methods

report(value, step)

Interface of report function.

set_system_attr(key, value)

set_user_attr(key, value)

should_prune()

Suggest whether the trial should be pruned or not.

suggest_categorical()

suggest_discrete_uniform(name, low, high, q)

suggest_float(name, low, high, *[, step, log])

suggest_int(name, low, high, *[, step, log])

suggest_loguniform(name, low, high)

suggest_uniform(name, low, high)

Attributes

datetime_start

distributions

duration

Return the elapsed time taken to complete the trial.

last_step

Return the maximum step of intermediate_values in the trial.

number

params

system_attrs

user_attrs

value

values

property duration: timedelta | None

Return the elapsed time taken to complete the trial.

Returns:

The duration.

property last_step: int | None

Return the maximum step of intermediate_values in the trial.

Returns:

The maximum step of intermediates.

report(value, step)[source]

Interface of report function.

Since FrozenTrial is not pruned, this report function does nothing.

See also

Please refer to should_prune().

Parameters:
  • value (float) – A value returned from the objective function.

  • step (int) – Step of the trial (e.g., Epoch of neural network training). Note that pruners assume that step starts at zero. For example, MedianPruner simply checks if step is less than n_warmup_steps as the warmup mechanism.

Return type:

None

set_system_attr(key, value)[source]

Warning

Deprecated in v3.1.0. This feature will be removed in the future. The removal of this feature is currently scheduled for v5.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v3.1.0.

Parameters:
Return type:

None

should_prune()[source]

Suggest whether the trial should be pruned or not.

The suggestion is always False regardless of a pruning algorithm.

Note

FrozenTrial only samples one combination of parameters.

Returns:

False.

Return type:

bool

suggest_discrete_uniform(name, low, high, q)[source]

Warning

Deprecated in v3.0.0. This feature will be removed in the future. The removal of this feature is currently scheduled for v6.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v3.0.0.

Use suggest_float(…, step=…) instead.

Parameters:
Return type:

float

suggest_loguniform(name, low, high)[source]

Warning

Deprecated in v3.0.0. This feature will be removed in the future. The removal of this feature is currently scheduled for v6.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v3.0.0.

Use suggest_float(…, log=True) instead.

Parameters:
Return type:

float

suggest_uniform(name, low, high)[source]

Warning

Deprecated in v3.0.0. This feature will be removed in the future. The removal of this feature is currently scheduled for v6.0.0, but this schedule is subject to change. See https://github.com/optuna/optuna/releases/tag/v3.0.0.

Use suggest_float instead.

Parameters:
Return type:

float