pyepo.model.opt
===============

.. py:module:: pyepo.model.opt

.. autoapi-nested-parse::

   Abstract optimization model



Classes
-------

.. autoapisummary::

   pyepo.model.opt.ModelSpec
   pyepo.model.opt.optModel


Module Contents
---------------

.. py:class:: ModelSpec(model_type: type[optModel], config: dict, args: tuple = ())

   Serializable recipe for building a fresh optimization model.


   .. py:attribute:: model_type
      :type:  type[optModel]


   .. py:property:: args
      :type: tuple


      Return an independent copy of positional constructor arguments.


   .. py:property:: config
      :type: dict


      Return an independent copy of keyword constructor arguments.


   .. py:method:: build() -> optModel

      Build a fresh model without sharing mutable configuration values.



.. py:class:: optModel

   Bases: :py:obj:`abc.ABC`


   Abstract base class for predict-then-optimize models.

   Subclasses wrap an optimization solver or algorithm with a unified
   ``_getModel`` / ``setObj`` / ``solve`` / ``num_cost`` interface that
   ``pyepo.func`` modules call during training. Concrete backends are
   provided for GurobiPy (``optGrbModel``), Pyomo (``optOmoModel``),
   COPT (``optCoptModel``), OR-Tools (``optOrtModel`` / ``optOrtCpModel``),
   and MPAX (``optMpaxModel``); subclass ``optModel`` directly to integrate
   any other solver or algorithm.

   The default objective sense is minimization; set
   ``self.modelSense = EPO.MAXIMIZE`` in ``_getModel`` or ``__init__`` for
   maximization problems (some backends, e.g. Gurobi and COPT, detect this
   automatically from the underlying solver model).

   :ivar _model: underlying solver model object
   :vartype _model: optimization model
   :ivar modelSense: EPO.MINIMIZE (default) or EPO.MAXIMIZE

   :vartype modelSense: ModelSense


   .. py:attribute:: modelSense
      :type:  pyepo.EPO.ModelSense


   .. py:attribute:: arcs
      :type:  list


   .. py:method:: get_config() -> dict

      Return the constructor configuration for this model.



   .. py:method:: from_config(config: dict, args: tuple = ()) -> Self
      :classmethod:


      Build a model from a configuration produced by ``get_config``.



   .. py:method:: to_spec() -> ModelSpec

      Return a serializable, immutable-snapshot rebuild recipe.



   .. py:method:: rebuild() -> Self

      Build a structurally equivalent model with clean runtime state.



   .. py:property:: num_cost
      :type: int


      number of costs to be predicted


   .. py:method:: setObj(c: numpy.ndarray | torch.Tensor | list) -> None
      :abstractmethod:


      An abstract method to set the objective function

      :param c: cost of objective function



   .. py:method:: solve() -> tuple[numpy.ndarray | torch.Tensor | list, float]
      :abstractmethod:


      An abstract method to solve the model

      :returns: optimal solution (list) and objective value (float)
      :rtype: tuple



   .. py:property:: c_pred_index
      :type: numpy.ndarray | None


      Variable positions the predicted cost lands on, or ``None`` when every variable is predicted (the default).


   .. py:method:: copy() -> Self

      A method to copy the model

      :returns: new copied model
      :rtype: optModel



   .. py:method:: addConstr(coefs: numpy.ndarray | torch.Tensor | list, rhs: float) -> Self
      :abstractmethod:


      A method to add a new constraint. Subclasses should override.

      :param coefs: coefficients of the new constraint
      :param rhs: right-hand side of new constraint

      :returns: new model with the added constraint
      :rtype: optModel



   .. py:method:: relax() -> optModel
      :abstractmethod:


      A method to relax the MIP model. Subclasses should override.