Callbacks¶

class BendersContext(benders: BendersSolver, master_problem: MasterProblem, sub_problem: SubProblem, state: BendersResult, current_comp_vals: dict[str, float]=<factory>, current_opti_cuts: list[Cut] = <factory>, current_feas_cuts: list[Cut] = <factory>, where: str = '')[source]¶

Bases: object

Context information passed to Benders decomposition callbacks.

This dataclass bundles the objects that callbacks commonly need while observing or interacting with a running Benders decomposition. It is passed as the sole argument to all callback methods in CallbackBase.

benders: BendersSolver¶: The Benders decomposition solver instance (BendersSolver).

master_problem: MasterProblem¶: The current master problem instance (MasterProblem).

sub_problem: SubProblem¶: The current subproblem instance (SubProblem, SubProblems, LogicBasedSubProblem).

state: BendersResult¶: The current state of the Benders decomposition process (BendersResult).

current_comp_vals: dict[str, float]¶: A dictionary mapping complicating variable names to their current values in the master problem solution.

current_opti_cuts: list[Cut]¶: A List of optimality cuts generated in the current iteration (OptimalityCut).

current_feas_cuts: list[Cut]¶: A List of feasibility cuts generated in the current iteration (FeasibilityCut).

where: str = ''¶

An identifier for the Branch-and-check callback trigger location (INCUMBENT or NODE).

This attributes is only relevant for callbacks in the Branch-and-check method. By default, the Branch-and-check callbacks are triggered when an incumbent solution is found. One can set bnc_frac_sol to True to trigger callbacks at fractional solutions as well, in which case this attribute will be set to NODE for those triggers.

Example

def on_opti_cut_generated(self, context: BendersContext):
    if context.where == CST.INCUMBENT:
        print("Optimality cut generated at an incumbent solution!")
    if context.where == CST.NODE:
        print("Optimality cut generated at a fractional solution!")

BD = BendersSolver(...)
BD.params.bnc_frac_sol = True
BD.register(on_opti_cut_generated)
BD.bnc_solve()

class CallbackBase[source]¶

Bases: ABC

Abstract base class for Benders decomposition callbacks.

Users can define custom callbacks by inheriting from CallbackBase and overriding the desired event methods. Each method receives a BendersContext object containing information about the current state of the Benders decomposition process. Alternatively, users can define standalone functions with names matching the methods in CallbackBase to serve as lightweight callbacks.

A callbacks are passed to Benders decomposition instances via register(). The callback can terminate the Benders process prematurely by returning the constant TERMINATE; If a callback returns PROCEED or does not return anything, the Benders process continues as normal.

See also

See Timeline of Callback Triggers for the precise timeline of when each callback is triggered.
See Expert Examples for callback usage examples.

Example

from benderslib import CallbackBase, BendersContext

# Class-based callback
class MyCallback(CallbackBase):

    def on_benders_start(self, context: BendersContext):
        print("Benders process started!")

# Function-based callback
def on_benders_end(self, context: BendersContext):
    print("Benders process finished!")

BD = BendersSolver(...)
BD.register(MyCallback())
BD.register(on_benders_end)

on_benders_start(context: BendersContext)[source]¶

Called at the start of the Benders decomposition process.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_benders_end(context: BendersContext)[source]¶

Called at the end of the Benders decomposition process.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_iteration_start(context: BendersContext)[source]¶

Called at the start of each Benders decomposition iteration.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_iteration_end(context: BendersContext)[source]¶

Called at the end of each Benders decomposition iteration.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_master_build(context: BendersContext)[source]¶

Called after the master problem is built.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_sub_build(context: BendersContext)[source]¶

Called after the subproblem is built.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_before_master_solve(context: BendersContext)[source]¶

Called before solving the master problem.

See Timeline of Callback Triggers for the precise timeline.

Caution

Not supported in the Branch-and-check method.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_after_master_solve(context: BendersContext)[source]¶

Called after solving the master problem.

See Timeline of Callback Triggers for the precise timeline.

Caution

Not supported in the Branch-and-check method.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_before_sub_solve(context: BendersContext)[source]¶

Called before solving the subproblem.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_after_sub_solve(context: BendersContext)[source]¶

Called after solving the subproblem.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_opti_cut_generated(context: BendersContext)[source]¶

Called when an optimality cut is generated.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_feas_cut_generated(context: BendersContext)[source]¶

Called when a feasibility cut is generated.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_opti_cut_added(context: BendersContext)[source]¶

Called when an optimality cut is added to the master problem.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_feas_cut_added(context: BendersContext)[source]¶

Called when a feasibility cut is added to the master problem.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_new_lower_bound(context: BendersContext)[source]¶

Called when a higher lower bound is found.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.

on_new_upper_bound(context: BendersContext)[source]¶

Called when a lower upper bound is found.

See Timeline of Callback Triggers for the precise timeline.

Parameters:

context (BendersContext) – The context object containing information about the current state of the Benders decomposition process.

Returns:

TERMINATE – If the callback determines that the Benders process should be terminated immediately.
PROCEED or None – If the callback determines that the Benders process should continue as normal.