Source code for benderslib.benders.combinatorial

# coding:utf-8
# SPDX-License-Identifier: Apache-2.0
# Copyright (c) 2021-2026 Peng-Hui Guo <[email protected]>

from ..core import BendersParams, MasterProblem, SubProblem, BendersSolver
from ..cuts import CombinatorialFCGen, CombinatorialOCGen




class CombinatorialBenders(BendersSolver):
    """An implementation of :doc:`../tutorials/cbd`.

    It builds a Benders decomposition framework using the provided master problem,
    subproblem, and complicating variables.
    The optimality cut is defined by :class:`CombinatorialOC` and generated by :class:`CombinatorialOCGen`;
    the feasibility cut is defined by :class:`NoGoodFC` and generated by :class:`CombinatorialFCGen`.

    .. caution::
        The class :class:`CombinatorialBenders` requires the **complicating variables be pure binary (0-1)**.

    Parameters
    ----------

    master_problem : MasterProblem
        An instance of :class:`MasterProblem` representing the master problem.
    sub_problem : SubProblem
        An instance of :class:`SubProblem` representing the subproblem.
    complicating_vars : list[str]
        A list of names of the complicating variables.
    params : BendersParams, optional
        An instance of :class:`BendersParams` containing parameters for the Benders decomposition process.
        If not provided, default parameters will be used.

    Example
    ----------

    .. code-block:: python

        from benderslib import CombinatorialBenders, MasterProblem, SubProblem
        from benderslib.solvers import Gurobi

        # Define master and subproblem models
        master_model = ...  # Define your master problem model here
        sub_model = ...     # Define your subproblem model here

        # Initialize master and subproblem
        mp = MasterProblem(Gurobi(master_model))
        sp = SubProblem(Gurobi(sub_model))

        # Define complicating variables (must be binary)
        complicating_vars = ['x1', 'x2', 'x3']

        # Initialize and solve
        BD = CombinatorialBenders(mp, sp, complicating_vars)
        BD.solve()
    """

    def __init__(
            self,
            master_problem: MasterProblem,
            sub_problem: SubProblem,
            complicating_vars: list[str],
            optimality_cut=CombinatorialOCGen,
            feasibility_cut=CombinatorialFCGen,
            params: BendersParams | None = None
    ):
        super().__init__(
            master_problem,
            sub_problem,
            complicating_vars,
            optimality_cut,
            feasibility_cut,
            params
        )



    @classmethod
    def from_models(
            cls,
            master_model,
            master_solver,
            sub_model,
            sub_solver,
            complicating_vars,
            optimality_cut=CombinatorialOCGen,
            feasibility_cut=CombinatorialFCGen,
            prob=None,
            params: BendersParams | None = None
    ):
        return super().from_models(
            master_model,
            master_solver,
            sub_model,
            sub_solver,
            complicating_vars,
            optimality_cut,
            feasibility_cut,
            prob,
            params
        )