../_images/logo1.png

Introduction

PyEPO is a Python library for predict-then-optimize. It is designed for problems where a model predicts the objective coefficients of an optimization problem with a fixed feasible region.

End-to-End Predict-then-Optimize Framework

Given a labeled dataset \(\mathcal{D}\) of feature-cost pairs \((\mathbf{x}, \mathbf{c})\) or feature-solution pairs \((\mathbf{x}, \mathbf{w})\), a neural network is trained to minimize decision error directly, rather than only the prediction error of cost coefficients.

../_images/e2e.png

New to predict-then-optimize? Start with Workflow.

Key Concepts

The main objects in a PyEPO training pipeline are:

  • pyepo.dsl: define the problem symbolically once and compile it to any backend.

  • optModel: an optimization model with fixed constraints and a predicted linear objective.

  • optDataset: a dataset that stores features, costs, optimal solutions, and optimal objective values.

  • pyepo.func: PyTorch training methods that call the optimization model during training.

  • pyepo.func.jax: JAX versions of the training methods.

  • pyepo.metric: decision-quality metrics, including regret and unambiguous regret.

Backends and Training Methods

PyEPO builds optimization models with GurobiPy, COPT, Pyomo, Google OR-Tools, and MPAX, a JAX-based solver for GPU batch solving. These backends are exposed through PyTorch and JAX training frontends. Training methods are grouped into the following families:

  • Surrogate losses: smart predict-then-optimize+ (SPO+), perturbation gradient (PG)

  • Perturbed methods: differentiable perturbed optimizer (DPO), perturbed Fenchel-Young loss (PFYL), implicit maximum likelihood estimator (I-MLE), adaptive implicit maximum likelihood estimator (AI-MLE)

  • Regularized methods: L2-regularized Frank-Wolfe optimizer (RFWO), L2-regularized Frank-Wolfe with Fenchel-Young loss (RFYL)

  • Black-box methods: differentiable black-box optimizer (DBB), negative identity backpropagation (NID)

  • Cone-aligned estimation: cone-aligned vector estimation (CaVE) for binary linear programs, with binding constraints extracted by a Gurobi-backed model

  • Contrastive methods: noise contrastive estimation (NCE), contrastive MAP (CMAP)

  • Learning to rank: pointwise, pairwise, and listwise learning to rank (LTR)

For guidance on picking a method, see the Choosing a Method section of Training Methods.

Publication

PyEPO is the official implementation of the paper PyEPO: A PyTorch-based End-to-End Predict-then-Optimize Library for Linear and Integer Programming (Mathematical Programming Computation, 2024).

Citation

If you use PyEPO in your research, please cite it. The BibTeX entries are collected in Citation and References.