optuna.multi_objective.study

class optuna.multi_objective.study.MultiObjectiveStudy(study: optuna.study.Study)[source]

A study corresponds to a multi-objective optimization task, i.e., a set of trials.

This object provides interfaces to run a new 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 create_study() and load_study() respectively.

Note

Added in v1.4.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v1.4.0.

property directions

Return the optimization direction list.

Returns

A list that contains the optimization direction for each objective value.

enqueue_trial(params: Dict[str, Any]) → None[source]

Enqueue a trial with given parameter values.

You can fix the next sampling parameters which will be evaluated in your objective function.

Please refer to the documentation of optuna.study.Study.enqueue_trial() for further details.

Parameters

params – Parameter values to pass your objective function.

get_pareto_front_trials() → List[optuna.multi_objective.trial.FrozenMultiObjectiveTrial][source]

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.

Returns

A list of FrozenMultiObjectiveTrial objects.

get_trials(deepcopy: bool = True) → List[optuna.multi_objective.trial.FrozenMultiObjectiveTrial][source]

Return all trials in the study.

The returned trials are ordered by trial number.

For library users, it’s recommended to use more handy trials property to get the trials instead.

Parameters

deepcopy – Flag to control whether to apply copy.deepcopy() to the trials. Note that if you set the flag to 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.

Returns

A list of FrozenMultiObjectiveTrial objects.

property n_objectives

Return the number of objectives.

Returns

Number of objectives.

optimize(objective: Callable[[multi_objective.trial.MultiObjectiveTrial], Sequence[float]], timeout: Optional[int] = None, n_trials: Optional[int] = None, n_jobs: int = 1, catch: Union[Tuple[()], Tuple[Type[Exception]]] = (), callbacks: Optional[List[Callable[[multi_objective.study.MultiObjectiveStudy, multi_objective.trial.FrozenMultiObjectiveTrial], None]]] = None, gc_after_trial: bool = True, show_progress_bar: bool = False) → None[source]

Optimize an objective function.

This method is the same as optuna.study.Study.optimize() except for taking an objective function that returns multi-objective values as the argument.

Please refer to the documentation of optuna.study.Study.optimize() for further details.

property sampler

Return the sampler.

Returns

A BaseMultiObjectiveSampler object.

set_user_attr(key: str, value: Any) → None[source]

Set a user attribute to the study.

Parameters

  • key – A key string of the attribute.

  • value – A value of the attribute. The value should be JSON serializable.

property 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).

Returns

A list of FrozenMultiObjectiveTrial objects.

property user_attrs

Return user attributes.

Returns

A dictionary containing all user attributes.

optuna.multi_objective.study.create_study(directions: List[str], study_name: Optional[str] = None, storage: Union[None, str, optuna.storages._base.BaseStorage] = None, sampler: Optional[multi_objective.samplers.BaseMultiObjectiveSampler] = None, load_if_exists: bool = False) → optuna.multi_objective.study.MultiObjectiveStudy[source]

Create a new MultiObjectiveStudy.

Parameters

  • directions – Optimization direction for each objective value. Set minimize for minimization and maximize for maximization.

  • study_name – Study’s name. If this argument is set to None, a unique name is generated automatically.

  • storage –

    Database URL. If this argument is set to None, in-memory storage is used, and the 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 RDBStorage with your desired options and pass it to the storage argument instead of a URL.

  • sampler – A sampler object that implements background algorithm for value suggestion. If None is specified, NSGAIIMultiObjectiveSampler is used as the default. See also samplers.

  • 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 DuplicatedStudyError is raised if load_if_exists is set to False. Otherwise, the creation of the study is skipped, and the existing one is returned.

Returns

A MultiObjectiveStudy object.

Note

Added in v1.4.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v1.4.0.

optuna.multi_objective.study.load_study(study_name: str, storage: Union[str, optuna.storages._base.BaseStorage], sampler: Optional[multi_objective.samplers.BaseMultiObjectiveSampler] = None) → optuna.multi_objective.study.MultiObjectiveStudy[source]

Load the existing MultiObjectiveStudy that has the specified name.

Parameters

  • study_name – Study’s name. Each study has a unique name as an identifier.

  • storage – Database URL such as sqlite:///example.db. Please see also the documentation of create_study() for further details.

  • sampler – A sampler object that implements background algorithm for value suggestion. If None is specified, RandomMultiObjectiveSampler is used as the default. See also samplers.

Returns

A MultiObjectiveStudy object.

Note

Added in v1.4.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v1.4.0.