Study¶

class optuna.study.Study(study_name, storage, sampler=None, pruner=None)[源代码]¶

一个 study 对应于一个优化任务，即一组 trials.

该对象提供了接口用于运行新的 Trial, 获取 trial 的历史记录和设置/获取 study 中用户定义的属性。

注意，我们不建议直接使用这个构造函数。要创建或者加载 study 的话，请参考 create_study() 和 load_study() 对应的文档。

property best_params¶

返回 study 中最佳 trial 对应的参数。

返回: 包含最佳 trial 的参数的字典。

property best_trial¶

返回 study 中最佳 trial.

返回: 最佳 trial 的 FrozenTrial.

property best_value¶

返回 study 中的最佳目标函数值。

返回: 代表最佳目标函数值的浮点数。

property direction¶

返回 study 的优化方向。

返回: A StudyDirection object.

enqueue_trial(params)[源代码]¶

插入具有特定参数的 trial.

你可以固定下一次将被求值的目标函数对应的参数。

示例

import optuna

def objective(trial):
    x = trial.suggest_uniform('x', 0, 10)
    return x ** 2

study = optuna.create_study()
study.enqueue_trial({'x': 5})
study.enqueue_trial({'x': 0})
study.optimize(objective, n_trials=2)

assert study.trials[0].params == {'x': 5}
assert study.trials[1].params == {'x': 0}

参数: params -- 传入目标函数的参数值。

注解

在版本 v1.2.0 中作为一个试验性特性加入。该接口在未来可能在没有提前告知的情况下改变，见 https://github.com/optuna/optuna/releases/tag/v1.2.0.

get_trials(deepcopy=True)¶

返回 study 中所有的 trial.

返回的 trial 是根据 trial number 来排序的。

我们推荐库用户使用更方便的 trials 属性来获取 trial.

参数: deepcopy -- 用于控制是否对 trial 应用 copy.deepcopy() 的选项。注意：如果你把该选项设置成 False 的话，就不要改变返回的 trial 中的任何东西了。否则 study 的内部状态可能会崩坏且导致不可预知的情况发生。
返回: FrozenTrial 对象的列表

optimize(func, n_trials=None, timeout=None, n_jobs=1, catch=(), callbacks=None, gc_after_trial=False, show_progress_bar=False)[源代码]¶

优化目标函数。

通过从一定范围内选择合适的超参数集合，该优化过程已经完成。使用一个从特定分布上获得 suggestion 值的 sampler. 该 sampler 是通过 create_study() 来确定的。其默认值是 TPE. 关于 TPE 的更多细节见 TPESampler.

参数

func -- 目标函数。
n_trials -- trial 的个数。如果该选项被设置成 None 的话， trial 数就不存在限制了。如果 timeout 也被设置成 None 的话，该 study 将会一直创建新 trial，除非它收到了一个比如 Ctrl+C 或者是 SIGTERM 的终止信号。
timeout -- 该给定的秒数之后终止 study. 如果该选项被设置成 None 的话，该 study 将会在没有时间限制的情况下一直运行。如果 n_trials 也被设置成 None 的话，该 study 将会一直创建新 trial，除非它收到了一个比如 Ctrl+C 或者是 SIGTERM 的终止信号。
n_jobs -- 并行运行的 job 数。如果该选项被设置成了 -1, job 数目将等于 CPU 核心数。
catch -- 该选项中指定一些异常，这样，当 trial 抛出这些异常时，study 仍然会继续运行。默认情况下这是一个空元组，也就是说， study 会在碰到任何除 TrialPruned 之外的异常时都终止运行。
callbacks -- 一系列在每个 trial 终止时会被调用的回调函数。每个函数必须按照 Study 和 FrozenTrial 的顺序接受两个对应类型的参数。
gc_after_trial -- 用于确认是否在每个 trial 完成以后进行垃圾回收的选项。设置成 True 的话，垃圾回收就会运行，设置成 False 就不会了。如果运行的话，他就在内部调用 gc.collect(). 如果你发现在数个 trial 之后内存消耗猛增，请试试把该选项设置成 True.
show_progress_bar -- 设置是否显示进度条的选项。要禁用它的话，将其设置成 False. 目前这是一个试验性特性，并且当 n_jobs \([\ne 1]\) 时会被自动禁用。

set_user_attr(key, value)[源代码]¶

给 study 设定一个用户属性。

参数

key -- 一个属性键值对。
value -- 属性对应的值，该值应是可 JSON 序列化的。

stop() → None [源代码]¶

当正在运行的 trial 结束以后，推出当前的优化过程。

该方法会正在运行的 optimize() 终止，只要其中由 optimize() 生成的 trial 都结束了。该方法不会影响并行或者序列执行的 study 的任何行为。

引发: RuntimeError -- 如果该方法实在目标函数或者一个回调函数之外被调用的话。

注解

在版本 v1.4.0 中作为一个试验性特性加入。该接口在未来可能在没有提前告知的情况下改变，见 https://github.com/optuna/optuna/releases/tag/v1.4.0.

property trials¶

返回 study 中所有的 trial.

返回的 trial 是根据 trial number 来排序的。

是 self.get_trials(deepcopy=True) 的简写形式。

返回: FrozenTrial 对象的列表

