Solver Interfaces¶

Abstract Base Classes¶

class SolverBase(model, solver_options: dict = None)[source]¶

Bases: ABC

The abstract base class for solver interfaces in BendersLib.

It defines the essential methods and attributes that any solver interface must implement to be compatible with BendersLib.

Parameters:

model – An instance of the solver’s model class (e.g., Gurobi’s gurobipy.Model).
solver_options (dict, optional) – A dictionary of solver-specific options.

model¶

A copy of the original solver model instance.

This attribute is exactly the solver-specific model instance passed during initialization. It allows direct access to solver-specific features (attributes and methods) not covered by the abstract interface. Refer to Supported Solvers’ Features for supported solvers, and their documentation.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

abstractmethod add_estimators(estimators: list[str], prob: list[float] = None, lb: float = 0) → None[source]¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

abstractmethod fix_vars(var_values: dict[str, float]) → None[source]¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

abstractmethod unfix_vars(vars: list[str]) → None[source]¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

abstractmethod get_var_values(vars: list[str] | None = None) → dict[str, float][source]¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

abstractmethod get_var_coefs(vars: list[str] | None = None) → dict[str, list][source]¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

abstractmethod get_rhs() → list[float][source]¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

abstractmethod get_dual_values() → list[float][source]¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

abstractmethod get_extreme_ray() → list[float][source]¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

abstractmethod get_obj() → float[source]¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

abstractmethod add_cut(cut, name) → None[source]¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

abstractmethod remove_cut(cut_name: str) → None[source]¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

abstractmethod solve() → None[source]¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

compute_iis() → set[str][source]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

This method can be useful for Combinatorial Benders Decomposition to identify a set of conflicting (binary) variables that causing subproblem infeasibility. This set of variables can be smaller than the full set of complicating variables, thus potentially leading to stronger NoGoodFC.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

static make_master_problem(original_model, master_vars: list[str]) → object[source]¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

The master problem variables are variables that appears only in the master problem. It has a subset, complicating variables, which are variables that are passed to the subproblem as known parameters. Though they are sometimes identical, the decomposition is based on the former.

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object[source]¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

class SolverCPBase(model, solver_options: dict = None)[source]¶

Bases: SolverBase

The abstract base class for Constraint Programming (CP) solver interfaces in BendersLib.

It defines the essential methods and attributes that any CP solver interface must implement to be compatible with BendersLib.

Parameters:

model – An instance of the solver’s model class (e.g., Gurobi’s gurobipy.Model).
solver_options (dict, optional) – A dictionary of solver-specific options.

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

abstractmethod fix_vars(var_values: dict[str, float]) → None¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

abstractmethod get_obj() → float¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

abstractmethod get_var_values(vars: list[str] | None = None) → dict[str, float]¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

abstractmethod solve() → None¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

abstractmethod unfix_vars(vars: list[str]) → None¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

Mathematical Programming Solver Interfaces¶

