Source code for benderslib.benders.glshaped

# 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 LShapedFCGen, GeneLShapedOCGen




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

    This method extends the L-shaped method to two-stage stochastic programming problems
    with convex second-stage (recourse) problems. It combines the multi-scenario
    framework of the L-shaped method with the cut generation principles
    of :doc:`Generalized Benders Decomposition <../tutorials/gbd>`.

    The optimality cut is defined by :class:`GeneLShapedOC` (single-cut) or
    :class:`GeneralizedOC` (multi-cut), and generated by :class:`GeneLShapedOCGen`.
    The feasibility cut is defined by :class:`ClassicalFC` and generated by :class:`LShapedFCGen`.

    .. caution::
        The class :class:`GeneLShaped` requires the second-stage **subproblems be convex**.
        The requirements to original problems, master problems and subproblems in :class:`GeneralizedBenders`
        also apply here.

    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 GeneLShaped, 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 convex 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']

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

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