trials_dataframe(attrs='number', 'value', 'datetime_start', 'datetime_complete', 'duration', 'params', 'user_attrs', 'system_attrs', 'state', multi_index=False)[源代码]¶

将 trial 导出为 pandas DataFrame.

DataFrame 提供了各种用于分析 study 的特性。它也可以用来画目标函数值的直方图或者将 trial 导出成 CSV 文件。如果 study 中没有 trial 的话，会返回一个空的 DataFrame.

示例

import optuna
import pandas

def objective(trial):
    x = trial.suggest_uniform('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.

参数

attrs -- 确定 FrozenTrial 的 field name, 将它们纳入 trial 的 DataFrame 中。
multi_index -- 指定返回的 DataFrame 是否使用 MultiIndex.如果该值为 False 的话，那些本来是多层的列（比如 (params, x)）将会被展平成 params_x.

返回

Study 中的包含 trial 的 DataFrame.

property user_attrs¶

返回用户属性。

返回: 包含所有用户属性的字典。

optuna.study.create_study(storage=None, sampler=None, pruner=None, study_name=None, direction='minimize', load_if_exists=False)[源代码]¶

创建新的 Study.

参数

storage -- 数据库 URL. 如果该参数被设置成 None 的话，Optuna 将采用内存存储。此时 Study 将无法被持久化。 .. note:: 当传入一个数据库URL之后，在内部，Optuna 将会使用 SQLAlchemy 来处理数据库。更多细节请参考 SQLAlchemy's document. 如果你想改变默认的 SQLAlchemy Engine 的话，你可以用你想要用的引擎实例化一个 RDBStorage, 并将其而不是一个 URL 传入 storage 参数。 .. _SQLAlchemy: https://www.sqlalchemy.org/ .. _SQLAlchemy 的文档: https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls .. _SQLAlchemy Engine: https://docs.sqlalchemy.org/en/latest/core/engines.html
sampler -- 一个实现了用于参数 suggestion 的 sampler 对象。如果设置成 None 的话，默认会启用 TPESampler. 参见 samplers.
pruner -- 一个用于确定提前终止无望 trial 的 pruner 对象。参见 pruners.
study_name -- Study 名。如果该参数是 None 的话，Optuna 会自动生成一个唯一的名字。
direction -- 优化方向。设置成 minimize 就是最小化，设置成 maximize 就是最大化。
load_if_exists -- 用于处理 study 名冲突情况下行为的选项。当 storage 中已经存在同名 study_name 时，如果此时 load_if_exists 是设置成 False 的话，DuplicatedStudyError 异常会被抛出。否则，创建 study 的过程将会被跳过，已经存在的那个 study 会被返回。

返回

Study 对象。

参见

也可以使用它的别名 optuna.create_study().

optuna.study.load_study(study_name, storage, sampler=None, pruner=None)[源代码]¶

加载一个指定名字的已经存在的 Study.

参数

study_name -- Study 名，每个 study 都有一个唯一的作为标识符的名字。
storage -- 诸如 sqlite:///example.db 这样的数据库 URL. 更多细节见 create_study() 的文档。
sampler -- 一个实现了用于参数 suggestion 的 sampler 对象。如果设置成 None 的话，默认会启用 TPESampler. 参见 samplers.
pruner -- 一个用于确定提前终止无望 trial 的 pruner 对象。如果设置成 None 的话，默认将会启用 MedianPruner.具体参见 pruners.

参见

也可以使用它的别名 optuna.load_study().

optuna.study.delete_study(study_name, storage)[源代码]¶

删除一个 Study 对象。

参数

study_name -- Study 名。
storage -- 诸如 sqlite:///example.db 这样的数据库 URL. 更多细节见 create_study() 的文档。

参见

也可以使用它的别名 optuna.delete_study().

optuna.study.get_all_study_summaries(storage)[源代码]¶

返回指定存储中所有 study 的历史记录。

参数: storage -- 诸如 sqlite:///example.db 这样的数据库 URL. 更多细节见 create_study() 的文档。
返回: 以 StudySummary 对象形式存在的 study 历史记录的列表。

参见

也可以使用它的别名 optuna.get_all_study_summaries().

class optuna.study.StudyDirection[源代码]¶

Study 的方向。

NOT_SET¶: 方向未设置。

MINIMIZE¶: Study 将最小化目标函数

MAXIMIZE¶: Study 将最大化目标函数

class optuna.study.StudySummary(study_name: str, direction: optuna._study_direction.StudyDirection, best_trial: Optional[optuna.trial._frozen.FrozenTrial], user_attrs: Dict[str, Any], system_attrs: Dict[str, Any], n_trials: int, datetime_start: Optional[datetime.datetime], study_id: int)[源代码]¶

一个 Study 的基本属性和简要结果。

参见 optuna.study.get_all_study_summaries().

study_name¶: Study 名。

direction¶: Study 的 StudyDirection

best_trial¶: Study 中有着最佳目标函数值的 FrozenTrial.

user_attrs¶: 通过 optuna.study.Study.set_user_attr() 来设置的，包含 Study 中属性的字典。

system_attrs¶: 由 Optuna 设定的，包含 Study 中属性的字典。

n_trials¶: Study 运行过的 trial 数目。

datetime_start¶: Study 开始的日期。