class_docstr: 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 the direct use of this constructor is not recommended.
  This object is seamlessly instantiated and passed to the objective function behind
  the :func:`optuna.study.Study.optimize()` method; hence library users do not care about
  instantiation of this object.
  
  Args:
      study:
          A :class:`~optuna.study.Study` object.
      trial_id:
          A trial ID that is automatically generated.
class_docstr_tok: ["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","the","direct","use","of","this","constructor","is","not","recommended",".","This","object","is","seamlessly","instantiated","and","passed","to","the","objective","function","behind","the",":","func",":","`","optuna.study.Study.optimize","(",")","`","method",";","hence","library","users","do","not","care","about","instantiation","of","this","object",".","Args",":","study",":","A",":","class",":","`","~optuna.study.Study","`","object",".","trial_id",":","A","trial","ID","that","is","automatically","generated","."]
docstr: Report an objective function value for a given step.
  
  The reported values are used by the pruners to determine whether this trial should be
  pruned.
  
  .. seealso::
      Please refer to :class:`~optuna.pruners.BasePruner`.
  
  .. note::
      The reported value is converted to ``float`` type by applying ``float()``
      function internally. Thus, it accepts all float-like types (e.g., ``numpy.float32``).
      If the conversion fails, a ``TypeError`` is raised.
  
  .. note::
      If this method is called multiple times at the same ``step`` in a trial,
      the reported ``value`` only the first time is stored and the reported values
      from the second time are ignored.
  
  .. note::
      :func:`~optuna.trial.Trial.report` does not support multi-objective
      optimization.
  
  Example:
  
      Report intermediate scores of `SGDClassifier <https://scikit-learn.org/stable/modules/
      generated/sklearn.linear_model.SGDClassifier.html>`_ training.
  
      .. testcode::
  
          import numpy as np
          from sklearn.datasets import load_iris
          from sklearn.linear_model import SGDClassifier
          from sklearn.model_selection import train_test_split
  
          import optuna
  
          X, y = load_iris(return_X_y=True)
          X_train, X_valid, y_train, y_valid = train_test_split(X, y)
  
  
          def objective(trial):
              clf = SGDClassifier(random_state=0)
              for step in range(100):
                  clf.partial_fit(X_train, y_train, np.unique(y))
                  intermediate_value = clf.score(X_valid, y_valid)
                  trial.report(intermediate_value, step=step)
                  if trial.should_prune():
                      raise optuna.TrialPruned()
  
              return clf.score(X_valid, y_valid)
  
  
          study = optuna.create_study(direction="maximize")
          study.optimize(objective, n_trials=3)
  
  
  Args:
      value:
          A value returned from the objective function.
      step:
          Step of the trial (e.g., Epoch of neural network training). Note that pruners
          assume that ``step`` starts at zero. For example,
          :class:`~optuna.pruners.MedianPruner` simply checks if ``step`` is less than
          ``n_warmup_steps`` as the warmup mechanism.
          ``step`` must be a positive integer.
