# Module `miplearn.components.component`

Expand source code

    #  MIPLearn: Extensible Framework for Learning-Enhanced Mixed-Integer Optimization
    #  Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
    #  Released under the modified BSD license. See COPYING.md for more details.

    from abc import ABC, abstractmethod
    from typing import Any, List, Union, TYPE_CHECKING

    from miplearn.instance import Instance
    from miplearn.types import LearningSolveStats, TrainingSample

    if TYPE_CHECKING:
        from miplearn.solvers.learning import LearningSolver

    class Component(ABC):
        """
        A Component is an object which adds functionality to a LearningSolver.

        For better code maintainability, LearningSolver simply delegates most of its
        functionality to Components. Each Component is responsible for exactly one ML
        strategy.
        """

        def before_solve(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> None:
            """
            Method called by LearningSolver before the problem is solved.

            Parameters
            ----------
            solver
                The solver calling this method.
            instance
                The instance being solved.
            model
                The concrete optimization model being solved.
            """
            return

        @abstractmethod
        def after_solve(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
            stats: LearningSolveStats,
            training_data: TrainingSample,
        ) -> None:
            """
            Method called by LearningSolver after the problem is solved to optimality.

            Parameters
            ----------
            solver: LearningSolver
                The solver calling this method.
            instance: Instance
                The instance being solved.
            model: Any
                The concrete optimization model being solved.
            stats: LearningSolveStats
                A dictionary containing statistics about the solution process, such as
                number of nodes explored and running time. Components are free to add
                their own statistics here. For example, PrimalSolutionComponent adds
                statistics regarding the number of predicted variables. All statistics in
                this dictionary are exported to the benchmark CSV file.
            training_data: TrainingSample
                A dictionary containing data that may be useful for training machine
                learning models and accelerating the solution process. Components are
                free to add their own training data here. For example,
                PrimalSolutionComponent adds the current primal solution. The data must
                be pickable.
            """
            pass

        def fit(
            self,
            training_instances: Union[List[str], List[Instance]],
        ) -> None:
            return

        def iteration_cb(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> bool:
            """
            Method called by LearningSolver at the end of each iteration.

            After solving the MIP, LearningSolver calls `iteration_cb` of each component,
            giving them a chance to modify the problem and resolve it before the solution
            process ends. For example, the lazy constraint component uses `iteration_cb`
            to check that all lazy constraints are satisfied.

            If `iteration_cb` returns False for all components, the solution process
            ends. If it retunrs True for any component, the MIP is solved again.

            Parameters
            ----------
            solver: LearningSolver
                The solver calling this method.
            instance: Instance
                The instance being solved.
            model: Any
                The concrete optimization model being solved.
            """
            return False

        def lazy_cb(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> None:
            return

## Classes

`class Component`

  A Component is an object which adds functionality to a LearningSolver.

  For better code maintainability, LearningSolver simply delegates most of its functionality to Components. Each Component is responsible for exactly one ML strategy.

  Expand source code

      class Component(ABC):
          """
          A Component is an object which adds functionality to a LearningSolver.

          For better code maintainability, LearningSolver simply delegates most of its
          functionality to Components. Each Component is responsible for exactly one ML
          strategy.
          """

          def before_solve(
              self,
              solver: "LearningSolver",
              instance: Instance,
              model: Any,
          ) -> None:
              """
              Method called by LearningSolver before the problem is solved.

              Parameters
              ----------
              solver
                  The solver calling this method.
              instance
                  The instance being solved.
              model
                  The concrete optimization model being solved.
              """
              return

          @abstractmethod
          def after_solve(
              self,
              solver: "LearningSolver",
              instance: Instance,
              model: Any,
              stats: LearningSolveStats,
              training_data: TrainingSample,
          ) -> None:
              """
              Method called by LearningSolver after the problem is solved to optimality.

              Parameters
              ----------
              solver: LearningSolver
                  The solver calling this method.
              instance: Instance
                  The instance being solved.
              model: Any
                  The concrete optimization model being solved.
              stats: LearningSolveStats
                  A dictionary containing statistics about the solution process, such as
                  number of nodes explored and running time. Components are free to add
                  their own statistics here. For example, PrimalSolutionComponent adds
                  statistics regarding the number of predicted variables. All statistics in
                  this dictionary are exported to the benchmark CSV file.
              training_data: TrainingSample
                  A dictionary containing data that may be useful for training machine
                  learning models and accelerating the solution process. Components are
                  free to add their own training data here. For example,
                  PrimalSolutionComponent adds the current primal solution. The data must
                  be pickable.
              """
              pass

          def fit(
              self,
              training_instances: Union[List[str], List[Instance]],
          ) -> None:
              return

          def iteration_cb(
              self,
              solver: "LearningSolver",
              instance: Instance,
              model: Any,
          ) -> bool:
              """
              Method called by LearningSolver at the end of each iteration.

              After solving the MIP, LearningSolver calls `iteration_cb` of each component,
              giving them a chance to modify the problem and resolve it before the solution
              process ends. For example, the lazy constraint component uses `iteration_cb`
              to check that all lazy constraints are satisfied.

              If `iteration_cb` returns False for all components, the solution process
              ends. If it retunrs True for any component, the MIP is solved again.

              Parameters
              ----------
              solver: LearningSolver
                  The solver calling this method.
              instance: Instance
                  The instance being solved.
              model: Any
                  The concrete optimization model being solved.
              """
              return False

          def lazy_cb(
              self,
              solver: "LearningSolver",
              instance: Instance,
              model: Any,
          ) -> None:
              return

  ### Ancestors

  - abc.ABC

  ### Subclasses

  - CompositeComponent
  - UserCutsComponent
  - DynamicLazyConstraintsComponent
  - StaticLazyConstraintsComponent
  - ObjectiveValueComponent
  - PrimalSolutionComponent
  - RelaxationComponent
  - ConvertTightIneqsIntoEqsStep
  - DropRedundantInequalitiesStep
  - RelaxIntegralityStep

  ### Methods

  `def after_solve(self, solver, instance, model, stats, training_data)`

    Method called by LearningSolver after the problem is solved to optimality.

    ## Parameters

    `solver` :`LearningSolver`
      The solver calling this method.
    `instance` :`Instance`
      The instance being solved.
    `model` :`Any`
      The concrete optimization model being solved.
    `stats` :`LearningSolveStats`
      A dictionary containing statistics about the solution process, such as number of nodes explored and running time. Components are free to add their own statistics here. For example, PrimalSolutionComponent adds statistics regarding the number of predicted variables. All statistics in this dictionary are exported to the benchmark CSV file.
    `training_data` :`TrainingSample`
      A dictionary containing data that may be useful for training machine learning models and accelerating the solution process. Components are free to add their own training data here. For example, PrimalSolutionComponent adds the current primal solution. The data must be pickable.
    Expand source code

        @abstractmethod
        def after_solve(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
            stats: LearningSolveStats,
            training_data: TrainingSample,
        ) -> None:
            """
            Method called by LearningSolver after the problem is solved to optimality.

            Parameters
            ----------
            solver: LearningSolver
                The solver calling this method.
            instance: Instance
                The instance being solved.
            model: Any
                The concrete optimization model being solved.
            stats: LearningSolveStats
                A dictionary containing statistics about the solution process, such as
                number of nodes explored and running time. Components are free to add
                their own statistics here. For example, PrimalSolutionComponent adds
                statistics regarding the number of predicted variables. All statistics in
                this dictionary are exported to the benchmark CSV file.
            training_data: TrainingSample
                A dictionary containing data that may be useful for training machine
                learning models and accelerating the solution process. Components are
                free to add their own training data here. For example,
                PrimalSolutionComponent adds the current primal solution. The data must
                be pickable.
            """
            pass

  `def before_solve(self, solver, instance, model)`

    Method called by LearningSolver before the problem is solved.

    ## Parameters

    `solver`
      The solver calling this method.
    `instance`
      The instance being solved.
    `model`
      The concrete optimization model being solved.
    Expand source code

        def before_solve(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> None:
            """
            Method called by LearningSolver before the problem is solved.

            Parameters
            ----------
            solver
                The solver calling this method.
            instance
                The instance being solved.
            model
                The concrete optimization model being solved.
            """
            return

  `def fit(self, training_instances)`
    Expand source code

        def fit(
            self,
            training_instances: Union[List[str], List[Instance]],
        ) -> None:
            return

  `def iteration_cb(self, solver, instance, model)`

    Method called by LearningSolver at the end of each iteration.

    After solving the MIP, LearningSolver calls `iteration_cb` of each component, giving them a chance to modify the problem and resolve it before the solution process ends. For example, the lazy constraint component uses `iteration_cb` to check that all lazy constraints are satisfied.

    If `iteration_cb` returns False for all components, the solution process ends. If it retunrs True for any component, the MIP is solved again.

    ## Parameters

    `solver` :`LearningSolver`
      The solver calling this method.
    `instance` :`Instance`
      The instance being solved.
    `model` :`Any`
      The concrete optimization model being solved.
    Expand source code

        def iteration_cb(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> bool:
            """
            Method called by LearningSolver at the end of each iteration.

            After solving the MIP, LearningSolver calls `iteration_cb` of each component,
            giving them a chance to modify the problem and resolve it before the solution
            process ends. For example, the lazy constraint component uses `iteration_cb`
            to check that all lazy constraints are satisfied.

            If `iteration_cb` returns False for all components, the solution process
            ends. If it retunrs True for any component, the MIP is solved again.

            Parameters
            ----------
            solver: LearningSolver
                The solver calling this method.
            instance: Instance
                The instance being solved.
            model: Any
                The concrete optimization model being solved.
            """
            return False

  `def lazy_cb(self, solver, instance, model)`
    Expand source code

        def lazy_cb(
            self,
            solver: "LearningSolver",
            instance: Instance,
            model: Any,
        ) -> None:
            return