
    -jiO              	         S SK Jr  S SKJr  S SKJr  S SKrS SKrS SKJr  S SKJ	r	  S SKJ
r
  S SKJr  S S	KJr  S S
KJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SKJr  S SK J!r!  \RD                  " \#5      r$Sr% " S S\5      r&\!RN                  SSSSSSSS.                 SS jjr(g)    )annotations)Mapping)SequenceN)Any)cast)overload)distributions)logging)convert_positional_args)deprecated_func)JSONSerializable)optuna_warn)-_convert_old_distribution_to_new_distribution)BaseDistribution)CategoricalChoiceType)CategoricalDistribution)FloatDistribution)IntDistribution)_SUGGEST_INT_POSITIONAL_ARGS)	BaseTrial)
TrialStatez Use suggest_float{args} instead.c                     \ rS rSrSrSS.                         S>S jjrS?S jrS?S jrS?S jrS@S	 jr	SAS
 jr
SSS.           SBS jjr\" SS\R                  SS9S9SCS j5       r\" SS\R                  SS9S9SCS j5       r\" SS\R                  SS9S9SDS j5       r\" \SSS9SSS.           SES jj5       r\SFS j5       r\SGS j5       r\SHS j5       r\SIS  j5       r\SJS! j5       r\      SKS" j5       r      SKS# jrSLS$ jrSMS% jrSNS& jr\" S'S5      SNS( j5       rSOS) jrSPS* jr\S@S+ j5       r\R>                  SQS, j5       r\SRS- j5       r \ R>                  SSS. j5       r STS/ jr!SUS0 jr"\" \!\"5      r#\SVS1 j5       r$\$R>                  SWS2 j5       r$\SXS3 j5       r%\%R>                  SYS4 j5       r%\SZS5 j5       r&\&R>                  S[S6 j5       r&\SXS7 j5       r'\'R>                  S\S8 j5       r'\SXS9 j5       r(\(R>                  S]S: j5       r(\S^S; j5       r)\S_S< j5       r*S=r+g)`FrozenTrial    a  Status and results of a :class:`~optuna.trial.Trial`.

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

It is therefore not possible to make persistent changes to a storage from this object by
itself, for instance by using :func:`~optuna.trial.FrozenTrial.set_user_attr`.

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

It can be passed to objective functions (see :func:`~optuna.study.Study.optimize`) and is
useful for deploying optimization results.

Example:

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

    .. testcode::

        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, :func:`~optuna.trial.FrozenTrial.set_user_attr` will update user attributes
    of objects in-place.


    Example:

        Overwritten attributes.

        .. testcode::

            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 :class:`~optuna.trial.Trial` for details of methods and properties.


Attributes:
    number:
        Unique and consecutive number of :class:`~optuna.trial.Trial` for each
        :class:`~optuna.study.Study`. Note that this field uses zero-based numbering.
    state:
        :class:`TrialState` of the :class:`~optuna.trial.Trial`.
    value:
        Objective value of the :class:`~optuna.trial.Trial`.
        ``value`` and ``values`` must not be specified at the same time.
    values:
        Sequence of objective values of the :class:`~optuna.trial.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 :class:`~optuna.trial.Trial` started.
    datetime_complete:
        Datetime where the :class:`~optuna.trial.Trial` finished.
    params:
        Dictionary that contains suggested parameters.
    distributions:
        Dictionary that contains the distributions of :attr:`params`.
    user_attrs:
        Dictionary that contains the attributes of the :class:`~optuna.trial.Trial` set with
        :func:`optuna.trial.Trial.set_user_attr`.
    system_attrs:
        Dictionary that contains the attributes of the :class:`~optuna.trial.Trial` set with
        :func:`optuna.trial.Trial.set_system_attr`.
    intermediate_values:
        Intermediate objective values set with :func:`optuna.trial.Trial.report`.
N)valuesc                   Xl         X l        S U l        Ub  Ub  [        S5      eUb	  U/U l        OUb  [	        U5      U l        X@l        XPl        X`l        Xl        Xl	        Xl
        Xpl        Xl        g )Nz)Specify only one of `value` and `values`.)_numberstate_values
