optuna API Reference
Full documentation for optuna (4.9.0)
optuna.Study
Python Library Documentation: class Study in module optuna.study.study
class Study(builtins.object)
| Study(study_name: 'str', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'None'
|
| A 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.
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, study_name: 'str', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| add_trial(self, trial: 'FrozenTrial') -> 'None'
| Add trial to study.
|
| The trial is validated before being added.
|
| Example:
|
| .. testcode::
|
| import optuna
| from optuna.distributions import FloatDistribution
|
|
| def objective(trial):
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| assert len(study.trials) == 0
|
| trial = optuna.trial.create_trial(
| params={"x": 2.0},
| distributions={"x": FloatDistribution(0, 10)},
| value=4.0,
| )
|
| study.add_trial(trial)
| assert len(study.trials) == 1
|
| study.optimize(objective, n_trials=3)
| assert len(study.trials) == 4
|
| other_study = optuna.create_study()
|
| for trial in study.trials:
| other_study.add_trial(trial)
| 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::
|
| This method should in general be used to add already evaluated trials
| (``trial.state.is_finished() == True``). To queue trials for evaluation,
| please refer to :func:`~optuna.study.Study.enqueue_trial`.
|
| .. seealso::
|
| See :func:`~optuna.trial.create_trial` for how to create trials.
|
| .. seealso::
| Please refer to :ref:`add_trial_tutorial` for the tutorial of specifying
| hyperparameters with the evaluated value manually.
|
| Args:
| trial: Trial to add.
|
| add_trials(self, trials: 'Iterable[FrozenTrial]') -> 'None'
| Add 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.
|
| ask(self, fixed_distributions: 'dict[str, BaseDistribution] | None' = None) -> 'Trial'
| Create 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`.
|
| enqueue_trial(self, params: 'dict[str, Any]', user_attrs: 'dict[str, Any] | None' = None, skip_if_exists: 'bool' = False) -> 'None'
| Enqueue a trial with given parameter values.
|
| You can fix the next sampling parameters which will be evaluated in your
| objective function.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| study.enqueue_trial({"x": 5})
| study.enqueue_trial({"x": 0}, user_attrs={"memo": "optimal"})
| study.optimize(objective, n_trials=2)
|
| assert study.trials[0].params == {"x": 5}
| assert study.trials[1].params == {"x": 0}
| assert study.trials[1].user_attrs == {"memo": "optimal"}
|
| Args:
| params:
| Parameter values to pass your objective function.
| user_attrs:
| A dictionary of user-specific attributes other than ``params``.
| skip_if_exists:
| When :obj:`True`, prevents duplicate trials from being enqueued again.
|
| .. note::
| This method might produce duplicated trials if called simultaneously
| by multiple processes at the same time with same ``params`` dict.
|
| .. seealso::
|
| Please refer to :ref:`enqueue_trial_tutorial` for the tutorial of specifying
| hyperparameters manually.
|
| get_trials(self, deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Return 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.
|
| optimize(self, func: 'ObjectiveFuncType', n_trials: 'int | None' = None, timeout: 'float | None' = None, n_jobs: 'int' = 1, catch: 'Iterable[type[Exception]] | type[Exception]' = (), callbacks: 'Iterable[Callable[[Study, FrozenTrial], None]] | None' = None, gc_after_trial: 'bool' = False, show_progress_bar: 'bool' = False) -> 'None'
| Optimize 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 <https://wiki.python.org/moin/GlobalInterpreterLock>`__.
| It is recommended to use :ref:`process-based parallelization<distributed>`
| 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.
|
| set_metric_names(self, metric_names: 'list[str]') -> 'None'
| Set 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.
|
| .. note::
| Added in v3.2.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.2.0.
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| Set a system attribute to the study.
|
| Note that Optuna internally uses this method to save system messages. Please use
| :func:`~optuna.study.Study.set_user_attr` to set users' attributes.
|
| Args:
| key: A key string of the attribute.
| value: A value of the attribute. The value should be JSON serializable.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
| Set a user attribute to the study.
|
| .. seealso::
|
| See :attr:`~optuna.study.Study.user_attrs` for related attribute.
|
| .. seealso::
|
| See the recipe on :ref:`attributes`.
|
| 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"],
| }
|
| Args:
| key: A key string of the attribute.
| value: A value of the attribute. The value should be JSON serializable.
|
| stop(self) -> 'None'
| Exit from the current optimization loop after the running trials finish.
|
| This method lets the running :meth:`~optuna.study.Study.optimize` method return
| immediately after all trials which the :meth:`~optuna.study.Study.optimize` method
| spawned finishes.
| This method does not affect any behaviors of parallel or successive study processes.
| This method only works when it is called inside an objective function or callback.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| if trial.number == 4:
| trial.study.stop()
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=10)
| assert len(study.trials) == 5
|
| tell(self, trial: 'Trial | int', values: 'float | Sequence[float] | None' = None, state: 'TrialState | None' = None, skip_if_finished: 'bool' = False) -> 'FrozenTrial'
| 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.
|
| trials_dataframe(self, attrs: 'tuple[str, ...]' = ('number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state'), multi_index: 'bool' = False) -> "'pd.DataFrame'"
| Export trials as a pandas DataFrame_.
|
| The DataFrame_ provides various features to analyze studies. It is also useful to draw a
| histogram of objective values and to export trials as a CSV file.
| If there are no trials, an empty DataFrame_ is returned.
|
| Example:
|
| .. testcode::
|
| import optuna
| import pandas
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| return x**2
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=3)
|
| # Create a dataframe from the study.
| df = study.trials_dataframe()
| assert isinstance(df, pandas.DataFrame)
| assert df.shape[0] == 3 # n_trials.
|
| Args:
| attrs:
| Specifies field names of :class:`~optuna.trial.FrozenTrial` to include them to a
| DataFrame of trials.
| multi_index:
| Specifies whether the returned DataFrame_ employs MultiIndex_ or not. Columns that
| are hierarchical by nature such as ``(params, x)`` will be flattened to
| ``params_x`` when set to :obj:`False`.
|
| Returns:
| A pandas DataFrame_ of trials in the :class:`~optuna.study.Study`.
|
| .. _DataFrame: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
| .. _MultiIndex: https://pandas.pydata.org/pandas-docs/stable/advanced.html
|
| Note:
| If ``value`` is in ``attrs`` during multi-objective optimization, it is implicitly
| replaced with ``values``.
|
| Note:
| If :meth:`~optuna.study.Study.set_metric_names` is called, the ``value`` or ``values``
| is implicitly replaced with the dictionary with the objective name as key and the
| objective value as value.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| best_params
| Return 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_trial
| Return 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.
|
| .. note::
| In constrained optimization, the best trial is selected from trials that
| satisfy all constraints. A trial is considered feasible when all of its
| constraint values are less than or equal to 0.0.
|
| Returns:
| A :class:`~optuna.trial.FrozenTrial` object of the best trial.
|
| Raises:
| RuntimeError:
| If the study is multi-objective.
| ValueError:
| If no trials are completed yet, or if no feasible trials exist
| in a constrained optimization.
|
| .. seealso::
| The :ref:`reuse_best_trial` tutorial provides a detailed example of how to use this
| method.
|
| best_trials
| Return 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.
|
| .. note::
| In constrained optimization, the best trials are selected from trials that
| satisfy all constraints. A trial is considered feasible when all of its
| constraint values are less than or equal to 0.0.
|
| .. note::
| When optimizing many objectives, a large fraction of trials may become non-dominated
| in general due to the curse of dimensionality in the objective space. If this makes
| post-hoc selection difficult, consider modeling some objectives as constraints.
| Constraints can be passed via the `constraints_func` argument at the sampler
| initialization.
|
| Returns:
| A list of :class:`~optuna.trial.FrozenTrial` objects. If no trials are
| completed or if no feasible trials exist in a constrained optimization,
| an empty list is returned.
|
| best_value
| Return 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.
|
| direction
| Return 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.
|
| directions
| Return the directions of the study.
|
| Returns:
| A list of :class:`~optuna.study.StudyDirection` objects.
|
| metric_names
| Return 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.
|
| system_attrs
| Return system attributes.
|
| Returns:
| A dictionary containing all system attributes.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| trials
| 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.
|
| user_attrs
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
optuna.TYPE_CHECKING
Python Library Documentation: bool object class bool(int) | bool(x) -> bool | | Returns True when the argument x is true, False otherwise. | The builtins True and False are the only two instances of the class bool. | The class bool is a subclass of the class int, and cannot be subclassed. | | Method resolution order: | bool | int | object | | Methods defined here: | | __and__(self, value, /) | Return self&value. | | __invert__(self, /) | ~self | | __or__(self, value, /) | Return self|value. | | __rand__(self, value, /) | Return value&self. | | __repr__(self, /) | Return repr(self). | | __ror__(self, value, /) | Return value|self. | | __rxor__(self, value, /) | Return value^self. | | __xor__(self, value, /) | Return self^value. | | ---------------------------------------------------------------------- | Static methods defined here: | | __new__(*args, **kwargs) | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Methods inherited from int: | | __abs__(self, /) | abs(self) | | __add__(self, value, /) | Return self+value. | | __bool__(self, /) | True if self else False | | __ceil__(...) | Ceiling of an Integral returns itself. | | __divmod__(self, value, /) | Return divmod(self, value). | | __eq__(self, value, /) | Return self==value. | | __float__(self, /) | float(self) | | __floor__(...) | Flooring an Integral returns itself. | | __floordiv__(self, value, /) | Return self//value. | | __format__(self, format_spec, /) | Convert to a string according to format_spec. | | __ge__(self, value, /) | Return self>=value. | | __getattribute__(self, name, /) | Return getattr(self, name). | | __getnewargs__(self, /) | | __gt__(self, value, /) | Return self>value. | | __hash__(self, /) | Return hash(self). | | __index__(self, /) | Return self converted to an integer, if self is suitable for use as an index into a list. | | __int__(self, /) | int(self) | | __le__(self, value, /) | Return self<=value. | | __lshift__(self, value, /) | Return self<<value. | | __lt__(self, value, /) | Return self<value. | | __mod__(self, value, /) | Return self%value. | | __mul__(self, value, /) | Return self*value. | | __ne__(self, value, /) | Return self!=value. | | __neg__(self, /) | -self | | __pos__(self, /) | +self | | __pow__(self, value, mod=None, /) | Return pow(self, value, mod). | | __radd__(self, value, /) | Return value+self. | | __rdivmod__(self, value, /) | Return divmod(value, self). | | __rfloordiv__(self, value, /) | Return value//self. | | __rlshift__(self, value, /) | Return value<<self. | | __rmod__(self, value, /) | Return value%self. | | __rmul__(self, value, /) | Return value*self. | | __round__(...) | Rounding an Integral returns itself. | | Rounding with an ndigits argument also returns an integer. | | __rpow__(self, value, mod=None, /) | Return pow(value, self, mod). | | __rrshift__(self, value, /) | Return value>>self. | | __rshift__(self, value, /) | Return self>>value. | | __rsub__(self, value, /) | Return value-self. | | __rtruediv__(self, value, /) | Return value/self. | | __sizeof__(self, /) | Returns size in memory, in bytes. | | __sub__(self, value, /) | Return self-value. | | __truediv__(self, value, /) | Return self/value. | | __trunc__(...) | Truncating an Integral returns itself. | | as_integer_ratio(self, /) | Return a pair of integers, whose ratio is equal to the original int. | | The ratio is in lowest terms and has a positive denominator. | | >>> (10).as_integer_ratio() | (10, 1) | >>> (-10).as_integer_ratio() | (-10, 1) | >>> (0).as_integer_ratio() | (0, 1) | | bit_count(self, /) | Number of ones in the binary representation of the absolute value of self. | | Also known as the population count. | | >>> bin(13) | '0b1101' | >>> (13).bit_count() | 3 | | bit_length(self, /) | Number of bits necessary to represent self in binary. | | >>> bin(37) | '0b100101' | >>> (37).bit_length() | 6 | | conjugate(...) | Returns self, the complex conjugate of any int. | | is_integer(self, /) | Returns True. Exists for duck type compatibility with float.is_integer. | | to_bytes(self, /, length=1, byteorder='big', *, signed=False) | Return an array of bytes representing an integer. | | length | Length of bytes object to use. An OverflowError is raised if the | integer is not representable with the given number of bytes. Default | is length 1. | byteorder | The byte order used to represent the integer. If byteorder is 'big', | the most significant byte is at the beginning of the byte array. If | byteorder is 'little', the most significant byte is at the end of the | byte array. To request the native byte order of the host system, use | `sys.byteorder' as the byte order value. Default is to use 'big'. | signed | Determines whether two's complement is used to represent the integer. | If signed is False and a negative integer is given, an OverflowError | is raised. | | ---------------------------------------------------------------------- | Class methods inherited from int: | | from_bytes(bytes, byteorder='big', *, signed=False) | Return the integer represented by the given array of bytes. | | bytes | Holds the array of bytes to convert. The argument must either | support the buffer protocol or be an iterable object producing bytes. | Bytes and bytearray are examples of built-in objects that support the | buffer protocol. | byteorder | The byte order used to represent the integer. If byteorder is 'big', | the most significant byte is at the beginning of the byte array. If | byteorder is 'little', the most significant byte is at the end of the | byte array. To request the native byte order of the host system, use | `sys.byteorder' as the byte order value. Default is to use 'big'. | signed | Indicates whether two's complement is used to represent the integer. | | ---------------------------------------------------------------------- | Data descriptors inherited from int: | | denominator | the denominator of a rational number in lowest terms | | imag | the imaginary part of a complex number | | numerator | the numerator of a rational number in lowest terms | | real | the real part of a complex number
optuna.Trial
Python Library Documentation: class Trial in module optuna.trial._trial
class Trial(optuna.trial._base.BaseTrial)
| Trial(study: 'Study', trial_id: 'int') -> 'None'
|
| 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.
|
| Method resolution order:
| Trial
| optuna.trial._base.BaseTrial
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, study: 'Study', trial_id: 'int') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| 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.
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| Set system attributes to the trial.
|
| Note that Optuna internally uses this method to save system messages such as failure
| reason of trials. Please use :func:`~optuna.trial.Trial.set_user_attr` to set users'
| attributes.
|
| Args:
| key:
| A key string of the attribute.
| value:
| A value of the attribute. The value should be JSON serializable.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
| Set user attributes to the trial.
|
| The user attributes in the trial can be access via :func:`optuna.trial.Trial.user_attrs`.
|
| .. seealso::
|
| See the recipe on :ref:`attributes`.
|
| Example:
|
| Save fixed hyperparameters of neural network training.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.neural_network import MLPClassifier
|
| import optuna
|
| X, y = load_iris(return_X_y=True)
| X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)
|
|
| def objective(trial):
| trial.set_user_attr("BATCHSIZE", 128)
| momentum = trial.suggest_float("momentum", 0, 1.0)
| clf = MLPClassifier(
| hidden_layer_sizes=(100, 50),
| batch_size=trial.user_attrs["BATCHSIZE"],
| momentum=momentum,
| solver="sgd",
| random_state=0,
| )
| clf.fit(X_train, y_train)
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
| assert "BATCHSIZE" in study.best_trial.user_attrs.keys()
| assert study.best_trial.user_attrs["BATCHSIZE"] == 128
|
|
| Args:
| key:
| A key string of the attribute.
| value:
| A value of the attribute. The value should be JSON serializable.
|
| should_prune(self) -> 'bool'
| Suggest whether the trial should be pruned or not.
|
| The suggestion is made by a pruning algorithm associated with the trial and is based on
| previously reported values. The algorithm can be specified when constructing a
| :class:`~optuna.study.Study`.
|
| .. note::
| If no values have been reported, the algorithm cannot make meaningful suggestions.
| Similarly, if this method is called multiple times with the exact same set of reported
| values, the suggestions will be the same.
|
| .. seealso::
| Please refer to the example code in :func:`optuna.trial.Trial.report`.
|
| .. note::
| :func:`~optuna.trial.Trial.should_prune` does not support multi-objective
| optimization.
|
| Returns:
| A boolean value. If :obj:`True`, the trial should be pruned according to the
| configured pruning algorithm. Otherwise, the trial should continue.
|
| suggest_categorical(self, name: 'str', choices: 'Sequence[CategoricalChoiceType]') -> 'CategoricalChoiceType'
| Suggest a value for the categorical parameter.
|
| The value is sampled from ``choices``.
|
| Example:
|
| Suggest a kernel function of `SVC <https://scikit-learn.org/stable/modules/generated/
| sklearn.svm.SVC.html>`__.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.svm import SVC
|
| 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):
| kernel = trial.suggest_categorical("kernel", ["linear", "poly", "rbf"])
| clf = SVC(kernel=kernel, gamma="scale", random_state=0)
| clf.fit(X_train, y_train)
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
|
| Args:
| name:
| A parameter name.
| choices:
| Parameter value candidates.
|
| .. seealso::
| :class:`~optuna.distributions.CategoricalDistribution`.
|
| Returns:
| A suggested value.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_discrete_uniform(self, name: 'str', low: 'float', high: 'float', q: 'float') -> 'float'
| Suggest a value for the discrete parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high}]`,
| and the step of discretization is :math:`q`. More specifically,
| this method returns one of the values in the sequence
| :math:`\mathsf{low}, \mathsf{low} + q, \mathsf{low} + 2 q, \dots,
| \mathsf{low} + k q \le \mathsf{high}`,
| where :math:`k` denotes an integer. Note that :math:`high` may be changed due to round-off
| errors if :math:`q` is not an integer. Please check warning messages to find the changed
| values.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| q:
| A step of discretization.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., step=...) instead.
|
| suggest_float(self, name: 'str', low: 'float', high: 'float', *, step: 'float | None' = None, log: 'bool' = False) -> 'float'
| Suggest a value for the floating point parameter.
|
| Example:
|
| Suggest a momentum, learning rate and scaling factor of learning rate
| for neural network training.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.neural_network import MLPClassifier
|
| import optuna
|
| X, y = load_iris(return_X_y=True)
| X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)
|
|
| def objective(trial):
| momentum = trial.suggest_float("momentum", 0.0, 1.0)
| learning_rate_init = trial.suggest_float(
| "learning_rate_init", 1e-5, 1e-3, log=True
| )
| power_t = trial.suggest_float("power_t", 0.2, 0.8, step=0.1)
| clf = MLPClassifier(
| hidden_layer_sizes=(100, 50),
| momentum=momentum,
| learning_rate_init=learning_rate_init,
| solver="sgd",
| random_state=0,
| power_t=power_t,
| )
| clf.fit(X_train, y_train)
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than 0.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A step of discretization.
|
| .. note::
| The ``step`` and ``log`` arguments cannot be used at the same time. To set
| the ``step`` argument to a float number, set the ``log`` argument to
| :obj:`False`.
| log:
| A flag to sample the value from the log domain or not.
| If ``log`` is true, the value is sampled from the range in the log domain.
| Otherwise, the value is sampled from the range in the linear domain.
|
| .. note::
| The ``step`` and ``log`` arguments cannot be used at the same time. To set
| the ``log`` argument to :obj:`True`, set the ``step`` argument to :obj:`None`.
|
| Returns:
| A suggested float value.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_int(self, name: 'str', low: 'int', high: 'int', *, step: 'int' = 1, log: 'bool' = False) -> 'int'
| Suggest a value for the integer parameter.
|
| The value is sampled from the integers in :math:`[\mathsf{low}, \mathsf{high}]`.
|
| Example:
|
| Suggest the number of trees in `RandomForestClassifier <https://scikit-learn.org/
| stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html>`__.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.ensemble import RandomForestClassifier
| 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):
| n_estimators = trial.suggest_int("n_estimators", 50, 400)
| clf = RandomForestClassifier(n_estimators=n_estimators, random_state=0)
| clf.fit(X_train, y_train)
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than 0.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A step of discretization.
|
| .. note::
| Note that :math:`\mathsf{high}` is modified if the range is not divisible by
| :math:`\mathsf{step}`. Please check the warning messages to find the changed
| values.
|
| .. note::
| The method returns one of the values in the sequence
| :math:`\mathsf{low}, \mathsf{low} + \mathsf{step}, \mathsf{low} + 2 *
| \mathsf{step}, \dots, \mathsf{low} + k * \mathsf{step} \le
| \mathsf{high}`, where :math:`k` denotes an integer.
|
| .. note::
| The ``step != 1`` and ``log`` arguments cannot be used at the same time.
| To set the ``step`` argument :math:`\mathsf{step} \ge 2`, set the
| ``log`` argument to :obj:`False`.
| log:
| A flag to sample the value from the log domain or not.
|
| .. note::
| If ``log`` is true, at first, the range of suggested values is divided into
| grid points of width 1. The range of suggested values is then converted to
| a log domain, from which a value is sampled. The uniformly sampled
| value is re-converted to the original domain and rounded to the nearest grid
| point that we just split, and the suggested value is determined.
| For example, if `low = 2` and `high = 8`, then the range of suggested values is
| `[2, 3, 4, 5, 6, 7, 8]` and lower values tend to be more sampled than higher
| values.
|
| .. note::
| The ``step != 1`` and ``log`` arguments cannot be used at the same time.
| To set the ``log`` argument to :obj:`True`, set the ``step`` argument to 1.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_loguniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| Suggest a value for the continuous parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high})`
| in the log domain. When :math:`\mathsf{low} = \mathsf{high}`, the value of
| :math:`\mathsf{low}` will be returned.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., log=True) instead.
|
| suggest_uniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| Suggest a value for the continuous parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high})`
| in the linear domain. When :math:`\mathsf{low} = \mathsf{high}`, the value of
| :math:`\mathsf{low}` will be returned.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float instead.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| datetime_start
| Return start datetime.
|
| Returns:
| Datetime where the :class:`~optuna.trial.Trial` started.
|
| distributions
| Return distributions of parameters to be optimized.
|
| Returns:
| A dictionary containing all distributions.
|
| number
| Return trial's number which is consecutive and unique in a study.
|
| Returns:
| A trial number.
|
| params
| Return parameters to be optimized.
|
| Returns:
| A dictionary containing all parameters.
|
| relative_params
|
| system_attrs
| Return system attributes.
|
| Returns:
| A dictionary containing all system attributes.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| user_attrs
| Return user attributes.
|
| Returns:
| A dictionary containing all user attributes.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.trial._base.BaseTrial:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
optuna.TrialPruned
Python Library Documentation: class TrialPruned in module optuna.exceptions
class TrialPruned(OptunaError)
| Exception for pruned trials.
|
| This error tells a trainer that the current :class:`~optuna.trial.Trial` was pruned. It is
| supposed to be raised after :func:`optuna.trial.Trial.should_prune` as shown in the following
| example.
|
| See also:
| :class:`optuna.TrialPruned` is an alias of :class:`optuna.exceptions.TrialPruned`.
|
| Example:
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, 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=20)
|
| Method resolution order:
| TrialPruned
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
optuna.artifacts
Python Library Documentation: package optuna.artifacts in optuna
NAME
optuna.artifacts
PACKAGE CONTENTS
_backoff
_boto3
_download
_filesystem
_gcs
_list_artifact_meta
_protocol
_upload
exceptions
CLASSES
builtins.object
optuna.artifacts._backoff.Backoff
optuna.artifacts._boto3.Boto3ArtifactStore
optuna.artifacts._filesystem.FileSystemArtifactStore
optuna.artifacts._gcs.GCSArtifactStore
optuna.artifacts._upload.ArtifactMeta
class ArtifactMeta(builtins.object)
| ArtifactMeta(artifact_id: 'str', filename: 'str', mimetype: 'str', encoding: 'str | None') -> None
|
| Meta information for an artifact.
|
| .. note::
| All the artifact meta linked to a study or trial can be listed by
| :func:`~optuna.artifacts.get_all_artifact_meta`.
| The artifact meta can be used for :func:`~optuna.artifacts.download_artifact`.
|
| Args:
| artifact_id:
| The identifier of the artifact.
| filename:
| The artifact file name used for the upload.
| mimetype:
| A MIME type of the artifact.
| If not specified, the MIME type is guessed from the file extension.
| encoding:
| An encoding of the artifact, which is suitable for use as a Content-Encoding header,
| e.g., gzip. If not specified, the encoding is guessed from the file extension.
|
| Methods defined here:
|
| __eq__(self, other)
| Return self==value.
|
| __init__(self, artifact_id: 'str', filename: 'str', mimetype: 'str', encoding: 'str | None') -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self)
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'artifact_id': 'str', 'encoding': 'str | None', 'fi...
|
| __dataclass_fields__ = {'artifact_id': Field(name='artifact_id',type='...
|
| __dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,or...
|
| __hash__ = None
|
| __match_args__ = ('artifact_id', 'filename', 'mimetype', 'encoding')
class Backoff(builtins.object)
| Backoff(backend: 'ArtifactStore', *, max_retries: 'int' = 10, multiplier: 'float' = 2, min_delay: 'float' = 0.1, max_delay: 'float' = 30) -> 'None'
|
| An artifact store's middleware for exponential backoff.
|
| Example:
| .. code-block:: python
|
| import optuna
| from optuna.artifacts import upload_artifact
| from optuna.artifacts import Boto3ArtifactStore
| from optuna.artifacts import Backoff
|
|
| artifact_store = Backoff(Boto3ArtifactStore("my-bucket"))
|
|
| def objective(trial: optuna.Trial) -> float:
| ... = trial.suggest_float("x", -10, 10)
| file_path = generate_example(...)
| upload_artifact(
| artifact_store=artifact_store,
| file_path=file_path,
| study_or_trial=trial,
| )
| return ...
|
| Methods defined here:
|
| __init__(self, backend: 'ArtifactStore', *, max_retries: 'int' = 10, multiplier: 'float' = 2, min_delay: 'float' = 0.1, max_delay: 'float' = 30) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| open_reader(self, artifact_id: 'str') -> 'BinaryIO'
|
| remove(self, artifact_id: 'str') -> 'None'
|
| write(self, artifact_id: 'str', content_body: 'BinaryIO') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Boto3ArtifactStore(builtins.object)
| Boto3ArtifactStore(bucket_name: 'str', client: 'S3Client | None' = None, *, avoid_buf_copy: 'bool' = False) -> 'None'
|
| An artifact backend for Boto3.
|
| Args:
| bucket_name:
| The name of the bucket to store artifacts.
|
| client:
| A Boto3 client to use for storage operations. If not specified, a new client will
| be created.
|
| avoid_buf_copy:
| If True, skip procedure to copy the content of the source file object to a buffer
| before uploading it to S3 ins. This is default to False because using
| ``upload_fileobj()`` method of Boto3 client might close the source file object.
|
| Example:
| .. code-block:: python
|
| import optuna
| from optuna.artifacts import upload_artifact
| from optuna.artifacts import Boto3ArtifactStore
|
|
| artifact_store = Boto3ArtifactStore("my-bucket")
|
|
| def objective(trial: optuna.Trial) -> float:
| ... = trial.suggest_float("x", -10, 10)
| file_path = generate_example(...)
| upload_artifact(
| artifact_store=artifact_store,
| file_path=file_path,
| study_or_trial=trial,
| )
| return ...
|
| Methods defined here:
|
| __init__(self, bucket_name: 'str', client: 'S3Client | None' = None, *, avoid_buf_copy: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| open_reader(self, artifact_id: 'str') -> 'BinaryIO'
|
| remove(self, artifact_id: 'str') -> 'None'
|
| write(self, artifact_id: 'str', content_body: 'BinaryIO') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class FileSystemArtifactStore(builtins.object)
| FileSystemArtifactStore(base_path: 'str | Path') -> 'None'
|
| An artifact store for file systems.
|
| Args:
| base_path:
| The base path to a directory to store artifacts.
|
| Example:
| .. code-block:: python
|
| import os
|
| import optuna
| from optuna.artifacts import FileSystemArtifactStore
| from optuna.artifacts import upload_artifact
|
|
| base_path = "./artifacts"
| os.makedirs(base_path, exist_ok=True)
| artifact_store = FileSystemArtifactStore(base_path=base_path)
|
|
| def objective(trial: optuna.Trial) -> float:
| ... = trial.suggest_float("x", -10, 10)
| file_path = generate_example(...)
| upload_artifact(
| artifact_store=artifact_store,
| file_path=file_path,
| study_or_trial=trial,
| )
| return ...
|
| Methods defined here:
|
| __init__(self, base_path: 'str | Path') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| open_reader(self, artifact_id: 'str') -> 'BinaryIO'
|
| remove(self, artifact_id: 'str') -> 'None'
|
| write(self, artifact_id: 'str', content_body: 'BinaryIO') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class GCSArtifactStore(builtins.object)
| GCSArtifactStore(bucket_name: 'str', client: 'google.cloud.storage.Client | None' = None) -> 'None'
|
| An artifact backend for Google Cloud Storage (GCS).
|
| Args:
| bucket_name:
| The name of the bucket to store artifacts.
|
| client:
| A google-cloud-storage ``Client`` to use for storage operations. If not specified, a
| new client will be created with default settings.
|
| Example:
| .. code-block:: python
|
| import optuna
| from optuna.artifacts import GCSArtifactStore, upload_artifact
|
|
| artifact_backend = GCSArtifactStore("my-bucket")
|
|
| def objective(trial: optuna.Trial) -> float:
| ... = trial.suggest_float("x", -10, 10)
| file_path = generate_example(...)
| upload_artifact(
| artifact_store=artifact_store,
| file_path=file_path,
| study_or_trial=trial,
| )
| return ...
|
| Before running this code, you will have to install ``gcloud`` and run
|
| .. code-block:: bash
|
| gcloud auth application-default login
|
| so that the Cloud Storage library can automatically find the credential.
|
| .. note::
| Added in v3.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.4.0.
|
| Methods defined here:
|
| __init__(self, bucket_name: 'str', client: 'google.cloud.storage.Client | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| open_reader(self, artifact_id: 'str') -> "'BinaryIO'"
|
| remove(self, artifact_id: 'str') -> 'None'
|
| write(self, artifact_id: 'str', content_body: "'BinaryIO'") -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
download_artifact(*, artifact_store: 'ArtifactStore', file_path: 'str', artifact_id: 'str') -> 'None'
Download an artifact from the artifact store.
Args:
artifact_store:
An artifact store.
file_path:
A path to save the downloaded artifact.
artifact_id:
The identifier of the artifact to download.
get_all_artifact_meta(study_or_trial: 'Trial | FrozenTrial | Study', *, storage: 'BaseStorage | None' = None) -> 'list[ArtifactMeta]'
List the associated artifact information of the provided trial or study.
Args:
study_or_trial:
A :class:`~optuna.trial.Trial` object, a :class:`~optuna.trial.FrozenTrial`, or
a :class:`~optuna.study.Study` object.
storage:
A storage object. This argument is required only if ``study_or_trial`` is
:class:`~optuna.trial.FrozenTrial`.
Example:
An example where this function is useful:
.. code::
import os
import optuna
# Get the storage that contains the study of interest.
storage = optuna.storages.get_storage(storage=...)
# Instantiate the artifact store used for the study.
# Optuna does not provide the API that stores the used artifact store information, so
# please manage the information in the user side.
artifact_store = ...
# Load study that contains the artifacts of interest.
study = optuna.load_study(study_name=..., storage=storage)
# Fetch the best trial.
best_trial = study.best_trial
# Fetch all the artifact meta connected to the best trial.
artifact_metas = optuna.artifacts.get_all_artifact_meta(best_trial, storage=storage)
download_dir_path = "./best_trial_artifacts/"
os.makedirs(download_dir_path, exist_ok=True)
for artifact_meta in artifact_metas:
download_file_path = os.path.join(download_dir_path, artifact_meta.filename)
# Download the artifacts to ``download_file_path``.
optuna.artifacts.download_artifact(
artifact_store=artifact_store,
artifact_id=artifact_meta.artifact_id,
file_path=download_file_path,
)
Returns:
The list of artifact meta in the trial or study.
Each artifact meta includes ``artifact_id``, ``filename``, ``mimetype``, and ``encoding``.
Note that if :class:`~optuna.study.Study` is provided, we return the information of the
artifacts uploaded to ``study``, but not to all the trials in the study.
upload_artifact(*, artifact_store: 'ArtifactStore', file_path: 'str', study_or_trial: 'Trial | FrozenTrial | Study', storage: 'BaseStorage | None' = None, mimetype: 'str | None' = None, encoding: 'str | None' = None) -> 'str'
Upload an artifact to the artifact store.
Args:
artifact_store:
An artifact store.
file_path:
A path to the file to be uploaded.
study_or_trial:
A :class:`~optuna.trial.Trial` object, a :class:`~optuna.trial.FrozenTrial`, or
a :class:`~optuna.study.Study` object.
storage:
A storage object. This argument is required only if ``study_or_trial`` is
:class:`~optuna.trial.FrozenTrial`.
mimetype:
A MIME type of the artifact. If not specified, the MIME type is guessed from the file
extension.
encoding:
An encoding of the artifact, which is suitable for use as a ``Content-Encoding``
header (e.g. gzip). If not specified, the encoding is guessed from the file extension.
Returns:
An artifact ID.
DATA
__all__ = ['ArtifactMeta', 'FileSystemArtifactStore', 'Boto3ArtifactSt...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\artifacts\__init__.py
optuna.copy_study
Python Library Documentation: function copy_study in module optuna.study.study
copy_study(*, from_study_name: 'str', from_storage: 'str | storages.BaseStorage', to_storage: 'str | storages.BaseStorage', to_study_name: 'str | None' = None) -> 'None'
Copy 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.
optuna.create_study
Python Library Documentation: function create_study in module optuna.study.study
create_study(*, storage: 'str | storages.BaseStorage | None' = None, sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None, study_name: 'str | None' = None, direction: 'str | StudyDirection | None' = None, load_if_exists: 'bool' = False, directions: 'Sequence[str | StudyDirection] | None' = None) -> 'Study'
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.
optuna.create_trial
Python Library Documentation: function create_trial in module optuna.trial._frozen
create_trial(*, state: 'TrialState' = <TrialState.COMPLETE: 1>, value: 'float | None' = None, values: 'Sequence[float] | None' = None, params: 'dict[str, Any] | None' = None, distributions: 'dict[str, BaseDistribution] | None' = None, user_attrs: 'dict[str, Any] | None' = None, system_attrs: 'dict[str, Any] | None' = None, intermediate_values: 'dict[int, float] | None' = None) -> 'FrozenTrial'
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.
optuna.delete_study
Python Library Documentation: function delete_study in module optuna.study.study
delete_study(*, study_name: 'str', storage: 'str | storages.BaseStorage') -> 'None'
Delete 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`.
optuna.distributions
Python Library Documentation: module optuna.distributions in optuna
NAME
optuna.distributions
CLASSES
abc.ABC(builtins.object)
BaseDistribution
CategoricalDistribution
FloatDistribution
DiscreteUniformDistribution
LogUniformDistribution
UniformDistribution
IntDistribution
IntLogUniformDistribution
IntUniformDistribution
class BaseDistribution(abc.ABC)
| Base class for distributions.
|
| Note that distribution classes are not supposed to be called by library users.
| They are used by :class:`~optuna.trial.Trial` and :class:`~optuna.samplers` internally.
|
| Method resolution order:
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'Any'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| to_internal_repr(self, param_value_in_external_repr: 'Any') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'_contains', 'single', 'to_internal_r...
class CategoricalDistribution(BaseDistribution)
| CategoricalDistribution(choices: 'Sequence[CategoricalChoiceType]') -> 'None'
|
| A categorical distribution.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_categorical`, and
| passed to :mod:`~optuna.samplers` in general.
|
| Args:
| choices:
| Parameter value candidates. ``choices`` must have one element at least.
|
| .. note::
|
| Not all types are guaranteed to be compatible with all storages. It is recommended to
| restrict the types of the choices to :obj:`None`, :class:`bool`, :class:`int`,
| :class:`float` and :class:`str`.
|
| Attributes:
| choices:
| Parameter value candidates.
|
| Method resolution order:
| CategoricalDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int' from BaseDistribution
| Return hash(self).
|
| __init__(self, choices: 'Sequence[CategoricalChoiceType]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'CategoricalChoiceType'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| to_internal_repr(self, param_value_in_external_repr: 'CategoricalChoiceType') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class DiscreteUniformDistribution(FloatDistribution)
| DiscreteUniformDistribution(low: 'float', high: 'float', q: 'float') -> 'None'
|
| A discretized uniform distribution in the linear domain.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_float` with ``step``
| argument, and passed to :mod:`~optuna.samplers` in general.
|
| .. note::
| If the range :math:`[\mathsf{low}, \mathsf{high}]` is not divisible by :math:`q`,
| :math:`\mathsf{high}` will be replaced with the maximum of :math:`k q + \mathsf{low}
| < \mathsf{high}`, where :math:`k` is an integer.
|
| Args:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| q:
| A discretization step. ``q`` must be larger than 0.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use :class:`~optuna.distributions.FloatDistribution` instead.
|
| Method resolution order:
| DiscreteUniformDistribution
| FloatDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'float', high: 'float', q: 'float') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| q
| Discretization step.
|
| :class:`~optuna.distributions.DiscreteUniformDistribution` is a subtype of
| :class:`~optuna.distributions.FloatDistribution`.
| This property is a proxy for its ``step`` attribute.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from FloatDistribution:
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_internal_repr(self, param_value_in_external_repr: 'float') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'Any'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class FloatDistribution(BaseDistribution)
| FloatDistribution(low: 'float', high: 'float', log: 'bool' = False, step: 'None | float' = None) -> 'None'
|
| A distribution on floats.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_float`, and passed to
| :mod:`~optuna.samplers` in general.
|
| .. note::
| When ``step`` is not :obj:`None`, if the range :math:`[\mathsf{low}, \mathsf{high}]`
| is not divisible by :math:`\mathsf{step}`, :math:`\mathsf{high}` will be replaced
| with the maximum of :math:`k \times \mathsf{step} + \mathsf{low} < \mathsf{high}`,
| where :math:`k` is an integer.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than 0.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| log:
| If ``log`` is :obj:`True`, this distribution is in log-scaled domain.
| In this case, all parameters enqueued to the distribution must be positive values.
| This parameter must be :obj:`False` when the parameter ``step`` is not :obj:`None`.
| step:
| A discretization step. ``step`` must be larger than 0.
| This parameter must be :obj:`None` when the parameter ``log`` is :obj:`True`.
|
| Method resolution order:
| FloatDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'float', high: 'float', log: 'bool' = False, step: 'None | float' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_internal_repr(self, param_value_in_external_repr: 'float') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'Any'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class IntDistribution(BaseDistribution)
| IntDistribution(low: 'int', high: 'int', log: 'bool' = False, step: 'int' = 1) -> 'None'
|
| A distribution on integers.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_int`, and passed to
| :mod:`~optuna.samplers` in general.
|
| .. note::
| When ``step`` is not :obj:`None`, if the range :math:`[\mathsf{low}, \mathsf{high}]`
| is not divisible by :math:`\mathsf{step}`, :math:`\mathsf{high}` will be replaced
| with the maximum of :math:`k \times \mathsf{step} + \mathsf{low} < \mathsf{high}`,
| where :math:`k` is an integer.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than or equal to 1.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| log:
| If ``log`` is :obj:`True`, this distribution is in log-scaled domain.
| In this case, all parameters enqueued to the distribution must be positive values.
| This parameter must be :obj:`False` when the parameter ``step`` is not 1.
| step:
| A discretization step. ``step`` must be a positive integer. This parameter must be 1
| when the parameter ``log`` is :obj:`True`.
|
| Method resolution order:
| IntDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'int', high: 'int', log: 'bool' = False, step: 'int' = 1) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'int'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| to_internal_repr(self, param_value_in_external_repr: 'int') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class IntLogUniformDistribution(IntDistribution)
| IntLogUniformDistribution(low: 'int', high: 'int', step: 'int' = 1) -> 'None'
|
| A uniform distribution on integers in the log domain.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_int`, and passed to
| :mod:`~optuna.samplers` in general.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range
| and must be larger than or equal to 1. ``low`` must be less than or equal to ``high``.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A discretization step. ``step`` must be a positive integer.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use :class:`~optuna.distributions.IntDistribution` instead.
|
| Method resolution order:
| IntLogUniformDistribution
| IntDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'int', high: 'int', step: 'int' = 1) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from IntDistribution:
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'int'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| to_internal_repr(self, param_value_in_external_repr: 'int') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class IntUniformDistribution(IntDistribution)
| IntUniformDistribution(low: 'int', high: 'int', step: 'int' = 1) -> 'None'
|
| A uniform distribution on integers.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_int`, and passed to
| :mod:`~optuna.samplers` in general.
|
| .. note::
| If the range :math:`[\mathsf{low}, \mathsf{high}]` is not divisible by
| :math:`\mathsf{step}`, :math:`\mathsf{high}` will be replaced with the maximum of
| :math:`k \times \mathsf{step} + \mathsf{low} < \mathsf{high}`, where :math:`k` is
| an integer.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A discretization step. ``step`` must be a positive integer.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use :class:`~optuna.distributions.IntDistribution` instead.
|
| Method resolution order:
| IntUniformDistribution
| IntDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'int', high: 'int', step: 'int' = 1) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from IntDistribution:
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'int'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| to_internal_repr(self, param_value_in_external_repr: 'int') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class LogUniformDistribution(FloatDistribution)
| LogUniformDistribution(low: 'float', high: 'float') -> 'None'
|
| A uniform distribution in the log domain.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_float` with ``log=True``,
| and passed to :mod:`~optuna.samplers` in general.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be larger than 0. ``low`` must be less than or equal to ``high``.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use :class:`~optuna.distributions.FloatDistribution` instead.
|
| Method resolution order:
| LogUniformDistribution
| FloatDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'float', high: 'float') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from FloatDistribution:
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_internal_repr(self, param_value_in_external_repr: 'float') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'Any'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class UniformDistribution(FloatDistribution)
| UniformDistribution(low: 'float', high: 'float') -> 'None'
|
| A uniform distribution in the linear domain.
|
| This object is instantiated by :func:`~optuna.trial.Trial.suggest_float`, and passed to
| :mod:`~optuna.samplers` in general.
|
| Attributes:
| low:
| Lower endpoint of the range of the distribution. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``.
| high:
| Upper endpoint of the range of the distribution. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use :class:`~optuna.distributions.FloatDistribution` instead.
|
| Method resolution order:
| UniformDistribution
| FloatDistribution
| BaseDistribution
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, low: 'float', high: 'float') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from FloatDistribution:
|
| single(self) -> 'bool'
| Test whether the range of this distribution contains just a single value.
|
| Returns:
| :obj:`True` if the range of this distribution contains just a single value,
| otherwise :obj:`False`.
|
| to_internal_repr(self, param_value_in_external_repr: 'float') -> 'float'
| Convert external representation of a parameter value into internal representation.
|
| Args:
| param_value_in_external_repr:
| Optuna's external representation of a parameter value.
|
| Returns:
| Optuna's internal representation of a parameter value.
|
| ----------------------------------------------------------------------
| Methods inherited from BaseDistribution:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| to_external_repr(self, param_value_in_internal_repr: 'float') -> 'Any'
| Convert internal representation of a parameter value into external representation.
|
| Args:
| param_value_in_internal_repr:
| Optuna's internal representation of a parameter value.
|
| Returns:
| Optuna's external representation of a parameter value.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseDistribution:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
check_distribution_compatibility(dist_old: 'BaseDistribution', dist_new: 'BaseDistribution') -> 'None'
A function to check compatibility of two distributions.
It checks whether ``dist_old`` and ``dist_new`` are the same kind of distributions.
If ``dist_old`` is :class:`~optuna.distributions.CategoricalDistribution`,
it further checks ``choices`` are the same between ``dist_old`` and ``dist_new``.
Note that this method is not supposed to be called by library users.
Args:
dist_old:
A distribution previously recorded in storage.
dist_new:
A distribution newly added to storage.
distribution_to_json(dist: 'BaseDistribution') -> 'str'
Serialize a distribution to JSON format.
Args:
dist: A distribution to be serialized.
Returns:
A JSON string of a given distribution.
json_to_distribution(json_str: 'str') -> 'BaseDistribution'
Deserialize a distribution in JSON format.
Args:
json_str: A JSON-serialized distribution.
Returns:
A deserialized distribution.
DATA
CategoricalChoiceType = typing.Union[NoneType, bool, int, float, str]
DISTRIBUTION_CLASSES = (<class 'optuna.distributions.IntDistribution'>...
TYPE_CHECKING = False
Union = typing.Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator
can also be used to denote unions;
X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by
type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
- Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
- Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
- When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
- You cannot subclass or instantiate a union.
- You can use Optional[X] as a shorthand for Union[X, None].
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\distributions.py
optuna.exceptions
Python Library Documentation: module optuna.exceptions in optuna
NAME
optuna.exceptions
CLASSES
builtins.Exception(builtins.BaseException)
OptunaError
CLIUsageError
DuplicatedStudyError
StorageInternalError
TrialPruned
UpdateFinishedTrialError(OptunaError, builtins.RuntimeError)
builtins.Warning(builtins.Exception)
ExperimentalWarning
class CLIUsageError(OptunaError)
| Exception for CLI.
|
| CLI raises this exception when it receives invalid configuration.
|
| Method resolution order:
| CLIUsageError
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class DuplicatedStudyError(OptunaError)
| Exception for a duplicated study name.
|
| This error is raised when a specified study name already exists in the storage.
|
| Method resolution order:
| DuplicatedStudyError
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class ExperimentalWarning(builtins.Warning)
| Experimental Warning class.
|
| This implementation exists here because the policy of `FutureWarning` has been changed
| since Python 3.7 was released. See the details in
| https://docs.python.org/3/library/warnings.html#warning-categories.
|
| Method resolution order:
| ExperimentalWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Warning:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Warning:
|
| __new__(*args, **kwargs) class method of builtins.Warning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class OptunaError(builtins.Exception)
| Base class for Optuna specific errors.
|
| Method resolution order:
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class StorageInternalError(OptunaError)
| Exception for storage operation.
|
| This error is raised when an operation failed in backend DB of storage.
|
| Method resolution order:
| StorageInternalError
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class TrialPruned(OptunaError)
| Exception for pruned trials.
|
| This error tells a trainer that the current :class:`~optuna.trial.Trial` was pruned. It is
| supposed to be raised after :func:`optuna.trial.Trial.should_prune` as shown in the following
| example.
|
| See also:
| :class:`optuna.TrialPruned` is an alias of :class:`optuna.exceptions.TrialPruned`.
|
| Example:
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, 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=20)
|
| Method resolution order:
| TrialPruned
| OptunaError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Exception:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class UpdateFinishedTrialError(OptunaError, builtins.RuntimeError)
| Exception for updating a finished trial.
|
| This error is raised when attempting to update a finished trial.
|
| Method resolution order:
| UpdateFinishedTrialError
| OptunaError
| builtins.RuntimeError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors inherited from OptunaError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.RuntimeError:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.RuntimeError:
|
| __new__(*args, **kwargs) class method of builtins.RuntimeError
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\exceptions.py
optuna.get_all_study_names
Python Library Documentation: function get_all_study_names in module optuna.study.study
get_all_study_names(storage: 'str | storages.BaseStorage') -> 'list[str]'
Get 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`.
optuna.get_all_study_summaries
Python Library Documentation: function get_all_study_summaries in module optuna.study.study
get_all_study_summaries(storage: 'str | storages.BaseStorage', include_best_trial: 'bool' = True) -> 'list[StudySummary]'
Get 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`.
optuna.importance
Python Library Documentation: package optuna.importance in optuna
NAME
optuna.importance
PACKAGE CONTENTS
_base
_fanova (package)
_mean_decrease_impurity
_ped_anova (package)
CLASSES
abc.ABC(builtins.object)
optuna.importance._base.BaseImportanceEvaluator
optuna.importance._fanova._evaluator.FanovaImportanceEvaluator
optuna.importance._mean_decrease_impurity.MeanDecreaseImpurityImportanceEvaluator
optuna.importance._ped_anova.evaluator.PedAnovaImportanceEvaluator
class BaseImportanceEvaluator(abc.ABC)
| Abstract parameter importance evaluator.
|
| Method resolution order:
| BaseImportanceEvaluator
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| evaluate(self, study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None) -> 'dict[str, float]'
| Evaluate parameter importances based on completed trials in the given study.
|
| .. note::
|
| This method is not meant to be called by library users.
|
| .. seealso::
|
| Please refer to :func:`~optuna.importance.get_param_importances` for how a concrete
| evaluator should implement this method.
|
| Args:
| study:
| An optimized study.
| params:
| A list of names of parameters to assess.
| If :obj:`None`, all parameters that are present in all of the completed trials are
| assessed.
| target:
| A function to specify the value to evaluate importances.
| If it is :obj:`None` and ``study`` is being used for single-objective optimization,
| the objective values are used. Can also be used for other trial attributes, such as
| the duration, like ``target=lambda t: t.duration.total_seconds()``.
|
| .. note::
| Specify this argument if ``study`` is being used for multi-objective
| optimization. For example, to get the hyperparameter importance of the first
| objective, use ``target=lambda t: t.values[0]`` for the target parameter.
|
| Returns:
| A :obj:`dict` where the keys are parameter names and the values are assessed
| importances.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'evaluate'})
class FanovaImportanceEvaluator(optuna.importance._base.BaseImportanceEvaluator)
| FanovaImportanceEvaluator(*, n_trees: 'int' = 64, max_depth: 'int' = 64, seed: 'int | None' = None) -> 'None'
|
| fANOVA importance evaluator.
|
| Implements the fANOVA hyperparameter importance evaluation algorithm in
| `An Efficient Approach for Assessing Hyperparameter Importance
| <http://proceedings.mlr.press/v32/hutter14.html>`__.
|
| fANOVA fits a random forest regression model that predicts the objective values
| of :class:`~optuna.trial.TrialState.COMPLETE` trials given their parameter configurations.
| The more accurate this model is, the more reliable the importances assessed
| by this class are.
|
| .. note::
|
| Requires the `sklearn <https://github.com/scikit-learn/scikit-learn>`__ Python package.
|
| .. note::
|
| The performance of fANOVA depends on the prediction performance of the underlying
| random forest model. In order to obtain high prediction performance, it is necessary to
| cover a wide range of the hyperparameter search space. It is recommended to use an
| exploration-oriented sampler such as :class:`~optuna.samplers.RandomSampler`.
|
| .. note::
|
| For how to cite the original work, please refer to
| https://automl.github.io/fanova/cite.html.
|
| Args:
| n_trees:
| The number of trees in the forest.
| max_depth:
| The maximum depth of the trees in the forest.
| seed:
| Controls the randomness of the forest. For deterministic behavior, specify a value
| other than :obj:`None`.
|
| Method resolution order:
| FanovaImportanceEvaluator
| optuna.importance._base.BaseImportanceEvaluator
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, n_trees: 'int' = 64, max_depth: 'int' = 64, seed: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| evaluate(self, study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None) -> 'dict[str, float]'
| Evaluate parameter importances based on completed trials in the given study.
|
| .. note::
|
| This method is not meant to be called by library users.
|
| .. seealso::
|
| Please refer to :func:`~optuna.importance.get_param_importances` for how a concrete
| evaluator should implement this method.
|
| Args:
| study:
| An optimized study.
| params:
| A list of names of parameters to assess.
| If :obj:`None`, all parameters that are present in all of the completed trials are
| assessed.
| target:
| A function to specify the value to evaluate importances.
| If it is :obj:`None` and ``study`` is being used for single-objective optimization,
| the objective values are used. Can also be used for other trial attributes, such as
| the duration, like ``target=lambda t: t.duration.total_seconds()``.
|
| .. note::
| Specify this argument if ``study`` is being used for multi-objective
| optimization. For example, to get the hyperparameter importance of the first
| objective, use ``target=lambda t: t.values[0]`` for the target parameter.
|
| Returns:
| A :obj:`dict` where the keys are parameter names and the values are assessed
| importances.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.importance._base.BaseImportanceEvaluator:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class MeanDecreaseImpurityImportanceEvaluator(optuna.importance._base.BaseImportanceEvaluator)
| MeanDecreaseImpurityImportanceEvaluator(*, n_trees: 'int' = 64, max_depth: 'int' = 64, seed: 'int | None' = None) -> 'None'
|
| Mean Decrease Impurity (MDI) parameter importance evaluator.
|
| This evaluator fits fits a random forest regression model that predicts the objective values
| of :class:`~optuna.trial.TrialState.COMPLETE` trials given their parameter configurations.
| Feature importances are then computed using MDI.
|
| .. note::
|
| This evaluator requires the `sklearn <https://scikit-learn.org/stable/>`__ Python package
| and is based on `sklearn.ensemble.RandomForestClassifier.feature_importances_
| <https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html#sklearn.ensemble.RandomForestClassifier.feature_importances_>`__.
|
| Args:
| n_trees:
| Number of trees in the random forest.
| max_depth:
| The maximum depth of each tree in the random forest.
| seed:
| Seed for the random forest.
|
| Method resolution order:
| MeanDecreaseImpurityImportanceEvaluator
| optuna.importance._base.BaseImportanceEvaluator
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, n_trees: 'int' = 64, max_depth: 'int' = 64, seed: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| evaluate(self, study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None) -> 'dict[str, float]'
| Evaluate parameter importances based on completed trials in the given study.
|
| .. note::
|
| This method is not meant to be called by library users.
|
| .. seealso::
|
| Please refer to :func:`~optuna.importance.get_param_importances` for how a concrete
| evaluator should implement this method.
|
| Args:
| study:
| An optimized study.
| params:
| A list of names of parameters to assess.
| If :obj:`None`, all parameters that are present in all of the completed trials are
| assessed.
| target:
| A function to specify the value to evaluate importances.
| If it is :obj:`None` and ``study`` is being used for single-objective optimization,
| the objective values are used. Can also be used for other trial attributes, such as
| the duration, like ``target=lambda t: t.duration.total_seconds()``.
|
| .. note::
| Specify this argument if ``study`` is being used for multi-objective
| optimization. For example, to get the hyperparameter importance of the first
| objective, use ``target=lambda t: t.values[0]`` for the target parameter.
|
| Returns:
| A :obj:`dict` where the keys are parameter names and the values are assessed
| importances.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.importance._base.BaseImportanceEvaluator:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PedAnovaImportanceEvaluator(optuna.importance._base.BaseImportanceEvaluator)
| PedAnovaImportanceEvaluator(*, target_quantile: 'float' = 0.1, region_quantile: 'float' = 1.0, baseline_quantile: 'float | None' = None, evaluate_on_local: 'bool' = True) -> 'None'
|
| PED-ANOVA importance evaluator.
|
| Implements the PED-ANOVA hyperparameter importance evaluation algorithm.
|
| PED-ANOVA fits Parzen estimators of :class:`~optuna.trial.TrialState.COMPLETE` trials better
| than a user-specified `target_quantile`.
| The importance can be interpreted as how important each hyperparameter is to get
| the performance better than `target_quantile`.
|
| For further information about PED-ANOVA algorithm, please refer to the following paper:
|
| - `PED-ANOVA: Efficiently Quantifying Hyperparameter Importance in Arbitrary Subspaces
| <https://arxiv.org/abs/2304.10255>`__
|
| `target_quantile` and `region_quantile` correspond to the parameters ``gamma'`` and ``gamma``
| in the original paper, respectively.
|
| .. note::
|
| The performance of PED-ANOVA depends on how many trials to consider above
| `target_quantile`. To stabilize the analysis, it is preferable to include at least
| 5 trials above `target_quantile`.
|
| .. note::
|
| Please refer to `the original work <https://github.com/nabenabe0928/local-anova>`__.
|
| Args:
| target_quantile:
| Compute the importance of achieving top-``target_quantile`` quantile objective value.
| For example, ``target_quantile=0.1`` means that the importances give the information
| of which parameters were important to achieve the top-10% performance during
| optimization.
|
| region_quantile:
| Define the region where we compute the importance. For example,
| ``region_quantile=0.5`` means that we compute the importance in the region where
| trials achieve top-50% performance. If ``region_quantile=1.0``, the importance is
| computed in the whole search space.
|
| baseline_quantile:
| Compute the importance of achieving top-``baseline_quantile`` quantile objective value.
| For example, ``baseline_quantile=0.1`` means that the importances give the information
| of which parameters were important to achieve the top-10% performance during
| optimization.
|
| .. warning::
| Deprecated in v4.7.0. This feature will be removed in the future. The removal of
| this feature is currently scheduled for v5.0.0, but this schedule is subject to
| change. `baseline_quantile` is currently ignored. Use `target_quantile` instead.
| See https://github.com/optuna/optuna/releases/tag/v4.7.0.
|
| evaluate_on_local:
| Whether we measure the importance in the local or global space.
| If :obj:`True`, the importances imply how importance each parameter is during
| optimization. Meanwhile, ``evaluate_on_local=False`` gives the importances in the
| specified search_space. ``evaluate_on_local=True`` is especially useful when users
| modify search space during optimization.
|
| Example:
| An example of using PED-ANOVA is as follows:
|
| .. testcode::
|
| import optuna
| from optuna.importance import PedAnovaImportanceEvaluator
|
|
| def objective(trial):
| x1 = trial.suggest_float("x1", -10, 10)
| x2 = trial.suggest_float("x2", -10, 10)
| return x1 + x2 / 1000
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=100)
| evaluator = PedAnovaImportanceEvaluator()
| importance = optuna.importance.get_param_importances(study, evaluator=evaluator)
|
| .. note::
| Added in v3.6.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.6.0.
|
| Method resolution order:
| PedAnovaImportanceEvaluator
| optuna.importance._base.BaseImportanceEvaluator
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, target_quantile: 'float' = 0.1, region_quantile: 'float' = 1.0, baseline_quantile: 'float | None' = None, evaluate_on_local: 'bool' = True) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| evaluate(self, study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None) -> 'dict[str, float]'
| Evaluate parameter importances based on completed trials in the given study.
|
| .. note::
|
| This method is not meant to be called by library users.
|
| .. seealso::
|
| Please refer to :func:`~optuna.importance.get_param_importances` for how a concrete
| evaluator should implement this method.
|
| Args:
| study:
| An optimized study.
| params:
| A list of names of parameters to assess.
| If :obj:`None`, all parameters that are present in all of the completed trials are
| assessed.
| target:
| A function to specify the value to evaluate importances.
| If it is :obj:`None` and ``study`` is being used for single-objective optimization,
| the objective values are used. Can also be used for other trial attributes, such as
| the duration, like ``target=lambda t: t.duration.total_seconds()``.
|
| .. note::
| Specify this argument if ``study`` is being used for multi-objective
| optimization. For example, to get the hyperparameter importance of the first
| objective, use ``target=lambda t: t.values[0]`` for the target parameter.
|
| Returns:
| A :obj:`dict` where the keys are parameter names and the values are assessed
| importances.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.importance._base.BaseImportanceEvaluator:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
get_param_importances(study: 'Study', *, evaluator: 'BaseImportanceEvaluator | None' = None, params: 'list[str] | None' = None, target: 'Callable[[FrozenTrial], float] | None' = None, normalize: 'bool' = True) -> 'dict[str, float]'
Evaluate parameter importances based on completed trials in the given study.
The parameter importances are returned as a dictionary where the keys consist of parameter
names and their values importances.
The importances are represented by non-negative floating point numbers, where higher values
mean that the parameters are more important.
The returned dictionary is ordered by its values in a descending order.
By default, the sum of the importance values are normalized to 1.0.
If ``params`` is :obj:`None`, all parameter that are present in all of the completed trials are
assessed.
This implies that conditional parameters will be excluded from the evaluation.
To assess the importances of conditional parameters, a :obj:`list` of parameter names can be
specified via ``params``.
If specified, only completed trials that contain all of the parameters will be considered.
If no such trials are found, an error will be raised.
If the given study does not contain completed trials, an error will be raised.
.. note::
If ``params`` is specified as an empty list, an empty dictionary is returned.
.. seealso::
See :func:`~optuna.visualization.plot_param_importances` to plot importances.
Args:
study:
An optimized study.
evaluator:
An importance evaluator object that specifies which algorithm to base the importance
assessment on.
Defaults to
:class:`~optuna.importance.FanovaImportanceEvaluator`.
params:
A list of names of parameters to assess.
If :obj:`None`, all parameters that are present in all of the completed trials are
assessed.
target:
A function to specify the value to evaluate importances.
If it is :obj:`None` and ``study`` is being used for single-objective optimization,
the objective values are used. ``target`` must be specified if ``study`` is being
used for multi-objective optimization.
.. note::
Specify this argument if ``study`` is being used for multi-objective
optimization. For example, to get the hyperparameter importance of the first
objective, use ``target=lambda t: t.values[0]`` for the target parameter.
normalize:
A boolean option to specify whether the sum of the importance values should be
normalized to 1.0.
Defaults to :obj:`True`.
.. note::
Added in v3.0.0 as an experimental feature. The interface may change in newer
versions without prior notice. See
https://github.com/optuna/optuna/releases/tag/v3.0.0.
Returns:
A :obj:`dict` where the keys are parameter names and the values are assessed importances.
DATA
__all__ = ['BaseImportanceEvaluator', 'FanovaImportanceEvaluator', 'Me...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\importance\__init__.py
optuna.integration
Python Library Documentation: package optuna.integration in optuna
NAME
optuna.integration
PACKAGE CONTENTS
allennlp (package)
botorch
catboost
chainer
chainermn
cma
dask
fastaiv2
keras
lightgbm
mlflow
mxnet
pytorch_distributed
pytorch_ignite
pytorch_lightning
shap
sklearn
skorch
tensorboard
tensorflow
tfkeras
wandb
xgboost
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\integration\__init__.py
optuna.load_study
Python Library Documentation: function load_study in module optuna.study.study
load_study(*, study_name: 'str | None', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'Study'
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`.
optuna.logging
Python Library Documentation: module optuna.logging in optuna
NAME
optuna.logging
DATA
CRITICAL = 50
DEBUG = 10
ERROR = 40
FATAL = 50
INFO = 20
WARN = 30
WARNING = 30
__all__ = ['CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'INFO', 'WARN', 'WAR...
__annotations__ = {'_default_handler': 'logging.Handler | None', '_loc...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\logging.py
optuna.progress_bar
Python Library Documentation: module optuna.progress_bar in optuna
NAME
optuna.progress_bar
DATA
TYPE_CHECKING = False
__annotations__ = {'_tqdm_handler': '_TqdmLoggingHandler | None'}
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\progress_bar.py
optuna.pruners
Python Library Documentation: package optuna.pruners in optuna
NAME
optuna.pruners
PACKAGE CONTENTS
_base
_hyperband
_median
_nop
_patient
_percentile
_successive_halving
_threshold
_wilcoxon
CLASSES
abc.ABC(builtins.object)
optuna.pruners._base.BasePruner
optuna.pruners._hyperband.HyperbandPruner
optuna.pruners._nop.NopPruner
optuna.pruners._patient.PatientPruner
optuna.pruners._percentile.PercentilePruner
optuna.pruners._median.MedianPruner
optuna.pruners._successive_halving.SuccessiveHalvingPruner
optuna.pruners._threshold.ThresholdPruner
optuna.pruners._wilcoxon.WilcoxonPruner
class BasePruner(abc.ABC)
| Base class for pruners.
|
| Method resolution order:
| BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| prune(self, study: "'optuna.study.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'prune'})
class HyperbandPruner(optuna.pruners._base.BasePruner)
| HyperbandPruner(min_resource: 'int' = 1, max_resource: 'str | int' = 'auto', reduction_factor: 'int' = 3, bootstrap_count: 'int' = 0) -> 'None'
|
| Pruner using Hyperband.
|
| As SuccessiveHalving (SHA) requires the number of configurations
| :math:`n` as its hyperparameter. For a given finite budget :math:`B`,
| all the configurations have the resources of :math:`B \over n` on average.
| As you can see, there will be a trade-off of :math:`B` and :math:`B \over n`.
| `Hyperband <http://www.jmlr.org/papers/volume18/16-558/16-558.pdf>`__ attacks this trade-off
| by trying different :math:`n` values for a fixed budget.
|
| .. note::
| * In the Hyperband paper, the counterpart of :class:`~optuna.samplers.RandomSampler`
| is used.
| * Optuna uses :class:`~optuna.samplers.TPESampler` by default.
| * `The benchmark result
| <https://github.com/optuna/optuna/pull/828#issuecomment-575457360>`__
| shows that :class:`optuna.pruners.HyperbandPruner` supports both samplers.
|
| .. note::
| If you use ``HyperbandPruner`` with :class:`~optuna.samplers.TPESampler`,
| it's recommended to consider setting larger ``n_trials`` or ``timeout`` to make full use of
| the characteristics of :class:`~optuna.samplers.TPESampler`
| because :class:`~optuna.samplers.TPESampler` uses some (by default, :math:`10`)
| :class:`~optuna.trial.Trial`\ s for its startup.
|
| As Hyperband runs multiple :class:`~optuna.pruners.SuccessiveHalvingPruner` and collects
| trials based on the current :class:`~optuna.trial.Trial`\ 's bracket ID, each bracket
| needs to observe more than :math:`10` :class:`~optuna.trial.Trial`\ s
| for :class:`~optuna.samplers.TPESampler` to adapt its search space.
|
| Thus, for example, if ``HyperbandPruner`` has :math:`4` pruners in it,
| at least :math:`4 \times 10` trials are consumed for startup.
|
| .. note::
| Hyperband has several :class:`~optuna.pruners.SuccessiveHalvingPruner`\ s. Each
| :class:`~optuna.pruners.SuccessiveHalvingPruner` is referred to as "bracket" in the
| original paper. The number of brackets is an important factor to control the early
| stopping behavior of Hyperband and is automatically determined by ``min_resource``,
| ``max_resource`` and ``reduction_factor`` as
| :math:`\mathrm{The\ number\ of\ brackets} =
| \mathrm{floor}(\log_{\texttt{reduction}\_\texttt{factor}}
| (\frac{\texttt{max}\_\texttt{resource}}{\texttt{min}\_\texttt{resource}})) + 1`.
| Please set ``reduction_factor`` so that the number of brackets is not too large (about 4 –
| 6 in most use cases). Please see Section 3.6 of the `original paper
| <http://www.jmlr.org/papers/volume18/16-558/16-558.pdf>`__ for the detail.
|
| .. note::
| ``HyperbandPruner`` computes bracket ID for each trial with a
| function taking ``study_name`` of :class:`~optuna.study.Study` and
| :attr:`~optuna.trial.Trial.number`. Please specify ``study_name``
| to make the pruning algorithm reproducible.
|
| Example:
|
| We minimize an objective function with Hyperband pruning algorithm.
|
| .. 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)
| classes = np.unique(y)
| n_train_iter = 100
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(
| direction="maximize",
| pruner=optuna.pruners.HyperbandPruner(
| min_resource=1, max_resource=n_train_iter, reduction_factor=3
| ),
| )
| study.optimize(objective, n_trials=20)
|
| Args:
| min_resource:
| A parameter for specifying the minimum resource allocated to a trial noted as :math:`r`
| in the paper. A smaller :math:`r` will give a result faster, but a larger
| :math:`r` will give a better guarantee of successful judging between configurations.
| See the details for :class:`~optuna.pruners.SuccessiveHalvingPruner`.
| max_resource:
| A parameter for specifying the maximum resource allocated to a trial. :math:`R` in the
| paper corresponds to ``max_resource / min_resource``. This value represents and should
| match the maximum iteration steps (e.g., the number of epochs for neural networks).
| When this argument is "auto", the maximum resource is estimated according to the
| completed trials. The default value of this argument is "auto".
|
| .. note::
| With "auto", the maximum resource will be the largest step reported by
| :meth:`~optuna.trial.Trial.report` in the first, or one of the first if trained in
| parallel, completed trial. No trials will be pruned until the maximum resource is
| determined.
|
| .. note::
| If the step of the last intermediate value may change with each trial, please
| manually specify the maximum possible step to ``max_resource``.
| reduction_factor:
| A parameter for specifying reduction factor of promotable trials noted as
| :math:`\eta` in the paper.
| See the details for :class:`~optuna.pruners.SuccessiveHalvingPruner`.
| bootstrap_count:
| Parameter specifying the number of trials required in a rung before any trial can be
| promoted. Incompatible with ``max_resource`` is ``"auto"``.
| See the details for :class:`~optuna.pruners.SuccessiveHalvingPruner`.
|
| Method resolution order:
| HyperbandPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, min_resource: 'int' = 1, max_resource: 'str | int' = 'auto', reduction_factor: 'int' = 3, bootstrap_count: 'int' = 0) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: "'optuna.study.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class MedianPruner(optuna.pruners._percentile.PercentilePruner)
| MedianPruner(n_startup_trials: int = 5, n_warmup_steps: int = 0, interval_steps: int = 1, *, n_min_trials: int = 1) -> None
|
| Pruner using the median stopping rule.
|
| Prune if the trial's best intermediate result is worse than median of intermediate results of
| previous trials at the same step. It stops unpromising trials early based on the
| intermediate results compared against the median of previous completed trials.
|
| The pruner handles NaN values in the following manner:
| 1. If all intermediate values of the current trial are NaN, the trial will be pruned.
| 2. During the median calculation across completed trials, NaN values are ignored.
| Only valid numeric values are considered.
|
| Example:
|
| We minimize an objective function with the median stopping rule.
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(
| direction="maximize",
| pruner=optuna.pruners.MedianPruner(
| n_startup_trials=5, n_warmup_steps=30, interval_steps=10
| ),
| )
| study.optimize(objective, n_trials=20)
|
| Args:
| n_startup_trials:
| Pruning is disabled until the given number of trials finish in the same study.
| n_warmup_steps:
| Pruning is disabled until the trial exceeds the given number of step. Note that
| this feature assumes that ``step`` starts at zero.
| interval_steps:
| Interval in number of steps between the pruning checks, offset by the warmup steps.
| If no value has been reported at the time of a pruning check, that particular check
| will be postponed until a value is reported.
| n_min_trials:
| Minimum number of reported trial results at a step to judge whether to prune.
| If the number of reported intermediate values from all trials at the current step
| is less than ``n_min_trials``, the trial will not be pruned. This can be used to ensure
| that a minimum number of trials are run to completion without being pruned.
|
| Method resolution order:
| MedianPruner
| optuna.pruners._percentile.PercentilePruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, n_startup_trials: int = 5, n_warmup_steps: int = 0, interval_steps: int = 1, *, n_min_trials: int = 1) -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.pruners._percentile.PercentilePruner:
|
| prune(self, study: "'optuna.study.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class NopPruner(optuna.pruners._base.BasePruner)
| Pruner which never prunes trials.
|
| Example:
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| assert False, "should_prune() should always return False with this pruner."
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize", pruner=optuna.pruners.NopPruner())
| study.optimize(objective, n_trials=20)
|
| Method resolution order:
| NopPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| prune(self, study: 'Study', trial: 'FrozenTrial') -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PatientPruner(optuna.pruners._base.BasePruner)
| PatientPruner(wrapped_pruner: 'BasePruner | None', patience: 'int', min_delta: 'float' = 0.0) -> 'None'
|
| Pruner which wraps another pruner with tolerance.
|
| This pruner monitors intermediate values in a trial and prunes the trial if the improvement in
| the intermediate values after a patience period is less than a threshold.
|
| The pruner handles NaN values in the following manner:
| 1. If all intermediate values before or during the patient period are NaN, the trial will
| not be pruned
| 2. During the pruning calculations, NaN values are ignored. Only valid numeric values are
| considered.
|
| Example:
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(
| direction="maximize",
| pruner=optuna.pruners.PatientPruner(optuna.pruners.MedianPruner(), patience=1),
| )
| study.optimize(objective, n_trials=20)
|
| Args:
| wrapped_pruner:
| Wrapped pruner to perform pruning when :class:`~optuna.pruners.PatientPruner` allows a
| trial to be pruned. If it is :obj:`None`, this pruner is equivalent to
| early-stopping taken the intermediate values in the individual trial.
| patience:
| Pruning is disabled until the objective doesn't improve for
| ``patience`` consecutive steps.
| min_delta:
| Tolerance value to check whether or not the objective improves.
| This value should be non-negative.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.8.0.
|
| Method resolution order:
| PatientPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, wrapped_pruner: 'BasePruner | None', patience: 'int', min_delta: 'float' = 0.0) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: 'optuna.study.Study', trial: 'optuna.trial.FrozenTrial') -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PercentilePruner(optuna.pruners._base.BasePruner)
| PercentilePruner(percentile: 'float', n_startup_trials: 'int' = 5, n_warmup_steps: 'int' = 0, interval_steps: 'int' = 1, *, n_min_trials: 'int' = 1) -> 'None'
|
| Pruner to keep the specified percentile of the trials.
|
| Prune if the best intermediate value is in the bottom percentile among trials at the same step.
|
| Example:
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(
| direction="maximize",
| pruner=optuna.pruners.PercentilePruner(
| 25.0, n_startup_trials=5, n_warmup_steps=30, interval_steps=10
| ),
| )
| study.optimize(objective, n_trials=20)
|
| Args:
| percentile:
| Percentile which must be between 0 and 100 inclusive
| (e.g., When given 25.0, top of 25th percentile trials are kept).
| n_startup_trials:
| Pruning is disabled until the given number of trials finish in the same study.
| n_warmup_steps:
| Pruning is disabled until the trial exceeds the given number of step. Note that
| this feature assumes that ``step`` starts at zero.
| interval_steps:
| Interval in number of steps between the pruning checks, offset by the warmup steps.
| If no value has been reported at the time of a pruning check, that particular check
| will be postponed until a value is reported. Value must be at least 1.
| n_min_trials:
| Minimum number of reported trial results at a step to judge whether to prune.
| If the number of reported intermediate values from all trials at the current step
| is less than ``n_min_trials``, the trial will not be pruned. This can be used to ensure
| that a minimum number of trials are run to completion without being pruned.
|
| Method resolution order:
| PercentilePruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, percentile: 'float', n_startup_trials: 'int' = 5, n_warmup_steps: 'int' = 0, interval_steps: 'int' = 1, *, n_min_trials: 'int' = 1) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: "'optuna.study.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class SuccessiveHalvingPruner(optuna.pruners._base.BasePruner)
| SuccessiveHalvingPruner(min_resource: 'str | int' = 'auto', reduction_factor: 'int' = 4, min_early_stopping_rate: 'int' = 0, bootstrap_count: 'int' = 0) -> 'None'
|
| Pruner using Asynchronous Successive Halving Algorithm.
|
| `Successive Halving <https://proceedings.mlr.press/v51/jamieson16.html>`__ is a bandit-based
| algorithm to identify the best one among multiple configurations. This class implements an
| asynchronous version of Successive Halving. Please refer to the paper of
| `Asynchronous Successive Halving <https://proceedings.mlsys.org/paper_files/paper/2020/file/
| a06f20b349c6cf09a6b171c71b88bbfc-Paper.pdf>`__ for detailed descriptions.
|
| Note that, this class does not take care of the parameter for the maximum
| resource, referred to as :math:`R` in the paper. The maximum resource allocated to a trial is
| typically limited inside the objective function (e.g., ``step`` number in `simple_pruning.py
| <https://github.com/optuna/optuna-examples/blob/main/basic/pruning.py>`__,
| ``EPOCH`` number in `chainer_integration.py
| <https://github.com/optuna/optuna-examples/tree/main/chainer/chainer_integration.py#L73>`__).
|
| .. seealso::
| Please refer to :meth:`~optuna.trial.Trial.report`.
|
| Example:
|
| We minimize an objective function with ``SuccessiveHalvingPruner``.
|
| .. 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)
| classes = np.unique(y)
|
|
| def objective(trial):
| alpha = trial.suggest_float("alpha", 0.0, 1.0)
| clf = SGDClassifier(alpha=alpha)
| n_train_iter = 100
|
| for step in range(n_train_iter):
| clf.partial_fit(X_train, y_train, classes=classes)
|
| intermediate_value = clf.score(X_valid, y_valid)
| trial.report(intermediate_value, step)
|
| if trial.should_prune():
| raise optuna.TrialPruned()
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(
| direction="maximize", pruner=optuna.pruners.SuccessiveHalvingPruner()
| )
| study.optimize(objective, n_trials=20)
|
| Args:
| min_resource:
| A parameter for specifying the minimum resource allocated to a trial
| (in the `paper <https://proceedings.mlsys.org/paper_files/paper/2020/file/
| a06f20b349c6cf09a6b171c71b88bbfc-Paper.pdf>`__ this parameter is referred to as
| :math:`r`).
| This parameter defaults to 'auto' where the value is determined based on a heuristic
| that looks at the number of required steps for the first trial to complete.
|
| A trial is never pruned until it executes
| :math:`\mathsf{min}\_\mathsf{resource} \times
| \mathsf{reduction}\_\mathsf{factor}^{
| \mathsf{min}\_\mathsf{early}\_\mathsf{stopping}\_\mathsf{rate}}`
| steps (i.e., the completion point of the first rung). When the trial completes
| the first rung, it will be promoted to the next rung only
| if the value of the trial is placed in the top
| :math:`{1 \over \mathsf{reduction}\_\mathsf{factor}}` fraction of
| the all trials that already have reached the point (otherwise it will be pruned there).
| If the trial won the competition, it runs until the next completion point (i.e.,
| :math:`\mathsf{min}\_\mathsf{resource} \times
| \mathsf{reduction}\_\mathsf{factor}^{
| (\mathsf{min}\_\mathsf{early}\_\mathsf{stopping}\_\mathsf{rate}
| + \mathsf{rung})}` steps)
| and repeats the same procedure.
|
| .. note::
| If the step of the last intermediate value may change with each trial, please
| manually specify the minimum possible step to ``min_resource``.
| reduction_factor:
| A parameter for specifying reduction factor of promotable trials
| (in the `paper <https://proceedings.mlsys.org/paper_files/paper/2020/file/
| a06f20b349c6cf09a6b171c71b88bbfc-Paper.pdf>`__ this parameter is
| referred to as :math:`\eta`). At the completion point of each rung,
| about :math:`{1 \over \mathsf{reduction}\_\mathsf{factor}}`
| trials will be promoted.
| min_early_stopping_rate:
| A parameter for specifying the minimum early-stopping rate
| (in the `paper <https://proceedings.mlsys.org/paper_files/paper/2020/file/
| a06f20b349c6cf09a6b171c71b88bbfc-Paper.pdf>`__ this parameter is
| referred to as :math:`s`).
| bootstrap_count:
| Minimum number of trials that need to complete a rung before any trial
| is considered for promotion into the next rung.
|
| Method resolution order:
| SuccessiveHalvingPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, min_resource: 'str | int' = 'auto', reduction_factor: 'int' = 4, min_early_stopping_rate: 'int' = 0, bootstrap_count: 'int' = 0) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: "'optuna.study.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class ThresholdPruner(optuna.pruners._base.BasePruner)
| ThresholdPruner(lower: 'float | None' = None, upper: 'float | None' = None, n_warmup_steps: 'int' = 0, interval_steps: 'int' = 1) -> 'None'
|
| Pruner to detect outlying metrics of the trials.
|
| Prune if a metric exceeds upper threshold,
| falls behind lower threshold or reaches ``nan``.
|
| Example:
| .. testcode::
|
| from optuna import create_study
| from optuna.pruners import ThresholdPruner
| from optuna import TrialPruned
|
|
| def objective_for_upper(trial):
| for step, y in enumerate(ys_for_upper):
| trial.report(y, step)
|
| if trial.should_prune():
| raise TrialPruned()
| return ys_for_upper[-1]
|
|
| def objective_for_lower(trial):
| for step, y in enumerate(ys_for_lower):
| trial.report(y, step)
|
| if trial.should_prune():
| raise TrialPruned()
| return ys_for_lower[-1]
|
|
| ys_for_upper = [0.0, 0.1, 0.2, 0.5, 1.2]
| ys_for_lower = [100.0, 90.0, 0.1, 0.0, -1]
|
| study = create_study(pruner=ThresholdPruner(upper=1.0))
| study.optimize(objective_for_upper, n_trials=10)
|
| study = create_study(pruner=ThresholdPruner(lower=0.0))
| study.optimize(objective_for_lower, n_trials=10)
|
| Args:
| lower:
| A minimum value which determines whether pruner prunes or not.
| If an intermediate value is smaller than lower, it prunes.
| upper:
| A maximum value which determines whether pruner prunes or not.
| If an intermediate value is larger than upper, it prunes.
| n_warmup_steps:
| Pruning is disabled if the step is less than the given number of warmup steps.
| interval_steps:
| Interval in number of steps between the pruning checks, offset by the warmup steps.
| If no value has been reported at the time of a pruning check, that particular check
| will be postponed until a value is reported. Value must be at least 1.
|
| Method resolution order:
| ThresholdPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, lower: 'float | None' = None, upper: 'float | None' = None, n_warmup_steps: 'int' = 0, interval_steps: 'int' = 1) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: 'Study', trial: 'FrozenTrial') -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class WilcoxonPruner(optuna.pruners._base.BasePruner)
| WilcoxonPruner(*, p_threshold: 'float' = 0.1, n_startup_steps: 'int' = 2) -> 'None'
|
| Pruner based on the `Wilcoxon signed-rank test <https://en.wikipedia.org/w/index.php?title=Wilcoxon_signed-rank_test&oldid=1195011212>`__.
|
| This pruner performs the Wilcoxon signed-rank test between the current trial and the current best trial,
| and stops whenever the pruner is sure up to a given p-value that the current trial is worse than the best one.
|
| This pruner is effective for optimizing the mean/median of some (costly-to-evaluate) performance scores over a set of problem instances.
| Example applications include the optimization of:
|
| * the mean performance of a heuristic method (simulated annealing, genetic algorithm, SAT solver, etc.) on a set of problem instances,
| * the k-fold cross-validation score of a machine learning model, and
| * the accuracy of outputs of a large language model (LLM) on a set of questions.
|
| There can be "easy" or "hard" instances (the pruner handles correspondence of the instances between different trials).
| In each trial, it is recommended to shuffle the evaluation order, so that the optimization doesn't overfit to the instances in the beginning.
|
| When you use this pruner, you must call ``Trial.report(value, step)`` method for each step (instance id) with
| the evaluated value. The instance id may not be in ascending order.
| This is different from other pruners in that the reported value need not converge
| to the real value. To use pruners such as :class:`~optuna.pruners.SuccessiveHalvingPruner`
| in the same setting, you must provide e.g., the historical average of the evaluated values.
|
| .. seealso::
| Please refer to :meth:`~optuna.trial.Trial.report`.
|
| .. note::
| This sampler requires ``scipy``.
| You can install these dependencies with ``pip install scipy``.
|
| Example:
|
| .. testcode::
|
| import optuna
| import numpy as np
|
|
| # We minimize the mean evaluation loss over all the problem instances.
| def evaluate(param, instance):
| # A toy loss function for demonstrative purpose.
| return (param - instance) ** 2
|
|
| problem_instances = np.linspace(-1, 1, 100)
|
|
| def objective(trial):
| # Sample a parameter.
| param = trial.suggest_float("param", -1, 1)
|
| # Evaluate performance of the parameter.
| results = []
|
| # For best results, shuffle the evaluation order in each trial.
| instance_ids = np.random.permutation(len(problem_instances))
| for instance_id in instance_ids:
| loss = evaluate(param, problem_instances[instance_id])
| results.append(loss)
|
| # Report loss together with the instance id.
| # CAVEAT: You need to pass the same id for the same instance,
| # otherwise WilcoxonPruner cannot correctly pair the losses across trials and
| # the pruning performance will degrade.
| trial.report(loss, instance_id)
|
| if trial.should_prune():
| # Return the current predicted value instead of raising `TrialPruned`.
| # This is a workaround to tell the Optuna about the evaluation
| # results in pruned trials. (See the note below.)
| return sum(results) / len(results)
|
| return sum(results) / len(results)
|
|
| study = optuna.create_study(pruner=optuna.pruners.WilcoxonPruner(p_threshold=0.1))
| study.optimize(objective, n_trials=100)
|
|
|
| .. note::
| This pruner cannot handle ``infinity`` or ``nan`` values.
| Trials containing those values are never pruned.
|
| .. note::
| If :func:`~optuna.trial.FrozenTrial.should_prune` returns :obj:`True`, you can return an
| estimation of the final value (e.g., the average of all evaluated
| values) instead of ``raise optuna.TrialPruned()``.
| This is a workaround for the problem that currently there is no way
| to tell Optuna the predicted objective value for trials raising
| :class:`optuna.TrialPruned`.
|
| Args:
| p_threshold:
| The p-value threshold for pruning. This value should be between 0 and 1.
| A trial will be pruned whenever the pruner is sure up to the given p-value
| that the current trial is worse than the best trial.
| The larger this value is, the more aggressive pruning will be performed.
| Defaults to 0.1.
|
| .. note::
| This pruner repeatedly performs statistical tests between the
| current trial and the current best trial with increasing samples.
| The false-positive rate of such a sequential test is different from
| performing the test only once. To get the nominal false-positive rate,
| please specify the Pocock-corrected p-value.
|
| n_startup_steps:
| The number of steps before which no trials are pruned.
| Pruning starts only after you have ``n_startup_steps`` steps of
| available observations for comparison between the current trial
| and the best trial.
| Defaults to 2. Note that the trial is not pruned at the first and second steps even if
| the `n_startup_steps` is set to 0 or 1 due to the lack of enough data for comparison.
|
| .. note::
| Added in v3.6.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.6.0.
|
| Method resolution order:
| WilcoxonPruner
| optuna.pruners._base.BasePruner
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, p_threshold: 'float' = 0.1, n_startup_steps: 'int' = 2) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| prune(self, study: "'optuna.study.Study'", trial: 'FrozenTrial') -> 'bool'
| Judge whether the trial should be pruned based on the reported values.
|
| Note that this method is not supposed to be called by library users. Instead,
| :func:`optuna.trial.Trial.report` and :func:`optuna.trial.Trial.should_prune` provide
| user interfaces to implement pruning mechanism in an objective function.
|
| Args:
| study:
| Study object of the target study.
| trial:
| FrozenTrial object of the target trial.
| Take a copy before modifying this object.
|
| Returns:
| A boolean value representing whether the trial should be pruned.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.pruners._base.BasePruner:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['BasePruner', 'HyperbandPruner', 'MedianPruner', 'NopPruner...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\pruners\__init__.py
optuna.samplers
Python Library Documentation: package optuna.samplers in optuna
NAME
optuna.samplers
PACKAGE CONTENTS
_base
_brute_force
_cmaes
_ga (package)
_gp (package)
_grid
_lazy_random_state
_nsgaiii (package)
_partial_fixed
_qmc
_random
_tpe (package)
nsgaii (package)
CLASSES
abc.ABC(builtins.object)
optuna.samplers._base.BaseSampler
optuna.samplers._brute_force.BruteForceSampler
optuna.samplers._cmaes.CmaEsSampler
optuna.samplers._ga._base.BaseGASampler(optuna.samplers._base.BaseSampler, abc.ABC)
optuna.samplers._nsgaiii._sampler.NSGAIIISampler
optuna.samplers.nsgaii._sampler.NSGAIISampler
optuna.samplers._gp.sampler.GPSampler
optuna.samplers._grid.GridSampler
optuna.samplers._partial_fixed.PartialFixedSampler
optuna.samplers._qmc.QMCSampler
optuna.samplers._random.RandomSampler
optuna.samplers._tpe.sampler.TPESampler
class BaseGASampler(optuna.samplers._base.BaseSampler, abc.ABC)
| BaseGASampler(population_size: 'int | None')
|
| Base class for Genetic Algorithm (GA) samplers.
|
| Genetic Algorithm samplers generate new trials by mimicking natural selection, using
| generations and populations to iteratively improve solutions. This base class defines the
| interface for GA samplers in Optuna and provides utility methods for managing generations and
| populations.
|
| The selection process is handled by :meth:`~BaseGASampler.select_parent`, which must be
| implemented by subclasses to define the parent selection strategy.
|
| Generation and population management is facilitated by methods like
| :meth:`~BaseGASampler.get_generation` and :meth:`~BaseGASampler.get_population`, ensuring
| consistent tracking and selection.
|
| Note:
| This class should be extended by subclasses that define specific GA sampling strategies,
| including parent selection and crossover operations.
|
| Method resolution order:
| BaseGASampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, population_size: 'int | None')
| Initialize self. See help(type(self)) for accurate signature.
|
| get_parent_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the parent population of the given generation.
|
| This method caches the parent population in the study's system attributes.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials. If `generation == 0`, returns an empty list.
|
| get_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the population of the given generation.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of frozen trials in the given generation.
|
| get_trial_generation(self, study: 'Study', trial: 'FrozenTrial') -> 'int'
| Get the generation number of the given trial.
|
| This method returns the generation number of the specified trial. If the generation number
| is not set in the trial's system attributes, it will calculate and set the generation
| number.
|
| The current generation number depends on the maximum generation number of all completed
| trials.
|
| Args:
| study:
| Study object which trial belongs to.
| trial:
| Trial object to get the generation number.
|
| Returns:
| Generation number of the given trial.
|
| select_parent(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Select parent trials from the population for the given generation.
|
| This method is called once per generation to select parents from
| the population of the current generation.
|
| Output of this function is cached in the study system attributes.
|
| This method must be implemented in a subclass to define the specific selection strategy.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| __init_subclass__(**kwargs: 'Any')
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| population_size
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'infer_relative_search_space', 'sampl...
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class BaseSampler(abc.ABC)
| Base class for samplers.
|
| Optuna combines two types of sampling strategies, which are called *relative sampling* and
| *independent sampling*.
|
| *The relative sampling* determines values of multiple parameters simultaneously so that
| sampling algorithms can use relationship between parameters (e.g., correlation).
| Target parameters of the relative sampling are described in a relative search space, which
| is determined by :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| *The independent sampling* determines a value of a single parameter without considering any
| relationship between parameters. Target parameters of the independent sampling are the
| parameters not described in the relative search space.
|
| More specifically, parameters are sampled by the following procedure.
| At the beginning of a trial, :meth:`~optuna.samplers.BaseSampler.infer_relative_search_space`
| is called to determine the relative search space for the trial.
| During the execution of the objective function,
| :meth:`~optuna.samplers.BaseSampler.sample_relative` is called only once
| when sampling the parameters belonging to the relative search space for the first time.
| :meth:`~optuna.samplers.BaseSampler.sample_independent` is used to sample
| parameters that don't belong to the relative search space.
|
| The following figure depicts the lifetime of a trial and how the above three methods are
| called in the trial.
|
| .. image:: ../../../../image/sampling-sequence.png
|
| |
|
| Method resolution order:
| BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __str__(self) -> 'str'
| Return str(self).
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'infer_relative_search_space', 'sampl...
class BruteForceSampler(optuna.samplers._base.BaseSampler)
| BruteForceSampler(seed: 'int | None' = None, avoid_premature_stop: 'bool' = False) -> 'None'
|
| Sampler that performs exhaustive search over the define-by-run search space.
|
| This sampler performs exhaustive search on the defined search space.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| c = trial.suggest_categorical("c", ["float", "int"])
| if c == "float":
| return trial.suggest_float("x", 1, 3, step=0.5)
| elif c == "int":
| a = trial.suggest_int("a", 1, 3)
| b = trial.suggest_int("b", a, 3)
| return a + b
|
|
| study = optuna.create_study(sampler=optuna.samplers.BruteForceSampler())
| study.optimize(objective)
|
| Note:
| The defined search space must be finite. Therefore, when using
| :class:`~optuna.distributions.FloatDistribution` or
| :func:`~optuna.trial.Trial.suggest_float`, ``step=None`` is not allowed.
|
| Note:
| The sampler may fail to try the entire search space in when the suggestion ranges or
| parameters are changed in the same :class:`~optuna.study.Study`.
|
| Args:
| seed:
| A seed to fix the order of trials as the search order randomly shuffled. Please note
| that it is not recommended using this option in distributed optimization settings since
| this option cannot ensure the order of trials and may increase the number of duplicate
| suggestions during distributed optimization.
| avoid_premature_stop:
| If :obj:`True`, the sampler performs a strict exhaustive search. Please note
| that enabling this option may increase the likelihood of duplicate sampling.
| When this option is not enabled (default), the sampler applies a looser criterion for
| determining when to stop the search, which may result in incomplete coverage of the
| search space. For more information, see https://github.com/optuna/optuna/issues/5780.
|
| .. note::
| Added in v3.1.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| Method resolution order:
| BruteForceSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, seed: 'int | None' = None, avoid_premature_stop: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class CmaEsSampler(optuna.samplers._base.BaseSampler)
| CmaEsSampler(*, x0: 'dict[str, Any] | None' = None, sigma0: 'float | None' = None, n_startup_trials: 'int' = 1, independent_sampler: 'BaseSampler | None' = None, warn_independent_sampling: 'bool' = True, seed: 'int | None' = None, consider_pruned_trials: 'bool' = False, restart_strategy: 'str | None' = None, popsize: 'int | None' = None, inc_popsize: 'int' = -1, use_separable_cma: 'bool' = False, with_margin: 'bool' = False, lr_adapt: 'bool' = False, source_trials: 'list[FrozenTrial] | None' = None) -> 'None'
|
| A sampler using `cmaes <https://github.com/CyberAgentAILab/cmaes>`__ as the backend.
|
| Example:
|
| Optimize a simple quadratic function by using :class:`~optuna.samplers.CmaEsSampler`.
|
| .. code-block:: console
|
| $ pip install cmaes
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| y = trial.suggest_int("y", -1, 1)
| return x**2 + y
|
|
| sampler = optuna.samplers.CmaEsSampler()
| study = optuna.create_study(sampler=sampler)
| study.optimize(objective, n_trials=20)
|
| Please note that this sampler does not support CategoricalDistribution.
| If your search space includes categorical parameters, it is recommended to use
| `CatCmawmSampler <https://hub.optuna.org/samplers/catcmawm/>`__ available on
| `OptunaHub <https://hub.optuna.org/>`__.
|
| Furthermore, there is room for performance improvements in parallel
| optimization settings. This sampler cannot use some trials for updating
| the parameters of multivariate normal distribution.
|
| For further information about CMA-ES algorithm, please refer to the following papers:
|
| - `N. Hansen, The CMA Evolution Strategy: A Tutorial. arXiv:1604.00772, 2016.
| <https://arxiv.org/abs/1604.00772>`__
| - `A. Auger and N. Hansen. A restart CMA evolution strategy with increasing population
| size. In Proceedings of the IEEE Congress on Evolutionary Computation (CEC 2005),
| pages 1769–1776. IEEE Press, 2005. <https://doi.org/10.1109/CEC.2005.1554902>`__
| - `N. Hansen. Benchmarking a BI-Population CMA-ES on the BBOB-2009 Function Testbed.
| GECCO Workshop, 2009. <https://doi.org/10.1145/1570256.1570333>`__
| - `Raymond Ros, Nikolaus Hansen. A Simple Modification in CMA-ES Achieving Linear Time and
| Space Complexity. 10th International Conference on Parallel Problem Solving From Nature,
| Sep 2008, Dortmund, Germany. inria-00287367. <https://doi.org/10.1007/978-3-540-87700-4_30>`__
| - `Masahiro Nomura, Shuhei Watanabe, Youhei Akimoto, Yoshihiko Ozaki, Masaki Onishi.
| Warm Starting CMA-ES for Hyperparameter Optimization, AAAI. 2021.
| <https://doi.org/10.1609/aaai.v35i10.17109>`__
| - `R. Hamano, S. Saito, M. Nomura, S. Shirakawa. CMA-ES with Margin: Lower-Bounding Marginal
| Probability for Mixed-Integer Black-Box Optimization, GECCO. 2022.
| <https://doi.org/10.1145/3512290.3528827>`__
| - `M. Nomura, Y. Akimoto, I. Ono. CMA-ES with Learning Rate Adaptation: Can CMA-ES with
| Default Population Size Solve Multimodal and Noisy Problems?, GECCO. 2023.
| <https://doi.org/10.1145/3583131.3590358>`__
|
| .. seealso::
| You can also use `optuna_integration.PyCmaSampler <https://optuna-integration.readthedocs.io/en/stable/reference/generated/optuna_integration.PyCmaSampler.html#optuna_integration.PyCmaSampler>`__ which is a sampler using cma
| library as the backend.
|
| Args:
|
| x0:
| A dictionary of an initial parameter values for CMA-ES. By default, the mean of ``low``
| and ``high`` for each distribution is used. Note that ``x0`` is sampled uniformly
| within the search space domain for each restart if you specify ``restart_strategy``
| argument.
|
| .. warning::
| Deprecated in v4.9.0. ``x0`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
|
| sigma0:
| Initial standard deviation of CMA-ES. By default, ``sigma0`` is set to
| ``min_range / 6``, where ``min_range`` denotes the minimum range of the distributions
| in the search space.
|
| .. warning::
| Deprecated in v4.9.0. ``sigma0`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
|
| seed:
| A random seed for CMA-ES.
|
| n_startup_trials:
| The independent sampling is used instead of the CMA-ES algorithm until the given number
| of trials finish in the same study.
|
| independent_sampler:
| A :class:`~optuna.samplers.BaseSampler` instance that is used for independent
| sampling. The parameters not contained in the relative search space are sampled
| by this sampler.
| The search space for :class:`~optuna.samplers.CmaEsSampler` is determined by
| :func:`~optuna.search_space.intersection_search_space()`.
|
| If :obj:`None` is specified, :class:`~optuna.samplers.RandomSampler` is used
| as the default.
|
| .. seealso::
| :class:`optuna.samplers` module provides built-in independent samplers
| such as :class:`~optuna.samplers.RandomSampler` and
| :class:`~optuna.samplers.TPESampler`.
|
| warn_independent_sampling:
| If this is :obj:`True`, a warning message is emitted when
| the value of a parameter is sampled by using an independent sampler.
|
| Note that the parameters of the first trial in a study are always sampled
| via an independent sampler, so no warning messages are emitted in this case.
|
| restart_strategy:
| Strategy for restarting CMA-ES optimization when converges to a local minimum.
| If :obj:`None` is given, CMA-ES will not restart (default).
| If 'ipop' is given, CMA-ES will restart with increasing population size.
| if 'bipop' is given, CMA-ES will restart with the population size
| increased or decreased.
| Please see also ``inc_popsize`` parameter.
|
| .. warning::
| Deprecated in v4.4.0. ``restart_strategy`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| From v4.4.0 onward, ``restart_strategy`` automatically falls back to ``None``, and
| ``restart_strategy`` will be supported in OptunaHub.
| See https://github.com/optuna/optuna/releases/tag/v4.4.0.
|
| popsize:
| A population size of CMA-ES.
|
| inc_popsize:
| Multiplier for increasing population size before each restart.
| This argument will be used when ``restart_strategy = 'ipop'``
| or ``restart_strategy = 'bipop'`` is specified.
|
| .. warning::
| Deprecated in v4.4.0. ``inc_popsize`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| From v4.4.0 onward, ``inc_popsize`` is no longer utilized within Optuna, and
| ``inc_popsize`` will be supported in OptunaHub.
| See https://github.com/optuna/optuna/releases/tag/v4.4.0.
|
| consider_pruned_trials:
| If this is :obj:`True`, the PRUNED trials are considered for sampling.
|
| .. note::
| Added in v2.0.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.0.0.
|
| .. note::
| It is suggested to set this flag :obj:`False` when the
| :class:`~optuna.pruners.MedianPruner` is used. On the other hand, it is suggested
| to set this flag :obj:`True` when the :class:`~optuna.pruners.HyperbandPruner` is
| used. Please see `the benchmark result
| <https://github.com/optuna/optuna/pull/1229>`__ for the details.
|
| use_separable_cma:
| If this is :obj:`True`, the covariance matrix is constrained to be diagonal.
| Due to reduce the model complexity, the learning rate for the covariance matrix
| is increased. Consequently, this algorithm outperforms CMA-ES on separable functions.
|
| .. note::
| Added in v2.6.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.6.0.
|
| with_margin:
| If this is :obj:`True`, CMA-ES with margin is used. This algorithm prevents samples in
| each discrete distribution (:class:`~optuna.distributions.FloatDistribution` with
| ``step`` and :class:`~optuna.distributions.IntDistribution`) from being fixed to a single
| point.
| Currently, this option cannot be used with ``use_separable_cma=True``.
|
| .. note::
| Added in v3.1.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| lr_adapt:
| If this is :obj:`True`, CMA-ES with learning rate adaptation is used.
| This algorithm focuses on working well on multimodal and/or noisy problems
| with default settings.
| Currently, this option cannot be used with ``use_separable_cma=True`` or
| ``with_margin=True``.
|
| .. note::
| Added in v3.3.0 or later, as an experimental feature.
| The interface may change in newer versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| source_trials:
| This option is for Warm Starting CMA-ES, a method to transfer prior knowledge on
| similar HPO tasks through the initialization of CMA-ES. This method estimates a
| promising distribution from ``source_trials`` and generates the parameter of
| multivariate gaussian distribution. Please note that it is prohibited to use
| ``use_separable_cma`` argument together.
|
| .. note::
| Added in v2.6.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.6.0.
|
| Method resolution order:
| CmaEsSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, x0: 'dict[str, Any] | None' = None, sigma0: 'float | None' = None, n_startup_trials: 'int' = 1, independent_sampler: 'BaseSampler | None' = None, warn_independent_sampling: 'bool' = True, seed: 'int | None' = None, consider_pruned_trials: 'bool' = False, restart_strategy: 'str | None' = None, popsize: 'int | None' = None, inc_popsize: 'int' = -1, use_separable_cma: 'bool' = False, with_margin: 'bool' = False, lr_adapt: 'bool' = False, source_trials: 'list[FrozenTrial] | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: "'optuna.Study'", trial: "'optuna.trial.FrozenTrial'", state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'optuna.Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: "'optuna.Study'", trial: "'optuna.trial.FrozenTrial'") -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: "'optuna.Study'", trial: "'optuna.trial.FrozenTrial'", param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: "'optuna.Study'", trial: "'optuna.trial.FrozenTrial'", search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class GPSampler(optuna.samplers._base.BaseSampler)
| GPSampler(*, seed: 'int | None' = None, independent_sampler: 'BaseSampler | None' = None, n_startup_trials: 'int' = 10, deterministic_objective: 'bool' = False, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, warn_independent_sampling: 'bool' = True) -> 'None'
|
| Sampler using Gaussian process-based Bayesian optimization.
|
| This sampler fits a Gaussian process (GP) to the objective function and optimizes
| the acquisition function to suggest the next parameters.
|
| The current implementation uses Matern kernel with nu=2.5 (twice differentiable) with automatic
| relevance determination (ARD) for the length scale of each parameter.
| The hyperparameters of the kernel are obtained by maximizing the marginal log-likelihood of the
| hyperparameters given the past trials.
| To prevent overfitting, Gamma prior is introduced for kernel scale and noise variance and
| a hand-crafted prior is introduced for inverse squared lengthscales.
|
| As an acquisition function, we use:
|
| - log expected improvement (logEI) for single-objective optimization,
| - log expected hypervolume improvement (logEHVI) for Multi-objective optimization, and
| - the summation of logEI and the logarithm of the feasible probability with the independent
| assumption of each constraint for (black-box inequality) constrained optimization.
|
| For further information about these acquisition functions, please refer to the following
| papers:
|
| - `Unexpected Improvements to Expected Improvement for Bayesian Optimization
| <https://arxiv.org/abs/2310.20708>`__
| - `Differentiable Expected Hypervolume Improvement for Parallel Multi-Objective Bayesian
| Optimization <https://arxiv.org/abs/2006.05078>`__
| - `Bayesian Optimization with Inequality Constraints
| <https://proceedings.mlr.press/v32/gardner14.pdf>`__
|
| Please also check our articles:
|
| - `[Optuna v4.5] Gaussian Process-Based Sampler (GPSampler) Can Now Perform Constrained
| Multi-Objective Optimization <https://medium.com/optuna/optuna-v4-5-81e78d8e077a>`__
| - `[Optuna v4.2] Gaussian Process-Based Sampler (GPSampler) Can Now Handle Inequality
| Constraints
| <https://medium.com/optuna/optuna-v4-2-gaussian-process-based-sampler-can-now-handle-inequality-constraints-a4f68e8ee810>`__
| - `Introducing Optuna's Native GPSampler
| <https://medium.com/optuna/introducing-optunas-native-gpsampler-0aa9aa3b4840>`__
|
| The optimization of the acquisition function is performed via:
|
| 1. Collect the best param from the past trials,
| 2. Collect ``n_preliminary_samples`` points using Quasi-Monte Carlo (QMC) sampling,
| 3. Choose the best point from the collected points,
| 4. Choose ``n_local_search - 2`` points from the collected points using the roulette
| selection,
| 5. Perform a local search for each chosen point as an initial point, and
| 6. Return the point with the best acquisition function value as the next parameter.
|
| Decoupled optimizer update with a batched evaluation is employed to perform a batch of local
| searches simultaneously, specifically speeding up Step 5 above.
|
| The following paper details the methodology:
|
| - `Batch Acquisition Function Evaluations and Decouple Optimizer Updates for Faster Bayesian
| Optimization <https://arxiv.org/abs/2511.13625>`__
|
| Note that the procedures for non single-objective optimization setups are slightly different
| from the single-objective version described above, but we omit the descriptions for the others
| for brevity.
|
| The local search iteratively optimizes the acquisition function by repeating:
|
| 1. Gradient ascent using l-BFGS-B for continuous parameters, and
| 2. Line search or exhaustive search for each discrete parameter independently.
|
| The local search is terminated if the routine stops updating the best parameter set or the
| maximum number of iterations is reached.
|
| We use line search instead of rounding the results from the continuous optimization since EI
| typically yields a high value between one grid and its adjacent grid.
|
| .. note::
| This sampler requires ``scipy`` and ``torch``.
| You can install these dependencies with ``pip install scipy torch``.
|
| Args:
| seed:
| Random seed to initialize internal random number generator.
| Defaults to :obj:`None` (a seed is picked randomly).
| independent_sampler:
| Sampler used for initial sampling (for the first ``n_startup_trials`` trials)
| and for conditional parameters. Defaults to :obj:`None`
| (a random sampler with the same ``seed`` is used).
| n_startup_trials:
| Number of initial trials. Defaults to 10.
| deterministic_objective:
| Whether the objective function is deterministic or not.
| If :obj:`True`, the sampler will fix the noise variance of the surrogate model to
| the minimum value (slightly above 0 to ensure numerical stability).
| Defaults to :obj:`False`. Currently, all the objectives will be assume to be
| deterministic if :obj:`True`.
| constraints_func:
| An optional function that computes the objective constraints. It must take a
| :class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
| be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
| constraints is violated. A value equal to or smaller than 0 is considered feasible.
| If ``constraints_func`` returns more than one value for a trial, that trial is
| considered feasible if and only if all values are equal to 0 or smaller.
|
| The ``constraints_func`` will be evaluated after each successful trial.
| The function won't be called when trials fail or are pruned, but this behavior is
| subject to change in future releases.
| warn_independent_sampling:
| If this is :obj:`True`, a warning message is emitted when
| the value of a parameter is sampled by using an independent sampler,
| meaning that no GP model is used in the sampling.
| Note that the parameters of the first trial in a study are always sampled
| via an independent sampler, so no warning messages are emitted in this case.
|
| .. note::
| Added in v3.6.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.6.0.
|
| Method resolution order:
| GPSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, seed: 'int | None' = None, independent_sampler: 'BaseSampler | None' = None, n_startup_trials: 'int' = 10, deterministic_objective: 'bool' = False, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, warn_independent_sampling: 'bool' = True) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class GridSampler(optuna.samplers._base.BaseSampler)
| GridSampler(search_space: 'Mapping[str, Sequence[GridValueType]]', seed: 'int | None' = None) -> 'None'
|
| Sampler that performs exhaustive search over the define-and-run user-specified grids.
|
| With :class:`~optuna.samplers.GridSampler`, the trials suggest all combinations of parameters
| in the given search space during the study.
|
| .. note::
| :class:`~optuna.samplers.BruteForceSampler` also provides the exhaustive search feature.
| Unlike :class:`~optuna.samplers.GridSampler`, :class:`~optuna.samplers.BruteForceSampler`
| does not ask users to provide search space and it supports hierarchical, aka dynamic search
| space, enabling users to seamlessly enjoy the exhaustive search.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -100, 100)
| y = trial.suggest_int("y", -100, 100)
| return x**2 + y**2
|
|
| search_space = {"x": [-50, 0, 50], "y": [-99, 0, 99]}
| study = optuna.create_study(sampler=optuna.samplers.GridSampler(search_space))
| study.optimize(objective)
|
| Note:
|
| This sampler with :ref:`ask_and_tell` raises :exc:`RuntimeError` just after evaluating
| the final grid. This is because :class:`~optuna.samplers.GridSampler` automatically
| stops the optimization if all combinations in the passed ``search_space`` have already
| been evaluated, internally invoking the :func:`~optuna.study.Study.stop` method.
| As a workaround, we need to handle the error manually as in
| https://github.com/optuna/optuna/issues/4121#issuecomment-1305289910.
|
| Note:
|
| :class:`~optuna.samplers.GridSampler` does not take care of a parameter's quantization
| specified by discrete suggest methods but just samples one of values specified in the
| search space. E.g., in the following code snippet, either of ``-0.5`` or ``0.5`` is
| sampled as ``x`` instead of an integer point.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| # The following suggest method specifies integer points between -5 and 5.
| x = trial.suggest_float("x", -5, 5, step=1)
| return x**2
|
|
| # Non-int points are specified in the grid.
| search_space = {"x": [-0.5, 0.5]}
| study = optuna.create_study(sampler=optuna.samplers.GridSampler(search_space))
| study.optimize(objective, n_trials=2)
|
| Note:
| A parameter configuration in the grid is not considered finished until its trial is
| finished. Therefore, during distributed optimization where trials run concurrently,
| different workers will occasionally suggest the same parameter configuration.
| The total number of actual trials may therefore exceed the size of the grid.
|
| Note:
| All parameters must be specified when using :class:`~optuna.samplers.GridSampler` with
| :meth:`~optuna.study.Study.enqueue_trial`.
|
| Args:
| search_space:
| A dictionary whose key and value are a parameter name and the corresponding candidates
| of values, respectively.
| seed:
| A seed to fix the order of trials as the grid is randomly shuffled. This shuffle is
| beneficial when the number of grids is larger than ``n_trials`` in
| :meth:`~optuna.Study.optimize` to suppress suggesting similar grids. Please note
| that fixing ``seed`` for each process is strongly recommended in distributed
| optimization to avoid duplicated suggestions.
|
| Method resolution order:
| GridSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, search_space: 'Mapping[str, Sequence[GridValueType]]', seed: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| is_exhausted(self, study: 'Study') -> 'bool'
| Return True if all the possible params are evaluated, otherwise return False.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class NSGAIIISampler(optuna.samplers._ga._base.BaseGASampler)
| NSGAIIISampler(*, population_size: 'int' = 50, mutation_prob: 'float | None' = None, crossover: 'BaseCrossover | None' = None, crossover_prob: 'float' = 0.9, swapping_prob: 'float' = 0.5, seed: 'int | None' = None, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, reference_points: 'np.ndarray | None' = None, dividing_parameter: 'int' = 3, elite_population_selection_strategy: 'Callable[[Study, list[FrozenTrial]], list[FrozenTrial]] | None' = None, child_generation_strategy: 'Callable[[Study, dict[str, BaseDistribution], list[FrozenTrial]], dict[str, Any]] | None' = None, after_trial_strategy: 'Callable[[Study, FrozenTrial, TrialState, Sequence[float] | None], None] | None' = None) -> 'None'
|
| Multi-objective sampler using the NSGA-III algorithm.
|
| NSGA-III stands for "Nondominated Sorting Genetic Algorithm III",
| which is a modified version of NSGA-II for many objective optimization problem.
|
| .. note::
| When optimizing many objectives, a large fraction of trials may become non-dominated
| in general due to the curse of dimensionality in the objective space. If possible, consider
| modeling some objectives as constraints. Constraints can be passed via the
| `constraints_func` argument at the sampler initialization.
| :class:`~optuna.samplers.NSGAIISampler`, :class:`~optuna.samplers.TPESampler`, and
| :class:`~optuna.samplers.GPSampler` also support constrained multi-objective optimization.
| Since Bayesian optimization is often sample efficient, it is worth considering
| :class:`~optuna.samplers.TPESampler`, or :class:`~optuna.samplers.GPSampler` for
| ``n_trials < 1000``.
|
| For further information about NSGA-III, please refer to the following papers:
|
| - `An Evolutionary Many-Objective Optimization Algorithm Using Reference-Point-Based
| Nondominated Sorting Approach, Part I: Solving Problems With Box Constraints
| <https://doi.org/10.1109/TEVC.2013.2281535>`__
| - `An Evolutionary Many-Objective Optimization Algorithm Using Reference-Point-Based
| Nondominated Sorting Approach, Part II: Handling Constraints and Extending to an Adaptive
| Approach
| <https://doi.org/10.1109/TEVC.2013.2281534>`__
|
| Args:
| reference_points:
| A 2 dimension ``numpy.ndarray`` with objective dimension columns. Represents
| a list of reference points which is used to determine who to survive.
| After non-dominated sort, who out of borderline front are going to survived is
| determined according to how sparse the closest reference point of each individual is.
| In the default setting the algorithm uses `uniformly` spread points to diversify the
| result. It is also possible to reflect your `preferences` by giving an arbitrary set of
| `target` points since the algorithm prioritizes individuals around reference points.
|
| dividing_parameter:
| A parameter to determine the density of default reference points. This parameter
| determines how many divisions are made between reference points on each axis. The
| smaller this value is, the less reference points you have. The default value is 3.
| Note that this parameter is not used when ``reference_points`` is not :obj:`None`.
|
| .. note::
| Other parameters than ``reference_points`` and ``dividing_parameter`` are the same as
| :class:`~optuna.samplers.NSGAIISampler`.
|
| .. note::
| Added in v3.2.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.2.0.
|
| Method resolution order:
| NSGAIIISampler
| optuna.samplers._ga._base.BaseGASampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, population_size: 'int' = 50, mutation_prob: 'float | None' = None, crossover: 'BaseCrossover | None' = None, crossover_prob: 'float' = 0.9, swapping_prob: 'float' = 0.5, seed: 'int | None' = None, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, reference_points: 'np.ndarray | None' = None, dividing_parameter: 'int' = 3, elite_population_selection_strategy: 'Callable[[Study, list[FrozenTrial]], list[FrozenTrial]] | None' = None, child_generation_strategy: 'Callable[[Study, dict[str, BaseDistribution], list[FrozenTrial]], dict[str, Any]] | None' = None, after_trial_strategy: 'Callable[[Study, FrozenTrial, TrialState, Sequence[float] | None], None] | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| select_parent(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Select parent trials from the population for the given generation.
|
| This method is called once per generation to select parents from
| the population of the current generation.
|
| Output of this function is cached in the study system attributes.
|
| This method must be implemented in a subclass to define the specific selection strategy.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._ga._base.BaseGASampler:
|
| get_parent_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the parent population of the given generation.
|
| This method caches the parent population in the study's system attributes.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials. If `generation == 0`, returns an empty list.
|
| get_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the population of the given generation.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of frozen trials in the given generation.
|
| get_trial_generation(self, study: 'Study', trial: 'FrozenTrial') -> 'int'
| Get the generation number of the given trial.
|
| This method returns the generation number of the specified trial. If the generation number
| is not set in the trial's system attributes, it will calculate and set the generation
| number.
|
| The current generation number depends on the maximum generation number of all completed
| trials.
|
| Args:
| study:
| Study object which trial belongs to.
| trial:
| Trial object to get the generation number.
|
| Returns:
| Generation number of the given trial.
|
| ----------------------------------------------------------------------
| Class methods inherited from optuna.samplers._ga._base.BaseGASampler:
|
| __init_subclass__(**kwargs: 'Any')
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._ga._base.BaseGASampler:
|
| population_size
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class NSGAIISampler(optuna.samplers._ga._base.BaseGASampler)
| NSGAIISampler(*, population_size: 'int' = 50, mutation_prob: 'float | None' = None, crossover: 'BaseCrossover | None' = None, crossover_prob: 'float' = 0.9, swapping_prob: 'float' = 0.5, seed: 'int | None' = None, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, elite_population_selection_strategy: 'Callable[[Study, list[FrozenTrial]], list[FrozenTrial]] | None' = None, child_generation_strategy: 'Callable[[Study, dict[str, BaseDistribution], list[FrozenTrial]], dict[str, Any]] | None' = None, after_trial_strategy: 'Callable[[Study, FrozenTrial, TrialState, Sequence[float] | None], None] | None' = None) -> 'None'
|
| Multi-objective sampler using the NSGA-II algorithm.
|
| NSGA-II stands for "Nondominated Sorting Genetic Algorithm II",
| which is a well known, fast and elitist multi-objective genetic algorithm.
|
| For further information about NSGA-II, please refer to the following paper:
|
| - `A fast and elitist multiobjective genetic algorithm: NSGA-II
| <https://doi.org/10.1109/4235.996017>`__
|
| .. note::
| :class:`~optuna.samplers.TPESampler` became much faster in v4.0.0 and supports several
| features not supported by ``NSGAIISampler`` such as handling of dynamic search
| space and categorical distance. To use :class:`~optuna.samplers.TPESampler`, you need to
| explicitly specify the sampler as follows:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -100, 100)
| y = trial.suggest_categorical("y", [-1, 0, 1])
| f1 = x**2 + y
| f2 = -((x - 2) ** 2 + y)
| return f1, f2
|
|
| # We minimize the first objective and maximize the second objective.
| sampler = optuna.samplers.TPESampler()
| study = optuna.create_study(directions=["minimize", "maximize"], sampler=sampler)
| study.optimize(objective, n_trials=100)
|
| Please also check `our article
| <https://medium.com/optuna/significant-speed-up-of-multi-objective-tpesampler-in-optuna-v4-0-0-2bacdcd1d99b>`__
| for more details of the speedup in v4.0.0.
|
| Args:
| population_size:
| Number of individuals (trials) in a generation.
| ``population_size`` must be greater than or equal to ``crossover.n_parents``.
| For :class:`~optuna.samplers.nsgaii.UNDXCrossover` and
| :class:`~optuna.samplers.nsgaii.SPXCrossover`, ``n_parents=3``, and for the other
| algorithms, ``n_parents=2``.
|
| mutation_prob:
| Probability of mutating each parameter when creating a new individual.
| If :obj:`None` is specified, the value ``1.0 / len(parent_trial.params)`` is used
| where ``parent_trial`` is the parent trial of the target individual.
|
| crossover:
| Crossover to be applied when creating child individuals.
| The available crossovers are listed here:
| https://optuna.readthedocs.io/en/stable/reference/samplers/nsgaii.html.
|
| :class:`~optuna.samplers.nsgaii.UniformCrossover` is always applied to parameters
| sampled from :class:`~optuna.distributions.CategoricalDistribution`, and by
| default for parameters sampled from other distributions unless this argument
| is specified.
|
| For more information on each of the crossover method, please refer to
| specific crossover documentation.
|
| crossover_prob:
| Probability that a crossover (parameters swapping between parents) will occur
| when creating a new individual.
|
| swapping_prob:
| Probability of swapping each parameter of the parents during crossover.
|
| seed:
| Seed for random number generator.
|
| constraints_func:
| An optional function that computes the objective constraints. It must take a
| :class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
| be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
| constraints is violated. A value equal to or smaller than 0 is considered feasible.
| If ``constraints_func`` returns more than one value for a trial, that trial is
| considered feasible if and only if all values are equal to 0 or smaller.
|
| The ``constraints_func`` will be evaluated after each successful trial.
| The function won't be called when trials fail or they are pruned, but this behavior is
| subject to change in the future releases.
|
| The constraints are handled by the constrained domination. A trial x is said to
| constrained-dominate a trial y, if any of the following conditions is true:
|
| 1. Trial x is feasible and trial y is not.
| 2. Trial x and y are both infeasible, but trial x has a smaller overall violation.
| 3. Trial x and y are feasible and trial x dominates trial y.
|
| .. note::
| Added in v2.5.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.5.0.
|
| elite_population_selection_strategy:
| The selection strategy for determining the individuals to survive from the current
| population pool. Default to :obj:`None`.
|
| .. note::
| The arguments ``elite_population_selection_strategy`` was added in v3.3.0 as an
| experimental feature. The interface may change in newer versions without prior
| notice.
| See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| child_generation_strategy:
| The strategy for generating child parameters from parent trials. Defaults to
| :obj:`None`.
|
| .. note::
| The arguments ``child_generation_strategy`` was added in v3.3.0 as an experimental
| feature. The interface may change in newer versions without prior notice.
| See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| after_trial_strategy:
| A set of procedure to be conducted after each trial. Defaults to :obj:`None`.
|
| .. note::
| The arguments ``after_trial_strategy`` was added in v3.3.0 as an experimental
| feature. The interface may change in newer versions without prior notice.
| See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Method resolution order:
| NSGAIISampler
| optuna.samplers._ga._base.BaseGASampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, population_size: 'int' = 50, mutation_prob: 'float | None' = None, crossover: 'BaseCrossover | None' = None, crossover_prob: 'float' = 0.9, swapping_prob: 'float' = 0.5, seed: 'int | None' = None, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, elite_population_selection_strategy: 'Callable[[Study, list[FrozenTrial]], list[FrozenTrial]] | None' = None, child_generation_strategy: 'Callable[[Study, dict[str, BaseDistribution], list[FrozenTrial]], dict[str, Any]] | None' = None, after_trial_strategy: 'Callable[[Study, FrozenTrial, TrialState, Sequence[float] | None], None] | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| select_parent(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Select parent trials from the population for the given generation.
|
| This method is called once per generation to select parents from
| the population of the current generation.
|
| Output of this function is cached in the study system attributes.
|
| This method must be implemented in a subclass to define the specific selection strategy.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._ga._base.BaseGASampler:
|
| get_parent_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the parent population of the given generation.
|
| This method caches the parent population in the study's system attributes.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of parent frozen trials. If `generation == 0`, returns an empty list.
|
| get_population(self, study: 'Study', generation: 'int') -> 'list[FrozenTrial]'
| Get the population of the given generation.
|
| Args:
| study:
| Target study object.
| generation:
| Target generation number.
|
| Returns:
| List of frozen trials in the given generation.
|
| get_trial_generation(self, study: 'Study', trial: 'FrozenTrial') -> 'int'
| Get the generation number of the given trial.
|
| This method returns the generation number of the specified trial. If the generation number
| is not set in the trial's system attributes, it will calculate and set the generation
| number.
|
| The current generation number depends on the maximum generation number of all completed
| trials.
|
| Args:
| study:
| Study object which trial belongs to.
| trial:
| Trial object to get the generation number.
|
| Returns:
| Generation number of the given trial.
|
| ----------------------------------------------------------------------
| Class methods inherited from optuna.samplers._ga._base.BaseGASampler:
|
| __init_subclass__(**kwargs: 'Any')
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._ga._base.BaseGASampler:
|
| population_size
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class PartialFixedSampler(optuna.samplers._base.BaseSampler)
| PartialFixedSampler(fixed_params: 'dict[str, Any]', base_sampler: 'BaseSampler') -> 'None'
|
| Sampler with partially fixed parameters.
|
| Example:
|
| After several steps of optimization, you can fix the value of ``y`` and re-optimize it.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| y = trial.suggest_int("y", -1, 1)
| return x**2 + y
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=10)
|
| best_params = study.best_params
| fixed_params = {"y": best_params["y"]}
| partial_sampler = optuna.samplers.PartialFixedSampler(fixed_params, study.sampler)
|
| study.sampler = partial_sampler
| study.optimize(objective, n_trials=10)
|
| Args:
|
| fixed_params:
| A dictionary of parameters to be fixed.
|
| base_sampler:
| A sampler which samples unfixed parameters.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Method resolution order:
| PartialFixedSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, fixed_params: 'dict[str, Any]', base_sampler: 'BaseSampler') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class QMCSampler(optuna.samplers._base.BaseSampler)
| QMCSampler(*, qmc_type: 'str' = 'sobol', scramble: 'bool' = False, seed: 'int | None' = None, independent_sampler: 'BaseSampler | None' = None, warn_asynchronous_seeding: 'bool' = True, warn_independent_sampling: 'bool' = True) -> 'None'
|
| A Quasi Monte Carlo Sampler that generates low-discrepancy sequences.
|
| Quasi Monte Carlo (QMC) sequences are designed to have lower discrepancies than
| standard random sequences. They are known to perform better than the standard
| random sequences in hyperparameter optimization.
|
| For further information about the use of QMC sequences for hyperparameter optimization,
| please refer to the following paper:
|
| - `Bergstra, James, and Yoshua Bengio. Random search for hyper-parameter optimization.
| Journal of machine learning research 13.2, 2012.
| <https://jmlr.org/papers/v13/bergstra12a.html>`__
|
| We use the QMC implementations in Scipy. For the details of the QMC algorithm,
| see the Scipy API references on `scipy.stats.qmc
| <https://scipy.github.io/devdocs/reference/stats.qmc.html>`__.
|
| .. note::
| If your search space contains categorical parameters, it samples the categorical
| parameters by its `independent_sampler` without using QMC algorithm.
|
| .. note::
| The search space of the sampler is determined by either previous trials in the study or
| the first trial that this sampler samples.
|
| If there are previous trials in the study, :class:`~optuna.samplers.QMCSampler` infers its
| search space using the trial which was created first in the study.
|
| Otherwise (if the study has no previous trials), :class:`~optuna.samplers.QMCSampler`
| samples the first trial using its `independent_sampler` and then infers the search space
| in the second trial.
|
| As mentioned above, the search space of the :class:`~optuna.samplers.QMCSampler` is
| determined by the first trial of the study. Once the search space is determined, it cannot
| be changed afterwards.
|
| Args:
| qmc_type:
| The type of QMC sequence to be sampled. This must be one of
| `"halton"` and `"sobol"`. Default is `"sobol"`.
|
| .. note::
| Sobol' sequence is designed to have low-discrepancy property when the number of
| samples is :math:`n=2^m` for each positive integer :math:`m`. When it is possible
| to pre-specify the number of trials suggested by `QMCSampler`, it is recommended
| that the number of trials should be set as power of two.
|
| scramble:
| If this option is :obj:`True`, scrambling (randomization) is applied to the QMC
| sequences.
|
| seed:
| A seed for ``QMCSampler``. This argument is used only when ``scramble`` is :obj:`True`.
| If this is :obj:`None`, the seed is initialized randomly. Default is :obj:`None`.
|
| .. note::
| When using multiple :class:`~optuna.samplers.QMCSampler`'s in parallel and/or
| distributed optimization, all the samplers must share the same seed when the
| `scrambling` is enabled. Otherwise, the low-discrepancy property of the samples
| will be degraded.
|
| independent_sampler:
| A :class:`~optuna.samplers.BaseSampler` instance that is used for independent
| sampling. The first trial of the study and the parameters not contained in the
| relative search space are sampled by this sampler.
|
| If :obj:`None` is specified, :class:`~optuna.samplers.RandomSampler` is used
| as the default.
|
| .. seealso::
| :class:`~optuna.samplers` module provides built-in independent samplers
| such as :class:`~optuna.samplers.RandomSampler` and
| :class:`~optuna.samplers.TPESampler`.
|
| warn_independent_sampling:
| If this is :obj:`True`, a warning message is emitted when
| the value of a parameter is sampled by using an independent sampler.
|
| Note that the parameters of the first trial in a study are sampled via an
| independent sampler in most cases, so no warning messages are emitted in such cases.
|
| warn_asynchronous_seeding:
| If this is :obj:`True`, a warning message is emitted when the scrambling
| (randomization) is applied to the QMC sequence and the random seed of the sampler is
| not set manually.
|
| .. note::
| When using parallel and/or distributed optimization without manually
| setting the seed, the seed is set randomly for each instances of
| :class:`~optuna.samplers.QMCSampler` for different workers, which ends up
| asynchronous seeding for multiple samplers used in the optimization.
|
| .. seealso::
| See parameter ``seed`` in :class:`~optuna.samplers.QMCSampler`.
|
| Example:
|
| Optimize a simple quadratic function by using :class:`~optuna.samplers.QMCSampler`.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| y = trial.suggest_int("y", -1, 1)
| return x**2 + y
|
|
| sampler = optuna.samplers.QMCSampler()
| study = optuna.create_study(sampler=sampler)
| study.optimize(objective, n_trials=8)
|
| .. note::
| Added in v3.0.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| Method resolution order:
| QMCSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, qmc_type: 'str' = 'sobol', scramble: 'bool' = False, seed: 'int | None' = None, independent_sampler: 'BaseSampler | None' = None, warn_asynchronous_seeding: 'bool' = True, warn_independent_sampling: 'bool' = True) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class RandomSampler(optuna.samplers._base.BaseSampler)
| RandomSampler(seed: 'int | None' = None) -> 'None'
|
| Sampler using random sampling.
|
| This sampler is based on *independent sampling*.
| See also :class:`~optuna.samplers.BaseSampler` for more details of 'independent sampling'.
|
| Example:
|
| .. testcode::
|
| import optuna
| from optuna.samplers import RandomSampler
|
|
| def objective(trial):
| x = trial.suggest_float("x", -5, 5)
| return x**2
|
|
| study = optuna.create_study(sampler=RandomSampler())
| study.optimize(objective, n_trials=10)
|
| Args:
| seed: Seed for random number generator.
|
| Method resolution order:
| RandomSampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, seed: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'distributions.BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TPESampler(optuna.samplers._base.BaseSampler)
| TPESampler(*, consider_prior: 'bool | None' = None, prior_weight: 'float | None' = None, consider_magic_clip: 'bool | None' = None, consider_endpoints: 'bool | None' = None, n_startup_trials: 'int' = 10, n_ei_candidates: 'int' = 24, gamma: 'Callable[[int], int] | None' = None, weights: 'Callable[[int], np.ndarray] | None' = None, seed: 'int | None' = None, multivariate: 'bool' = False, group: 'bool' = False, warn_independent_sampling: 'bool | None' = None, constant_liar: 'bool' = False, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, categorical_distance_func: 'dict[str, Callable[[CategoricalChoiceType, CategoricalChoiceType], float]] | None' = None) -> 'None'
|
| Sampler using TPE (Tree-structured Parzen Estimator) algorithm.
|
| On each trial, for each parameter, TPE fits one Gaussian Mixture Model (GMM) ``l(x)`` to
| the set of parameter values associated with the best objective values, and another GMM
| ``g(x)`` to the remaining parameter values. It chooses the parameter value ``x`` that
| maximizes the ratio ``l(x)/g(x)``.
|
| For further information about TPE algorithm, please refer to the following papers:
|
| - `Algorithms for Hyper-Parameter Optimization
| <https://papers.nips.cc/paper/4443-algorithms-for-hyper-parameter-optimization.pdf>`__
| - `Making a Science of Model Search: Hyperparameter Optimization in Hundreds of
| Dimensions for Vision Architectures <http://proceedings.mlr.press/v28/bergstra13.pdf>`__
| - `Tree-Structured Parzen Estimator: Understanding Its Algorithm Components and Their Roles for
| Better Empirical Performance <https://arxiv.org/abs/2304.11127>`__
|
| For multi-objective TPE (MOTPE), please refer to the following papers:
|
| - `Multiobjective Tree-Structured Parzen Estimator for Computationally Expensive Optimization
| Problems <https://doi.org/10.1145/3377930.3389817>`__
| - `Multiobjective Tree-Structured Parzen Estimator <https://doi.org/10.1613/jair.1.13188>`__
|
| For the `categorical_distance_func`, please refer to the following paper:
|
| - `Tree-Structured Parzen Estimator Can Solve Black-Box Combinatorial Optimization More
| Efficiently <https://arxiv.org/abs/2507.08053>`__
|
| Please also check our articles:
|
| - `Significant Speed Up of Multi-Objective TPESampler in Optuna v4.0.0
| <https://medium.com/optuna/significant-speed-up-of-multi-objective-tpesampler-in-optuna-v4-0-0-2bacdcd1d99b>`__
| - `Multivariate TPE Makes Optuna Even More Powerful
| <https://medium.com/optuna/multivariate-tpe-makes-optuna-even-more-powerful-63c4bfbaebe2>`__
|
| Example:
| An example of a single-objective optimization is as follows:
|
| .. testcode::
|
| import optuna
| from optuna.samplers import TPESampler
|
|
| def objective(trial):
| x = trial.suggest_float("x", -10, 10)
| return x**2
|
|
| study = optuna.create_study(sampler=TPESampler())
| study.optimize(objective, n_trials=10)
|
| .. note::
| :class:`~optuna.samplers.TPESampler`, which became much faster in v4.0.0, c.f. `our article
| <https://medium.com/optuna/significant-speed-up-of-multi-objective-tpesampler-in-optuna-v4-0-0-2bacdcd1d99b>`__,
| can handle multi-objective optimization with many trials as well.
| Please note that :class:`~optuna.samplers.NSGAIISampler` will be used by default for
| multi-objective optimization, so if users would like to use
| :class:`~optuna.samplers.TPESampler` for multi-objective optimization, ``sampler`` must be
| explicitly specified when study is created.
|
| Args:
| consider_prior:
| Enhance the stability of Parzen estimator by imposing a Gaussian prior when
| :obj:`True`. The prior is only effective if the sampling distribution is
| either :class:`~optuna.distributions.FloatDistribution`,
| or :class:`~optuna.distributions.IntDistribution`.
|
| .. warning::
| Deprecated in v4.3.0. ``consider_prior`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| From v4.3.0 onward, ``consider_prior`` automatically falls back to ``True``.
| See https://github.com/optuna/optuna/releases/tag/v4.3.0.
| prior_weight:
| The weight of the prior. This argument is used in
| :class:`~optuna.distributions.FloatDistribution`,
| :class:`~optuna.distributions.IntDistribution`, and
| :class:`~optuna.distributions.CategoricalDistribution`.
|
| .. warning::
| Deprecated in v4.9.0. ``prior_weight`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| consider_magic_clip:
| Enable a heuristic to limit the smallest variances of Gaussians used in
| the Parzen estimator.
|
| .. warning::
| Deprecated in v4.9.0. ``consider_magic_clip`` argument will be removed in the
| future. The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| consider_endpoints:
| Take endpoints of domains into account when calculating variances of Gaussians
| in Parzen estimator. See the original paper for details on the heuristics
| to calculate the variances.
|
| .. warning::
| Deprecated in v4.9.0. ``consider_endpoints`` argument will be removed in the
| future. The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| n_startup_trials:
| The random sampling is used instead of the TPE algorithm until the given number
| of trials finish in the same study.
| n_ei_candidates:
| Number of candidate samples used to calculate the expected improvement.
| gamma:
| A function that takes the number of finished trials and returns the number
| of trials to form a density function for samples with low grains.
| See the original paper for more details.
|
| .. warning::
| Deprecated in v4.9.0. ``gamma`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| weights:
| A function that takes the number of finished trials and returns a weight for them.
| See `Making a Science of Model Search: Hyperparameter Optimization in Hundreds of
| Dimensions for Vision Architectures
| <http://proceedings.mlr.press/v28/bergstra13.pdf>`__ for more details.
|
| .. note::
| In the multi-objective case, this argument is only used to compute the weights of
| bad trials, i.e., trials to construct `g(x)` in the `paper
| <https://papers.nips.cc/paper/4443-algorithms-for-hyper-parameter-optimization.pdf>`__
| ). The weights of good trials, i.e., trials to construct `l(x)`, are computed by a
| rule based on the hypervolume contribution proposed in the `paper of MOTPE
| <https://doi.org/10.1613/jair.1.13188>`__.
|
| .. warning::
| Deprecated in v4.9.0. ``weights`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| seed:
| Seed for random number generator.
| multivariate:
| If this is :obj:`True`, the multivariate TPE is used when suggesting parameters.
| The multivariate TPE is reported to outperform the independent TPE. See `BOHB: Robust
| and Efficient Hyperparameter Optimization at Scale
| <http://proceedings.mlr.press/v80/falkner18a.html>`__ and `our article
| <https://medium.com/optuna/multivariate-tpe-makes-optuna-even-more-powerful-63c4bfbaebe2>`__
| for more details.
|
| .. note::
| Added in v2.2.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.2.0.
| group:
| If this and ``multivariate`` are :obj:`True`, the multivariate TPE with the group
| decomposed search space is used when suggesting parameters.
| The sampling algorithm decomposes the search space based on past trials and samples
| from the joint distribution in each decomposed subspace.
| The decomposed subspaces are a partition of the whole search space. Each subspace
| is a maximal subset of the whole search space, which satisfies the following:
| for a trial in completed trials, the intersection of the subspace and the search space
| of the trial becomes subspace itself or an empty set.
| Sampling from the joint distribution on the subspace is realized by multivariate TPE.
| If ``group`` is :obj:`True`, ``multivariate`` must be :obj:`True` as well.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.8.0.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_categorical("x", ["A", "B"])
| if x == "A":
| return trial.suggest_float("y", -10, 10)
| else:
| return trial.suggest_int("z", -10, 10)
|
|
| sampler = optuna.samplers.TPESampler(multivariate=True, group=True)
| study = optuna.create_study(sampler=sampler)
| study.optimize(objective, n_trials=10)
| warn_independent_sampling:
| If this is :obj:`True` and ``multivariate=True``, a warning message is emitted when
| the value of a parameter is sampled by using an independent sampler.
| If ``multivariate=False``, this flag has no effect.
|
| .. warning::
| Deprecated in v4.9.0. ``warn_independent_sampling`` argument will be removed in
| the future. The removal of this feature is currently scheduled for v6.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
| constant_liar:
| If :obj:`True`, penalize running trials to avoid suggesting parameter configurations
| nearby.
|
| .. note::
| Abnormally terminated trials often leave behind a record with a state of
| ``RUNNING`` in the storage.
| Such "zombie" trial parameters will be avoided by the constant liar algorithm
| during subsequent sampling.
| When using an :class:`~optuna.storages.RDBStorage`, it is possible to enable the
| ``heartbeat_interval`` to change the records for abnormally terminated trials to
| ``FAIL``.
|
| .. note::
| It is recommended to set this value to :obj:`True` during distributed
| optimization to avoid having multiple workers evaluating similar parameter
| configurations. In particular, if each objective function evaluation is costly
| and the durations of the running states are significant, and/or the number of
| workers is high.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer
| versions without prior notice. See
| https://github.com/optuna/optuna/releases/tag/v2.8.0.
| constraints_func:
| An optional function that computes the objective constraints. It must take a
| :class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
| be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
| constraints is violated. A value equal to or smaller than 0 is considered feasible.
| If ``constraints_func`` returns more than one value for a trial, that trial is
| considered feasible if and only if all values are equal to 0 or smaller.
|
| The ``constraints_func`` will be evaluated after each successful trial.
| The function won't be called when trials fail or they are pruned, but this behavior is
| subject to change in the future releases.
|
| .. note::
| Added in v3.0.0 as an experimental feature. The interface may change in newer
| versions without prior notice.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
| categorical_distance_func:
| A dictionary of distance functions for categorical parameters. The key is the name of
| the categorical parameter and the value is a distance function that takes two
| :class:`~optuna.distributions.CategoricalChoiceType` s and returns a :obj:`float`
| value. The distance function must return a non-negative value.
|
| While categorical choices are handled equally by default, this option allows users to
| specify prior knowledge on the structure of categorical parameters. When specified,
| categorical choices closer to current best choices are more likely to be sampled.
|
| .. warning::
| Deprecated in v4.9.0. ``categorical_distance_func`` argument will be removed in
| the future. The removal of this feature is currently scheduled for v5.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
|
| Method resolution order:
| TPESampler
| optuna.samplers._base.BaseSampler
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, *, consider_prior: 'bool | None' = None, prior_weight: 'float | None' = None, consider_magic_clip: 'bool | None' = None, consider_endpoints: 'bool | None' = None, n_startup_trials: 'int' = 10, n_ei_candidates: 'int' = 24, gamma: 'Callable[[int], int] | None' = None, weights: 'Callable[[int], np.ndarray] | None' = None, seed: 'int | None' = None, multivariate: 'bool' = False, group: 'bool' = False, warn_independent_sampling: 'bool | None' = None, constant_liar: 'bool' = False, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, categorical_distance_func: 'dict[str, Callable[[CategoricalChoiceType, CategoricalChoiceType], float]] | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| after_trial(self, study: 'Study', trial: 'FrozenTrial', state: 'TrialState', values: 'Sequence[float] | None') -> 'None'
| Trial post-processing.
|
| This method is called after the objective function returns and right before the trial is
| finished and its state is stored.
|
| .. note::
| Added in v2.4.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.4.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| state:
| Resulting trial state.
| values:
| Resulting trial values. Guaranteed to not be :obj:`None` if trial succeeded.
|
| before_trial(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Trial pre-processing.
|
| This method is called before the objective function is called and right after the trial is
| instantiated. More precisely, this method is called during trial initialization, just
| before the :func:`~optuna.samplers.BaseSampler.infer_relative_search_space` call. In other
| words, it is responsible for pre-processing that should be done before inferring the search
| space.
|
| .. note::
| Added in v3.3.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
|
| infer_relative_search_space(self, study: 'Study', trial: 'FrozenTrial') -> 'dict[str, BaseDistribution]'
| Infer the search space that will be used by relative sampling in the target trial.
|
| This method is called right before :func:`~optuna.samplers.BaseSampler.sample_relative`
| method, and the search space returned by this method is passed to it. The parameters not
| contained in the search space will be sampled by using
| :func:`~optuna.samplers.BaseSampler.sample_independent` method.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions.
|
| .. seealso::
| Please refer to :func:`~optuna.search_space.intersection_search_space` as an
| implementation of :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| reseed_rng(self) -> 'None'
| Reseed sampler's random number generator.
|
| This method is called by the :class:`~optuna.study.Study` instance if trials are executed
| in parallel with the option ``n_jobs>1``. In that case, the sampler instance will be
| replicated including the state of the random number generator, and they may suggest the
| same values. To prevent this issue, this method assigns a different seed to each random
| number generator.
|
| sample_independent(self, study: 'Study', trial: 'FrozenTrial', param_name: 'str', param_distribution: 'BaseDistribution') -> 'Any'
| Sample a parameter for a given distribution.
|
| This method is called only for the parameters not contained in the search space returned
| by :func:`~optuna.samplers.BaseSampler.sample_relative` method. This method is suitable
| for sampling algorithms that do not use relationship between parameters such as random
| sampling and TPE.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| param_name:
| Name of the sampled parameter.
| param_distribution:
| Distribution object that specifies a prior and/or scale of the sampling algorithm.
|
| Returns:
| A parameter value.
|
| sample_relative(self, study: 'Study', trial: 'FrozenTrial', search_space: 'dict[str, BaseDistribution]') -> 'dict[str, Any]'
| Sample parameters in a given search space.
|
| This method is called once at the beginning of each trial, i.e., right before the
| evaluation of the objective function. This method is suitable for sampling algorithms
| that use relationship between parameters such as Gaussian Process and CMA-ES.
|
| .. note::
| The failed trials are ignored by any build-in samplers when they sample new
| parameters. Thus, failed trials are regarded as deleted in the samplers'
| perspective.
|
| Args:
| study:
| Target study object.
| trial:
| Target trial object.
| Take a copy before modifying this object.
| search_space:
| The search space returned by
| :func:`~optuna.samplers.BaseSampler.infer_relative_search_space`.
|
| Returns:
| A dictionary containing the parameter names and the values.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| hyperopt_parameters() -> 'dict[str, Any]'
| Return the the default parameters of hyperopt (v0.1.2).
|
| :class:`~optuna.samplers.TPESampler` can be instantiated with the parameters returned
| by this method.
|
| Example:
|
| Create a :class:`~optuna.samplers.TPESampler` instance with the default
| parameters of `hyperopt <https://github.com/hyperopt/hyperopt/tree/0.1.2>`__.
|
| .. testcode::
|
| import optuna
| from optuna.samplers import TPESampler
|
|
| def objective(trial):
| x = trial.suggest_float("x", -10, 10)
| return x**2
|
|
| sampler = TPESampler(**TPESampler.hyperopt_parameters())
| study = optuna.create_study(sampler=sampler)
| study.optimize(objective, n_trials=10)
|
| Returns:
| A dictionary containing the default parameters of hyperopt.
|
| .. warning::
| Deprecated in v4.9.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.samplers._base.BaseSampler:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.samplers._base.BaseSampler:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
DATA
__all__ = ['BaseSampler', 'BaseGASampler', 'BruteForceSampler', 'CmaEs...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\samplers\__init__.py
optuna.search_space
Python Library Documentation: package optuna.search_space in optuna
NAME
optuna.search_space
PACKAGE CONTENTS
group_decomposed
intersection
CLASSES
builtins.object
optuna.search_space.group_decomposed._GroupDecomposedSearchSpace
optuna.search_space.group_decomposed._SearchSpaceGroup
optuna.search_space.intersection.IntersectionSearchSpace
class IntersectionSearchSpace(builtins.object)
| IntersectionSearchSpace(include_pruned: 'bool' = False) -> 'None'
|
| A class to calculate the intersection search space of a :class:`~optuna.study.Study`.
|
| Intersection search space contains the intersection of parameter distributions that have been
| suggested in the completed trials of the study so far.
| If there are multiple parameters that have the same name but different distributions,
| neither is included in the resulting search space
| (i.e., the parameters with dynamic value ranges are excluded).
|
| Note that an instance of this class is supposed to be used for only one study.
| If different studies are passed to
| :func:`~optuna.search_space.IntersectionSearchSpace.calculate`,
| a :obj:`ValueError` is raised.
|
| Args:
| include_pruned:
| Whether pruned trials should be included in the search space.
|
| Methods defined here:
|
| __init__(self, include_pruned: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| calculate(self, study: 'Study', use_cache: 'bool' = False) -> 'dict[str, BaseDistribution]'
| Returns the intersection search space of the :class:`~optuna.study.Study`.
|
| Args:
| study:
| A study with completed trials. The same study must be passed for one instance
| of this class through its lifetime.
| use_cache:
| An option to use cached trials for each trial.
|
| Returns:
| A dictionary containing the parameter names and parameter's distributions sorted by
| parameter names.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class _GroupDecomposedSearchSpace(builtins.object)
| _GroupDecomposedSearchSpace(include_pruned: 'bool' = False) -> 'None'
|
| Methods defined here:
|
| __init__(self, include_pruned: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| calculate(self, study: 'Study', use_cache: 'bool' = False) -> '_SearchSpaceGroup'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class _SearchSpaceGroup(builtins.object)
| _SearchSpaceGroup() -> 'None'
|
| Methods defined here:
|
| __init__(self) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_distributions(self, distributions: 'dict[str, BaseDistribution]') -> 'None'
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| search_spaces
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
intersection_search_space(trials: 'list[optuna.trial.FrozenTrial]', include_pruned: 'bool' = False) -> 'dict[str, BaseDistribution]'
Return the intersection search space of the given trials.
Intersection search space contains the intersection of parameter distributions that have been
suggested in the completed trials of the study so far.
If there are multiple parameters that have the same name but different distributions,
neither is included in the resulting search space
(i.e., the parameters with dynamic value ranges are excluded).
.. note::
:class:`~optuna.search_space.IntersectionSearchSpace` provides the same functionality with
a much faster way. Please consider using it if you want to reduce execution time
as much as possible.
Args:
trials:
A list of trials.
include_pruned:
Whether pruned trials should be included in the search space.
Returns:
A dictionary containing the parameter names and parameter's distributions sorted by
parameter names.
DATA
__all__ = ['_GroupDecomposedSearchSpace', '_SearchSpaceGroup', 'Inters...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\search_space\__init__.py
optuna.storages
Python Library Documentation: package optuna.storages in optuna
NAME
optuna.storages
PACKAGE CONTENTS
_base
_cached_storage
_callbacks
_grpc (package)
_heartbeat
_in_memory
_rdb (package)
journal (package)
CLASSES
abc.ABC(builtins.object)
optuna.storages._base.BaseStorage
optuna.storages._cached_storage._CachedStorage(optuna.storages._base.BaseStorage, optuna.storages._heartbeat.BaseHeartbeat)
optuna.storages._grpc.client.GrpcStorageProxy
optuna.storages._in_memory.InMemoryStorage
optuna.storages._rdb.storage.RDBStorage(optuna.storages._base.BaseStorage, optuna.storages._heartbeat.BaseHeartbeat)
optuna.storages.journal._storage.JournalStorage
builtins.object
optuna.storages._callbacks.RetryHeartbeatStaleTrialCallback
optuna.storages._callbacks.RetryFailedTrialCallback
optuna.storages.journal._base.BaseJournalBackend(abc.ABC)
optuna.storages.journal._base.BaseJournalLogStorage
optuna.storages.journal._file.JournalFileBackend(optuna.storages.journal._base.BaseJournalBackend)
optuna.storages.journal._file.JournalFileStorage
optuna.storages.journal._file.JournalFileOpenLock(optuna.storages.journal._file.BaseJournalFileLock)
optuna.storages.journal._file.DeprecatedJournalFileOpenLock
optuna.storages.journal._file.JournalFileSymlinkLock(optuna.storages.journal._file.BaseJournalFileLock)
optuna.storages.journal._file.DeprecatedJournalFileSymlinkLock
optuna.storages.journal._redis.JournalRedisBackend(optuna.storages.journal._base.BaseJournalBackend, optuna.storages.journal._base.BaseJournalSnapshot)
optuna.storages.journal._redis.JournalRedisStorage
class BaseJournalLogStorage(BaseJournalBackend)
| BaseJournalLogStorage(*args, **kwargs)
|
| Base class for Journal storages.
|
| Storage classes implementing this base class must guarantee process safety. This means,
| multiple processes might concurrently call ``read_logs`` and ``append_logs``. If the
| backend storage does not internally support mutual exclusion mechanisms, such as locks,
| you might want to use :class:`~optuna.storages.journal.JournalFileSymlinkLock` or
| :class:`~optuna.storages.journal.JournalFileOpenLock` for creating a critical section.
|
| .. warning::
| Deprecated in v4.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.0.0.
|
|
| Use :class:`~optuna.storages.journal.BaseJournalBackend` instead.
|
| Method resolution order:
| BaseJournalLogStorage
| BaseJournalBackend
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, /, *args, **kwargs) from optuna._deprecated.object
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'append_logs', 'read_logs'})
|
| ----------------------------------------------------------------------
| Methods inherited from BaseJournalBackend:
|
| append_logs(self, logs: 'list[dict[str, Any]]') -> 'None'
| Append logs to the backend.
|
| Args:
| logs:
| A list that contains json-serializable logs.
|
| read_logs(self, log_number_from: 'int') -> 'Iterable[dict[str, Any]]'
| Read logs with a log number greater than or equal to ``log_number_from``.
|
| If ``log_number_from`` is 0, read all the logs.
|
| Args:
| log_number_from:
| A non-negative integer value indicating which logs to read.
|
| Returns:
| Logs with log number greater than or equal to ``log_number_from``.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseJournalBackend:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class BaseStorage(abc.ABC)
| Base 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.
|
| Method resolution order:
| BaseStorage
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| get_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| remove_session(self) -> 'None'
| Clean up all connections to a database.
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'create_new_study', 'create_new_trial...
class GrpcStorageProxy(optuna.storages._base.BaseStorage)
| GrpcStorageProxy(*, host: 'str' = 'localhost', port: 'int' = 13000) -> 'None'
|
| gRPC client for :func:`~optuna.storages.run_grpc_proxy_server`.
|
| Example:
|
| This is a simple example of using :class:`~optuna.storages.GrpcStorageProxy` with
| :func:`~optuna.storages.run_grpc_proxy_server`.
|
| .. code::
|
| import optuna
| from optuna.storages import GrpcStorageProxy
|
| storage = GrpcStorageProxy(host="localhost", port=13000)
| study = optuna.create_study(storage=storage)
|
| Please refer to the example in :func:`~optuna.storages.run_grpc_proxy_server` for the
| server side code.
|
| Args:
| host: The hostname of the gRPC server.
| port: The port of the gRPC server.
|
| .. warning::
|
| Currently, gRPC storage proxy in combination with an SQLite3 database may cause unexpected
| behaviors when calling :func:`optuna.delete_study` due to non-invalidated cache.
|
| .. note::
| Added in v4.2.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v4.2.0.
|
| Method resolution order:
| GrpcStorageProxy
| optuna.storages._base.BaseStorage
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, *, host: 'str' = 'localhost', port: 'int' = 13000) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| close(self) -> 'None'
| Close the gRPC channel.
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| wait_server_ready(self, timeout: 'float | None' = None) -> 'None'
| Wait until the gRPC server is ready.
|
| Args:
| timeout: The maximum time to wait in seconds. If :obj:`None`, wait indefinitely.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._base.BaseStorage:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| get_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| remove_session(self) -> 'None'
| Clean up all connections to a database.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages._base.BaseStorage:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class InMemoryStorage(optuna.storages._base.BaseStorage)
| InMemoryStorage() -> 'None'
|
| Storage class that stores data in memory of the Python process.
|
| Example:
|
| Create an :class:`~optuna.storages.InMemoryStorage` instance.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -100, 100)
| return x**2
|
|
| storage = optuna.storages.InMemoryStorage()
|
| study = optuna.create_study(storage=storage)
| study.optimize(objective, n_trials=10)
|
| Method resolution order:
| InMemoryStorage
| optuna.storages._base.BaseStorage
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'distributions.BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._base.BaseStorage:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| remove_session(self) -> 'None'
| Clean up all connections to a database.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages._base.BaseStorage:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
JournalFileOpenLock = class DeprecatedJournalFileOpenLock(JournalFileOpenLock)
| JournalFileOpenLock(filepath: 'str', grace_period: 'int | None' = 30) -> 'None'
|
| .. warning::
| Deprecated in v4.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.0.0.
|
|
| Use :class:`~optuna.storages.journal.JournalFileOpenLock` instead.
|
| Method resolution order:
| DeprecatedJournalFileOpenLock
| JournalFileOpenLock
| BaseJournalFileLock
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, filepath: 'str', grace_period: 'int | None' = 30) -> 'None' from optuna.storages.journal._file.JournalFileOpenLock
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from JournalFileOpenLock:
|
| acquire(self) -> 'bool'
| Acquire a lock in a blocking way by creating a lock file.
|
| Returns:
| :obj:`True` if it succeeded in creating a ``self._lock_file``.
|
| release(self) -> 'None'
| Release a lock by removing the created file.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseJournalFileLock:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class JournalFileStorage(JournalFileBackend)
| JournalFileStorage(file_path: 'str', lock_obj: 'BaseJournalFileLock | None' = None) -> 'None'
|
| .. warning::
| Deprecated in v4.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.0.0.
|
|
| Use :class:`~optuna.storages.journal.JournalFileBackend` instead.
|
| Method resolution order:
| JournalFileStorage
| JournalFileBackend
| optuna.storages.journal._base.BaseJournalBackend
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, file_path: 'str', lock_obj: 'BaseJournalFileLock | None' = None) -> 'None' from optuna.storages.journal._file.JournalFileBackend
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from JournalFileBackend:
|
| append_logs(self, logs: 'list[dict[str, Any]]') -> 'None'
| Append logs to the backend.
|
| Args:
| logs:
| A list that contains json-serializable logs.
|
| read_logs(self, log_number_from: 'int') -> 'Generator[dict[str, Any], None, None]'
| Read logs with a log number greater than or equal to ``log_number_from``.
|
| If ``log_number_from`` is 0, read all the logs.
|
| Args:
| log_number_from:
| A non-negative integer value indicating which logs to read.
|
| Returns:
| Logs with log number greater than or equal to ``log_number_from``.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages.journal._base.BaseJournalBackend:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
JournalFileSymlinkLock = class DeprecatedJournalFileSymlinkLock(JournalFileSymlinkLock)
| JournalFileSymlinkLock(filepath: 'str', grace_period: 'int | None' = 30) -> 'None'
|
| .. warning::
| Deprecated in v4.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.0.0.
|
|
| Use :class:`~optuna.storages.journal.JournalFileSymlinkLock` instead.
|
| Method resolution order:
| DeprecatedJournalFileSymlinkLock
| JournalFileSymlinkLock
| BaseJournalFileLock
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, filepath: 'str', grace_period: 'int | None' = 30) -> 'None' from optuna.storages.journal._file.JournalFileSymlinkLock
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from JournalFileSymlinkLock:
|
| acquire(self) -> 'bool'
| Acquire a lock in a blocking way by creating a symbolic link of a file.
|
| Returns:
| :obj:`True` if it succeeded in creating a symbolic link of ``self._lock_target_file``.
|
| release(self) -> 'None'
| Release a lock by removing the symbolic link.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from BaseJournalFileLock:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class JournalRedisStorage(JournalRedisBackend)
| JournalRedisStorage(url: 'str', use_cluster: 'bool' = False, prefix: 'str' = '') -> 'None'
|
| .. warning::
| Deprecated in v4.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.0.0.
|
|
| Use :class:`~optuna.storages.journal.JournalRedisBackend` instead.
|
| Method resolution order:
| JournalRedisStorage
| JournalRedisBackend
| optuna.storages.journal._base.BaseJournalBackend
| optuna.storages.journal._base.BaseJournalSnapshot
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, url: 'str', use_cluster: 'bool' = False, prefix: 'str' = '') -> 'None' from optuna.storages.journal._redis.JournalRedisBackend
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from JournalRedisBackend:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| append_logs(self, logs: 'list[dict[str, Any]]') -> 'None'
| Append logs to the backend.
|
| Args:
| logs:
| A list that contains json-serializable logs.
|
| load_snapshot(self) -> 'bytes | None'
| Load snapshot from the backend.
|
| Returns:
| A serialized snapshot (bytes) if found, otherwise :obj:`None`.
|
| read_logs(self, log_number_from: 'int') -> 'Generator[dict[str, Any], None, None]'
| Read logs with a log number greater than or equal to ``log_number_from``.
|
| If ``log_number_from`` is 0, read all the logs.
|
| Args:
| log_number_from:
| A non-negative integer value indicating which logs to read.
|
| Returns:
| Logs with log number greater than or equal to ``log_number_from``.
|
| save_snapshot(self, snapshot: 'bytes') -> 'None'
| Save snapshot to the backend.
|
| Args:
| snapshot: A serialized snapshot (bytes)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages.journal._base.BaseJournalBackend:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class JournalStorage(optuna.storages._base.BaseStorage)
| JournalStorage(log_storage: 'BaseJournalBackend') -> 'None'
|
| Storage class for Journal storage backend.
|
| Note that library users can instantiate this class, but the attributes
| provided by this class are not supposed to be directly accessed by them.
|
| Journal storage writes a record of every operation to the database as it is executed and
| at the same time, keeps a latest snapshot of the database in-memory. If the database crashes
| for any reason, the storage can re-establish the contents in memory by replaying the
| operations stored from the beginning.
|
| Journal storage has several benefits over the conventional value logging storages.
|
| 1. The number of IOs can be reduced because of larger granularity of logs.
| 2. Journal storage has simpler backend API than value logging storage.
| 3. Journal storage keeps a snapshot in-memory so no need to add more cache.
|
| Example:
|
| .. code::
|
| import optuna
|
|
| def objective(trial): ...
|
|
| storage = optuna.storages.JournalStorage(
| optuna.storages.journal.JournalFileBackend("./optuna_journal_storage.log")
| )
|
| study = optuna.create_study(storage=storage)
| study.optimize(objective)
|
| In a Windows environment, an error message "A required privilege is not held by the
| client" may appear. In this case, you can solve the problem with creating storage
| by specifying :class:`~optuna.storages.journal.JournalFileOpenLock` as follows.
|
| .. code::
|
| file_path = "./optuna_journal_storage.log"
| lock_obj = optuna.storages.journal.JournalFileOpenLock(file_path)
|
| storage = optuna.storages.JournalStorage(
| optuna.storages.journal.JournalFileBackend(file_path, lock_obj=lock_obj),
| )
|
| Method resolution order:
| JournalStorage
| optuna.storages._base.BaseStorage
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, log_storage: 'BaseJournalBackend') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| restore_replay_result(self, snapshot: 'bytes') -> 'None'
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._base.BaseStorage:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| get_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| remove_session(self) -> 'None'
| Clean up all connections to a database.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages._base.BaseStorage:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class RDBStorage(optuna.storages._base.BaseStorage, optuna.storages._heartbeat.BaseHeartbeat)
| RDBStorage(url: 'str', engine_kwargs: 'dict[str, Any] | None' = None, skip_compatibility_check: 'bool' = False, *, heartbeat_interval: 'int | None' = None, grace_period: 'int | None' = None, heartbeat_stale_trial_callback: "Callable[['optuna.study.Study', FrozenTrial], None] | None" = None, failed_trial_callback: "Callable[['optuna.study.Study', FrozenTrial], None] | None" = None, skip_table_creation: 'bool' = False) -> 'None'
|
| Storage class for RDB backend.
|
| Note that library users can instantiate this class, but the attributes
| provided by this class are not supposed to be directly accessed by them.
|
| Example:
|
| Create an :class:`~optuna.storages.RDBStorage` instance with customized
| ``pool_size`` and ``timeout`` settings.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -100, 100)
| return x**2
|
|
| storage = optuna.storages.RDBStorage(
| url="sqlite:///:memory:",
| engine_kwargs={"pool_size": 20, "connect_args": {"timeout": 10}},
| )
|
| study = optuna.create_study(storage=storage)
| study.optimize(objective, n_trials=10)
|
| Args:
| url:
| URL of the storage.
| engine_kwargs:
| A dictionary of keyword arguments that is passed to
| `sqlalchemy.engine.create_engine`_ function.
| skip_compatibility_check:
| Flag to skip schema compatibility check if set to :obj:`True`.
| heartbeat_interval:
| Interval to record the heartbeat. It is recorded every ``interval`` seconds.
| ``heartbeat_interval`` must be :obj:`None` or a positive integer.
|
| .. note::
| Heartbeat mechanism is experimental. API would change in the future.
|
| .. note::
| The heartbeat is supposed to be used with :meth:`~optuna.study.Study.optimize`.
| If you use :meth:`~optuna.study.Study.ask` and
| :meth:`~optuna.study.Study.tell` instead, it will not work.
|
| grace_period:
| Grace period before a running trial is failed from the last heartbeat.
| ``grace_period`` must be :obj:`None` or a positive integer.
| If it is :obj:`None`, the grace period will be `2 * heartbeat_interval`.
| heartbeat_stale_trial_callback:
| A callback function that is invoked after failing each heartbeat-stale trial.
| The function must accept two parameters with the following types in this order:
| :class:`~optuna.study.Study` and :class:`~optuna.trial.FrozenTrial`.
|
| .. note::
| The procedure to fail existing stale trials is called just before asking the
| study for a new trial.
| failed_trial_callback:
| Deprecated in v4.9.0. This argument will be removed in v6.0.0.
| Use ``heartbeat_stale_trial_callback`` instead.
|
| skip_table_creation:
| Flag to skip table creation if set to :obj:`True`.
|
| .. _sqlalchemy.engine.create_engine:
| https://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine
|
| .. note::
| If you use MySQL, `pool_pre_ping`_ will be set to :obj:`True` by default to prevent
| connection timeout. You can turn it off with ``engine_kwargs['pool_pre_ping']=False``, but
| it is recommended to keep the setting if execution time of your objective function is
| longer than the `wait_timeout` of your MySQL configuration.
|
| .. _pool_pre_ping:
| https://docs.sqlalchemy.org/en/13/core/engines.html#sqlalchemy.create_engine.params.
| pool_pre_ping
|
| .. note::
| We would never recommend SQLite3 for parallel optimization.
| Please see the FAQ :ref:`sqlite_concurrency` for details.
|
| .. note::
| Mainly in a cluster environment, running trials are often killed unexpectedly.
| If you want to detect a failure of trials, please use the heartbeat
| mechanism. Set ``heartbeat_interval``, ``grace_period``, and
| ``heartbeat_stale_trial_callback`` appropriately according to your use case.
| For more details, please refer to the :ref:`tutorial <heartbeat_monitoring>` and
| `Example page
| <https://github.com/optuna/optuna-examples/blob/main/pytorch/pytorch_checkpoint.py>`__.
|
| .. seealso::
| You can use :class:`~optuna.storages.RetryHeartbeatStaleTrialCallback` to automatically
| retry heartbeat-stale trials.
|
| Method resolution order:
| RDBStorage
| optuna.storages._base.BaseStorage
| abc.ABC
| optuna.storages._heartbeat.BaseHeartbeat
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, url: 'str', engine_kwargs: 'dict[str, Any] | None' = None, skip_compatibility_check: 'bool' = False, *, heartbeat_interval: 'int | None' = None, grace_period: 'int | None' = None, heartbeat_stale_trial_callback: "Callable[['optuna.study.Study', FrozenTrial], None] | None" = None, failed_trial_callback: "Callable[['optuna.study.Study', FrozenTrial], None] | None" = None, skip_table_creation: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_all_versions(self) -> 'list[str]'
| Return the schema version list.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_current_version(self) -> 'str'
| Return the schema version currently used by this storage.
|
| get_head_version(self) -> 'str'
| Return the latest schema version.
|
| get_heartbeat_interval(self) -> 'int | None'
| Get the heartbeat interval if it is set.
|
| Returns:
| The heartbeat interval if it is set, otherwise :obj:`None`.
|
| get_heartbeat_stale_trial_callback(self) -> "Callable[['optuna.study.Study', FrozenTrial], None] | None"
| Get the heartbeat-stale trial callback function.
|
| Returns:
| The heartbeat-stale trial callback function if it is set, otherwise :obj:`None`.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| get_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| record_heartbeat(self, trial_id: 'int') -> 'None'
| Record the heartbeat of the trial.
|
| Args:
| trial_id:
| ID of the trial.
|
| remove_session(self) -> 'None'
| Removes the current session.
|
| A session is stored in SQLAlchemy's ThreadLocalRegistry for each thread. This method
| closes and removes the session which is associated to the current thread. Particularly,
| under multi-thread use cases, it is important to call this method *from each thread*.
| Otherwise, all sessions and their associated DB connections are destructed by a thread
| that occasionally invoked the garbage collector. By default, it is not allowed to touch
| a SQLite connection from threads other than the thread that created the connection.
| Therefore, we need to explicitly close the connection from each thread.
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'distributions.BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| upgrade(self) -> 'None'
| Upgrade the storage schema.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._base.BaseStorage:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages._base.BaseStorage:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._heartbeat.BaseHeartbeat:
|
| get_failed_trial_callback(self) -> "Callable[['optuna.Study', FrozenTrial], None] | None"
| Get the failed trial callback function.
|
| .. warning::
| Deprecated in v4.9.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
|
|
| Use `get_heartbeat_stale_trial_callback` instead.
class RetryFailedTrialCallback(RetryHeartbeatStaleTrialCallback)
| RetryFailedTrialCallback(max_retry: 'int | None' = None, inherit_intermediate_values: 'bool' = False) -> 'None'
|
| Deprecated alias of :class:`~optuna.storages.RetryHeartbeatStaleTrialCallback`.
|
| Deprecated in v4.9.0. This class will be removed in v6.0.0.
|
| .. warning::
| Deprecated in v4.9.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
|
|
| Use `RetryHeartbeatStaleTrialCallback` instead.
|
| Method resolution order:
| RetryFailedTrialCallback
| RetryHeartbeatStaleTrialCallback
| builtins.object
|
| Methods defined here:
|
| __init__(self, max_retry: 'int | None' = None, inherit_intermediate_values: 'bool' = False) -> 'None' from optuna.storages._callbacks.RetryHeartbeatStaleTrialCallback
|
| ----------------------------------------------------------------------
| Methods inherited from RetryHeartbeatStaleTrialCallback:
|
| __call__(self, study: "'optuna.study.Study'", trial: 'FrozenTrial') -> 'None'
| Call self as a function.
|
| ----------------------------------------------------------------------
| Static methods inherited from RetryHeartbeatStaleTrialCallback:
|
| retried_trial_number(trial: 'FrozenTrial') -> 'int | None'
| Return the number of the original trial being retried.
|
| Args:
| trial:
| The trial object.
|
| Returns:
| The number of the first failed trial. If not retry of a previous trial,
| returns :obj:`None`.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.8.0.
|
| retry_history(trial: 'FrozenTrial') -> 'list[int]'
| Return the list of retried trial numbers with respect to the specified trial.
|
| Args:
| trial:
| The trial object.
|
| Returns:
| A list of trial numbers in ascending order of the series of retried trials.
| The first item of the list indicates the original trial which is identical
| to the :func:`~optuna.storages.RetryHeartbeatStaleTrialCallback.retried_trial_number`,
| and the last item is the one right before the specified trial in the retry series.
| If the specified trial is not a retry of any trial, returns an empty list.
|
| .. note::
| Added in v3.0.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from RetryHeartbeatStaleTrialCallback:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class RetryHeartbeatStaleTrialCallback(builtins.object)
| RetryHeartbeatStaleTrialCallback(max_retry: 'int | None' = None, inherit_intermediate_values: 'bool' = False) -> 'None'
|
| Retry a heartbeat-stale trial up to a maximum number of times.
|
| When a running trial becomes stale due to the heartbeat mechanism, this callback can be
| used with a class in :mod:`optuna.storages` to recreate the trial in ``TrialState.WAITING``
| to queue up the trial to be run again.
|
| The original stale trial can be identified by the
| :func:`~optuna.storages.RetryHeartbeatStaleTrialCallback.retried_trial_number` function.
| Even if repetitive failure occurs (a retried trial becomes stale again), this method returns
| the number of the original trial. To get a full list including the numbers of the retried
| trials as well as their original trial, call the
| :func:`~optuna.storages.RetryHeartbeatStaleTrialCallback.retry_history` function.
|
| This callback is helpful in environments where running trials may become stale due to external
| conditions, such as worker preemption or unexpected process termination.
|
| Usage:
|
| .. testcode::
|
| import optuna
| from optuna.storages import RetryHeartbeatStaleTrialCallback
|
| storage = optuna.storages.RDBStorage(
| url="sqlite:///:memory:",
| heartbeat_interval=60,
| grace_period=120,
| heartbeat_stale_trial_callback=RetryHeartbeatStaleTrialCallback(max_retry=3),
| )
|
| study = optuna.create_study(
| storage=storage,
| )
|
| .. seealso::
| See :class:`~optuna.storages.RDBStorage`.
|
| Args:
| max_retry:
| The max number of times a trial can be retried. Must be set to :obj:`None` or an
| integer. If set to the default value of :obj:`None` will retry indefinitely.
| If set to an integer, will only retry that many times.
| inherit_intermediate_values:
| Option to inherit `trial.intermediate_values` reported by
| :func:`optuna.trial.Trial.report` from the failed trial. Default is :obj:`False`.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.8.0.
|
| Methods defined here:
|
| __call__(self, study: "'optuna.study.Study'", trial: 'FrozenTrial') -> 'None'
| Call self as a function.
|
| __init__(self, max_retry: 'int | None' = None, inherit_intermediate_values: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| retried_trial_number(trial: 'FrozenTrial') -> 'int | None'
| Return the number of the original trial being retried.
|
| Args:
| trial:
| The trial object.
|
| Returns:
| The number of the first failed trial. If not retry of a previous trial,
| returns :obj:`None`.
|
| .. note::
| Added in v2.8.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.8.0.
|
| retry_history(trial: 'FrozenTrial') -> 'list[int]'
| Return the list of retried trial numbers with respect to the specified trial.
|
| Args:
| trial:
| The trial object.
|
| Returns:
| A list of trial numbers in ascending order of the series of retried trials.
| The first item of the list indicates the original trial which is identical
| to the :func:`~optuna.storages.RetryHeartbeatStaleTrialCallback.retried_trial_number`,
| and the last item is the one right before the specified trial in the retry series.
| If the specified trial is not a retry of any trial, returns an empty list.
|
| .. note::
| Added in v3.0.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class _CachedStorage(optuna.storages._base.BaseStorage, optuna.storages._heartbeat.BaseHeartbeat)
| _CachedStorage(backend: 'RDBStorage') -> 'None'
|
| A wrapper class of storage backends.
|
| This class is used in :func:`~optuna.get_storage` function and automatically
| wraps :class:`~optuna.storages.RDBStorage` class.
|
| :class:`~optuna.storages._CachedStorage` meets the following **Data persistence** requirements.
|
| **Data persistence**
|
| :class:`~optuna.storages._CachedStorage` does not guarantee that write operations are logged
| into a persistent storage, even when write methods succeed.
| Thus, when process failure occurs, some writes might be lost.
| As exceptions, when a persistent storage is available, any writes on any attributes
| of `Study` and writes on `state` of `Trial` are guaranteed to be persistent.
| Additionally, any preceding writes on any attributes of `Trial` are guaranteed to
| be written into a persistent storage before writes on `state` of `Trial` succeed.
| The same applies for `param`, `user_attrs', 'system_attrs' and 'intermediate_values`
| attributes.
|
| Args:
| backend:
| :class:`~optuna.storages.RDBStorage` class instance to wrap.
|
| Method resolution order:
| _CachedStorage
| optuna.storages._base.BaseStorage
| abc.ABC
| optuna.storages._heartbeat.BaseHeartbeat
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, backend: 'RDBStorage') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| create_new_study(self, directions: 'Sequence[StudyDirection]', study_name: 'str | None' = None) -> 'int'
| Create 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.
|
| create_new_trial(self, study_id: 'int', template_trial: 'FrozenTrial | None' = None) -> 'int'
| 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.
|
| delete_study(self, study_id: 'int') -> 'None'
| Delete a study.
|
| Args:
| study_id:
| ID of the study.
|
| Raises:
| :exc:`KeyError`:
| If no study with the matching ``study_id`` exists.
|
| get_all_studies(self) -> 'list[FrozenStudy]'
| Read a list of :class:`~optuna.study.FrozenStudy` objects.
|
| Returns:
| A list of :class:`~optuna.study.FrozenStudy` objects, sorted by ``study_id``.
|
| get_all_trials(self, study_id: 'int', deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Read 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.
|
| get_best_trial(self, study_id: 'int') -> 'FrozenTrial'
| Return 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.
|
| get_heartbeat_interval(self) -> 'int | None'
| Get the heartbeat interval if it is set.
|
| Returns:
| The heartbeat interval if it is set, otherwise :obj:`None`.
|
| get_heartbeat_stale_trial_callback(self) -> "Callable[['optuna.Study', FrozenTrial], None] | None"
| Get the heartbeat-stale trial callback function.
|
| Returns:
| The heartbeat-stale trial callback function if it is set, otherwise :obj:`None`.
|
| get_study_directions(self, study_id: 'int') -> 'list[StudyDirection]'
| 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.
|
| get_study_id_from_name(self, study_name: 'str') -> 'int'
| 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.
|
| get_study_name_from_id(self, study_id: 'int') -> 'str'
| Read 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.
|
| get_study_system_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_study_user_attrs(self, study_id: 'int') -> 'dict[str, Any]'
| 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.
|
| get_trial(self, trial_id: 'int') -> 'FrozenTrial'
| 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.
|
| get_trial_id_from_study_id_trial_number(self, study_id: 'int', trial_number: 'int') -> 'int'
| 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.
|
| record_heartbeat(self, trial_id: 'int') -> 'None'
| Record the heartbeat of the trial.
|
| Args:
| trial_id:
| ID of the trial.
|
| set_study_system_attr(self, study_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Register 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.
|
| set_study_user_attr(self, study_id: 'int', key: 'str', value: 'Any') -> 'None'
| Register 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.
|
| set_trial_intermediate_value(self, trial_id: 'int', step: 'int', intermediate_value: 'float') -> 'None'
| Report 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.
|
| set_trial_param(self, trial_id: 'int', param_name: 'str', param_value_internal: 'float', distribution: 'distributions.BaseDistribution') -> 'None'
| 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.
|
| set_trial_state_values(self, trial_id: 'int', state: 'TrialState', values: 'Sequence[float] | None' = None) -> 'bool'
| Update 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.
|
| set_trial_system_attr(self, trial_id: 'int', key: 'str', value: 'JSONSerializable') -> 'None'
| Set 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.
|
| set_trial_user_attr(self, trial_id: 'int', key: 'str', value: 'Any') -> 'None'
| Set 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._base.BaseStorage:
|
| check_trial_is_updatable(self, trial_id: 'int', trial_state: 'TrialState') -> 'None'
| Check 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.
|
| get_n_trials(self, study_id: 'int', state: 'tuple[TrialState, ...] | TrialState | None' = None) -> 'int'
| Count 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.
|
| get_trial_number_from_id(self, trial_id: 'int') -> 'int'
| Read 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_trial_param(self, trial_id: 'int', param_name: 'str') -> 'float'
| Read 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.
|
| get_trial_params(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_system_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| get_trial_user_attrs(self, trial_id: 'int') -> 'dict[str, Any]'
| Read 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.
|
| remove_session(self) -> 'None'
| Clean up all connections to a database.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.storages._base.BaseStorage:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from optuna.storages._heartbeat.BaseHeartbeat:
|
| get_failed_trial_callback(self) -> "Callable[['optuna.Study', FrozenTrial], None] | None"
| Get the failed trial callback function.
|
| .. warning::
| Deprecated in v4.9.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v4.9.0.
|
|
| Use `get_heartbeat_stale_trial_callback` instead.
FUNCTIONS
fail_stale_trials(study: "'optuna.Study'") -> 'None'
Fail stale trials and run their failure callbacks.
The running trials whose heartbeat has not been updated for a long time will be failed,
that is, those states will be changed to :obj:`~optuna.trial.TrialState.FAIL`.
.. seealso::
See :class:`~optuna.storages.RDBStorage`.
Args:
study:
Study holding the trials to check.
.. note::
Added in v2.9.0 as an experimental feature. The interface may change in newer versions
without prior notice. See https://github.com/optuna/optuna/releases/tag/v2.9.0.
run_grpc_proxy_server(storage: 'BaseStorage', *, host: 'str' = 'localhost', port: 'int' = 13000, thread_pool: 'ThreadPoolExecutor | None' = None) -> 'None'
Run a gRPC server for the given storage URL, host, and port.
Example:
Run this server with the following way:
.. code::
from optuna.storages import run_grpc_proxy_server
from optuna.storages import get_storage
storage = get_storage("mysql+pymysql://<user>:<pass>@<host>/<dbname>[?<options>]")
run_grpc_proxy_server(storage, host="localhost", port=13000)
Please refer to the client class :class:`~optuna.storages.GrpcStorageProxy` for
the client usage. Please use :func:`~optuna.storages.get_storage` instead of
:class:`~optuna.storages.RDBStorage` since ``RDBStorage`` by itself does not use cache in
process and it may cause significant slowdown.
Args:
storage: A storage object to proxy.
host: Hostname to listen on.
port: Port to listen on.
thread_pool:
Thread pool to use for the server. If :obj:`None`, a default thread pool
with 10 workers will be used.
.. warning::
Currently, gRPC storage proxy does not support the
:class:`~optuna.storages.JournalStorage`. This issue is tracked in
https://github.com/optuna/optuna/issues/6084. Please use
:class:`~optuna.storages.RDBStorage` instead.
.. note::
Added in v4.2.0 as an experimental feature. The interface may change in newer versions
without prior notice. See https://github.com/optuna/optuna/releases/tag/v4.2.0.
DATA
__all__ = ['BaseStorage', 'BaseJournalLogStorage', 'InMemoryStorage', ...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\storages\__init__.py
optuna.study
Python Library Documentation: package optuna.study in optuna
NAME
optuna.study
PACKAGE CONTENTS
_constrained_optimization
_dataframe
_frozen
_multi_objective
_optimize
_study_direction
_study_summary
_tell
study
CLASSES
builtins.object
optuna._callbacks.MaxTrialsCallback
optuna.study._study_summary.StudySummary
optuna.study.study.Study
enum.IntEnum(builtins.int, enum.ReprEnum)
optuna.study._study_direction.StudyDirection
class MaxTrialsCallback(builtins.object)
| MaxTrialsCallback(n_trials: 'int', states: 'Container[TrialState] | None' = (<TrialState.COMPLETE: 1>,)) -> 'None'
|
| Set a maximum number of trials before ending the study.
|
| While the ``n_trials`` argument of :meth:`optuna.study.Study.optimize` sets the number of
| trials that will be run, you may want to continue running until you have a certain number of
| successfully completed trials or stop the study when you have a certain number of trials that
| fail. This ``MaxTrialsCallback`` class allows you to set a maximum number of trials for a
| particular :class:`~optuna.trial.TrialState` before stopping the study.
|
| Example:
|
| .. testcode::
|
| import optuna
| from optuna.study import MaxTrialsCallback
| from optuna.trial import TrialState
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| return x**2
|
|
| study = optuna.create_study()
| study.optimize(
| objective,
| callbacks=[MaxTrialsCallback(10, states=(TrialState.COMPLETE,))],
| )
|
| Args:
| n_trials:
| The max number of trials. Must be set to an integer.
| states:
| Tuple of the :class:`~optuna.trial.TrialState` to be counted
| towards the max trials limit. Default value is ``(TrialState.COMPLETE,)``.
| If :obj:`None`, count all states.
|
| Methods defined here:
|
| __call__(self, study: 'Study', trial: 'FrozenTrial') -> 'None'
| Call self as a function.
|
| __init__(self, n_trials: 'int', states: 'Container[TrialState] | None' = (<TrialState.COMPLETE: 1>,)) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Study(builtins.object)
| Study(study_name: 'str', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'None'
|
| A 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.
|
| Methods defined here:
|
| __getstate__(self) -> 'dict[Any, Any]'
| Helper for pickle.
|
| __init__(self, study_name: 'str', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'dict[Any, Any]') -> 'None'
|
| add_trial(self, trial: 'FrozenTrial') -> 'None'
| Add trial to study.
|
| The trial is validated before being added.
|
| Example:
|
| .. testcode::
|
| import optuna
| from optuna.distributions import FloatDistribution
|
|
| def objective(trial):
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| assert len(study.trials) == 0
|
| trial = optuna.trial.create_trial(
| params={"x": 2.0},
| distributions={"x": FloatDistribution(0, 10)},
| value=4.0,
| )
|
| study.add_trial(trial)
| assert len(study.trials) == 1
|
| study.optimize(objective, n_trials=3)
| assert len(study.trials) == 4
|
| other_study = optuna.create_study()
|
| for trial in study.trials:
| other_study.add_trial(trial)
| 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::
|
| This method should in general be used to add already evaluated trials
| (``trial.state.is_finished() == True``). To queue trials for evaluation,
| please refer to :func:`~optuna.study.Study.enqueue_trial`.
|
| .. seealso::
|
| See :func:`~optuna.trial.create_trial` for how to create trials.
|
| .. seealso::
| Please refer to :ref:`add_trial_tutorial` for the tutorial of specifying
| hyperparameters with the evaluated value manually.
|
| Args:
| trial: Trial to add.
|
| add_trials(self, trials: 'Iterable[FrozenTrial]') -> 'None'
| Add 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.
|
| ask(self, fixed_distributions: 'dict[str, BaseDistribution] | None' = None) -> 'Trial'
| Create 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`.
|
| enqueue_trial(self, params: 'dict[str, Any]', user_attrs: 'dict[str, Any] | None' = None, skip_if_exists: 'bool' = False) -> 'None'
| Enqueue a trial with given parameter values.
|
| You can fix the next sampling parameters which will be evaluated in your
| objective function.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| study.enqueue_trial({"x": 5})
| study.enqueue_trial({"x": 0}, user_attrs={"memo": "optimal"})
| study.optimize(objective, n_trials=2)
|
| assert study.trials[0].params == {"x": 5}
| assert study.trials[1].params == {"x": 0}
| assert study.trials[1].user_attrs == {"memo": "optimal"}
|
| Args:
| params:
| Parameter values to pass your objective function.
| user_attrs:
| A dictionary of user-specific attributes other than ``params``.
| skip_if_exists:
| When :obj:`True`, prevents duplicate trials from being enqueued again.
|
| .. note::
| This method might produce duplicated trials if called simultaneously
| by multiple processes at the same time with same ``params`` dict.
|
| .. seealso::
|
| Please refer to :ref:`enqueue_trial_tutorial` for the tutorial of specifying
| hyperparameters manually.
|
| get_trials(self, deepcopy: 'bool' = True, states: 'Container[TrialState] | None' = None) -> 'list[FrozenTrial]'
| Return 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.
|
| optimize(self, func: 'ObjectiveFuncType', n_trials: 'int | None' = None, timeout: 'float | None' = None, n_jobs: 'int' = 1, catch: 'Iterable[type[Exception]] | type[Exception]' = (), callbacks: 'Iterable[Callable[[Study, FrozenTrial], None]] | None' = None, gc_after_trial: 'bool' = False, show_progress_bar: 'bool' = False) -> 'None'
| Optimize 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 <https://wiki.python.org/moin/GlobalInterpreterLock>`__.
| It is recommended to use :ref:`process-based parallelization<distributed>`
| 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.
|
| set_metric_names(self, metric_names: 'list[str]') -> 'None'
| Set 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.
|
| .. note::
| Added in v3.2.0 as an experimental feature. The interface may change in newer versions
| without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.2.0.
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| Set a system attribute to the study.
|
| Note that Optuna internally uses this method to save system messages. Please use
| :func:`~optuna.study.Study.set_user_attr` to set users' attributes.
|
| Args:
| key: A key string of the attribute.
| value: A value of the attribute. The value should be JSON serializable.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
| Set a user attribute to the study.
|
| .. seealso::
|
| See :attr:`~optuna.study.Study.user_attrs` for related attribute.
|
| .. seealso::
|
| See the recipe on :ref:`attributes`.
|
| 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"],
| }
|
| Args:
| key: A key string of the attribute.
| value: A value of the attribute. The value should be JSON serializable.
|
| stop(self) -> 'None'
| Exit from the current optimization loop after the running trials finish.
|
| This method lets the running :meth:`~optuna.study.Study.optimize` method return
| immediately after all trials which the :meth:`~optuna.study.Study.optimize` method
| spawned finishes.
| This method does not affect any behaviors of parallel or successive study processes.
| This method only works when it is called inside an objective function or callback.
|
| Example:
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| if trial.number == 4:
| trial.study.stop()
| x = trial.suggest_float("x", 0, 10)
| return x**2
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=10)
| assert len(study.trials) == 5
|
| tell(self, trial: 'Trial | int', values: 'float | Sequence[float] | None' = None, state: 'TrialState | None' = None, skip_if_finished: 'bool' = False) -> 'FrozenTrial'
| 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.
|
| trials_dataframe(self, attrs: 'tuple[str, ...]' = ('number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state'), multi_index: 'bool' = False) -> "'pd.DataFrame'"
| Export trials as a pandas DataFrame_.
|
| The DataFrame_ provides various features to analyze studies. It is also useful to draw a
| histogram of objective values and to export trials as a CSV file.
| If there are no trials, an empty DataFrame_ is returned.
|
| Example:
|
| .. testcode::
|
| import optuna
| import pandas
|
|
| def objective(trial):
| x = trial.suggest_float("x", -1, 1)
| return x**2
|
|
| study = optuna.create_study()
| study.optimize(objective, n_trials=3)
|
| # Create a dataframe from the study.
| df = study.trials_dataframe()
| assert isinstance(df, pandas.DataFrame)
| assert df.shape[0] == 3 # n_trials.
|
| Args:
| attrs:
| Specifies field names of :class:`~optuna.trial.FrozenTrial` to include them to a
| DataFrame of trials.
| multi_index:
| Specifies whether the returned DataFrame_ employs MultiIndex_ or not. Columns that
| are hierarchical by nature such as ``(params, x)`` will be flattened to
| ``params_x`` when set to :obj:`False`.
|
| Returns:
| A pandas DataFrame_ of trials in the :class:`~optuna.study.Study`.
|
| .. _DataFrame: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
| .. _MultiIndex: https://pandas.pydata.org/pandas-docs/stable/advanced.html
|
| Note:
| If ``value`` is in ``attrs`` during multi-objective optimization, it is implicitly
| replaced with ``values``.
|
| Note:
| If :meth:`~optuna.study.Study.set_metric_names` is called, the ``value`` or ``values``
| is implicitly replaced with the dictionary with the objective name as key and the
| objective value as value.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| best_params
| Return 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_trial
| Return 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.
|
| .. note::
| In constrained optimization, the best trial is selected from trials that
| satisfy all constraints. A trial is considered feasible when all of its
| constraint values are less than or equal to 0.0.
|
| Returns:
| A :class:`~optuna.trial.FrozenTrial` object of the best trial.
|
| Raises:
| RuntimeError:
| If the study is multi-objective.
| ValueError:
| If no trials are completed yet, or if no feasible trials exist
| in a constrained optimization.
|
| .. seealso::
| The :ref:`reuse_best_trial` tutorial provides a detailed example of how to use this
| method.
|
| best_trials
| Return 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.
|
| .. note::
| In constrained optimization, the best trials are selected from trials that
| satisfy all constraints. A trial is considered feasible when all of its
| constraint values are less than or equal to 0.0.
|
| .. note::
| When optimizing many objectives, a large fraction of trials may become non-dominated
| in general due to the curse of dimensionality in the objective space. If this makes
| post-hoc selection difficult, consider modeling some objectives as constraints.
| Constraints can be passed via the `constraints_func` argument at the sampler
| initialization.
|
| Returns:
| A list of :class:`~optuna.trial.FrozenTrial` objects. If no trials are
| completed or if no feasible trials exist in a constrained optimization,
| an empty list is returned.
|
| best_value
| Return 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.
|
| direction
| Return 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.
|
| directions
| Return the directions of the study.
|
| Returns:
| A list of :class:`~optuna.study.StudyDirection` objects.
|
| metric_names
| Return 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.
|
| system_attrs
| Return system attributes.
|
| Returns:
| A dictionary containing all system attributes.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| trials
| 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.
|
| user_attrs
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class StudyDirection(enum.IntEnum)
| StudyDirection(*values)
|
| Direction of a :class:`~optuna.study.Study`.
|
| Attributes:
| NOT_SET:
| Direction has not been set.
| MINIMIZE:
| :class:`~optuna.study.Study` minimizes the objective function.
| MAXIMIZE:
| :class:`~optuna.study.Study` maximizes the objective function.
|
| Method resolution order:
| StudyDirection
| enum.IntEnum
| builtins.int
| enum.ReprEnum
| enum.Enum
| builtins.object
|
| Methods defined here:
|
| __format__(self, format_spec, /) from builtins.int
| Convert to a string according to format_spec.
|
| __new__(cls, value) from enum.Enum
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| MAXIMIZE = <StudyDirection.MAXIMIZE: 2>
|
| MINIMIZE = <StudyDirection.MINIMIZE: 1>
|
| NOT_SET = <StudyDirection.NOT_SET: 0>
|
| ----------------------------------------------------------------------
| Methods inherited from enum.IntEnum:
|
| __repr__(self) from enum.Enum
| Return repr(self).
|
| __str__ = __repr__(self, /) from builtins.int
| Return repr(self).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.int:
|
| __abs__(self, /)
| abs(self)
|
| __add__(self, value, /)
| Return self+value.
|
| __and__(self, value, /)
| Return self&value.
|
| __bool__(self, /)
| True if self else False
|
| __ceil__(...)
| Ceiling of an Integral returns itself.
|
| __divmod__(self, value, /)
| Return divmod(self, value).
|
| __eq__(self, value, /)
| Return self==value.
|
| __float__(self, /)
| float(self)
|
| __floor__(...)
| Flooring an Integral returns itself.
|
| __floordiv__(self, value, /)
| Return self//value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getnewargs__(self, /)
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __index__(self, /)
| Return self converted to an integer, if self is suitable for use as an index into a list.
|
| __int__(self, /)
| int(self)
|
| __invert__(self, /)
| ~self
|
| __le__(self, value, /)
| Return self<=value.
|
| __lshift__(self, value, /)
| Return self<<value.
|
| __lt__(self, value, /)
| Return self<value.
|
| __mod__(self, value, /)
| Return self%value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __neg__(self, /)
| -self
|
| __or__(self, value, /)
| Return self|value.
|
| __pos__(self, /)
| +self
|
| __pow__(self, value, mod=None, /)
| Return pow(self, value, mod).
|
| __radd__(self, value, /)
| Return value+self.
|
| __rand__(self, value, /)
| Return value&self.
|
| __rdivmod__(self, value, /)
| Return divmod(value, self).
|
| __rfloordiv__(self, value, /)
| Return value//self.
|
| __rlshift__(self, value, /)
| Return value<<self.
|
| __rmod__(self, value, /)
| Return value%self.
|
| __rmul__(self, value, /)
| Return value*self.
|
| __ror__(self, value, /)
| Return value|self.
|
| __round__(...)
| Rounding an Integral returns itself.
|
| Rounding with an ndigits argument also returns an integer.
|
| __rpow__(self, value, mod=None, /)
| Return pow(value, self, mod).
|
| __rrshift__(self, value, /)
| Return value>>self.
|
| __rshift__(self, value, /)
| Return self>>value.
|
| __rsub__(self, value, /)
| Return value-self.
|
| __rtruediv__(self, value, /)
| Return value/self.
|
| __rxor__(self, value, /)
| Return value^self.
|
| __sizeof__(self, /)
| Returns size in memory, in bytes.
|
| __sub__(self, value, /)
| Return self-value.
|
| __truediv__(self, value, /)
| Return self/value.
|
| __trunc__(...)
| Truncating an Integral returns itself.
|
| __xor__(self, value, /)
| Return self^value.
|
| as_integer_ratio(self, /)
| Return a pair of integers, whose ratio is equal to the original int.
|
| The ratio is in lowest terms and has a positive denominator.
|
| >>> (10).as_integer_ratio()
| (10, 1)
| >>> (-10).as_integer_ratio()
| (-10, 1)
| >>> (0).as_integer_ratio()
| (0, 1)
|
| bit_count(self, /)
| Number of ones in the binary representation of the absolute value of self.
|
| Also known as the population count.
|
| >>> bin(13)
| '0b1101'
| >>> (13).bit_count()
| 3
|
| bit_length(self, /)
| Number of bits necessary to represent self in binary.
|
| >>> bin(37)
| '0b100101'
| >>> (37).bit_length()
| 6
|
| conjugate(...)
| Returns self, the complex conjugate of any int.
|
| is_integer(self, /)
| Returns True. Exists for duck type compatibility with float.is_integer.
|
| to_bytes(self, /, length=1, byteorder='big', *, signed=False)
| Return an array of bytes representing an integer.
|
| length
| Length of bytes object to use. An OverflowError is raised if the
| integer is not representable with the given number of bytes. Default
| is length 1.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Determines whether two's complement is used to represent the integer.
| If signed is False and a negative integer is given, an OverflowError
| is raised.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.int:
|
| from_bytes(bytes, byteorder='big', *, signed=False)
| Return the integer represented by the given array of bytes.
|
| bytes
| Holds the array of bytes to convert. The argument must either
| support the buffer protocol or be an iterable object producing bytes.
| Bytes and bytearray are examples of built-in objects that support the
| buffer protocol.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Indicates whether two's complement is used to represent the integer.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.int:
|
| denominator
| the denominator of a rational number in lowest terms
|
| imag
| the imaginary part of a complex number
|
| numerator
| the numerator of a rational number in lowest terms
|
| real
| the real part of a complex number
|
| ----------------------------------------------------------------------
| Methods inherited from enum.Enum:
|
| __dir__(self)
| Returns public methods and other interesting attributes.
|
| __init__(self, *args, **kwds)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce_ex__(self, proto)
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from enum.Enum:
|
| name
| The name of the Enum member.
|
| value
| The value of the Enum member.
|
| ----------------------------------------------------------------------
| Static methods inherited from enum.EnumType:
|
| __contains__(value)
| Return True if `value` is in `cls`.
|
| `value` is in `cls` if:
| 1) `value` is a member of `cls`, or
| 2) `value` is the value of one of the `cls`'s members.
|
| __getitem__(name)
| Return the member matching `name`.
|
| __iter__()
| Return members in definition order.
|
| __len__()
| Return the number of members (no aliases)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from enum.EnumType:
|
| __members__
| Returns a mapping of member name->value.
|
| This mapping lists all enum members, including aliases. Note that this
| is a read-only view of the internal mapping.
class StudySummary(builtins.object)
| StudySummary(study_name: 'str', direction: 'StudyDirection | None', best_trial: 'FrozenTrial | None', user_attrs: 'dict[str, Any]', system_attrs: 'dict[str, Any]', n_trials: 'int', datetime_start: 'datetime | None', study_id: 'int', *, directions: 'Sequence[StudyDirection] | None' = None)
|
| Basic attributes and aggregated results of a :class:`~optuna.study.Study`.
|
| See also :func:`optuna.study.get_all_study_summaries`.
|
| Attributes:
| study_name:
| Name of the :class:`~optuna.study.Study`.
| direction:
| :class:`~optuna.study.StudyDirection` of the :class:`~optuna.study.Study`.
|
| .. note::
| This attribute is only available during single-objective optimization.
| directions:
| A sequence of :class:`~optuna.study.StudyDirection` objects.
| best_trial:
| :class:`optuna.trial.FrozenTrial` with best objective value in the
| :class:`~optuna.study.Study`.
| user_attrs:
| Dictionary that contains the attributes of the :class:`~optuna.study.Study` set with
| :func:`optuna.study.Study.set_user_attr`.
| system_attrs:
| Dictionary that contains the attributes of the :class:`~optuna.study.Study` internally
| set by Optuna.
|
| .. warning::
| Deprecated in v3.1.0. ``system_attrs`` argument will be removed in the future.
| The removal of this feature is currently scheduled for v5.0.0,
| but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
| n_trials:
| The number of trials ran in the :class:`~optuna.study.Study`.
| datetime_start:
| Datetime where the :class:`~optuna.study.Study` started.
|
| Methods defined here:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __init__(self, study_name: 'str', direction: 'StudyDirection | None', best_trial: 'FrozenTrial | None', user_attrs: 'dict[str, Any]', system_attrs: 'dict[str, Any]', n_trials: 'int', datetime_start: 'datetime | None', study_id: 'int', *, directions: 'Sequence[StudyDirection] | None' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __le__(self, other: 'Any') -> 'bool'
| Return self<=value.
|
| __lt__(self, other: 'Any') -> 'bool'
| Return self<value.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| direction
|
| directions
|
| system_attrs
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __hash__ = None
FUNCTIONS
copy_study(*, from_study_name: 'str', from_storage: 'str | storages.BaseStorage', to_storage: 'str | storages.BaseStorage', to_study_name: 'str | None' = None) -> 'None'
Copy 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.
create_study(*, storage: 'str | storages.BaseStorage | None' = None, sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None, study_name: 'str | None' = None, direction: 'str | StudyDirection | None' = None, load_if_exists: 'bool' = False, directions: 'Sequence[str | StudyDirection] | None' = None) -> 'Study'
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.
delete_study(*, study_name: 'str', storage: 'str | storages.BaseStorage') -> 'None'
Delete 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`.
get_all_study_names(storage: 'str | storages.BaseStorage') -> 'list[str]'
Get 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`.
get_all_study_summaries(storage: 'str | storages.BaseStorage', include_best_trial: 'bool' = True) -> 'list[StudySummary]'
Get 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`.
load_study(*, study_name: 'str | None', storage: 'str | storages.BaseStorage', sampler: "'samplers.BaseSampler' | None" = None, pruner: 'pruners.BasePruner | None' = None) -> 'Study'
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`.
DATA
__all__ = ['MaxTrialsCallback', 'StudyDirection', 'StudySummary', 'cop...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\study\__init__.py
optuna.trial
Python Library Documentation: package optuna.trial in optuna
NAME
optuna.trial
PACKAGE CONTENTS
_base
_fixed
_frozen
_state
_trial
CLASSES
abc.ABC(builtins.object)
optuna.trial._base.BaseTrial
optuna.trial._fixed.FixedTrial
optuna.trial._frozen.FrozenTrial
optuna.trial._trial.Trial
enum.IntEnum(builtins.int, enum.ReprEnum)
optuna.trial._state.TrialState
class BaseTrial(abc.ABC)
| Base class for trials.
|
| Note that this class is not supposed to be directly accessed by library users.
|
| Method resolution order:
| BaseTrial
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| report(self, value: 'float', step: 'int') -> 'None'
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
|
| should_prune(self) -> 'bool'
|
| suggest_categorical(self, name: 'str', choices: 'Sequence[CategoricalChoiceType]') -> 'CategoricalChoiceType'
|
| suggest_discrete_uniform(self, name: 'str', low: 'float', high: 'float', q: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| suggest_float(self, name: 'str', low: 'float', high: 'float', *, step: 'float | None' = None, log: 'bool' = False) -> 'float'
|
| suggest_int(self, name: 'str', low: 'int', high: 'int', *, step: 'int' = 1, log: 'bool' = False) -> 'int'
|
| suggest_loguniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| suggest_uniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| datetime_start
|
| distributions
|
| number
|
| params
|
| system_attrs
|
| user_attrs
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'datetime_start', 'distributions', 'p...
class FixedTrial(optuna.trial._base.BaseTrial)
| FixedTrial(params: 'dict[str, Any]', number: 'int' = 0) -> 'None'
|
| A trial class which suggests a fixed value for each parameter.
|
| This object has the same methods as :class:`~optuna.trial.Trial`, and it suggests pre-defined
| parameter values. The parameter values can be determined at the construction of the
| :class:`~optuna.trial.FixedTrial` object. In contrast to :class:`~optuna.trial.Trial`,
| :class:`~optuna.trial.FixedTrial` does not depend on :class:`~optuna.study.Study`, and it is
| useful for deploying optimization results.
|
| Example:
|
| Evaluate an objective function with parameter values given by a user.
|
| .. testcode::
|
| import optuna
|
|
| def objective(trial):
| x = trial.suggest_float("x", -100, 100)
| y = trial.suggest_categorical("y", [-1, 0, 1])
| return x**2 + y
|
|
| assert objective(optuna.trial.FixedTrial({"x": 1, "y": 0})) == 1
|
|
| .. note::
| Please refer to :class:`~optuna.trial.Trial` for details of methods and properties.
|
| Args:
| params:
| A dictionary containing all parameters.
| number:
| A trial number. Defaults to ``0``.
|
| Method resolution order:
| FixedTrial
| optuna.trial._base.BaseTrial
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, params: 'dict[str, Any]', number: 'int' = 0) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| report(self, value: 'float', step: 'int') -> 'None'
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
|
| should_prune(self) -> 'bool'
|
| suggest_categorical(self, name: 'str', choices: 'Sequence[CategoricalChoiceType]') -> 'CategoricalChoiceType'
|
| suggest_discrete_uniform(self, name: 'str', low: 'float', high: 'float', q: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., step=...) instead.
|
| suggest_float(self, name: 'str', low: 'float', high: 'float', *, step: 'float | None' = None, log: 'bool' = False) -> 'float'
|
| suggest_int(self, name: 'str', low: 'int', high: 'int', *, step: 'int' = 1, log: 'bool' = False) -> 'int'
|
| suggest_loguniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., log=True) instead.
|
| suggest_uniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float instead.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| datetime_start
|
| distributions
|
| number
|
| params
|
| system_attrs
|
| user_attrs
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.trial._base.BaseTrial:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class FrozenTrial(optuna.trial._base.BaseTrial)
| FrozenTrial(number: 'int', state: 'TrialState', value: 'float | None', datetime_start: 'datetime.datetime | None', datetime_complete: 'datetime.datetime | None', params: 'dict[str, Any]', distributions: 'dict[str, BaseDistribution]', user_attrs: 'dict[str, Any]', system_attrs: 'dict[str, Any]', intermediate_values: 'dict[int, float]', trial_id: 'int', *, values: 'Sequence[float] | None' = None) -> 'None'
|
| 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`.
|
| Method resolution order:
| FrozenTrial
| optuna.trial._base.BaseTrial
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __init__(self, number: 'int', state: 'TrialState', value: 'float | None', datetime_start: 'datetime.datetime | None', datetime_complete: 'datetime.datetime | None', params: 'dict[str, Any]', distributions: 'dict[str, BaseDistribution]', user_attrs: 'dict[str, Any]', system_attrs: 'dict[str, Any]', intermediate_values: 'dict[int, float]', trial_id: 'int', *, values: 'Sequence[float] | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __le__(self, other: 'Any') -> 'bool'
| Return self<=value.
|
| __lt__(self, other: 'Any') -> 'bool'
| Return self<value.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| report(self, value: 'float', step: 'int') -> 'None'
| 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.
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
|
| should_prune(self) -> 'bool'
| Suggest 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`.
|
| suggest_categorical(self, name: 'str', choices: 'Sequence[CategoricalChoiceType]') -> 'CategoricalChoiceType'
|
| suggest_discrete_uniform(self, name: 'str', low: 'float', high: 'float', q: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., step=...) instead.
|
| suggest_float(self, name: 'str', low: 'float', high: 'float', *, step: 'float | None' = None, log: 'bool' = False) -> 'float'
|
| suggest_int(self, name: 'str', low: 'int', high: 'int', *, step: 'int' = 1, log: 'bool' = False) -> 'int'
|
| suggest_loguniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., log=True) instead.
|
| suggest_uniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float instead.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| duration
| Return the elapsed time taken to complete the trial.
|
| Returns:
| The duration.
|
| last_step
| Return the maximum step of :attr:`intermediate_values` in the trial.
|
| Returns:
| The maximum step of intermediates.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| datetime_start
|
| distributions
|
| number
|
| params
|
| system_attrs
|
| user_attrs
|
| value
|
| values
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.trial._base.BaseTrial:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Trial(optuna.trial._base.BaseTrial)
| Trial(study: 'Study', trial_id: 'int') -> 'None'
|
| 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.
|
| Method resolution order:
| Trial
| optuna.trial._base.BaseTrial
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, study: 'Study', trial_id: 'int') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| 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.
|
| set_system_attr(self, key: 'str', value: 'Any') -> 'None'
| Set system attributes to the trial.
|
| Note that Optuna internally uses this method to save system messages such as failure
| reason of trials. Please use :func:`~optuna.trial.Trial.set_user_attr` to set users'
| attributes.
|
| Args:
| key:
| A key string of the attribute.
| value:
| A value of the attribute. The value should be JSON serializable.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| set_user_attr(self, key: 'str', value: 'Any') -> 'None'
| Set user attributes to the trial.
|
| The user attributes in the trial can be access via :func:`optuna.trial.Trial.user_attrs`.
|
| .. seealso::
|
| See the recipe on :ref:`attributes`.
|
| Example:
|
| Save fixed hyperparameters of neural network training.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.neural_network import MLPClassifier
|
| import optuna
|
| X, y = load_iris(return_X_y=True)
| X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)
|
|
| def objective(trial):
| trial.set_user_attr("BATCHSIZE", 128)
| momentum = trial.suggest_float("momentum", 0, 1.0)
| clf = MLPClassifier(
| hidden_layer_sizes=(100, 50),
| batch_size=trial.user_attrs["BATCHSIZE"],
| momentum=momentum,
| solver="sgd",
| random_state=0,
| )
| clf.fit(X_train, y_train)
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
| assert "BATCHSIZE" in study.best_trial.user_attrs.keys()
| assert study.best_trial.user_attrs["BATCHSIZE"] == 128
|
|
| Args:
| key:
| A key string of the attribute.
| value:
| A value of the attribute. The value should be JSON serializable.
|
| should_prune(self) -> 'bool'
| Suggest whether the trial should be pruned or not.
|
| The suggestion is made by a pruning algorithm associated with the trial and is based on
| previously reported values. The algorithm can be specified when constructing a
| :class:`~optuna.study.Study`.
|
| .. note::
| If no values have been reported, the algorithm cannot make meaningful suggestions.
| Similarly, if this method is called multiple times with the exact same set of reported
| values, the suggestions will be the same.
|
| .. seealso::
| Please refer to the example code in :func:`optuna.trial.Trial.report`.
|
| .. note::
| :func:`~optuna.trial.Trial.should_prune` does not support multi-objective
| optimization.
|
| Returns:
| A boolean value. If :obj:`True`, the trial should be pruned according to the
| configured pruning algorithm. Otherwise, the trial should continue.
|
| suggest_categorical(self, name: 'str', choices: 'Sequence[CategoricalChoiceType]') -> 'CategoricalChoiceType'
| Suggest a value for the categorical parameter.
|
| The value is sampled from ``choices``.
|
| Example:
|
| Suggest a kernel function of `SVC <https://scikit-learn.org/stable/modules/generated/
| sklearn.svm.SVC.html>`__.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.svm import SVC
|
| 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):
| kernel = trial.suggest_categorical("kernel", ["linear", "poly", "rbf"])
| clf = SVC(kernel=kernel, gamma="scale", random_state=0)
| clf.fit(X_train, y_train)
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
|
| Args:
| name:
| A parameter name.
| choices:
| Parameter value candidates.
|
| .. seealso::
| :class:`~optuna.distributions.CategoricalDistribution`.
|
| Returns:
| A suggested value.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_discrete_uniform(self, name: 'str', low: 'float', high: 'float', q: 'float') -> 'float'
| Suggest a value for the discrete parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high}]`,
| and the step of discretization is :math:`q`. More specifically,
| this method returns one of the values in the sequence
| :math:`\mathsf{low}, \mathsf{low} + q, \mathsf{low} + 2 q, \dots,
| \mathsf{low} + k q \le \mathsf{high}`,
| where :math:`k` denotes an integer. Note that :math:`high` may be changed due to round-off
| errors if :math:`q` is not an integer. Please check warning messages to find the changed
| values.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| q:
| A step of discretization.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., step=...) instead.
|
| suggest_float(self, name: 'str', low: 'float', high: 'float', *, step: 'float | None' = None, log: 'bool' = False) -> 'float'
| Suggest a value for the floating point parameter.
|
| Example:
|
| Suggest a momentum, learning rate and scaling factor of learning rate
| for neural network training.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.model_selection import train_test_split
| from sklearn.neural_network import MLPClassifier
|
| import optuna
|
| X, y = load_iris(return_X_y=True)
| X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)
|
|
| def objective(trial):
| momentum = trial.suggest_float("momentum", 0.0, 1.0)
| learning_rate_init = trial.suggest_float(
| "learning_rate_init", 1e-5, 1e-3, log=True
| )
| power_t = trial.suggest_float("power_t", 0.2, 0.8, step=0.1)
| clf = MLPClassifier(
| hidden_layer_sizes=(100, 50),
| momentum=momentum,
| learning_rate_init=learning_rate_init,
| solver="sgd",
| random_state=0,
| power_t=power_t,
| )
| clf.fit(X_train, y_train)
|
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than 0.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A step of discretization.
|
| .. note::
| The ``step`` and ``log`` arguments cannot be used at the same time. To set
| the ``step`` argument to a float number, set the ``log`` argument to
| :obj:`False`.
| log:
| A flag to sample the value from the log domain or not.
| If ``log`` is true, the value is sampled from the range in the log domain.
| Otherwise, the value is sampled from the range in the linear domain.
|
| .. note::
| The ``step`` and ``log`` arguments cannot be used at the same time. To set
| the ``log`` argument to :obj:`True`, set the ``step`` argument to :obj:`None`.
|
| Returns:
| A suggested float value.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_int(self, name: 'str', low: 'int', high: 'int', *, step: 'int' = 1, log: 'bool' = False) -> 'int'
| Suggest a value for the integer parameter.
|
| The value is sampled from the integers in :math:`[\mathsf{low}, \mathsf{high}]`.
|
| Example:
|
| Suggest the number of trees in `RandomForestClassifier <https://scikit-learn.org/
| stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html>`__.
|
| .. testcode::
|
| import numpy as np
| from sklearn.datasets import load_iris
| from sklearn.ensemble import RandomForestClassifier
| 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):
| n_estimators = trial.suggest_int("n_estimators", 50, 400)
| clf = RandomForestClassifier(n_estimators=n_estimators, random_state=0)
| clf.fit(X_train, y_train)
| return clf.score(X_valid, y_valid)
|
|
| study = optuna.create_study(direction="maximize")
| study.optimize(objective, n_trials=3)
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| ``low`` must be less than or equal to ``high``. If ``log`` is :obj:`True`,
| ``low`` must be larger than 0.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
| ``high`` must be greater than or equal to ``low``.
| step:
| A step of discretization.
|
| .. note::
| Note that :math:`\mathsf{high}` is modified if the range is not divisible by
| :math:`\mathsf{step}`. Please check the warning messages to find the changed
| values.
|
| .. note::
| The method returns one of the values in the sequence
| :math:`\mathsf{low}, \mathsf{low} + \mathsf{step}, \mathsf{low} + 2 *
| \mathsf{step}, \dots, \mathsf{low} + k * \mathsf{step} \le
| \mathsf{high}`, where :math:`k` denotes an integer.
|
| .. note::
| The ``step != 1`` and ``log`` arguments cannot be used at the same time.
| To set the ``step`` argument :math:`\mathsf{step} \ge 2`, set the
| ``log`` argument to :obj:`False`.
| log:
| A flag to sample the value from the log domain or not.
|
| .. note::
| If ``log`` is true, at first, the range of suggested values is divided into
| grid points of width 1. The range of suggested values is then converted to
| a log domain, from which a value is sampled. The uniformly sampled
| value is re-converted to the original domain and rounded to the nearest grid
| point that we just split, and the suggested value is determined.
| For example, if `low = 2` and `high = 8`, then the range of suggested values is
| `[2, 3, 4, 5, 6, 7, 8]` and lower values tend to be more sampled than higher
| values.
|
| .. note::
| The ``step != 1`` and ``log`` arguments cannot be used at the same time.
| To set the ``log`` argument to :obj:`True`, set the ``step`` argument to 1.
|
| .. seealso::
| :ref:`configurations` tutorial describes more details and flexible usages.
|
| suggest_loguniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| Suggest a value for the continuous parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high})`
| in the log domain. When :math:`\mathsf{low} = \mathsf{high}`, the value of
| :math:`\mathsf{low}` will be returned.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float(..., log=True) instead.
|
| suggest_uniform(self, name: 'str', low: 'float', high: 'float') -> 'float'
| Suggest a value for the continuous parameter.
|
| The value is sampled from the range :math:`[\mathsf{low}, \mathsf{high})`
| in the linear domain. When :math:`\mathsf{low} = \mathsf{high}`, the value of
| :math:`\mathsf{low}` will be returned.
|
| Args:
| name:
| A parameter name.
| low:
| Lower endpoint of the range of suggested values. ``low`` is included in the range.
| high:
| Upper endpoint of the range of suggested values. ``high`` is included in the range.
|
| Returns:
| A suggested float value.
|
| .. warning::
| Deprecated in v3.0.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v6.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.0.0.
|
|
| Use suggest_float instead.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| datetime_start
| Return start datetime.
|
| Returns:
| Datetime where the :class:`~optuna.trial.Trial` started.
|
| distributions
| Return distributions of parameters to be optimized.
|
| Returns:
| A dictionary containing all distributions.
|
| number
| Return trial's number which is consecutive and unique in a study.
|
| Returns:
| A trial number.
|
| params
| Return parameters to be optimized.
|
| Returns:
| A dictionary containing all parameters.
|
| relative_params
|
| system_attrs
| Return system attributes.
|
| Returns:
| A dictionary containing all system attributes.
|
| .. warning::
| Deprecated in v3.1.0. This feature will be removed in the future. The removal of this
| feature is currently scheduled for v5.0.0, but this schedule is subject to change.
| See https://github.com/optuna/optuna/releases/tag/v3.1.0.
|
| user_attrs
| Return user attributes.
|
| Returns:
| A dictionary containing all user attributes.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from optuna.trial._base.BaseTrial:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class TrialState(enum.IntEnum)
| TrialState(*values)
|
| State of a :class:`~optuna.trial.Trial`.
|
| Attributes:
| RUNNING:
| The :class:`~optuna.trial.Trial` is running.
| WAITING:
| The :class:`~optuna.trial.Trial` is waiting and unfinished.
| COMPLETE:
| The :class:`~optuna.trial.Trial` has been finished without any error.
| PRUNED:
| The :class:`~optuna.trial.Trial` has been pruned with
| :class:`~optuna.exceptions.TrialPruned`.
| FAIL:
| The :class:`~optuna.trial.Trial` has failed due to an uncaught error.
|
| Method resolution order:
| TrialState
| enum.IntEnum
| builtins.int
| enum.ReprEnum
| enum.Enum
| builtins.object
|
| Methods defined here:
|
| __format__(self, format_spec, /) from builtins.int
| Convert to a string according to format_spec.
|
| __new__(cls, value) from enum.Enum
| Create and return a new object. See help(type) for accurate signature.
|
| __str__(self) from enum.Enum
| Return str(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| COMPLETE = <TrialState.COMPLETE: 1>
|
| FAIL = <TrialState.FAIL: 3>
|
| PRUNED = <TrialState.PRUNED: 2>
|
| RUNNING = <TrialState.RUNNING: 0>
|
| WAITING = <TrialState.WAITING: 4>
|
| ----------------------------------------------------------------------
| Methods inherited from enum.IntEnum:
|
| __repr__(self) from enum.Enum
| Return repr(self).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.int:
|
| __abs__(self, /)
| abs(self)
|
| __add__(self, value, /)
| Return self+value.
|
| __and__(self, value, /)
| Return self&value.
|
| __bool__(self, /)
| True if self else False
|
| __ceil__(...)
| Ceiling of an Integral returns itself.
|
| __divmod__(self, value, /)
| Return divmod(self, value).
|
| __eq__(self, value, /)
| Return self==value.
|
| __float__(self, /)
| float(self)
|
| __floor__(...)
| Flooring an Integral returns itself.
|
| __floordiv__(self, value, /)
| Return self//value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getnewargs__(self, /)
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __index__(self, /)
| Return self converted to an integer, if self is suitable for use as an index into a list.
|
| __int__(self, /)
| int(self)
|
| __invert__(self, /)
| ~self
|
| __le__(self, value, /)
| Return self<=value.
|
| __lshift__(self, value, /)
| Return self<<value.
|
| __lt__(self, value, /)
| Return self<value.
|
| __mod__(self, value, /)
| Return self%value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __neg__(self, /)
| -self
|
| __or__(self, value, /)
| Return self|value.
|
| __pos__(self, /)
| +self
|
| __pow__(self, value, mod=None, /)
| Return pow(self, value, mod).
|
| __radd__(self, value, /)
| Return value+self.
|
| __rand__(self, value, /)
| Return value&self.
|
| __rdivmod__(self, value, /)
| Return divmod(value, self).
|
| __rfloordiv__(self, value, /)
| Return value//self.
|
| __rlshift__(self, value, /)
| Return value<<self.
|
| __rmod__(self, value, /)
| Return value%self.
|
| __rmul__(self, value, /)
| Return value*self.
|
| __ror__(self, value, /)
| Return value|self.
|
| __round__(...)
| Rounding an Integral returns itself.
|
| Rounding with an ndigits argument also returns an integer.
|
| __rpow__(self, value, mod=None, /)
| Return pow(value, self, mod).
|
| __rrshift__(self, value, /)
| Return value>>self.
|
| __rshift__(self, value, /)
| Return self>>value.
|
| __rsub__(self, value, /)
| Return value-self.
|
| __rtruediv__(self, value, /)
| Return value/self.
|
| __rxor__(self, value, /)
| Return value^self.
|
| __sizeof__(self, /)
| Returns size in memory, in bytes.
|
| __sub__(self, value, /)
| Return self-value.
|
| __truediv__(self, value, /)
| Return self/value.
|
| __trunc__(...)
| Truncating an Integral returns itself.
|
| __xor__(self, value, /)
| Return self^value.
|
| as_integer_ratio(self, /)
| Return a pair of integers, whose ratio is equal to the original int.
|
| The ratio is in lowest terms and has a positive denominator.
|
| >>> (10).as_integer_ratio()
| (10, 1)
| >>> (-10).as_integer_ratio()
| (-10, 1)
| >>> (0).as_integer_ratio()
| (0, 1)
|
| bit_count(self, /)
| Number of ones in the binary representation of the absolute value of self.
|
| Also known as the population count.
|
| >>> bin(13)
| '0b1101'
| >>> (13).bit_count()
| 3
|
| bit_length(self, /)
| Number of bits necessary to represent self in binary.
|
| >>> bin(37)
| '0b100101'
| >>> (37).bit_length()
| 6
|
| conjugate(...)
| Returns self, the complex conjugate of any int.
|
| is_integer(self, /)
| Returns True. Exists for duck type compatibility with float.is_integer.
|
| to_bytes(self, /, length=1, byteorder='big', *, signed=False)
| Return an array of bytes representing an integer.
|
| length
| Length of bytes object to use. An OverflowError is raised if the
| integer is not representable with the given number of bytes. Default
| is length 1.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Determines whether two's complement is used to represent the integer.
| If signed is False and a negative integer is given, an OverflowError
| is raised.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.int:
|
| from_bytes(bytes, byteorder='big', *, signed=False)
| Return the integer represented by the given array of bytes.
|
| bytes
| Holds the array of bytes to convert. The argument must either
| support the buffer protocol or be an iterable object producing bytes.
| Bytes and bytearray are examples of built-in objects that support the
| buffer protocol.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Indicates whether two's complement is used to represent the integer.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.int:
|
| denominator
| the denominator of a rational number in lowest terms
|
| imag
| the imaginary part of a complex number
|
| numerator
| the numerator of a rational number in lowest terms
|
| real
| the real part of a complex number
|
| ----------------------------------------------------------------------
| Methods inherited from enum.Enum:
|
| __dir__(self)
| Returns public methods and other interesting attributes.
|
| __init__(self, *args, **kwds)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce_ex__(self, proto)
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from enum.Enum:
|
| name
| The name of the Enum member.
|
| value
| The value of the Enum member.
|
| ----------------------------------------------------------------------
| Static methods inherited from enum.EnumType:
|
| __contains__(value)
| Return True if `value` is in `cls`.
|
| `value` is in `cls` if:
| 1) `value` is a member of `cls`, or
| 2) `value` is the value of one of the `cls`'s members.
|
| __getitem__(name)
| Return the member matching `name`.
|
| __iter__()
| Return members in definition order.
|
| __len__()
| Return the number of members (no aliases)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from enum.EnumType:
|
| __members__
| Returns a mapping of member name->value.
|
| This mapping lists all enum members, including aliases. Note that this
| is a read-only view of the internal mapping.
FUNCTIONS
create_trial(*, state: 'TrialState' = <TrialState.COMPLETE: 1>, value: 'float | None' = None, values: 'Sequence[float] | None' = None, params: 'dict[str, Any] | None' = None, distributions: 'dict[str, BaseDistribution] | None' = None, user_attrs: 'dict[str, Any] | None' = None, system_attrs: 'dict[str, Any] | None' = None, intermediate_values: 'dict[int, float] | None' = None) -> 'FrozenTrial'
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.
DATA
__all__ = ['BaseTrial', 'FixedTrial', 'FrozenTrial', 'Trial', 'TrialSt...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\trial\__init__.py
optuna.version
Python Library Documentation: module optuna.version in optuna
NAME
optuna.version
VERSION
4.9.0
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\version.py
optuna.visualization
Python Library Documentation: package optuna.visualization in optuna
NAME
optuna.visualization
PACKAGE CONTENTS
_contour
_edf
_hypervolume_history
_intermediate_values
_optimization_history
_parallel_coordinate
_param_importances
_pareto_front
_plotly_imports
_rank
_slice
_terminator_improvement
_timeline
_utils
matplotlib (package)
FUNCTIONS
is_available() -> 'bool'
Returns whether visualization with plotly is available or not.
.. note::
:mod:`~optuna.visualization` module depends on plotly version 4.0.0 or higher. If a
supported version of plotly isn't installed in your environment, this function will return
:obj:`False`. In such case, please execute ``$ pip install -U plotly>=4.0.0`` to install
plotly.
Returns:
:obj:`True` if visualization with plotly is available, :obj:`False` otherwise.
plot_contour(study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot the parameter relationship as contour plot in a study.
Note that, if a parameter contains missing values, a trial with missing values is not plotted.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the color bar.
Returns:
A :class:`plotly.graph_objects.Figure` object.
.. note::
The colormap is reversed when the ``target`` argument isn't :obj:`None` or ``direction``
of :class:`~optuna.study.Study` is ``minimize``.
plot_edf(study: 'Study | Sequence[Study]', *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot the objective value EDF (empirical distribution function) of a study.
Note that only the complete trials are considered when plotting the EDF.
.. note::
EDF is useful to analyze and improve search spaces.
For instance, you can see a practical use case of EDF in the paper
`Designing Network Design Spaces
<https://doi.ieeecomputersociety.org/10.1109/CVPR42600.2020.01044>`__.
.. note::
The plotted EDF assumes that the value of the objective function is in
accordance with the uniform distribution over the objective space.
Args:
study:
A target :class:`~optuna.study.Study` object.
You can pass multiple studies if you want to compare those EDFs.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_hypervolume_history(study: 'Study', reference_point: 'Sequence[float]') -> "'go.Figure'"
Plot hypervolume history of all trials in a study.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their hypervolumes.
The number of objectives must be 2 or more.
reference_point:
A reference point to use for hypervolume computation.
The dimension of the reference point must be the same as the number of objectives.
Returns:
A :class:`plotly.graph_objects.Figure` object.
.. note::
Added in v3.3.0 as an experimental feature. The interface may change in newer versions
without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.
plot_intermediate_values(study: 'Study') -> "'go.Figure'"
Plot intermediate values of all trials in a study.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their intermediate
values.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_optimization_history(study: 'Study | Sequence[Study]', *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value', error_bar: 'bool' = False) -> "'go.Figure'"
Plot optimization history of all trials in a study.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
You can pass multiple studies if you want to compare those optimization histories.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label and the legend.
error_bar:
A flag to show the error bar.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_parallel_coordinate(study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot the high-dimensional parameter relationships in a study.
Note that, if a parameter contains missing values, a trial with missing values is not plotted.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label and the legend.
Returns:
A :class:`plotly.graph_objects.Figure` object.
.. note::
The colormap is reversed when the ``target`` argument isn't :obj:`None` or ``direction``
of :class:`~optuna.study.Study` is ``minimize``.
plot_param_importances(study: 'Study', evaluator: 'BaseImportanceEvaluator | None' = None, params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot hyperparameter importances.
.. seealso::
This function visualizes the results of :func:`optuna.importance.get_param_importances`.
Args:
study:
An optimized study.
evaluator:
An importance evaluator object that specifies which algorithm to base the importance
assessment on.
Defaults to
:class:`~optuna.importance.FanovaImportanceEvaluator`.
.. note::
Although the default importance evaluator in Optuna is
:class:`~optuna.importance.FanovaImportanceEvaluator`, Optuna Dashboard uses a
light-weight evaluator, i.e.,
:class:`~optuna.importance.PedAnovaImportanceEvaluator`, for runtime performance
purposes, yielding a different result.
params:
A list of names of parameters to assess.
If :obj:`None`, all parameters that are present in all of the completed trials are
assessed.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
For multi-objective optimization, all objectives will be plotted if ``target``
is :obj:`None`.
.. note::
This argument can be used to specify which objective to plot if ``study`` is being
used for multi-objective optimization. For example, to get only the hyperparameter
importance of the first objective, use ``target=lambda t: t.values[0]`` for the
target parameter.
target_name:
Target's name to display on the legend. Names set via
:meth:`~optuna.study.Study.set_metric_names` will be used if ``target`` is :obj:`None`,
overriding this argument.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_pareto_front(study: 'Study', *, target_names: 'list[str] | None' = None, include_dominated_trials: 'bool' = True, axis_order: 'list[int] | None' = None, constraints_func: 'Callable[[FrozenTrial], Sequence[float]] | None' = None, targets: 'Callable[[FrozenTrial], Sequence[float]] | None' = None) -> "'go.Figure'"
Plot the Pareto front of a study.
.. seealso::
Please refer to :ref:`multi_objective` for the tutorial of the Pareto front visualization.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values. The number of objectives must be either 2 or 3 when ``targets`` is :obj:`None`.
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead. If ``targets`` is specified
for a study that does not contain any completed trial,
``target_name`` must be specified.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used. ``axis_order`` and ``targets`` cannot be used at the same time.
.. warning::
Deprecated in v3.0.0. This feature will be removed in the future. The removal of
this feature is currently scheduled for v5.0.0, but this schedule is subject to
change. See https://github.com/optuna/optuna/releases/tag/v3.0.0.
constraints_func:
An optional function that computes the objective constraints. It must take a
:class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
constraint is violated. A value equal to or smaller than 0 is considered feasible.
This specification is the same as in, for example,
:class:`~optuna.samplers.NSGAIISampler`.
If given, trials are classified into three categories: feasible and best, feasible but
non-best, and infeasible. Categories are shown in different colors. Here, whether a
trial is best (on Pareto front) or not is determined ignoring all infeasible trials.
.. warning::
Deprecated in v4.0.0. This feature will be removed in the future. The removal of
this feature is currently scheduled for v6.0.0, but this schedule is subject to
change. See https://github.com/optuna/optuna/releases/tag/v4.0.0.
targets:
A function that returns targets values to display.
The argument to this function is :class:`~optuna.trial.FrozenTrial`.
``axis_order`` and ``targets`` cannot be used at the same time.
If ``study.n_objectives`` is neither 2 nor 3, ``targets`` must be specified.
.. note::
Added in v3.0.0 as an experimental feature. The interface may change in newer
versions without prior notice.
See https://github.com/optuna/optuna/releases/tag/v3.0.0.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_rank(study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot parameter relations as scatter plots with colors indicating ranks of target value.
Note that trials missing the specified parameters will not be plotted.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the color bar.
Returns:
A :class:`plotly.graph_objects.Figure` object.
.. note::
This function requires plotly >= 5.0.0.
plot_slice(study: 'Study', params: 'list[str] | None' = None, *, target: 'Callable[[FrozenTrial], float] | None' = None, target_name: 'str' = 'Objective Value') -> "'go.Figure'"
Plot the parameter relationship as slice plot in a study.
Note that, if a parameter contains missing values, a trial with missing values is not plotted.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label.
Returns:
A :class:`plotly.graph_objects.Figure` object.
plot_terminator_improvement(study: 'Study', plot_error: 'bool' = False, improvement_evaluator: 'BaseImprovementEvaluator | None' = None, error_evaluator: 'BaseErrorEvaluator | None' = None, min_n_trials: 'int' = 20) -> "'go.Figure'"
Plot the potentials for future objective improvement.
This function visualizes the objective improvement potentials, evaluated
with ``improvement_evaluator``.
It helps to determine whether we should continue the optimization or not.
You can also plot the error evaluated with
``error_evaluator`` if the ``plot_error`` argument is set to :obj:`True`.
Note that this function may take some time to compute
the improvement potentials.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted
for their improvement.
plot_error:
A flag to show the error. If it is set to :obj:`True`, errors
evaluated by ``error_evaluator`` are also plotted as line graph.
Defaults to :obj:`False`.
improvement_evaluator:
An object that evaluates the improvement of the objective function.
Defaults to :class:`~optuna.terminator.RegretBoundEvaluator`.
error_evaluator:
An object that evaluates the error inherent in the objective function.
Defaults to :class:`~optuna.terminator.CrossValidationErrorEvaluator`.
min_n_trials:
The minimum number of trials before termination is considered.
Terminator improvements for trials below this value are
shown in a lighter color. Defaults to ``20``.
Returns:
A :class:`plotly.graph_objects.Figure` object.
.. note::
Added in v3.2.0 as an experimental feature. The interface may change in newer versions
without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.2.0.
plot_timeline(study: 'Study', n_recent_trials: 'int | None' = None) -> "'go.Figure'"
Plot the timeline of a study.
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted with
their lifetime.
n_recent_trials:
The number of recent trials to plot. If :obj:`None`, all trials are plotted.
If specified, only the most recent ``n_recent_trials`` will be displayed.
Must be a positive integer.
Returns:
A :class:`plotly.graph_objects.Figure` object.
Raises:
ValueError: if ``n_recent_trials`` is 0 or negative.
DATA
__all__ = ['is_available', 'matplotlib', 'plot_contour', 'plot_edf', '...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\optuna\visualization\__init__.py