# Trial¶

class optuna.trial.Trial(study, trial_id)[source]

A trial is a process of evaluating an objective function.

This object is passed to an objective function and provides interfaces to get parameter suggestion, manage the trial’s state, and set/get user-defined attributes of the trial.

Note that this object is seamlessly instantiated and passed to the objective function behind optuna.study.Study.optimize() method (as well as optimize function); hence, in typical use cases, library users do not care about instantiation of this object.

Parameters: study – A Study object. trial_id – A trial ID that is automatically generated.
params

Return parameters to be optimized.

Returns: A dictionary containing all parameters.
report(value, step=None)[source]

Report an objective function value.

If step is set to None, the value is stored as a final value of the trial. Otherwise, it is saved as an intermediate value.

Example

Report intermediate scores of SGDClassifier training

>>> def objective(trial):
>>>     ...
>>>     clf = sklearn.linear_model.SGDClassifier()
>>>     for step in range(100):
>>>         clf.partial_fit(x_train , y_train , classes)
>>>         intermediate_value = clf.score(x_val , y_val)
>>>         trial.report(intermediate_value , step=step)
>>>         if trial.should_prune(step):
>>>             raise TrialPruned()
>>>     ...

Parameters: value – A value returned from the objective function. step – Step of the trial (e.g., Epoch of neural network training).
set_user_attr(key, value)[source]

Set user attributes to the trial.

The user attributes in the trial can be access via optuna.trial.Trial.user_attrs().

Example

Save fixed hyperparameters of neural network training:

>>> def objective(trial):
>>>     ...
>>>     trial.set_user_attr('BATCHSIZE', 128)
>>>
>>> study.best_trial.user_attrs
{'BATCHSIZE': 128}

Parameters: key – A key string of the attribute. value – A value of the attribute. The value should be JSON serializable.
should_prune(step)[source]

Judge whether the trial should be pruned.

This method calls prune method of the pruner, which judges whether the trial should be pruned at the given step. Please refer to the example code of optuna.trial.Trial.report().

Parameters: step – Step of the trial (e.g., epoch of neural network training). A boolean value. If True, the trial should be pruned. Otherwise, the trial will be continued.
suggest_categorical(name, choices)[source]

Suggest a value for the categorical parameter.

The value is sampled from choices.

Example

Suggest a kernel function of SVC.

>>> def objective(trial):
>>>     ...
>>>     kernel = trial.suggest_categorical('kernel', ['linear', 'poly', 'rbf'])
>>>     clf = sklearn.svm.SVC(kernel=kernel)
>>>     ...

Parameters: name – A parameter name. choices – Candidates of parameter values. A suggested value.
suggest_discrete_uniform(name, low, high, q)[source]

Suggest a value for the discrete parameter.

The value is sampled from the range [low, high], and the step of discretization is q.

Example

Suggest a fraction of samples used for fitting the individual learners of GradientBoostingClassifier.

>>> def objective(trial):
>>>     ...
>>>     subsample = trial.suggest_discrete_uniform('subsample', 0.1, 1.0, 0.1)
>>>     ...

Parameters: name – A parameter name. low – Lower endpoint of the range of suggested values. low is included in the range. high – Upper endpoint of the range of suggested values. high is included in the range. q – A step of discretization. A suggested float value.
suggest_int(name, low, high)[source]

Suggest a value for the integer parameter.

The value is sampled from the integers in [low, high].

Example

Suggest the number of trees in RandomForestClassifier.

>>> def objective(trial):
>>>     ...
>>>     n_estimators = trial.suggest_int('n_estimators', 50, 400)
>>>     clf = sklearn.ensemble.RandomForestClassifier(n_estimators=n_estimators)
>>>     ...

Parameters: name – A parameter name. low – Lower endpoint of the range of suggested values. low is included in the range. high – Upper endpoint of the range of suggested values. high is included in the range. A suggested integer value.
suggest_loguniform(name, low, high)[source]

Suggest a value for the continuous parameter.

The value is sampled from the range [low, high) in the log domain.

Example

Suggest penalty parameter C of SVC.

>>> def objective(trial):
>>>     ...
>>>     c = trial.suggest_logunifrom('c', 1e-5, 1e2)
>>>     clf = sklearn.svm.SVC(C=c)
>>>     ...

Parameters: name – A parameter name. low – Lower endpoint of the range of suggested values. low is included in the range. high – Upper endpoint of the range of suggested values. high is excluded from the range. A suggested float value.
suggest_uniform(name, low, high)[source]

Suggest a value for the continuous parameter.

The value is sampled from the range [low, high) in the linear domain.

Example

Suggest a dropout rate for neural network training.

>>> def objective(trial):
>>>     ...
>>>     dropout_rate = trial.suggest_unifrom('dropout_rate', 0, 1.0)
>>>     ...

Parameters: name – A parameter name. low – Lower endpoint of the range of suggested values. low is included in the range. high – Upper endpoint of the range of suggested values. high is excluded from the range. A suggested float value.
user_attrs

Return user attributes.

Returns: A dictionary containing all user attributes.
class optuna.trial.FixedTrial(params)[source]

A trial class which suggests a fixed value for each parameter.

This object has the same methods as Trial, and it suggests pre-defined parameter values. The parameter values can be determined at the construction of the FixedTrial object. In contrast to Trial, FixedTrial does not depend on Study, and it is useful for deploying optimization results.

Example

Evaluate an objective function with parameter values given by a user:

>>> def objective(trial):
>>>     x = trial.suggest_uniform('x', -100, 100)
>>>     y = trial.suggest_categorical('y', [-1, 0, 1])
>>>     return x ** 2 + y
>>>
>>> objective(FixedTrial({'x': 1, 'y': 0}))
1


Note

Please refer to Trial for details of methods and properties.

Parameters: params – A dictionary containing all parameters.