discrete_optimization.generic_tools.callbacks package

Submodules

discrete_optimization.generic_tools.callbacks.backup module

class discrete_optimization.generic_tools.callbacks.backup.PickleBestSolutionBackup(save_nb_steps: int, backup_path: str = 'debug.pkl')

Bases: Callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.callback module

class discrete_optimization.generic_tools.callbacks.callback.Callback

Bases: object

Base class used to build new callbacks.

Callbacks can be passed to solvers solve() in order to hook into the various stages of the solve.

To create a custom callback, subclass discrete_optimization.generic_tools.callbacks.Callback and override the method associated with the stage of interest.

on_solve_end(res: ResultStorage, solver: SolverDO)

Called at the end of solve.

Parameters:

• res – current result storage

• solver – solvers using the callback

on_solve_start(solver: SolverDO)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

set_params(params)

class discrete_optimization.generic_tools.callbacks.callback.CallbackList(callbacks=None, **params)

Bases: Callback

Container abstracting a list of callbacks.

append(callback)

on_solve_end(res: ResultStorage, solver: SolverDO)

Called at the end of solve.

Parameters:

• res – current result storage

• solver – solvers using the callback

on_solve_start(solver: SolverDO)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

set_params(params)

discrete_optimization.generic_tools.callbacks.early_stoppers module

class discrete_optimization.generic_tools.callbacks.early_stoppers.NbIterationStopper(nb_iteration_max: int)

Bases: Callback

Callback to stop the optimization when a given number of solutions are found.

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

class discrete_optimization.generic_tools.callbacks.early_stoppers.ObjectiveGapCpSatSolver(objective_gap_rel: float | None = None, objective_gap_abs: float | None = None)

Bases: Callback

Stop the cpsat solver according to some classical convergence criteria It could be done differently (playing with parameters of cpsat directly)

on_step_end(step: int, res: ResultStorage, solver: OrtoolsCpSatSolver) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

class discrete_optimization.generic_tools.callbacks.early_stoppers.TimerStopper(total_seconds: int, check_nb_steps: int = 1)

Bases: Callback

Callback to stop the optimization after a given time.

Stops the optimization process if a limit training time has been elapsed. This time is checked after each check_nb_steps steps.

on_solve_start(solver: SolverDO)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.loggers module

class discrete_optimization.generic_tools.callbacks.loggers.NbIterationTracker(step_verbosity_level: int = 10, end_verbosity_level: int = 20)

Bases: Callback

Log the number of iteration of a given solver

on_solve_end(res: ResultStorage, solver: SolverDO)

Called at the end of solve.

Parameters:

• res – current result storage

• solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

class discrete_optimization.generic_tools.callbacks.loggers.ObjectiveLogger(step_verbosity_level: int = 10, end_verbosity_level: int = 20)

Bases: Callback

Log the current best objective function at every iteration/new solution found by the solver

on_solve_end(res: ResultStorage, solver: SolverDO)

Called at the end of solve.

Parameters:

• res – current result storage

• solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.optuna module

class discrete_optimization.generic_tools.callbacks.optuna.OptunaCallback(trial: optuna.trial.Trial, optuna_report_nb_steps: int = 1, starting_time: float | None = None, elapsed_time_attr: str = 'elapsed_time', report_time: bool = False, report_time_unit: float = 1.0, pruning: bool = True, **kwargs)

Bases: Callback

Callback reporting intermediate values to prune unpromising trials during Optuna hyperparameters tuning.

Adapted to single objective optimization (res.fit is a float)

The callback report to optuna intermediate fitness with the corresponding step number or elapsed time since starting time. It also updates the user attribute used to store computing time, so that pruned or failed trials will still have the user attribute updated. If the optuna pruner see that the trial should be pruned, raise the appropriate TrialPruned exception.

Parameters:

• trial – A optuna.trial.Trial corresponding to the current evaluation of the objective function.

• optuna_report_nb_steps – report intermediate result every optuna_report_nb_steps steps when the number of iterations is high, setting this to 1 could slow too much run of a single trial

• starting_time – float representing the start time of the solving process. Should be the result of a call to time.perf_counter(). Default to time.perf_counter() called by on_solve_start(). Useful to be on par with a clock set outside the callback.

• elapsed_time_attr – key of trial user attribute used to store the elapsed time at each step

• report_time – if True, report to optuna intermediate fitness with elapsed time instead of step

• report_time_unit – fraction of second used as unit when reporting time. Second is represented by 1, millisecond by 0.001, etc. This may be useful starting from optuna 4.0 as report steps are converted to integers.

• pruning – if True, use the optuna pruner to decide if we the trial should be pruned. Else never try to prune.

on_solve_start(solver: SolverDO)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.sequential_solvers_callback module

class discrete_optimization.generic_tools.callbacks.sequential_solvers_callback.RetrieveSubRes

Bases: Callback

Utility to store separately solutions found at each step of a lexico or Sequential solve. WARNING : This will work only if the solution object can be stored in a set.

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.stats_retrievers module

class discrete_optimization.generic_tools.callbacks.stats_retrievers.BasicStatsCallback

Bases: Callback

This callback is storing the computation time at different step of the solving process, this can help to display the evolution of the best solution through time, and compare easily different solvers.

on_solve_end(res: ResultStorage, solver: SolverDO)

Called at the end of solve. Args: res: current result storage solver: solvers using the callback

on_solve_start(solver: SolverDO)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

class discrete_optimization.generic_tools.callbacks.stats_retrievers.StatsCpsatCallback

Bases: BasicStatsCallback

This callback is specific to cpsat solver.

on_solve_end(res: ResultStorage, solver: OrtoolsCpSatSolver)

Called at the end of solve. Args: res: current result storage solver: solvers using the callback

on_solve_start(solver: OrtoolsCpSatSolver)

Called at the start of solve.

Parameters:

solver – solvers using the callback

on_step_end(step: int, res: ResultStorage, solver: OrtoolsCpSatSolver) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

discrete_optimization.generic_tools.callbacks.warm_start_callback module

class discrete_optimization.generic_tools.callbacks.warm_start_callback.WarmStartCallback(warm_start_best_solution: bool = True, warm_start_last_solution: bool = False)

Bases: Callback

on_step_end(step: int, res: ResultStorage, solver: SolverDO) → bool | None

Called at the end of an optimization step.

Parameters:

• step – index of step

• res – current result storage

• solver – solvers using the callback

Returns:

If True, the optimization process is stopped, else it goes on.

Module contents