../_images/logo1.png

Introduction

PyEPO is a Python library for predict-then-optimize. It focuses on problems where a model predicts objective coefficients and the feasible region is fixed, then trains the predictor against downstream decision quality rather than prediction error alone.

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

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

Key Concepts

The main objects in a PyEPO training pipeline are:

  • 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, and exposes them 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 (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), binary linear programs only

  • 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.

Additional Components

For binary linear programs (TSP, CVRP, knapsack, shortest path with binary edges), PyEPO includes CaVE, a cone-alignment loss that uses binding-constraint normals at the true optimum. CaVE requires the optDatasetConstrs dataset and a Gurobi-backed optModel for extracting binding constraints.

PyEPO also integrates MPAX, a JAX-based solver for GPU batch solving of linear and quadratic programs.

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}
}