class Gurobi(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Gurobi’ solver. Raises ImportError on instantiation.

add_cut(**kwargs)¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

add_estimators(**kwargs)¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_dual_values(**kwargs)¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

get_extreme_ray(**kwargs)¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_rhs(**kwargs)¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

get_var_coefs(**kwargs)¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

static make_master_problem(original_model, master_vars: list[str]) → object¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

remove_cut(**kwargs)¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

class Copt(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Copt’ solver. Raises ImportError on instantiation.

add_cut(**kwargs)¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

add_estimators(**kwargs)¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_dual_values(**kwargs)¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

get_extreme_ray(**kwargs)¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_rhs(**kwargs)¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

get_var_coefs(**kwargs)¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

static make_master_problem(original_model, master_vars: list[str]) → object¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

remove_cut(**kwargs)¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

class Pyomo(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Pyomo’ solver. Raises ImportError on instantiation.

add_cut(**kwargs)¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

add_estimators(**kwargs)¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_dual_values(**kwargs)¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

get_extreme_ray(**kwargs)¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_rhs(**kwargs)¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

get_var_coefs(**kwargs)¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

static make_master_problem(original_model, master_vars: list[str]) → object¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

remove_cut(**kwargs)¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

class Scip(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Scip’ solver. Raises ImportError on instantiation.

add_cut(**kwargs)¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

add_estimators(**kwargs)¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_dual_values(**kwargs)¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

get_extreme_ray(**kwargs)¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_rhs(**kwargs)¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

get_var_coefs(**kwargs)¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

static make_master_problem(original_model, master_vars: list[str]) → object¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

remove_cut(**kwargs)¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

class Cplex(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Cplex’ solver. Raises ImportError on instantiation.

add_cut(**kwargs)¶

Add a Benders cut to the solver’s model as a constraint.

Parameters:

cut (Cut) – An instance of a Cut, either OptimalityCut or FeasibilityCut.
name (str) – The name of the constraint to be added.

Example

from benderslib import OptimalityCut

cut = OptimalityCut(vars=['x1', 'x2'], coefs=[1.0, 2.0], rhs=10.0, sense=CST.GEQ)
solver.add_cut(cut, name='BendersOC_1')

add_estimators(**kwargs)¶

Add estimator variable(s) to the objective function of the model.

Parameters:

estimators (list[str]) – A list of names for the estimator variables to be added.
prob (list[float]) – A list of probabilities (weights) associated with each estimator variable. The length of prob should match that of estimators. If None, equal weights are assigned to all estimator variables. Note that the sum of probabilities does not need to equal 1.
lb (float) – The lower bound for the estimator variables. Default is 0.0.

Example

# Adding multiple estimators with specified probabilities
solver.add_estimators(
    estimators=['theta1', 'theta2'],
    prob=[0.3, 0.7],
    lb=0.0
)

# Adding a single estimator
solver.add_estimators(['theta'])

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_dual_values(**kwargs)¶

Get the dual values (shadow prices) of all constraints in the model.

This is essential for generating Classical Benders optimality cuts.

Returns:: A list of dual values for each constraint.
Return type:: list[float]

Example

pi = solver.get_dual_values()

get_extreme_ray(**kwargs)¶

Get the extreme ray of the model.

This is essential for generating Classical Benders feasibility cuts.

Returns:: A list representing the extreme ray.
Return type:: list[float]

Example

ray = solver.get_extreme_ray()

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_rhs(**kwargs)¶

Get the right-hand side values of all constraints in the model.

Returns:: A list of right-hand side values for each constraint.
Return type:: list[float]

Example

rhs = solver.get_rhs()

get_var_coefs(**kwargs)¶

Get the coefficients of specified variables in all the constraints of the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve coefficients for. If None, retrieves coefficients for all variables.
Returns:: A dictionary mapping variable names to a list of their coefficients in each constraint.
Return type:: dict[str, list]

Example

coefs = solver.get_var_coefs(['x1', 'x2'])
# or get coefficients for all variables
all_coefs = solver.get_var_coefs()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

static make_master_problem(original_model, master_vars: list[str]) → object¶

Build the master problem from the original problem.

The master problem is built from a copy of the original problem, following these steps.

In the variable set, remove all non-master variables.
In the objective function, remove all terms involving non-master variables.
In the constraints, remove constraints that contains non-master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the master problem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
master_model = Gurobi.make_master_problem(original_model, ['x1', 'x2'])

static make_sub_problem(original_model, master_vars: list[str]) → object¶

Build the subproblem from the original problem.

The subproblem is built from a copy of the original problem, following these steps.

In the variable set, make the master variables be continuous variables. They will be fixed later when solving the subproblem.
In the objective function, remove all terms involving master variables.
In the constraints, remove constraints that contains only master variables.

Master problem variables vs. complicating variables

Parameters:

original_model – An instance of a solver’s model class (e.g., Gurobi’s gurobipy.Model).
master_vars (list[str]) – A list of variable names that are considered master problem variables.

Returns:

A new model instance representing the subproblem, in the solver-specific format.

Return type:

object

Example

from benderslib.solvers import Gurobi

original_model = ...
# It is a static method, which can be called without initializing an instance
sub_model = Gurobi.make_sub_problem(original_model, ['x1', 'x2'])

remove_cut(**kwargs)¶

Remove a constraint from the solver’s model by its name.

Parameters:: cut_name (str) – The name of the constraint to be removed.

Example

solver.remove_cut('BendersOC_1')

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

Constraint Programming Solver Interfaces¶

class Ortools(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘Ortools’ solver. Raises ImportError on instantiation.

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

class CplexCP(*args, **kwargs)¶

Bases: SolverBase

Placeholder for the ‘CplexCP’ solver. Raises ImportError on instantiation.

compute_iis() → set[str]¶

Compute the Irreducible Infeasible Subsystem (IIS) of the model if it is infeasible.

Caution

IIS is not guaranteed to be unique.

Returns:: A list of variable names involved in the IIS.
Return type:: list[str]

Example

iis_vars = solver.compute_iis()

fix_vars(**kwargs)¶

Fix the values of specified variables in the model.

Parameters:: var_values (dict[str, float]) – A dictionary mapping variable names to their fixed values.

Example

solver.fix_vars({'x1': 10, 'x2': 5.5})

get_obj(**kwargs)¶

Get the objective value of the model after solving.

Returns:: The objective value.
Return type:: float

Example

obj_val = solver.get_obj()

get_var_values(**kwargs)¶

Get the current values of specified variables in the model.

Parameters:: vars (list[str] or None) – A list of variable names to retrieve values for. If None, retrieves values for all variables
Returns:: A dictionary mapping variable names to their current values.
Return type:: dict[str, float]

Example

values = solver.get_var_values(['x1', 'x2'])
# or get all variable values
all_values = solver.get_var_values()

solve(**kwargs)¶

Solve the optimization model using the solver’s built-in optimization method.

Solver-specific parameters can be set in this method, such as hiding the solver’s output log in the console. After solving, status should be updated accordingly to OPTIMAL or INFEASIBLE.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.

unfix_vars(**kwargs)¶

Unfix the specified variables in the model by restoring their original bounds.

Parameters:: vars (list[str]) – A list of variable names to be unfixed.

Example

solver.unfix_vars(['x1', 'x2'])

model¶

A copy of the original solver model instance.

status¶

The status of the last solve attempt.

It is initialized to UNSOLVED, and it should be updated to OPTIMAL or INFEASIBLE, after calling the solve() method.

Caution

status should only be set to OPTIMAL or INFEASIBLE, since it is not clear how other statuses (e.g., feasible but not optimal) would impact convergence of Benders decomposition.