Tutorial

This guide walks through the main PyEPO workflow for predict-then-optimize problems: define an optimization model, build an optimization-aware dataset, choose a training module, train a predictor, and evaluate decision quality.

Where to Start

• New to PyEPO — read the pages below in order. Model and Data set up the modeling primitives; Two-Stage Method introduces the regression baseline; Autograd Functions and Training cover the end-to-end methods; Solution Pool explains the cached solution pool shared by the contrastive and learning-to-rank methods; Evaluation defines the metrics.

• Want to pick a method — jump to the Choosing a Method section of Autograd Functions. It poses three questions (what supervision you have, whether you want a loss or a solution, special constraints) and points you at the right module.

• Prefer hands-on — jump to the Notebooks section below for runnable Colab examples grouped by purpose.

Notebooks

Each notebook is a self-contained Colab walkthrough. They are grouped by purpose, and most entries link back to the docs section that explains the underlying API.

Getting Started

• 01 Optimization Model — build an optModel from a GurobiPy / COPT / Pyomo / OR-Tools / MPAX backend. Pairs with Model.

• 02 Optimization Dataset — generate synthetic data and wrap it in optDataset. Pairs with Data.

• 03 Training and Testing — train and compare every method family on the same shortest-path benchmark. Pairs with Training and Evaluation.

Method Deep Dives

• 04 CaVE for Binary Linear Programs — train with the cone-aligned CaVE loss on TSP and compare against SPO+. Pairs with the Cone-Aligned Estimation section of Autograd Functions.

• 08 kNN Robust Losses — train with the kNN robust loss via optDatasetKNN. Pairs with the optDatasetKNN section of Data.

GPU Acceleration

• 09 Solving on MPAX with PDHG — batch-solve LPs on GPU via MPAX, end-to-end without CPU round-trips. Pairs with the User-Defined MPAX Models section of Model.

Applied Examples

• 05 2D Knapsack Solution Visualization — visualize selected items for a 2D knapsack instance to inspect what the trained predictor is doing.

• 06 Warcraft Shortest Path — train an image-based shortest-path predictor on the Warcraft terrain dataset, using a CNN encoder feeding into PyEPO.

• 07 Real-World Energy Scheduling — apply PyEPO to a real-world energy scheduling benchmark with measured demand data.

Reference Pages

• Model
  • User-Defined Models
  • Pre-Defined Models
• Data
  • Data Generator
  • optDataset
  • optDatasetKNN
  • optDatasetConstrs
• Two-Stage Method
• Autograd Functions
  • Overview
  • Choosing a Method
  • Surrogate Losses
  • Perturbed Methods
  • Regularized Methods
  • Black-Box Methods
  • Cone-Aligned Estimation
  • Contrastive Methods
  • Learning to Rank
  • Parallel Computation
• Solution Pool
• Training
  • Common Setup
  • Surrogate Losses
  • Perturbed Methods
  • Regularized Methods
  • Black-Box Methods
  • Cone-Aligned Estimation
  • Contrastive Methods
  • Learning to Rank (LTR)
• Evaluation
  • Regret
  • Unambiguous Regret