pyepo.model.bases¶

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¶

`shortestPathBase`	Problem-level base for grid shortest path.
`knapsackBase`	Problem-level base for the multi-dimensional knapsack.
`portfolioBase`	Problem-level base for Markowitz mean-variance portfolio optimization.
`tspABBase`	Problem-level base for the symmetric traveling-salesperson problem.
`vrpABBase`	Problem-level base for the capacitated vehicle routing problem.

Module Contents¶

class pyepo.model.bases.shortestPathBase(grid: tuple[int, int], *args, **kwargs)¶

Bases: 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.

Variables:

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

grid¶

arcs = []¶

property num_cost: int¶: number of costs to be predicted

class pyepo.model.bases.knapsackBase(weights: numpy.ndarray | list, capacity: numpy.ndarray | list, *args, **kwargs)¶

Bases: 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.

Variables:

weights (np.ndarray) – item weights, shape (dim, n_items)
capacity (np.ndarray) – per-dimension capacity, shape (dim,)
items (list) – item indices 0 .. n_items - 1

modelSense¶

weights¶

capacity¶

items¶

get_config() → dict¶: Return the constructor configuration for this model.

property num_cost: int¶: number of costs to be predicted

class pyepo.model.bases.portfolioBase(num_assets: int, covariance: numpy.ndarray, gamma: float = 2.25, *args, **kwargs)¶

Bases: 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 \(\mathbf{x}^\top \boldsymbol{\Sigma} \mathbf{x} \le \gamma\, \overline{\boldsymbol{\Sigma}}\), where \(\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.

Variables:

num_assets (int) – number of assets
covariance (np.ndarray) – asset-return covariance matrix
gamma (float) – risk tolerance multiplier
risk_level (float) – derived risk budget = gamma * mean(covariance)

modelSense¶

num_assets¶

covariance¶

gamma¶

property num_cost: int¶: number of costs to be predicted

property risk_level: float¶

class pyepo.model.bases.tspABBase(num_nodes: int, *args, **kwargs)¶

Bases: 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).

Variables:

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

num_nodes¶

nodes¶

edges¶

property num_cost: int¶: number of costs to be predicted

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.

copy() → Self¶: Return a fresh model with all extra constraints replayed onto it.

addConstr(coefs: numpy.ndarray | torch.Tensor | list, rhs: float) → Self¶

Return a new model with one extra linear constraint added.

Parameters:

coefs – per-edge coefficients aligned with self.edges
rhs – right-hand side

class pyepo.model.bases.vrpABBase(num_nodes: int, demands: list[float] | numpy.ndarray, capacity: float, num_vehicle: int, *args, **kwargs)¶

Bases: pyepo.model.opt.optModel

Problem-level base for the capacitated vehicle routing problem.

Routes a fleet of num_vehicle vehicles of capacity capacity from a depot (node 0) to serve every customer’s demands exactly once at minimum total edge cost. Concrete formulations (RCI with lazy cuts, MTZ with load potentials) are supplied per backend.

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

Variables:

num_nodes (int) – number of nodes (depot at index 0)
nodes (list) – node indices 0 .. num_nodes - 1
edges (list) – undirected edges as (i, j) with i < j
demands (list | np.ndarray) – per-customer demands, length num_nodes - 1
capacity (float) – per-vehicle capacity
num_vehicle (int) – number of vehicles

num_nodes¶

nodes¶

edges¶

demands = []¶

capacity¶

num_vehicle¶

property num_cost: int¶: number of costs to be predicted

getTour(sol: numpy.ndarray | torch.Tensor | list) → list[list[int]]¶

Reconstruct vehicle tours from an undirected edge-selection vector.

Parameters:: sol – per-edge selection values aligned with self.edges
Returns:: list of tours; each tour is a node sequence starting and ending at the depot

copy() → Self¶: Return a fresh model with all extra constraints replayed onto it.

addConstr(coefs: numpy.ndarray | torch.Tensor | list, rhs: float) → Self¶

Return a new model with one extra linear constraint added.

Parameters:

coefs – per-edge coefficients aligned with self.edges
rhs – right-hand side