-ji SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKrSSK J r SSK r SS K J r SS K Jr SS K Jr SS K Jr SSKrSSKrSS KJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJ r SSK!J"r" SSK#J$r$ SSK%J&r& SSK%J'r' SSK(J)r) SSK*J+r+ SSK*J,r, SSK-J.r. SSK/J0r0 SSK1J2r2 SS K3J4r4 SS!K5J6r6 SS"K5J7r7 SS#K8J9r9 SS$K8J:r: \ "S%5r;\(aSS&Kr> SS(K8J?r? \S)/\\@\\@44rAS*rB\R"\D5rE"S+S,\ R5rG"S-S.5rH\"/S/QS0S1S29SSSSSS3SS4.SCS7jj5rI\"/S8QS0S1S29SSS9.SDS:jj5rJ\"S6S5/S0S1S29SES;j5rK\"/S9SS?.SFS@jj5rLSGSHSAjjrMSISBjrNg)J) annotations)Callable) Container)Iterable)Mapping)SequenceN)Real)Any)cast) TYPE_CHECKING)Union) exceptions)logging)pruners)samplers)storages)convert_positional_args)deprecated_func)experimental_func) _LazyImport)JSONSerializable) optuna_warn)-_convert_old_distribution_to_new_distribution)BaseDistribution)is_heartbeat_enabled)_CONSTRAINTS_KEY)_get_feasible_trials)_get_pareto_front_trials) _optimize)StudyDirection) StudySummary)_get_frozen_trial)_tell_with_warning) create_trial) TrialStatezoptuna.study._dataframe)pd) FrozenTrial)Trialr(zstudy:metric_namesc2\rSrSr%SrS\S'SrS\S'Srg) _ThreadLocalStudyAttribute>Fboolin_optimize_loopNzlist[FrozenTrial] | Nonecached_all_trials)__name__ __module__ __qualname____firstlineno__r-__annotations__r.__static_attributes__r/L/home/james-whalen/.local/lib/python3.13/site-packages/optuna/study/study.pyr*r*>s"d"26/6r6r*c\rSrSrSrS'S(SjjrS)SjrS*Sjr\S+Sj5r \S,Sj5r \S-S j5r \S.S j5r \S/S j5r \S0S j5r\S.S j5rS1S2SjjrS3S4SjjrS5Sjr\S+Sj5r\\"SS5S+Sj55r\S6Sj5rS7S8SjjrS9S:SjjrS;SS?SjjrS@SjrSASBSjjrSCSjrSDSjr \!"S 5SES!j5r"SFS"jr#SGS#jr$SHS$jr%SIS%jr&S&r'g)JStudyCaA study corresponds to an optimization task, i.e., a set of trials. This object provides interfaces to run a new :class:`~optuna.trial.Trial`, access trials' history, set/get user-defined attributes of the study itself. Note that the direct use of this constructor is not recommended. To create and load a study, please refer to the documentation of :func:`~optuna.study.create_study` and :func:`~optuna.study.load_study` respectively. NcZXl[R"U5nURU5nXPlX lUR U5UlU=(d [R"5Ul U=(d [R"5Ul [5UlSUlgNF) study_namer get_storageget_study_id_from_name _study_id_storageget_study_directions _directionsr TPESamplersamplerr MedianPrunerprunerr* _thread_local _stop_flag)selfr=storagerErGstudy_ids r7__init__Study.__init__Os%&&w/11*=! "77A7("5"5"7 6 4 4 6 79r6c@URR5nUS U$)NrH)__dict__copyrJstates r7 __getstate__Study.__getstate__cs! ""$ / " r6cXURRU5 [5UlgN)rPupdater*rHrRs r7 __setstate__Study.__setstate__hs U#79r6c.URR$)zReturn parameters of the best trial in the study. .. note:: This feature can only be used for single-objective optimization. Returns: A dictionary containing parameters of the best trial. ) best_trialparamsrJs r7 best_paramsStudy.best_paramsls%%%r6c<URRnUceU$)zReturn the best objective value in the study. .. note:: This feature can only be used for single-objective optimization. Returns: A float representing the best objective value. )r\value)rJ best_values r7rcStudy.best_valuezs%__** %%%r6c URSS9$)aReturn the best trial in the study. .. note:: This feature can only be used for single-objective optimization. If your study is multi-objective, use :attr:`~optuna.study.Study.best_trials` instead. Returns: A :class:`~optuna.trial.FrozenTrial` object of the best trial. .. seealso:: The :ref:`reuse_best_trial` tutorial provides a detailed example of how to use this method. Tdeepcopy)_get_best_trialr^s r7r\Study.best_trials"##T#22r6cVURSS9n[SU55n[XS9$)aReturn trials located at the Pareto front in the study. A trial is located at the Pareto front if there are no trials that dominate the trial. It's called that a trial ``t0`` dominates another trial ``t1`` if ``all(v0 <= v1) for v0, v1 in zip(t0.values, t1.values)`` and ``any(v0 < v1) for v0, v1 in zip(t0.values, t1.values)`` are held. Returns: A list of :class:`~optuna.trial.FrozenTrial` objects. Frfc3H# UHn[UR;v M g7frW)r system_attrs).0trials r7 $Study.best_trials..sZSY%.%2D2DDSYs ")consider_constraint) get_trialsanyr)rJtrialsis_constraineds r7 best_trialsStudy.best_trialss0%0ZSYZZ'QQr6c`UR5(a [S5eURS$)aReturn the direction of the study. .. note:: This feature can only be used for single-objective optimization. If your study is multi-objective, use :attr:`~optuna.study.Study.directions` instead. Returns: A :class:`~optuna.study.StudyDirection` object. zA single direction cannot be retrieved from a multi-objective study. Consider using Study.directions to retrieve a list containing all directions.r)_is_multi_objective RuntimeError directionsr^s r7 directionStudy.directions7  # # % %W  q!!r6cUR$)zkReturn the directions of the study. Returns: A list of :class:`~optuna.study.StudyDirection` objects. )rCr^s r7r{Study.directionssr6c"URSSS9$)a:Return all trials in the study. The returned trials are ordered by trial number. This is a short form of ``self.get_trials(deepcopy=True, states=None)``. Returns: A list of :class:`~optuna.trial.FrozenTrial` objects. .. seealso:: See :func:`~optuna.study.Study.get_trials` for related method. TNrgstates)rrr^s r7rt Study.trialss T::r6c"URXSS9$)aReturn all trials in the study. The returned trials are ordered by trial number. .. seealso:: See :attr:`~optuna.study.Study.trials` for related property. Example: .. 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) trials = study.get_trials() assert len(trials) == 3 Args: deepcopy: Flag to control whether to apply ``copy.deepcopy()`` to the trials. Note that if you set the flag to :obj:`False`, you shouldn't mutate any fields of the returned trial. Otherwise the internal state of the study may corrupt and unexpected behavior may happen. states: Trial states to filter on. If :obj:`None`, include all states. Returns: A list of :class:`~optuna.trial.FrozenTrial` objects. F) use_cache) _get_trials)rJrgrs r7rrStudy.get_trialssPEBBr6cU(aURRc3URRURSS9URlURRnUb$UVs/sHoUR U;dMUPM nnOUnU(a[ R"U5$U$URRURXS9$s snf)NFrfr)rHr.rAget_all_trialsr@rSrQrg)rJrgrrrttfiltered_trialss r7rStudy._get_trials s !!33;7;}}7S7SNNU8T8""4''99F!.4"Jf68I1f"J"(5=4==1 R? R}}++DNNX+]] #Ks /CCcPUR5(a [S5eURRUR5nUR R [5nUb[UVs/sHoDS:PM sn5(ayURS[R/S9n[U5n[U5S:Xa [S5eUR[ R":Xa [%USS9nO ['US S9nU(a[(R*"U5$U$s snf) aReturn the best trial in the study. Args: deepcopy: Flag to control whether to apply ``copy.deepcopy()`` to the trial. If :obj:`False`, returns the trial without deep copying for better performance. Note that if you set this to :obj:`False`, you shouldn't mutate any fields of the returned trial. Returns: A :class:`~optuna.trial.FrozenTrial` object of the best trial. zA single best trial cannot be retrieved from a multi-objective study. Consider using Study.best_trials to retrieve a list containing the best trials.Frrz%No feasible trials are completed yet.c6[[UR5$rWr floatrbrs r7'Study._get_best_trial..@UAGG@Tr6keyc6[[UR5$rWrrs r7rrBrr6)ryrzrAget_best_trialr@rlgetrrsrrr%COMPLETErlen ValueErrorr|r MAXIMIZEmaxminrQrg)rJrgr\ constraintsxcomplete_trialsfeasible_trialss r7rhStudy._get_best_trial!s  # # % %Y  ]]11$..A !--112BC  "s[+I[G[+I'J'J"ooujFYFYEZo[O2?CO?#q( !HII~~!8!88 6TU  6TU ,4t}}Z(D*D,Js1D#ct[R"URRUR55$)a Return user attributes. .. seealso:: See :func:`~optuna.study.Study.set_user_attr` for related method. Example: .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", 0, 1) y = trial.suggest_float("y", 0, 1) return x**2 + y**2 study = optuna.create_study() study.set_user_attr("objective function", "quadratic function") study.set_user_attr("dimensions", 2) study.set_user_attr("contributors", ["Akiba", "Sano"]) assert study.user_attrs == { "objective function": "quadratic function", "dimensions": 2, "contributors": ["Akiba", "Sano"], } Returns: A dictionary containing all user attributes. )rQrgrAget_study_user_attrsr@r^s r7 user_attrsStudy.user_attrsFs'J}}T]]??OPPr6z3.1.05.0.0ct[R"URRUR55$)zWReturn system attributes. Returns: A dictionary containing all system attributes. )rQrgrAget_study_system_attrsr@r^s r7rlStudy.system_attrsms&}}T]]AA$..QRRr6crURRUR5R[5$)zReturn metric names. .. note:: Use :meth:`~optuna.study.Study.set_metric_names` to set the metric names first. Returns: A list with names for each dimension of the returned values of the objective function. )rArr@r_SYSTEM_ATTR_METRIC_NAMESr^s r7 metric_namesStudy.metric_namesxs)}}33DNNCGGHabbr6c h[UUUUU[U[5(a [U5OU4UUUS9 g)aOptimize an objective function. Optimization is done by choosing a suitable set of hyperparameter values from a given range. Uses a sampler which implements the task of value suggestion based on a specified distribution. The sampler is specified in :func:`~optuna.study.create_study` and the default choice for the sampler is TPE. See also :class:`~optuna.samplers.TPESampler` for more details on 'TPE'. Optimization will be stopped when receiving a termination signal such as SIGINT and SIGTERM. Unlike other signals, a trial is automatically and cleanly failed when receiving SIGINT (Ctrl+C). If ``n_jobs`` is greater than one or if another signal than SIGINT is used, the interrupted trial state won't be properly updated. Example: .. 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) Args: func: A callable that implements objective function. n_trials: The number of trials for each process. :obj:`None` represents no limit in terms of the number of trials. The study continues to create trials until the number of trials reaches ``n_trials``, ``timeout`` period elapses, :func:`~optuna.study.Study.stop` is called, or a termination signal such as SIGTERM or Ctrl+C is received. .. seealso:: :class:`optuna.study.MaxTrialsCallback` can ensure how many times trials will be performed across all processes. timeout: Stop study after the given number of second(s). :obj:`None` represents no limit in terms of elapsed time. The study continues to create trials until the number of trials reaches ``n_trials``, ``timeout`` period elapses, :func:`~optuna.study.Study.stop` is called or, a termination signal such as SIGTERM or Ctrl+C is received. n_jobs: The number of parallel jobs. If this argument is set to ``-1``, the number is set to CPU count. .. note:: ``n_jobs`` allows parallelization using :obj:`threading` and may suffer from `Python's GIL `__. It is recommended to use :ref:`process-based parallelization` if ``func`` is CPU bound. catch: A study continues to run even when a trial raises one of the exceptions specified in this argument. Default is an empty tuple, i.e. the study will stop for any exception except for :class:`~optuna.exceptions.TrialPruned`. callbacks: List of callback functions that are invoked at the end of each trial. Each function must accept two parameters with the following types in this order: :class:`~optuna.study.Study` and :class:`~optuna.trial.FrozenTrial`. .. seealso:: See the tutorial of :ref:`optuna_callback` for how to use and implement callback functions. gc_after_trial: Flag to determine whether to automatically run garbage collection after each trial. Set to :obj:`True` to run the garbage collection, :obj:`False` otherwise. When it runs, it runs a full collection by internally calling :func:`gc.collect`. If you see an increase in memory consumption over several trials, try setting this flag to :obj:`True`. .. seealso:: :ref:`out-of-memory-gc-collect` show_progress_bar: Flag to show progress bars or not. To show progress bar, set this :obj:`True`. Note that it is disabled when ``n_trials`` is :obj:`None`, ``timeout`` is not :obj:`None`, and ``n_jobs`` :math:`\ne 1`. Raises: RuntimeError: If nested invocation of this method occurs. ) studyfuncn_trialstimeoutn_jobscatch callbacksgc_after_trialshow_progress_barN)r isinstancertuple) rJrrrrrrrrs r7optimizeStudy.optimizes<L ",UH"="=%,E8)/ r6cURR(d%[UR5(a [ S5 U=(d 0nUR 5VVs0sHup#U[ U5_M nnnSURlUR5nUc%URRUR5n[R"X5nUR 5HupgURXg5 M U$s snnf)aCreate a new trial from which hyperparameters can be suggested. This method is part of an alternative to :func:`~optuna.study.Study.optimize` that allows controlling the lifetime of a trial outside the scope of ``func``. Each call to this method should be followed by a call to :func:`~optuna.study.Study.tell` to finish the created trial. .. seealso:: The :ref:`ask_and_tell` tutorial provides use-cases with examples. Example: Getting the trial object with the :func:`~optuna.study.Study.ask` method. .. testcode:: import optuna study = optuna.create_study() trial = study.ask() x = trial.suggest_float("x", -1, 1) study.tell(trial, x**2) Example: Passing previously defined distributions to the :func:`~optuna.study.Study.ask` method. .. testcode:: import optuna study = optuna.create_study() distributions = { "optimizer": optuna.distributions.CategoricalDistribution(["adam", "sgd"]), "lr": optuna.distributions.FloatDistribution(0.0001, 0.1, log=True), } # You can pass the distributions previously defined. trial = study.ask(fixed_distributions=distributions) # `optimizer` and `lr` are already suggested and accessible with `trial.params`. assert "optimizer" in trial.params assert "lr" in trial.params Args: fixed_distributions: A dictionary containing the parameter names and parameter's distributions. Each parameter in this dictionary is automatically suggested for the returned trial, even when the suggest method is not explicitly invoked by the user. If this argument is set to :obj:`None`, no parameter is automatically suggested. Returns: A :class:`~optuna.trial.Trial`. z@Heartbeat of storage is supposed to be used with Study.optimize.N)rHr-rrAritemsrr._pop_waiting_trial_idcreate_new_trialr@optunar(_suggest)rJfixed_distributionsrdisttrial_idrnnameparams r7ask Study.asks@!!227KDMM7Z7Z Z [17R1668 8  >tD D8  04,--/  }}55dnnEH T,.446KD NN4 '7 ! sDcZ[UUUUUS9 [R"[X55$)a} 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 :obj:`None`, :class:`~optuna.trial.TrialState.COMPLETE`, :class:`~optuna.trial.TrialState.FAIL` or :class:`~optuna.trial.TrialState.PRUNED`. If ``state`` is :obj:`None`, it will be updated to :class:`~optuna.trial.TrialState.COMPLETE` or :class:`~optuna.trial.TrialState.FAIL` depending on whether validation for ``values`` reported succeed or not. 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. Returns: A :class:`~optuna.trial.FrozenTrial` representing the resulting trial. A returned trial is deep copied thus user can modify it as needed. )rrnvalue_or_valuesrSskip_if_finished)r#rQrgr")rJrnvaluesrSrs r7tell Study.tellLs3h "-  }}.t;<%%  &&t~~e&Lr6c8UHnURU5 M g)aAdd trials to study. The trials are validated before being added. Example: .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", 0, 10) return x**2 study = optuna.create_study() study.optimize(objective, n_trials=3) assert len(study.trials) == 3 other_study = optuna.create_study() other_study.add_trials(study.trials) assert len(other_study.trials) == len(study.trials) other_study.optimize(objective, n_trials=2) assert len(other_study.trials) == len(study.trials) + 2 .. seealso:: See :func:`~optuna.study.Study.add_trial` for addition of each trial. Args: trials: Trials to add. N)r)rJrtrns r7 add_trialsStudy.add_trialssJE NN5 !r6z3.2.0c[UR5[U5:wa [S5eURR UR [ U5 g)aSet metric names. This method names each dimension of the returned values of the objective function. It is particularly useful in multi-objective optimization. The metric names are mainly referenced by the visualization functions. Example: .. testcode:: import optuna import pandas def objective(trial): x = trial.suggest_float("x", 0, 10) return x**2, x + 1 study = optuna.create_study(directions=["minimize", "minimize"]) study.set_metric_names(["x**2", "x+1"]) study.optimize(objective, n_trials=3) df = study.trials_dataframe(multi_index=True) assert isinstance(df, pandas.DataFrame) assert list(df.get("values").keys()) == ["x**2", "x+1"] .. seealso:: The names set by this method are used in :meth:`~optuna.study.Study.trials_dataframe` and :func:`~optuna.visualization.plot_pareto_front`. Args: metric_names: A list of metric names for the objective function. zCThe number of objectives must match the length of the metric names.N)rr{rrArr@r)rJrs r7set_metric_namesStudy.set_metric_namessEH t 3|#4 4bc c ++ NN5| r6c2[UR5S:$)zReturn :obj:`True` if the study has multiple objectives. Returns: A boolean value indicates if `self.directions` has more than 1 element or not. )rr{r^s r7ryStudy._is_multi_objective)s4??#a''r6cURRURS[R4S9HmnURR UR [RS9(dM=[RSURS35 UR s $ g![Ra Mf=f)NFr)rSTrial z popped from the trial queue.) rArr@r%rset_trial_state_values _trial_idRUNNINGrUpdateFinishedTrialErrorrdebugnumberrs r7rStudy._pop_waiting_trial_id2s]]11 NNUJ4F4F3H2 E }};;OO$,,<  MMF5<<.0MN O?? "% ( 66  s7B''B?>B?cURSS9GH-nURRSUR5nUR 5UR 5:waMN/nUR 5HupVX5n[ U[U55(dURS5 M6[ U[5(aN[R"[U55=(d( [R"[U5[U5SS9OXg:HnUR[U55 M [U5(dGM. g g)NFrfrr)atolT)rrrlrr]keysrrtypeappendr npisnanriscloser,all) rJr]rn trial_paramsrepeated_params param_name param_valueexisting_param is_repeateds r7rStudy._should_skip_enqueueIs __e_4E --11.%,,OL  "fkkm3*,O+1<<>' !-!9!+tN/CDD $**51 "+t44HHU;/0Wzz% "4eN6KRUV$6   &&tK'89!,:$?##558r6c 6[R[R5(dgURn[ U5S:aEUcUnO[ XA5VVs0sHupgXg_M nnn[RSUSUSUS35 g[ U5S:XaeUcUSnO USUS0nSUSUSUS3n URSS 9n U S U RS U RS3- n [RU 5 gS 5es snnf![a N/f=f) Nrrz finished with values: z and parameters: .rz finished with value: Frfz Best is trial z with value: zShould not reach.) r isEnabledForrINFOrrziprrhr rbr) rJrr r]r trial_valuesrrb trial_valuemessager\s r7_log_completed_trialStudy._log_completed_trialhsK##GLL11 (( v;?#% ?B->,?}ZM]M]L^^_`` LL ! -- -5- Z"  sD9/D DD)rCrIrAr@rHrGrEr=)NN) r=strrKstr | storages.BaseStoragerE'samplers.BaseSampler' | NonerGpruners.BasePruner | NonereturnNone)r+dict[Any, Any])rSr-r+r,)r+dict[str, Any])r+r)r+r')r+list[FrozenTrial])r+r )r+zlist[StudyDirection])TN)rgr,rContainer[TrialState] | Noner+r/)TNF)rgr,rr0rr,r+r/)rgr,r+r')r+zlist[str] | None)NNrr/NFF)rObjectiveFuncTyper int | Nonerz float | Nonerintrz+Iterable[type[Exception]] | type[Exception]rz5Iterable[Callable[[Study, FrozenTrial], None]] | Nonerr,rr,r+r,rW)rz"dict[str, BaseDistribution] | Noner+r()NNF) rnz Trial | intrzfloat | Sequence[float] | NonerSzTrialState | Nonerr,r+r')rr'rbr r+r,)) r rbdatetime_startdatetime_completedurationr]rrlrSF)rztuple[str, ...]rr,r+z'pd.DataFrame')r+r,r<)r]r.rzdict[str, Any] | Nonerr,r+r,)rnr'r+r,)rtzIterable[FrozenTrial]r+r,)r list[str]r+r,)r+r,)r+r2)r]zMapping[str, JSONSerializable]r+r,)rz list[float]r r3r]r.r+r,)(r0r1r2r3__doc__rMrTrYpropertyr_rcr\rvr|r{rtrrrrhrrrlrrrrrrrrrrrrrryrrr%r5r/r6r7r9r9CsZ 26,0   , /  *    ( : & & 33$RR$""*  ;;&/3(C(C-(C  (CX/3 ^^-^ ^  ^(#EJ$Q$QLWg&S'S c c $ $=?KO$"'p p p  p  p ; p Ip p  p  p dTr26#'!& [=[=/[=! [=  [=  [=z*FXWg& H' H " "BFBFBF BFH#P-1$ ? ? *?  ?  ? BFMP&"Pw(  ( T(.>#.!#.+.#.8F#. #.r6r9)rKrErGr=r|load_if_existsz3.0.0r)previous_positional_arg_namesdeprecated_versionremoved_versionF)rKrErGr=r|r:r{rKr=cRUcUcS/nO^UbUb [S5eUb9[U[5(a [U[5(d [S5eU/nOUb [ U5nOe[ U5S:a [S5e[ SU55(a[SUS35eUVs/sH1n[U[5(aUO[UR5PM3 nn[R"U5nURX5n Uc$[ U5S:a["R$"5nUR'U 5n[)X0XS 9n U $s snf![Ra: U(a1Uce[RS US 35 UR!U5n Nef=f) aQ Create a new :class:`~optuna.study.Study`. Example: .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", 0, 10) return x**2 study = optuna.create_study() study.optimize(objective, n_trials=3) Args: storage: Database URL. If this argument is set to None, :class:`~optuna.storages.InMemoryStorage` is used, and the :class:`~optuna.study.Study` will not be persistent. .. note:: When a database URL is passed, Optuna internally uses `SQLAlchemy`_ to handle the database. Please refer to `SQLAlchemy's document`_ for further details. If you want to specify non-default options to `SQLAlchemy Engine`_, you can instantiate :class:`~optuna.storages.RDBStorage` with your desired options and pass it to the ``storage`` argument instead of a URL. .. _SQLAlchemy: https://www.sqlalchemy.org/ .. _SQLAlchemy's document: https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls .. _SQLAlchemy Engine: https://docs.sqlalchemy.org/en/latest/core/engines.html sampler: A sampler object that implements background algorithm for value suggestion. If :obj:`None` is specified, :class:`~optuna.samplers.TPESampler` is used during single-objective optimization and :class:`~optuna.samplers.NSGAIISampler` during multi-objective optimization. See also :class:`~optuna.samplers`. pruner: A pruner object that decides early stopping of unpromising trials. If :obj:`None` is specified, :class:`~optuna.pruners.MedianPruner` is used as the default. See also :class:`~optuna.pruners`. study_name: Study's name. If this argument is set to None, a unique name is generated automatically. direction: Direction of optimization. Set ``minimize`` for minimization and ``maximize`` for maximization. You can also pass the corresponding :class:`~optuna.study.StudyDirection` object. ``direction`` and ``directions`` must not be specified at the same time. .. note:: If none of `direction` and `directions` are specified, the direction of the study is set to "minimize". load_if_exists: Flag to control the behavior to handle a conflict of study names. In the case where a study named ``study_name`` already exists in the ``storage``, a :class:`~optuna.exceptions.DuplicatedStudyError` is raised if ``load_if_exists`` is set to :obj:`False`. Otherwise, the creation of the study is skipped, and the existing one is returned. directions: A sequence of directions during multi-objective optimization. ``direction`` and ``directions`` must not be specified at the same time. Returns: A :class:`~optuna.study.Study` object. See also: :func:`optuna.create_study` is an alias of :func:`optuna.study.create_study`. See also: The :ref:`rdb` tutorial provides concrete examples to save and resume optimization using RDB. minimizez1Specify only one of `direction` and `directions`.zIUse `directions` instead of `direction` for multi-objective optimization.rz0The number of objectives must be greater than 0.c3l# UH*nUSS[R[R4;v M, g7f)r?maximizeN)r MINIMIZEr)rmds r7rocreate_study..s1 A *j.*A*A>CZCZ[[s24zA`directions` must be a list of `minimize` or `maximize`, but got zT. For single-objective optimization, please use `direction` instead of `directions`.z#Using an existing study with name 'z ' instead of creating a new one.r=rKrErG)rrrr'listrrsr upperrr>create_new_studyrDuplicatedStudyErrorrrr?r NSGAIISamplerget_study_name_from_idr9) rKrErGr=r|r:r{rCdirection_objectsrLrs r7 create_studyrMsFZ/ \  :#9LMM   i * *:i3M3M[  [  *% u :KLL     OPZ|\a a  T^S]aZ> * *qwwy0IIS]""7+G ++,=J301A5((*//9J Z' YE L1  * *  ) )) LL5j\Aab 55jAH  s-8E>EA F&$F&rE)rErGcUcG[U5n[U5S:wa[SUS35eUSn[R SUS35 [ XX#S9nUc3[UR 5S:a[R"5Ul U$)a Load the existing :class:`~optuna.study.Study` that has the specified name. Example: .. testsetup:: import os if os.path.exists("example.db"): raise RuntimeError("'example.db' already exists. Please remove it.") .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", 0, 10) return x**2 study = optuna.create_study(storage="sqlite:///example.db", study_name="my_study") study.optimize(objective, n_trials=3) loaded_study = optuna.load_study(study_name="my_study", storage="sqlite:///example.db") assert len(loaded_study.trials) == len(study.trials) .. testcleanup:: os.remove("example.db") Args: study_name: Study's name. Each study has a unique name as an identifier. If :obj:`None`, checks whether the storage contains a single study, and if so loads that study. ``study_name`` is required if there are multiple studies in the storage. storage: Database URL such as ``sqlite:///example.db``. Please see also the documentation of :func:`~optuna.study.create_study` for further details. sampler: A sampler object that implements background algorithm for value suggestion. If :obj:`None` is specified, :class:`~optuna.samplers.TPESampler` is used as the default. See also :class:`~optuna.samplers`. pruner: A pruner object that decides early stopping of unpromising trials. If :obj:`None` is specified, :class:`~optuna.pruners.MedianPruner` is used as the default. See also :class:`~optuna.pruners`. Returns: A :class:`~optuna.study.Study` object. See also: :func:`optuna.load_study` is an alias of :func:`optuna.study.load_study`. rz5Could not determine the study name since the storage z8 does not contain exactly 1 study. Specify `study_name`.rz+Study name was omitted but trying to load 'z7' because that was the only study found in the storage.rE) get_all_study_namesrrrrr9r{rrJrE)r=rKrErG study_namesrs r7 load_studyrQ&sP)'2 { q GyQAA !^  9*F* * Z' YE3u//014 ..0 Lr6ct[R"U5nURU5nURU5 g)aDelete a :class:`~optuna.study.Study` object. Example: .. testsetup:: import os if os.path.exists("example.db"): raise RuntimeError("'example.db' already exists. Please remove it.") .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", -10, 10) return (x - 2) ** 2 study = optuna.create_study(study_name="example-study", storage="sqlite:///example.db") study.optimize(objective, n_trials=3) optuna.delete_study(study_name="example-study", storage="sqlite:///example.db") .. testcleanup:: os.remove("example.db") Args: study_name: Study's name. storage: Database URL such as ``sqlite:///example.db``. Please see also the documentation of :func:`~optuna.study.create_study` for further details. See also: :func:`optuna.delete_study` is an alias of :func:`optuna.study.delete_study`. N)rr>r? delete_study)r=rKrLs r7rSrSs3n""7+G--j9H "r6)from_study_name from_storage to_storage to_study_name)r;warning_stacklevelr<r=)rWc [XS9n[U=(d UUURSS9nURR UR 5R 5H+upgURRUR Xg5 M- URR 5HupgURXg5 M URSS9HnURbd[UR5[UR5:wa8[S[UR5S[UR5S35eURRUR US 9 M g) alCopy study from one storage to another. The direction(s) of the objective(s) in the study, trials, user attributes and system attributes are copied. .. note:: :func:`~optuna.copy_study` copies a study even if the optimization is working on. It means users will get a copied study that contains a trial that is not finished. Example: .. testsetup:: import os if os.path.exists("example.db"): raise RuntimeError("'example.db' already exists. Please remove it.") if os.path.exists("example_copy.db"): raise RuntimeError("'example_copy.db' already exists. Please remove it.") .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", -10, 10) return (x - 2) ** 2 study = optuna.create_study( study_name="example-study", storage="sqlite:///example.db", ) study.optimize(objective, n_trials=3) optuna.copy_study( from_study_name="example-study", from_storage="sqlite:///example.db", to_storage="sqlite:///example_copy.db", ) study = optuna.load_study( study_name=None, storage="sqlite:///example_copy.db", ) .. testcleanup:: os.remove("example.db") os.remove("example_copy.db") Args: from_study_name: Name of study. from_storage: Source database URL such as ``sqlite:///example.db``. Please see also the documentation of :func:`~optuna.study.create_study` for further details. to_storage: Destination database URL. to_study_name: Name of the created study. If omitted, ``from_study_name`` is used. Raises: :class:`~optuna.exceptions.DuplicatedStudyError`: If a study with a conflicting name already exists in the destination storage. )r=rKF)r=rKr{r:rfNrrrr)rQrMr{rArr@rrrrrrrrrr) rTrUrVrW from_studyto_studyrrbrns r7 copy_studyr]sEnMJ 3O(( H!))@@AUAUV\\^ //0B0BCO_!++113 s*4&&&6 << #H,?,?(@C DU(U&s5<<'8&9:((+H,?,?(@'AB%%  **8+=+=e*T7r6c[R"U5nUR5n/nUGHRnURUR5nUVs/sH$ofR [ R:XdM"UPM& nn[U5n[UR5S:XaSURn Sn U(a;[U5S:wa,U [R:Xa [USS9n O[USS9n OSn OSn URn Sn [UVs/sHofRcMURPM snSS9n UR![#UR$U U UR&UR(UU URU S9 5 GMU U$s snfs snf) azGet all history of studies stored in a specified storage. Example: .. testsetup:: import os if os.path.exists("example.db"): raise RuntimeError("'example.db' already exists. Please remove it.") .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", -10, 10) return (x - 2) ** 2 study = optuna.create_study(study_name="example-study", storage="sqlite:///example.db") study.optimize(objective, n_trials=3) study_summaries = optuna.study.get_all_study_summaries(storage="sqlite:///example.db") assert len(study_summaries) == 1 study_summary = study_summaries[0] assert study_summary.study_name == "example-study" .. testcleanup:: os.remove("example.db") Args: storage: Database URL such as ``sqlite:///example.db``. Please see also the documentation of :func:`~optuna.study.create_study` for further details. include_best_trial: Include the best trials if exist. It potentially increases the number of queries and may take longer to fetch summaries depending on the storage. Returns: List of study history summarized as :class:`~optuna.study.StudySummary` objects. See also: :func:`optuna.get_all_study_summaries` is an alias of :func:`optuna.study.get_all_study_summaries`. rNrc6[[UR5$rWrrs r7r)get_all_study_summaries..rT%QRQXQXEYr6rc6[[UR5$rWrrs r7rr`trar6)default) r=r|r\rrlrr4rLr{)rr>get_all_studiesrr@rSr%rrr{r|r rrrr4rr!r=rrl) rKinclude_best_trialfrozen_studiesstudy_summariess all_trialsrcompleted_trialsrr|r{r\r4s r7get_all_study_summariesrk-skl""7+G,,.NO ++AKK8 '1Tz!WW @S@S5SAzTz? q||  ! IJ!c*:&;q&@ 7 77!$%5;Y!ZJ!$%5;Y!ZJ! IJJ'1 Rz!5E5E Q  z R\`   <<#%<<^^!-%  3N KU( Ss!F3F F F c[R"U5nUR5Vs/sHoRPM nnU$s snf)aGGet all study names stored in a specified storage. Example: .. testsetup:: import os if os.path.exists("example.db"): raise RuntimeError("'example.db' already exists. Please remove it.") .. testcode:: import optuna def objective(trial): x = trial.suggest_float("x", -10, 10) return (x - 2) ** 2 study = optuna.create_study(study_name="example-study", storage="sqlite:///example.db") study.optimize(objective, n_trials=3) study_names = optuna.study.get_all_study_names(storage="sqlite:///example.db") assert len(study_names) == 1 assert study_names[0] == "example-study" .. testcleanup:: os.remove("example.db") Args: storage: Database URL such as ``sqlite:///example.db``. Please see also the documentation of :func:`~optuna.study.create_study` for further details. Returns: List of all study names in the storage. See also: :func:`optuna.get_all_study_names` is an alias of :func:`optuna.study.get_all_study_names`. )rr>rdr=)rKrrPs r7rOrOsD`""7+G181H1H1JK1J##1JKK LsA)rKz!str | storages.BaseStorage | NonerEr)rGr*r= str | Noner|zstr | StudyDirection | Noner:r,r{z%Sequence[str | StudyDirection] | Noner+r9) r=rmrKr(rEr)rGr*r+r9)r=r'rKr(r+r,) rTr'rUr(rVr(rWrmr+r,)T)rKr(rer,r+zlist[StudySummary])rKr(r+r7)O __future__rcollections.abcrrrrrrQnumbersr threadingtypingr r r r numpyrrrrrrroptuna._convert_positional_argsroptuna._deprecatedroptuna._experimentalroptuna._importsroptuna._typingroptuna._warningsroptuna.distributionsrroptuna.storages._heartbeatr&optuna.study._constrained_optimizationrroptuna.study._multi_objectiveroptuna.study._optimizeroptuna.study._study_directionr optuna.study._study_summaryr!optuna.study._tellr"r# optuna.trialr$r%roptuna.study._dataframer&r'r(rr1r get_loggerr0rlocalr*r9rMrQrSr]rkrOr/r6r7rs"$%$#$   C.2'+(N1;CGB,8401%#2 3 *("gYeXe_.D(EEF1   X &77 H.H.V"# 26-1(,!-1 8<I .I+I & I  I + II6I I IX#  .2(, NN(N+ N & N  N Nb# 1#1#(1# 1#1#h#   !% bUbU-bU+ bU  bU  bU bULEIa 'a=AaaH3r6