docstr_tok: ["Report","an","objective","function","value","for","a","given","step",".","The","reported","values","are","used","by","the","pruners","to","determine","whether","this","trial","should","be","pruned",".","..","seealso",":",":","Please","refer","to",":","class",":","`","~optuna.pruners.BasePruner","`",".","..","note",":",":","The","reported","value","is","converted","to","``","float","``","type","by","applying","``","float","(",")","``","function","internally",".","Thus",",","it","accepts","all","float-like","types","(","e.g.",",","``","numpy.float32","``",")",".","If","the","conversion","fails",",","a","``","TypeError","``","is","raised",".","..","note",":",":","If","this","method","is","called","multiple","times","at","the","same","``","step","``","in","a","trial",",","the","reported","``","value","``","only","the","first","time","is","stored","and","the","reported","values","from","the","second","time","are","ignored",".","..","note",":",":",":","func",":","`","~optuna.trial.Trial.report","`","does","not","support","multi-objective","optimization",".","Example",":","Report","intermediate","scores","of","`","SGDClassifier","<","https",":","\/\/scikit-learn.org\/stable\/modules\/","generated\/sklearn.linear_model.SGDClassifier.html",">","`","_","training",".","..","testcode",":",":","import","numpy","as","np","from","sklearn.datasets","import","load_iris","from","sklearn.linear_model","import","SGDClassifier","from","sklearn.model_selection","import","train_test_split","import","optuna","X",",","y","=","load_iris","(","return_X_y=True",")","X_train",",","X_valid",",","y_train",",","y_valid","=","train_test_split","(","X",",","y",")","def","objective","(","trial",")",":","clf","=","SGDClassifier","(","random_state=0",")","for","step","in","range","(","100",")",":","clf.partial_fit","(","X_train",",","y_train",",","np.unique","(","y",")",")","intermediate_value","=","clf.score","(","X_valid",",","y_valid",")","trial.report","(","intermediate_value",",","step=step",")","if","trial.should_prune","(",")",":","raise","optuna.TrialPruned","(",")","return","clf.score","(","X_valid",",","y_valid",")","study","=","optuna.create_study","(","direction=","''","maximize","''",")","study.optimize","(","objective",",","n_trials=3",")","Args",":","value",":","A","value","returned","from","the","objective","function",".","step",":","Step","of","the","trial","(","e.g.",",","Epoch","of","neural","network","training",")",".","Note","that","pruners","assume","that","``","step","``","starts","at","zero",".","For","example",",",":","class",":","`","~optuna.pruners.MedianPruner","`","simply","checks","if","``","step","``","is","less","than","``","n_warmup_steps","``","as","the","warmup","mechanism",".","``","step","``","must","be","a","positive","integer","."]
code: def report(self, value: float, step: int) -> None:
      """Report an objective function value for a given step.
  
      The reported values are used by the pruners to determine whether this trial should be
      pruned.
  
      .. seealso::
          Please refer to :class:`~optuna.pruners.BasePruner`.
  
      .. note::
          The reported value is converted to ``float`` type by applying ``float()``
          function internally. Thus, it accepts all float-like types (e.g., ``numpy.float32``).
          If the conversion fails, a ``TypeError`` is raised.
  
      .. note::
          If this method is called multiple times at the same ``step`` in a trial,
          the reported ``value`` only the first time is stored and the reported values
          from the second time are ignored.
  
      .. note::
          :func:`~optuna.trial.Trial.report` does not support multi-objective
          optimization.
  
      Example:
  
          Report intermediate scores of `SGDClassifier <https://scikit-learn.org/stable/modules/
          generated/sklearn.linear_model.SGDClassifier.html>`_ training.
  
          .. testcode::
  
              import numpy as np
              from sklearn.datasets import load_iris
              from sklearn.linear_model import SGDClassifier
              from sklearn.model_selection import train_test_split
  
              import optuna
  
              X, y = load_iris(return_X_y=True)
              X_train, X_valid, y_train, y_valid = train_test_split(X, y)
  
  
              def objective(trial):
                  clf = SGDClassifier(random_state=0)
                  for step in range(100):
                      clf.partial_fit(X_train, y_train, np.unique(y))
                      intermediate_value = clf.score(X_valid, y_valid)
                      trial.report(intermediate_value, step=step)
                      if trial.should_prune():
                          raise optuna.TrialPruned()
  
                  return clf.score(X_valid, y_valid)
  
  
              study = optuna.create_study(direction="maximize")
              study.optimize(objective, n_trials=3)
  
  
      Args:
          value:
              A value returned from the objective function.
          step:
              Step of the trial (e.g., Epoch of neural network training). Note that pruners
              assume that ``step`` starts at zero. For example,
              :class:`~optuna.pruners.MedianPruner` simply checks if ``step`` is less than
              ``n_warmup_steps`` as the warmup mechanism.
              ``step`` must be a positive integer.
      """
  
      if len(self.study.directions) > 1:
          raise NotImplementedError(
              "Trial.report is not supported for multi-objective optimization."
          )
  
      try:
          # For convenience, we allow users to report a value that can be cast to `float`.
          value = float(value)
      except (TypeError, ValueError):
          message = "The `value` argument is of type '{}' but supposed to be a float.".format(
              type(value).__name__
          )
          raise TypeError(message) from None
  
      if step < 0:
          raise ValueError(
              "The `step` argument is {} but cannot be negative.".format(
                  step
              )
          )
  
      if step in self._cached_frozen_trial.intermediate_values:
          # Do nothing if already reported.
          warnings.warn(
              "The reported value is ignored because this `step` {} is already reported.".format(
                  step
              )
          )
          return
  
      self.storage.set_trial_intermediate_value(
          self._trial_id, step, value
      )
      self._cached_frozen_trial.intermediate_values[step] = value
  
imports: from __future__ import annotations
  from collections import UserDict
  import copy
  import datetime
  from typing import Any
  from typing import Dict
  from typing import Optional
  from typing import overload
  from typing import Sequence
  import warnings
  import optuna
  from optuna import distributions
  from optuna import logging
  from optuna import pruners
  from optuna._convert_positional_args import convert_positional_args
  from optuna._deprecated import deprecated_func
  from optuna.distributions import BaseDistribution
  from optuna.distributions import CategoricalChoiceType
  from optuna.distributions import CategoricalDistribution
  from optuna.distributions import FloatDistribution
  from optuna.distributions import IntDistribution
  from optuna.trial import FrozenTrial
  from optuna.trial._base import _SUGGEST_INT_POSITIONAL_ARGS
  from optuna.trial._base import BaseTrial
label_desc: Use image node_id 15 for calling the Trial obj's underlying member method code with example usage: obj.report(value, step) without return types