pyepo.model.bases
=================

.. py:module:: pyepo.model.bases

.. autoapi-nested-parse::

   Problem-level base classes for optimization models.

   Each base captures the problem-specific state (data, indices, derived attrs)
   and methods that are independent of the underlying solver. Concrete classes
   combine a problem base with a backend base via multiple inheritance, with the
   problem base listed first so its ``__init__`` runs before the backend's::

       class shortestPathModel(shortestPathBase, optGrbModel):
           def _getModel(self):
               ...  # solver-specific build



Classes
-------

.. autoapisummary::

   pyepo.model.bases.shortestPathBase
   pyepo.model.bases.knapsackBase
   pyepo.model.bases.portfolioBase
   pyepo.model.bases.tspABBase


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

.. py:class:: shortestPathBase(grid: tuple[int, int], *args, **kwargs)

   Bases: :py:obj:`pyepo.model.opt.optModel`


   Problem-level base for grid shortest path.

   Finds the minimum-cost path from the northwest corner to the southeast
   corner of an ``(h, w)`` grid network. The problem is formulated as a
   minimum-cost flow LP with arc-incidence equality constraints; arcs are
   enumerated automatically from the grid dimensions and stored on
   ``self.arcs``.

   :ivar grid: grid dimensions (rows, cols)
   :vartype grid: tuple of int
   :ivar arcs: ordered list of (source, target) arcs in the grid

   :vartype arcs: list


   .. py:attribute:: grid


   .. py:attribute:: arcs
      :value: []



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


      number of costs to be predicted


.. py:class:: knapsackBase(weights: numpy.ndarray | list, capacity: numpy.ndarray | list, *args, **kwargs)

   Bases: :py:obj:`pyepo.model.opt.optModel`


   Problem-level base for the multi-dimensional knapsack.

   Selects a subset of items that maximizes total value subject to
   per-resource capacity constraints. Items, dimensions, and capacities are
   inferred from the shapes of ``weights`` and ``capacity``: ``weights``
   has shape ``(dim, n_items)`` and ``capacity`` has length ``dim``. Item
   values are the predicted cost coefficients ``c`` set via ``setObj``.

   :ivar weights: item weights, shape ``(dim, n_items)``
   :vartype weights: np.ndarray
   :ivar capacity: per-dimension capacity, shape ``(dim,)``
   :vartype capacity: np.ndarray
   :ivar items: item indices ``0 .. n_items - 1``

   :vartype items: list


   .. py:attribute:: modelSense


   .. py:attribute:: weights


   .. py:attribute:: capacity


   .. py:attribute:: items


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


      number of costs to be predicted


.. py:class:: portfolioBase(num_assets: int, covariance: numpy.ndarray, gamma: float = 2.25, *args, **kwargs)

   Bases: :py:obj:`pyepo.model.opt.optModel`


   Problem-level base for Markowitz mean-variance portfolio optimization.

   Allocates a unit budget across ``num_assets`` to maximize predicted
   expected return subject to a quadratic risk budget
   :math:`\mathbf{x}^\top \boldsymbol{\Sigma} \mathbf{x} \le \gamma\,
   \overline{\boldsymbol{\Sigma}}`, where :math:`\overline{\boldsymbol{\Sigma}}`
   is the mean covariance entry. Predicted asset returns are the cost
   coefficients ``c`` set via ``setObj``; the covariance and risk budget
   are fixed across instances.

   :ivar num_assets: number of assets
   :vartype num_assets: int
   :ivar covariance: asset-return covariance matrix
   :vartype covariance: np.ndarray
   :ivar risk_level: risk budget = ``gamma * mean(covariance)``

   :vartype risk_level: float


   .. py:attribute:: modelSense


   .. py:attribute:: num_assets


   .. py:attribute:: covariance


   .. py:attribute:: risk_level


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


      number of costs to be predicted


.. py:class:: tspABBase(num_nodes: int, *args, **kwargs)

   Bases: :py:obj:`pyepo.model.opt.optModel`


   Problem-level base for the symmetric traveling-salesperson problem.

   Finds the shortest tour visiting each of ``num_nodes`` cities exactly
   once and returning to the origin. Three concrete ILP formulations are
   supplied per backend:

   * **DFJ** (Dantzig-Fulkerson-Johnson) -- lazy subtour-elimination
     constraints via solver callbacks (no LP relaxation).
   * **GG** (Gavish-Graves) -- flow-based formulation with auxiliary
     flow variables.
   * **MTZ** (Miller-Tucker-Zemlin) -- compact formulation with per-node
     potential auxiliaries.

   The base only manages formulation-independent state (nodes, edges,
   extra-constraint replay) and the ``getTour`` helper. Concrete
   formulations implement ``_getModel`` (build the solver model) and
   ``_addExtraConstr`` (add a single linear extra constraint).

   :ivar num_nodes: number of nodes
   :vartype num_nodes: int
   :ivar nodes: node indices ``0 .. num_nodes - 1``
   :vartype nodes: list
   :ivar edges: undirected edges as ``(i, j)`` with ``i < j``

   :vartype edges: list


   .. py:attribute:: num_nodes


   .. py:attribute:: nodes


   .. py:attribute:: edges


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


      number of costs to be predicted


   .. py:method:: getTour(sol: numpy.ndarray | torch.Tensor | list) -> list[int]

      Reconstruct a TSP tour from an undirected edge-selection vector.

      :raises ValueError: if the solution does not form a single connected tour.



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

      Return a fresh model with all extra constraints replayed onto it.



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

      Return a new model with one extra linear constraint added.

      :param coefs: per-edge coefficients aligned with ``self.edges``
      :param rhs: right-hand side