optuna.trial.create_trial

optuna.trial.create_trial(*, state=TrialState.COMPLETE, value=None, values=None, params=None, distributions=None, user_attrs=None, system_attrs=None, intermediate_values=None)[source]

Create a new FrozenTrial.

Example

import optuna
from optuna.distributions import CategoricalDistribution
from optuna.distributions import FloatDistribution

trial = optuna.trial.create_trial(
    params={"x": 1.0, "y": 0},
    distributions={
        "x": FloatDistribution(0, 10),
        "y": CategoricalDistribution([-1, 0, 1]),
    },
    value=5.0,
)

assert isinstance(trial, optuna.trial.FrozenTrial)
assert trial.value == 5.0
assert trial.params == {"x": 1.0, "y": 0}

See also

See add_trial() for how this function can be used to create a study from existing trials.

Note

Please note that this is a low-level API. In general, trials that are passed to objective functions are created inside optimize().

Note

When state is TrialState.COMPLETE, the following parameters are required:

params
distributions
value or values

Parameters:

state (TrialState) – Trial state.
value (float | None) – Trial objective value. Must be specified if state is TrialState.COMPLETE. value and values must not be specified at the same time.
values (Sequence[float] | None) – Sequence of the trial objective values. The length is greater than 1 if the problem is multi-objective optimization. Must be specified if state is TrialState.COMPLETE. value and values must not be specified at the same time.
params (Dict[str, Any] | None) – Dictionary with suggested parameters of the trial.
distributions (Dict[str, BaseDistribution] | None) – Dictionary with parameter distributions of the trial.
user_attrs (Dict[str, Any] | None) – Dictionary with user attributes.
system_attrs (Dict[str, Any] | None) – Dictionary with system attributes. Should not have to be used for most users.
intermediate_values (Dict[int, float] | None) – Dictionary with intermediate objective values of the trial.

Returns:

Created trial.

Return type:

FrozenTrial