optuna.storages.RetryFailedTrialCallback

class optuna.storages.RetryFailedTrialCallback(max_retry=None, inherit_intermediate_values=False)[source]

Retry a failed trial up to a maximum number of times.

When a trial fails, this callback can be used with a class in optuna.storages to recreate the trial in TrialState.WAITING to queue up the trial to be run again.

The failed trial can be identified by the retried_trial_number() function. Even if repetitive failure occurs (a retried trial fails 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 retry_history() function.

This callback is helpful in environments where trials may fail due to external conditions, such as being preempted by other processes.

Usage:

import optuna
from optuna.storages import RetryFailedTrialCallback

storage = optuna.storages.RDBStorage(
    url="sqlite:///:memory:",
    heartbeat_interval=60,
    grace_period=120,
    failed_trial_callback=RetryFailedTrialCallback(max_retry=3),
)

study = optuna.create_study(
    storage=storage,
)

See also

See RDBStorage.

Parameters:

max_retry (int | None) – The max number of times a trial can be retried. Must be set to None or an integer. If set to the default value of None will retry indefinitely. If set to an integer, will only retry that many times.
inherit_intermediate_values (bool) – Option to inherit trial.intermediate_values reported by optuna.trial.Trial.report() from the failed trial. Default is 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

`retried_trial_number`(trial)	Return the number of the original trial being retried.
`retry_history`(trial)	Return the list of retried trial numbers with respect to the specified trial.

static retried_trial_number(trial)[source]

Return the number of the original trial being retried.

Parameters:: trial (FrozenTrial) – The trial object.
Returns:: The number of the first failed trial. If not retry of a previous trial, returns None.
Return type:: int | 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.

static retry_history(trial)[source]

Return the list of retried trial numbers with respect to the specified trial.

Parameters:: trial (FrozenTrial) – 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 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.
Return type:: list[int]

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.