
    -ji                        S SK J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\R$                  S9r\" S5       " S S\5      5       rg)    )annotationsN)experimental_class)Study)BaseErrorEvaluator)CrossValidationErrorEvaluator)StaticErrorEvaluator)BaseImprovementEvaluator)BestValueStagnationEvaluator)DEFAULT_MIN_N_TRIALS)RegretBoundEvaluator)
TrialStatec                  @    \ rS rSrSr\R                  SS j5       rSrg)BaseTerminator   zBase class for terminators.c                    g )N )selfstudys     V/home/james-whalen/.local/lib/python3.13/site-packages/optuna/terminator/terminator.pyshould_terminateBaseTerminator.should_terminate   s        r   Nr   r   returnbool)	__name__
__module____qualname____firstlineno____doc__abcabstractmethodr   __static_attributes__r   r   r   r   r      s    % r   r   )	metaclassz3.2.0c                  N    \ rS rSrSrSS\4       SS jjrS	S jrS
S jrSr	g)
Terminator   a
  Automatic stopping mechanism for Optuna studies.

This class implements an automatic stopping mechanism for Optuna studies, aiming to prevent
unnecessary computation. The study is terminated when the statistical error, e.g.
cross-validation error, exceeds the room left for optimization.

For further information about the algorithm, please refer to the following paper:

- `A. Makarova et al. Automatic termination for hyperparameter optimization.
  <https://proceedings.mlr.press/v188/makarova22a.html>`__

Args:
    improvement_evaluator:
        An evaluator object for assessing the room left for optimization. Defaults to a
        :class:`~optuna.terminator.improvement.evaluator.RegretBoundEvaluator` object.
    error_evaluator:
        An evaluator for calculating the statistical error, e.g. cross-validation error.
        Defaults to a :class:`~optuna.terminator.CrossValidationErrorEvaluator`
        object.
    min_n_trials:
        The minimum number of trials before termination is considered. Defaults to ``20``.

Raises:
    ValueError: If ``min_n_trials`` is not a positive integer.

Example:

    .. testcode::

        import logging
        import sys

        from sklearn.datasets import load_wine
        from sklearn.ensemble import RandomForestClassifier
        from sklearn.model_selection import cross_val_score
        from sklearn.model_selection import KFold

        import optuna
        from optuna.terminator import Terminator
        from optuna.terminator import report_cross_validation_scores


        study = optuna.create_study(direction="maximize")
        terminator = Terminator()
        min_n_trials = 20

        while True:
            trial = study.ask()

            X, y = load_wine(return_X_y=True)

            clf = RandomForestClassifier(
                max_depth=trial.suggest_int("max_depth", 2, 32),
                min_samples_split=trial.suggest_float("min_samples_split", 0, 1),
                criterion=trial.suggest_categorical("criterion", ("gini", "entropy")),
            )

            scores = cross_val_score(clf, X, y, cv=KFold(n_splits=5, shuffle=True))
            report_cross_validation_scores(trial, scores)

            value = scores.mean()
            logging.info(f"Trial #{trial.number} finished with value {value}.")
            study.tell(trial, value)

            if trial.number > min_n_trials and terminator.should_terminate(study):
                logging.info("Terminated by Optuna Terminator!")
                break

.. seealso::
    Please refer to :class:`~optuna.terminator.TerminatorCallback` for how to use
    the terminator mechanism with the :func:`~optuna.study.Study.optimize` method.

Nc                    US::  a  [        S5      eU=(       d
    [        5       U l        U=(       d    U R                  5       U l        X0l        g )Nr   z4`min_n_trials` is expected to be a positive integer.)
ValueErrorr   _improvement_evaluator_initialize_error_evaluator_error_evaluator_min_n_trials)r   improvement_evaluatorerror_evaluatormin_n_trialss       r   __init__Terminator.__init__e   sE     1STT&;&U?S?U# / U43S3S3U)r   c                f    [        U R                  [        5      (       a	  [        SS9$ [	        5       $ )Nr   )constant)
isinstancer*   r
   r   r   )r   s    r   r+   &Terminator._initialize_error_evaluatorr   s*    d113OPP'33,..r   c                6   UR                  [        R                  /S9n[        U5      U R                  :  a  gU R
                  R                  UR                  UR                  S9nU R                  R                  UR                  UR                  S9nX4:  nU$ )zJJudge whether the study should be terminated based on the reported values.)statesF)trialsstudy_direction)

get_trialsr   COMPLETElenr-   r*   evaluater9   	directionr,   )r   r   r9   improvementerrorr   s         r   r   Terminator.should_terminatew   s    !!**=*=)>!?v;+++11::<<!OO ; 

 %%..<< / 
 '.r   )r,   r*   r-   )r.   zBaseImprovementEvaluator | Noner/   zBaseErrorEvaluator | Noner0   intr   None)r   r   r   )
r   r   r   r   r    r   r1   r+   r   r#   r   r   r   r&   r&      sK    HX BF590	*>* 3* 	*
 
*/
 r   r&   )
__future__r   r!   optuna._experimentalr   optuna.study.studyr   optuna.terminator.errorevalr   r   r   'optuna.terminator.improvement.evaluatorr	   r
   r   r   optuna.trialr   ABCMetar   r&   r   r   r   <module>rL      s\    " 
 3 $ : E < L P H H #s{{  Gn  n  n r   