ValueErrorlist_datetime_startdatetime_complete_params_user_attrs_system_attrsintermediate_values_distributions	_trial_id)selfnumberr   valuedatetime_startr#   paramsr	   
user_attrssystem_attrsr'   trial_idr   s                N/home/james-whalen/.local/lib/python3.13/site-packages/optuna/trial/_frozen.py__init__FrozenTrial.__init__   sz      
+/!3HII!7DL<DL-!2%)#6 +!    c                j    [        U[        5      (       d  [        $ UR                  U R                  :H  $ N)
isinstancer   NotImplemented__dict__r*   others     r2   __eq__FrozenTrial.__eq__   s(    %--!!~~..r5   c                j    [        U[        5      (       d  [        $ U R                  UR                  :  $ r7   r8   r   r9   r+   r;   s     r2   __lt__FrozenTrial.__lt__   s(    %--!!{{U\\))r5   c                j    [        U[        5      (       d  [        $ U R                  UR                  :*  $ r7   r@   r;   s     r2   __le__FrozenTrial.__le__   s(    %--!!{{ell**r5   c                T   ^  [        [        U 4S jT R                   5       5      5      $ )Nc              3  <   >#    U  H  n[        TU5      v   M     g 7fr7   )getattr.0fieldr*   s     r2   	<genexpr>'FrozenTrial.__hash__.<locals>.<genexpr>   s     JM5'$..Ms   )hashtupler:   r*   s   `r2   __hash__FrozenTrial.__hash__   s    EJDMMJJKKr5   c                   ^  SR                  T R                  R                  SR                  U 4S jT R                   5       5      S-   S9$ )Nz{cls}({kwargs})z, c           
   3     >#    U  HC  nS R                  UR                  S5      (       d  UOUSS [        [        TU5      5      S9v   ME     g7f)z{field}={value}_   N)rK   r,   )format
startswithreprrH   rI   s     r2   rL   'FrozenTrial.__repr__.<locals>.<genexpr>   sV      
 +E	 "((','7'7'<'<%%)wtU34 )  +s   AAz, value=None)clskwargs)rW   	__class____name__joinr:   rP   s   `r2   __repr__FrozenTrial.__repr__   sQ     ''''99 
 "]]   ( 

 
	
r5   F)steplogc          
     6    U R                  U[        X#XTS95      $ N)rc   rb   )_suggestr   r*   namelowhighrb   rc   s         r2   suggest_floatFrozenTrial.suggest_float   s     }}T#4SC#STTr5   z3.0.0z6.0.0 )args)textc                &    U R                  XU5      $ r7   rk   r*   rh   ri   rj   s       r2   suggest_uniformFrozenTrial.suggest_uniform   s    !!$T22r5   z(..., log=True)c                $    U R                  XUSS9$ )NT)rc   rq   rr   s       r2   suggest_loguniformFrozenTrial.suggest_loguniform   s    !!$Tt!<<r5   z(..., step=...)c                "    U R                  XX4S9$ )N)rb   rq   )r*   rh   ri   rj   qs        r2   suggest_discrete_uniform$FrozenTrial.suggest_discrete_uniform   s    !!$T!::r5   z3.5.0z5.0.0)previous_positional_arg_namesdeprecated_versionremoved_versionrV   c               H    [        U R                  U[        X#XTS95      5      $ re   )intrf   r   rg   s         r2   suggest_intFrozenTrial.suggest_int   s!     4==sc'UVWWr5   c                    g r7    r*   rh   choicess      r2   suggest_categoricalFrozenTrial.suggest_categorical       ORr5   c                    g r7   r   r   s      r2   r   r      r   r5   c                    g r7   r   r   s      r2   r   r          MPr5   c                    g r7   r   r   s      r2   r   r      s    QTr5   c                    g r7   r   r   s      r2   r   r      r   r5   c                    g r7   r   r   s      r2   r   r      s     !$r5   c                4    U R                  U[        US95      $ )N)r   )rf   r   r   s      r2   r   r     s     }}T#:7#KLLr5   c                    g)a7  Interface of report function.

Since :class:`~optuna.trial.FrozenTrial` is not pruned,
this report function does nothing.

.. seealso::
    Please refer to :func:`~optuna.trial.FrozenTrial.should_prune`.

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.
Nr   )r*   r,   rb   s      r2   reportFrozenTrial.report	  s    & 	r5   c                    g)zSuggest whether the trial should be pruned or not.

The suggestion is always :obj:`False` regardless of a pruning algorithm.

.. note::
    :class:`~optuna.trial.FrozenTrial` only samples one combination of parameters.

Returns:
    :obj:`False`.
Fr   rP   s    r2   should_pruneFrozenTrial.should_prune  s     r5   c                     X R                   U'   g r7   r%   r*   keyr,   s      r2   set_user_attrFrozenTrial.set_user_attr,  s     %r5   z3.1.0c                     X R                   U'   g r7   r&   r   s      r2   set_system_attrFrozenTrial.set_system_attr/  s    "'3r5   c           	        U R                   [        R                  :w  a  U R                  c  [	        S5      eU R                   R                  5       (       a  U R                  c  [	        S5      eOU R                  b  [	        S5      eU R                   [        R                  :X  a&  U R                  b  [	        SU R                   S35      eU R                   [        R                  :X  aD  U R                  c  [	        S5      e[        S U R                   5       5      (       a  [	        S5      e[        U R                  R                  5       5      [        U R                  R                  5       5      :w  a]  [	        S	R                  [        U R                  R                  5       5      [        U R                  R                  5       5      5      5      eU R                  R!                  5        HV  u  pU R                  U   nUR#                  U5      nUR%                  U5      (       a  M=  [	        S
R                  X!U5      5      e   g )NzK`datetime_start` is supposed to be set when the trial state is not waiting.z?`datetime_complete` is supposed to be set for a finished trial.zC`datetime_complete` is supposed to be None for an unfinished trial.z2values should be None for a failed trial, but got .z*values should be set for a complete trial.c              3  N   #    U  H  n[         R                  " U5      v   M     g 7fr7   )mathisnan)rJ   xs     r2   rL   (FrozenTrial._validate.<locals>.<genexpr>G  s     9LqTZZ]]Ls   #%zvalues should not contain NaN.z0Inconsistent parameters {} and distributions {}.zFThe value {} of parameter '{}' isn't contained in the distribution {}.)r   r   WAITINGr-   r    is_finishedr#   FAILr   COMPLETEanysetr.   keysr	   rW   itemsto_internal_repr	_contains)r*   
param_nameparam_valuedistributionparam_value_in_internal_reprs        r2   	_validateFrozenTrial._validate3  s   ::+++0C0C0K]  ::!!##%%- !bcc . %%1 Y  ::(T\\-EQRVR^R^Q__`abb::,,,||# !MNN9DLL999 !ABBt{{!"c$*<*<*A*A*C&DDBII((*+S1C1C1H1H1J-K  (,{{'8'8':#J--j9L+7+H+H+U())*FGG  &,G  (;r5   c                |   XR                   ;  a  [        SR                  U5      5      eU R                   U   nUR                  U5      nUR	                  U5      (       d  [        SR                  X1U5      5        XR                  ;   a$  [        R                  " U R                  U   U5        X R                  U'   U$ )NzjThe value of the parameter '{}' is not found. Please set it at the construction of the FrozenTrial object.zNThe value {} of the parameter '{}' is out of the range of the distribution {}.)	r$   r    rW   r   r   r   r(   r	    check_distribution_compatibility)r*   rh   r   r,   r   s        r2   rf   FrozenTrial._suggest[  s    ||#>>DfTl 
 T"'3'D'DU'K$%%&BCC44:F54U
 &&&::4;N;Nt;TVbc$0D!r5   c                    U R                   $ r7   r   rP   s    r2   r+   FrozenTrial.numberq      ||r5   c                    Xl         g r7   r   r*   r,   s     r2   r+   r   u  s    r5   c                    U R                   b3  [        U R                   5      S:  a  [        S5      eU R                   S   $ g )NrV   DThis attribute is not available during multi-objective optimization.r   r   lenRuntimeErrorrP   s    r2   r,   FrozenTrial.valuey  s@    <<#4<< 1$"Z  <<?"r5   c                    U R                   b$  [        U R                   5      S:  a  [        S5      eUb	  U/U l         g S U l         g )NrV   r   r   r*   vs     r2   r,   r     sD    <<#4<< 1$"Z  =3DLDLr5   c                    U R                   $ r7   )r   rP   s    r2   _get_valuesFrozenTrial._get_values  s    ||r5   c                :    Ub  [        U5      U l        g S U l        g r7   )r!   r   r   s     r2   _set_valuesFrozenTrial._set_values  s    =7DLDLr5   c                    U R                   $ r7   r"   rP   s    r2   r-   FrozenTrial.datetime_start  s    ###r5   c                    Xl         g r7   r   r   s     r2   r-   r     s    $r5   c                    U R                   $ r7   r$   rP   s    r2   r.   FrozenTrial.params  r   r5   c                    Xl         g r7   r   )r*   r.   s     r2   r.   r     s    r5   c                    U R                   $ r7   r(   rP   s    r2   r	   FrozenTrial.distributions  s    """r5   c                    Xl         g r7   r   r   s     r2   r	   r     s    #r5   c                    U R                   $ r7   r   rP   s    r2   r/   FrozenTrial.user_attrs  s    r5   c                    Xl         g r7   r   r   s     r2   r/   r     s     r5   c                    U R                   $ r7   r   rP   s    r2   r0   FrozenTrial.system_attrs  s    !!!r5   c                H    [        [        [        [        4   U5      U l        g r7   )r   dictstrr   r&   r   s     r2   r0   r     s    !$sCx.%8r5   c                |    [        U R                  5      S:X  a  g[        U R                  R                  5       5      $ )zvReturn the maximum step of :attr:`intermediate_values` in the trial.

Returns:
    The maximum step of intermediates.
r   N)r   r'   maxr   rP   s    r2   	last_stepFrozenTrial.last_step  s4     t''(A-t//44677r5   c                z    U R                   (       a*  U R                  (       a  U R                  U R                   -
  $ g)zQReturn the elapsed time taken to complete the trial.

Returns:
    The duration.
N)r-   r#   rP   s    r2   durationFrozenTrial.duration  s/     4#9#9))D,?,???r5   )r"   r(   r   r$   r&   r)   r%   r   r#   r'   r   )r+   r   r   r   r,   float | Noner-   datetime.datetime | Noner#   r   r.   dict[str, Any]r	   dict[str, BaseDistribution]r/   r   r0   r   r'   zdict[int, float]r1   r   r   Sequence[float] | NonereturnNone)r<   r   r   bool)r   r   )r   r   )rh   r   ri   floatrj   r   rb   r   rc   r   r   r   )rh   r   ri   r   rj   r   r   r   )
rh   r   ri   r   rj   r   ry   r   r   r   )rh   r   ri   r   rj   r   rb   r   rc   r   r   r   )rh   r   r   zSequence[None]r   r   )rh   r   r   zSequence[bool]r   r   )rh   r   r   zSequence[int]r   r   )rh   r   r   zSequence[float]r   r   )rh   r   r   zSequence[str]r   r   )rh   r   r   zSequence[CategoricalChoiceType]r   r   )r,   r   rb   r   r   r   )r   r   )r   r   r,   r   r   r   )r   r   )rh   r   r   r   r   r   )r,   r   r   r   )r   r   )r   r   r   r   )r   zlist[float] | None)r   r   r   r   )r   r   )r,   r   r   r   )r   r   )r.   r   r   r   )r   r   )r,   r   r   r   )r,   r   r   r   )r,   zMapping[str, JSONSerializable]r   r   )r   z
int | None)r   zdatetime.timedelta | None),r^   
__module____qualname____firstlineno____doc__r3   r=   rA   rD   rQ   r`   rk   r   _suggest_deprecated_msgrW   rs   rv   rz   r   r   r   r   r   r   r   r   r   r   rf   propertyr+   setterr,   r   r   r   r-   r.   r	   r/   r0   r   r   __static_attributes__r   r5   r2   r   r       s)   ir *. " "  " 	 "
 1 " 4 "  " 3 " # " % " . "  " ' " 
 "D/
*+L
& "	U	U 	U 		U 	U 	U 
	U Wg,C,J,JPR,J,ST3 U3 Wg,C,J,JPa,J,bc= d= Wg,C,J,JPa,J,bc; d; &B" >?EXX!X),X7:XEIX	X
X
 R RR RP PT TP P$$"A$	$ $MM"AM	M
*& Wg&( '(&P,   ]]    \\
  
   k;/F$ $ % %   ]]  # # $ $     ! ! " " 9 9 
8 
8 
 
r5   r   )r   r,   r   r.   r	   r/   r0   r'   c                   U=(       d    0 nU=(       d    0 nUR                   " 5        VV	s0 s H  u  pU[        U	5      _M     nnn	U=(       d    0 nU=(       d    0 nU=(       d    0 nU [        R                  :X  a  Sn
O[        R                  R                  5       n
U R                  5       (       a  U
nOSn[        SSU UUU
UUUUUUS9nUR                  5         U$ s  sn	nf )a  Create a new :class:`~optuna.trial.FrozenTrial`.

Example:

    .. testcode::

        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}

.. seealso::

    See :func:`~optuna.study.Study.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 :func:`~optuna.study.Study.optimize`.

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

    * ``params``
    * ``distributions``
    * ``value`` or ``values``

