Source code for benderslib.benders.lshaped

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

from ..core import BendersParams, MasterProblem, SubProblems, BendersSolver
from ..cuts import LShapedOCGen, LShapedFCGen




class LShaped(BendersSolver):
    """An implementation of :doc:`../tutorials/lshaped` (linear recourse).

    It builds a Benders decomposition framework using the provided master problem,
    subproblem, and complicating variables.
    The optimality cut is defined by :class:`LShapedOC` (single-cut) or :class:`ClassicalOC` (multi-cut),
    and generated by :class:`LShapedOCGen`;
    the feasibility cut is defined by :class:`ClassicalFC` and generated by :class:`LShapedFCGen`.

    Note that L-shaped method is a generalization of classical Benders
    decomposition applied to two-stage stochastic programming problems.
    Therefore, :class:`ClassicalOC` and :class:`ClassicalFC` are also used in the L-shaped method.

    .. caution::
        The class :class:`LShaped` requires the (second-stage) **subproblems be pure LP**.

    Parameters
    ----------

    master_problem : MasterProblem
        An instance of :class:`MasterProblem` representing the master problem.
    sub_problem : SubProblems
        An instance of :class:`SubProblems` representing the collection of subproblems.
    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 LShaped, MasterProblem, SubProblems
        from benderslib.solvers import Gurobi

        # Define master and subproblem models
        master_model = ...  # Define your master problem model here
        sub_models = [...]  # Define your list of subproblem models here
        probs = [1/len(sub_models)] * len(sub_models)  # Define probabilities for each scenario

        # Initialize master and subproblems
        mp = MasterProblem(Gurobi(master_model))
        sp = SubProblems([Gurobi(sm) for sm in sub_models], prob=probs)

        # Define complicating variables
        complicating_vars = ['x1', 'x2', 'x3']

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

    def __init__(
            self,
            master_problem: MasterProblem,
            sub_problem: SubProblems,
            complicating_vars: list[str],
            optimality_cut=LShapedOCGen,
            feasibility_cut=LShapedFCGen,
            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=LShapedOCGen,
            feasibility_cut=LShapedFCGen,
            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
        )