(
        self,
        trial: Union[trial_module.Trial, int],
        values: Optional[Union[float, Sequence[float]]] = None,
        state: TrialState = TrialState.COMPLETE,
        skip_if_finished: bool = False,
    )
Finish a trial created with :func:`~optuna.study.Study.ask`.

        .. seealso::

            The :ref:`ask_and_tell` tutorial provides use-cases with examples.

        Example:

            .. testcode::

                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)

        Args:
            trial:
                A :class:`~optuna.trial.Trial` object or a trial number.
            values:
                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`` is
                :class:`~optuna.trial.TrialState.COMPLETE` and should be :obj:`None` if ``state``
                is :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
            state:
                State to be reported. Must be :class:`~optuna.trial.TrialState.COMPLETE`,
                :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
            skip_if_finished:
                Flag to control whether exception should be raised when values for already
                finished trial are told. If :obj:`True`, tell is skipped without any error
                when the trial is already finished.

        Raises:
            TypeError:
                If ``trial`` is not a :class:`~optuna.trial.Trial` or an :obj:`int`.
            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`` is :class:`~optuna.trial.TrialState.COMPLETE` but
                ``values`` is :obj:`None`.
                ``state`` is :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED` but
                ``values`` is not :obj:`None`.
                ``state`` is not
                :class:`~optuna.trial.TrialState.COMPLETE`,
                :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
                ``trial`` is a trial number but no
                trial exists with that number.
Finish a trial created with :func:`~optuna.study.Study.ask`.
Finish a trial created with : func : ~optuna . study . Study . ask .
def tell(
        self,
        trial: Union[trial_module.Trial, int],
        values: Optional[Union[float, Sequence[float]]] = None,
        state: TrialState = TrialState.COMPLETE,
        skip_if_finished: bool = False,
    ) -> None:
        """Finish a trial created with :func:`~optuna.study.Study.ask`.

        .. seealso::

            The :ref:`ask_and_tell` tutorial provides use-cases with examples.

        Example:

            .. testcode::

                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)

        Args:
            trial:
                A :class:`~optuna.trial.Trial` object or a trial number.
            values:
                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`` is
                :class:`~optuna.trial.TrialState.COMPLETE` and should be :obj:`None` if ``state``
                is :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
            state:
                State to be reported. Must be :class:`~optuna.trial.TrialState.COMPLETE`,
                :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
            skip_if_finished:
                Flag to control whether exception should be raised when values for already
                finished trial are told. If :obj:`True`, tell is skipped without any error
                when the trial is already finished.

        Raises:
            TypeError:
                If ``trial`` is not a :class:`~optuna.trial.Trial` or an :obj:`int`.
            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`` is :class:`~optuna.trial.TrialState.COMPLETE` but
                ``values`` is :obj:`None`.
                ``state`` is :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED` but
                ``values`` is not :obj:`None`.
                ``state`` is not
                :class:`~optuna.trial.TrialState.COMPLETE`,
                :class:`~optuna.trial.TrialState.FAIL` or
                :class:`~optuna.trial.TrialState.PRUNED`.
                ``trial`` is a trial number but no
                trial exists with that number.
        """

        if not isinstance(trial, (trial_module.Trial, int)):
            raise TypeError("Trial must be a trial object or trial number.")

        if state == TrialState.COMPLETE:
            if values is None:
                raise ValueError(
                    "No values were told. Values are required when state is TrialState.COMPLETE."
                )
        elif state in (TrialState.PRUNED, TrialState.FAIL):
            if values is not None:
                raise ValueError(
                    "Values were told. Values cannot be specified when state is "
                    "TrialState.PRUNED or TrialState.FAIL."
                )
        else:
            raise ValueError(f"Cannot tell with state {state}.")

        if isinstance(trial, trial_module.Trial):
            trial_number = trial.number
            trial_id = trial._trial_id
        elif isinstance(trial, int):
            trial_number = trial
            try:
                trial_id = self._storage.get_trial_id_from_study_id_trial_number(
                    self._study_id, trial_number
                )
            except NotImplementedError as e:
                warnings.warn(
                    "Study.tell may be slow because the trial was represented by its number but "
                    f"the storage {self._storage.__class__.__name__} does not implement the "
                    "method required to map numbers back. Please provide the trial object "
                    "to avoid performance degradation."
                )

                trials = self.get_trials(deepcopy=False)

                if len(trials) <= trial_number:
                    raise ValueError(
                        f"Cannot tell for trial with number {trial_number} since it has not been "
                        "created."
                    ) from e

                trial_id = trials[trial_number]._trial_id
            except KeyError as e:
                raise ValueError(
                    f"Cannot tell for trial with number {trial_number} since it has not been "
                    "created."
                ) from e
        else:
            assert False, "Should not reach."

        frozen_trial = self._storage.get_trial(trial_id)

        if frozen_trial.state.is_finished() and skip_if_finished:
            _logger.info(
                f"Skipped telling trial {trial_number} with values "
                f"{values} and state {state} since trial was already finished. "
                f"Finished trial has values {frozen_trial.values} and state {frozen_trial.state}."
            )
            return

        if state == TrialState.PRUNED:
            # Register the last intermediate value if present as the value of the trial.
            # TODO(hvy): Whether a pruned trials should have an actual value can be discussed.
            assert values is None

            last_step = frozen_trial.last_step
            if last_step is not None:
                values = [frozen_trial.intermediate_values[last_step]]

        if values is not None:
            values, values_conversion_failure_message = _check_and_convert_to_values(
                len(self.directions), values, trial_number
            )
            # When called from `Study.optimize` and `state` is pruned, the given `values` contains
            # the intermediate value with the largest step so far. In this case, the value is
            # allowed to be NaN and errors should not be raised.
            if state != TrialState.PRUNED and values_conversion_failure_message is not None:
                raise ValueError(values_conversion_failure_message)

        try:
            # Sampler defined trial post-processing.
            study = pruners._filter_study(self, frozen_trial)
            self.sampler.after_trial(study, frozen_trial, state, values)
        except Exception:
            raise
        finally:
            if values is not None:
                self._storage.set_trial_values(trial_id, values)

            self._storage.set_trial_state(trial_id, state)
def tell ( self , trial : Union [ trial_module . Trial , int ] , values : Optional [ Union [ float , Sequence [ float ] ] ] = None , state : TrialState = TrialState . COMPLETE , skip_if_finished : bool = False , ) -> None : if not isinstance ( trial , ( trial_module . Trial , int ) ) : raise TypeError ( "Trial must be a trial object or trial number." ) if state == TrialState . COMPLETE : if values is None : raise ValueError ( "No values were told. Values are required when state is TrialState.COMPLETE." ) elif state in ( TrialState . PRUNED , TrialState . FAIL ) : if values is not None : raise ValueError ( "Values were told. Values cannot be specified when state is " "TrialState.PRUNED or TrialState.FAIL." ) else : raise ValueError ( f"Cannot tell with state {state}." ) if isinstance ( trial , trial_module . Trial ) : trial_number = trial . number trial_id = trial . _trial_id elif isinstance ( trial , int ) : trial_number = trial try : trial_id = self . _storage . get_trial_id_from_study_id_trial_number ( self . _study_id , trial_number ) except NotImplementedError as e : warnings . warn ( "Study.tell may be slow because the trial was represented by its number but " f"the storage {self._storage.__class__.__name__} does not implement the " "method required to map numbers back. Please provide the trial object " "to avoid performance degradation." ) trials = self . get_trials ( deepcopy = False ) if len ( trials ) <= trial_number : raise ValueError ( f"Cannot tell for trial with number {trial_number} since it has not been " "created." ) from e trial_id = trials [ trial_number ] . _trial_id except KeyError as e : raise ValueError ( f"Cannot tell for trial with number {trial_number} since it has not been " "created." ) from e else : assert False , "Should not reach." frozen_trial = self . _storage . get_trial ( trial_id ) if frozen_trial . state . is_finished ( ) and skip_if_finished : _logger . info ( f"Skipped telling trial {trial_number} with values " f"{values} and state {state} since trial was already finished. " f"Finished trial has values {frozen_trial.values} and state {frozen_trial.state}." ) return if state == TrialState . PRUNED : # Register the last intermediate value if present as the value of the trial. # TODO(hvy): Whether a pruned trials should have an actual value can be discussed. assert values is None last_step = frozen_trial . last_step if last_step is not None : values = [ frozen_trial . intermediate_values [ last_step ] ] if values is not None : values , values_conversion_failure_message = _check_and_convert_to_values ( len ( self . directions ) , values , trial_number ) # When called from `Study.optimize` and `state` is pruned, the given `values` contains # the intermediate value with the largest step so far. In this case, the value is # allowed to be NaN and errors should not be raised. if state != TrialState . PRUNED and values_conversion_failure_message is not None : raise ValueError ( values_conversion_failure_message ) try : # Sampler defined trial post-processing. study = pruners . _filter_study ( self , frozen_trial ) self . sampler . after_trial ( study , frozen_trial , state , values ) except Exception : raise finally : if values is not None : self . _storage . set_trial_values ( trial_id , values ) self . _storage . set_trial_state ( trial_id , state )