Args:
    state:
        Trial state.
    value:
        Trial objective value. Must be specified if ``state`` is :class:`TrialState.COMPLETE`.
        ``value`` and ``values`` must not be specified at the same time.
    values:
        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 :class:`TrialState.COMPLETE`.
        ``value`` and ``values`` must not be specified at the same time.
    params:
        Dictionary with suggested parameters of the trial.
    distributions:
        Dictionary with parameter distributions of the trial.
    user_attrs:
        Dictionary with user attributes.
    system_attrs:
        Dictionary with system attributes. Should not have to be used for most users.
    intermediate_values:
        Dictionary with intermediate objective values of the trial.

Returns:
    Created trial.
N)r+   r1   r   r,   r   r-   r#   r.   r	   r/   r0   r'   )	r   r   r   r   datetimenowr   r   r   )r   r,   r   r.   r	   r/   r0   r'   r   distr-   r#   trials                r2   create_trialr    s    \ \rF!'RM ',,..IC 	:4@@.   !rJ%2L-3
"""!**..06D %+#!/E 
OOLGs   C)r   r   r,   r   r   r   r.   dict[str, Any] | Noner	   z"dict[str, BaseDistribution] | Noner/   r  r0   r  r'   zdict[int, float] | Noner   r   ))
__future__r   collections.abcr   r   r   r   typingr   r   r   optunar	   r
   optuna._convert_positional_argsr   optuna._deprecatedr   optuna._typingr   optuna._warningsr   optuna.distributionsr   r   r   r   r   r   optuna.trial._baser   r   optuna.trial._stater   
get_loggerr^   _loggerr   r   r   r  r   r5   r2   <module>r     s    " # $         C . + ( N 1 6 8 2 0 ; ( * 

X
&< ~) ~F #++%)$(8<(,*.37ss s #	s
 "s 6s &s (s 1s sr5   