o /wiK@sddlmZddlZddlmZddlmZddlmZddlmZddl m Z ddl m Z dd l mZdd lmZdd lmZdd lmZdd lmZdZGdddejZdS)) annotationsN) Container)Sequence)Any)cast)JSONSerializable)BaseDistribution)UpdateFinishedTrialError) FrozenStudy)StudyDirection) FrozenTrial) TrialStatezno-name-c@seZdZdZej dcddd d Zejded dZejdfddZejdgddZ ejdhddZ ejdiddZ ejdjddZ ejdkd d!Z ejdkd"d#Zejdld%d&Zejdcdmd)d*Zejdnd1d2Zdod4d5Zdpd6d7Zdqd8d9Zej dcdrd?d@ZejdsdCdDZejdtdEdFZejdudGdHZejdvdJdKZej L dwdxdQdRZ dcdydTdUZdzdVdWZd{dXdYZd{dZd[Zd{d\d]Zd|d^d_Z d}dadbZ!dS)~ BaseStorageaBase class for storages. This class is not supposed to be directly accessed by library users. This class abstracts a backend database and provides internal interfaces to read/write histories of studies and trials. A storage class implementing this class must meet the following requirements. **Thread safety** A storage class instance can be shared among multiple threads, and must therefore be thread-safe. It must guarantee that a data instance read from the storage must not be modified by subsequent writes. For example, `FrozenTrial` instance returned by `get_trial` should not be updated by the subsequent `set_trial_xxx`. This is usually achieved by replacing the old data with a copy on `set_trial_xxx`. A storage class can also assume that a data instance returned are never modified by its user. When a user modifies a return value from a storage class, the internal state of the storage may become inconsistent. Consequences are undefined. **Ownership of RUNNING trials** Trials in finished states are not allowed to be modified. Trials in the WAITING state are not allowed to be modified except for the `state` field. N directionsSequence[StudyDirection] study_name str | NonereturnintcCt)aCreate a new study from a name. If no name is specified, the storage class generates a name. The returned study ID is unique among all current and deleted studies. Args: directions: A sequence of direction whose element is either :obj:`~optuna.study.StudyDirection.MAXIMIZE` or :obj:`~optuna.study.StudyDirection.MINIMIZE`. study_name: Name of the new study to create. Returns: ID of the created study. Raises: :exc:`optuna.exceptions.DuplicatedStudyError`: If a study with the same ``study_name`` already exists. NotImplementedError)selfrrrR/home/ubuntu/sommelier/.venv/lib/python3.10/site-packages/optuna/storages/_base.pycreate_new_study3szBaseStorage.create_new_studystudy_idNonecCr)zDelete a study. Args: study_id: ID of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrrrr delete_studyMs zBaseStorage.delete_studykeystrvaluercCr)aRegister a user-defined attribute to a study. This method overwrites any existing attribute. Args: study_id: ID of the study. key: Attribute key. value: Attribute value. It should be JSON serializable. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrr r"rrrset_study_user_attr[zBaseStorage.set_study_user_attrrcCr)aRegister an optuna-internal attribute to a study. This method overwrites any existing attribute. Args: study_id: ID of the study. key: Attribute key. value: Attribute value. It should be JSON serializable. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rr#rrrset_study_system_attror%z!BaseStorage.set_study_system_attrcCr)a Read the ID of a study. Args: study_name: Name of the study. Returns: ID of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_name`` exists. r)rrrrrget_study_id_from_namez"BaseStorage.get_study_id_from_namecCr)aRead the study name of a study. Args: study_id: ID of the study. Returns: Name of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrrrget_study_name_from_idr(z"BaseStorage.get_study_name_from_idlist[StudyDirection]cCr)a@Read whether a study maximizes or minimizes an objective. Args: study_id: ID of a study. Returns: Optimization directions list of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrrrget_study_directionsr(z BaseStorage.get_study_directionsdict[str, Any]cCr)a<Read the user-defined attributes of a study. Args: study_id: ID of the study. Returns: Dictionary with the user attributes of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrrrget_study_user_attrsr(z BaseStorage.get_study_user_attrscCr)aJRead the optuna-internal attributes of a study. Args: study_id: ID of the study. Returns: Dictionary with the optuna-internal attributes of the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. rrrrrget_study_system_attrsr(z"BaseStorage.get_study_system_attrslist[FrozenStudy]cCr)zRead a list of :class:`~optuna.study.FrozenStudy` objects. Returns: A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``. rrrrrget_all_studiesszBaseStorage.get_all_studiestemplate_trialFrozenTrial | NonecCr)a'Create and add a new trial to a study. The returned trial ID is unique among all current and deleted trials. Args: study_id: ID of the study. template_trial: Template :class:`~optuna.trial.FrozenTrial` with default user-attributes, system-attributes, intermediate-values, and a state. Returns: ID of the created trial. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. r)rrr2rrrcreate_new_trialzBaseStorage.create_new_trialtrial_id param_nameparam_value_internalfloat distributionrcCr)a?Set a parameter to a trial. Args: trial_id: ID of the trial. param_name: Name of the parameter. param_value_internal: Internal representation of the parameter value. distribution: Sampled distribution of the parameter. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. r)rr6r7r8r:rrrset_trial_paramszBaseStorage.set_trial_param trial_numbercCs4|j|dd}t||krtd||||jS)a`Read the trial ID of a trial. Args: study_id: ID of the study. trial_number: Number of the trial. Returns: ID of the trial. Raises: :exc:`KeyError`: If no trial with the matching ``study_id`` and ``trial_number`` exists. F)deepcopyz?No trial with trial number {} exists in study with study_id {}.)get_all_trialslenKeyErrorformat _trial_id)rrr<trialsrrr'get_trial_id_from_study_id_trial_numbers  z3BaseStorage.get_trial_id_from_study_id_trial_numbercC ||jS)awRead the trial number of a trial. .. note:: The trial number is only unique within a study, and is sequential. Args: trial_id: ID of the trial. Returns: Number of the trial. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. ) get_trialnumberrr6rrrget_trial_number_from_id1s z$BaseStorage.get_trial_number_from_idcCs ||}|j||j|S)aRead the parameter of a trial. Args: trial_id: ID of the trial. param_name: Name of the parameter. Returns: Internal representation of the parameter. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. If no such parameter exists. )rF distributionsto_internal_reprparams)rr6r7trialrrrget_trial_paramEs zBaseStorage.get_trial_paramstater valuesSequence[float] | NoneboolcCr)aUpdate the state and values of a trial. Set return values of an objective function to values argument. If values argument is not :obj:`None`, this method overwrites any existing trial values. Args: trial_id: ID of the trial. state: New state of the trial. values: Values of the objective function. Returns: :obj:`True` if the state is successfully updated. :obj:`False` if the state is kept the same. The latter happens when this method tries to update the state of :obj:`~optuna.trial.TrialState.RUNNING` trial to :obj:`~optuna.trial.TrialState.RUNNING`. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. r)rr6rOrPrrrset_trial_state_valuesYsz"BaseStorage.set_trial_state_valuesstepintermediate_valuecCr)aReport an intermediate value of an objective function. This method overwrites any existing intermediate value associated with the given step. Args: trial_id: ID of the trial. step: Step of the trial (e.g., the epoch when training a neural network). intermediate_value: Intermediate value corresponding to the step. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. r)rr6rTrUrrrset_trial_intermediate_valueysz(BaseStorage.set_trial_intermediate_valuecCr)aSet a user-defined attribute to a trial. This method overwrites any existing attribute. Args: trial_id: ID of the trial. key: Attribute key. value: Attribute value. It should be JSON serializable. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. rrr6r r"rrrset_trial_user_attrr5zBaseStorage.set_trial_user_attrcCr)aSet an optuna-internal attribute to a trial. This method overwrites any existing attribute. Args: trial_id: ID of the trial. key: Attribute key. value: Attribute value. It should be JSON serializable. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. rrWrrrset_trial_system_attrr5z!BaseStorage.set_trial_system_attrr cCr)a Read a trial. Args: trial_id: ID of the trial. Returns: Trial with a matching trial ID. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. rrHrrrrFr(zBaseStorage.get_trialTr=statesContainer[TrialState] | Nonelist[FrozenTrial]cCr)aIRead all trials in a study. Args: study_id: ID of the study. deepcopy: Whether to copy the list of trials before returning. Set to :obj:`True` if you intend to update the list or elements of the list. states: Trial states to filter on. If :obj:`None`, include all states. Returns: List of trials in the study, sorted by ``trial_id``. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. r)rrr=rZrrrr>szBaseStorage.get_all_trials*tuple[TrialState, ...] | TrialState | NonecCs$t|tr|f}t|j|d|dS)aCount the number of trials in a study. Args: study_id: ID of the study. state: Trial states to filter on. If :obj:`None`, include all states. Returns: Number of trials in the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. Fr=rZ) isinstancer r?r>)rrrOrrr get_n_trialss zBaseStorage.get_n_trialscCs|j|dtjgd}t|dkrtd||}t|dkr#td|d}|tjkr6t |ddd }|St |d dd }|S) aSReturn the trial with the best value in a study. This method is valid only during single-objective optimization. Args: study_id: ID of the study. Returns: The trial with the best objective value among all finished trials in the study. Raises: :exc:`KeyError`: If no study with the matching ``study_id`` exists. :exc:`RuntimeError`: If the study has more than one direction. :exc:`ValueError`: If no trials have been completed. Fr^rzNo trials are completed yet.zBBest trial can be obtained only for single-objective optimization.cS tt|jSNrr9r"trrr$ z,BaseStorage.get_best_trial..)r cSrbrcrdrerrrrg&rh) r>r COMPLETEr? ValueErrorr+ RuntimeErrorr MAXIMIZEmaxmin)rr all_trialsr direction best_trialrrrget_best_trials    zBaseStorage.get_best_trialcCrE)aRead the parameter dictionary of a trial. Args: trial_id: ID of the trial. Returns: Dictionary of a parameters. Keys are parameter names and values are external representations of the parameter values. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. )rFrLrHrrrget_trial_params*s zBaseStorage.get_trial_paramscCrE)aDRead the user-defined attributes of a trial. Args: trial_id: ID of the trial. Returns: Dictionary with the user-defined attributes of the trial. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. )rF user_attrsrHrrrget_trial_user_attrs; z BaseStorage.get_trial_user_attrscCrE)aJRead the optuna-internal attributes of a trial. Args: trial_id: ID of the trial. Returns: Dictionary with the optuna-internal attributes of the trial. Raises: :exc:`KeyError`: If no trial with the matching ``trial_id`` exists. )rF system_attrsrHrrrget_trial_system_attrsKrvz"BaseStorage.get_trial_system_attrscCsdS)z'Clean up all connections to a database.Nrr0rrrremove_session[szBaseStorage.remove_session trial_statecCs&|r||}td|jdS)ajCheck whether a trial state is updatable. Args: trial_id: ID of the trial. Only used for an error message. trial_state: Trial state to check. Raises: :exc:`~optuna.exceptions.UpdateFinishedTrialError`: If the trial is already finished. z5Trial#{} has already finished and can not be updated.N) is_finishedrFr rArG)rr6rzrMrrrcheck_trial_is_updatable_s   z$BaseStorage.check_trial_is_updatablerc)rrrrrr)rrrr)rrr r!r"rrr)rrr r!r"rrr)rr!rr)rrrr!)rrrr*)rrrr,)rr/)rrr2r3rr) r6rr7r!r8r9r:rrr)rrr<rrr)r6rrr)r6rr7r!rr9)r6rrOr rPrQrrR)r6rrTrrUr9rr)r6rr r!r"rrr)r6rr r!r"rrr)r6rrr )TN)rrr=rRrZr[rr\)rrrOr]rr)rrrr )r6rrr,)rr)r6rrzr rr)"__name__ __module__ __qualname____doc__abcabstractmethodrrr$r&r'r)r+r-r.r1r4r;rDrIrNrSrVrXrYrFr>r`rrrsrurxryr|rrrrrsj                    '   r) __future__rrcollections.abcrrtypingrroptuna._typingroptuna.distributionsroptuna.exceptionsr optuna.study._frozenr optuna.study._study_directionr optuna.trialr r DEFAULT_STUDY_NAME_PREFIXABCrrrrrs