../_images/logo1.png

Introduction

PyEPO (PyTorch-based End-to-End Predict-then-Optimize Tool) is a Python library for modeling and solving predict-then-optimize problems with linear objective functions.

PyEPO builds optimization models with GurobiPy, COPT, Pyomo, Google OR-Tools, MPAX, or any custom solver or algorithm, and embeds them into neural networks for end-to-end training. All decision-focused learning methods are implemented as PyTorch autograd modules, grouped into the following families:

  • Surrogate losses – SPO+, perturbation gradient (PG)

  • Perturbed methods – differentiable perturbed optimizers (DPO), perturbed Fenchel-Young loss (PFYL), I-MLE / AI-MLE

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

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

  • Cone-aligned estimation – CaVE (binary linear programs only)

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

  • Learning to rank – pointwise, pairwise, listwise LTR

For end-to-end learning on binary linear programs (TSP, CVRP, knapsack, shortest path with binary edges), PyEPO ships CaVE, a cone-alignment loss that projects the predicted cost onto the cone of binding-constraint normals at the true optimum. Backed by an interior-point QP solver (Clarabel) with a low iteration cap, CaVE delivers paper-faithful regret on TSP-scale binary LPs. Because the cone projection is far cheaper than the per-instance ILP solve, CaVE trains an order of magnitude faster than SPO+ at this scale.

PyEPO also integrates MPAX, a JAX-based mathematical programming solver using the PDHG (Primal-Dual Hybrid Gradient) algorithm for GPU-accelerated optimization. MPAX brings three key advantages for end-to-end training: (1) GPU-native solving – the first-order PDHG method is inherently parallelizable and runs efficiently on GPU; (2) batch solving – an entire mini-batch of optimization instances is solved simultaneously via vectorization; (3) no GPU-CPU data transfer overhead – both the neural network and the solver stay on GPU, eliminating the data-transfer bottleneck of CPU-side solvers like Gurobi.

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 directly minimize the decision error, rather than the prediction error of cost coefficients.

../_images/e2e.png

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:

@article{tang2024,
  title={PyEPO: a PyTorch-based end-to-end predict-then-optimize library for linear and integer programming},
  author={Tang, Bo and Khalil, Elias B},
  journal={Mathematical Programming Computation},
  issn={1867-2957},
  doi={10.1007/s12532-024-00255-x},
  year={2024},
  month={July},
  publisher={Springer}
}