Theory Overview

DiffAPQP embeds a parameterized convex optimization problem in a PyTorch computational graph. In decision-focused learning, a forecaster first produces optimization parameters

\[ \hat y=f(x,\theta), \]

where \(x\) is contextual input and \(\theta\) contains trainable model weights. DiffAPQP then solves the optimization problem parameterized by \(\hat y\) and propagates derivatives back to \(\theta\).

Computational structure

The optimization layer is decomposed into three maps:

\[ \hat y \xrightarrow{\mathcal C} (P,q,A,b,G,h) \xrightarrow{\mathcal S} (\tilde z^\star,\tilde\nu^\star,\tilde\lambda^\star) \xrightarrow{\mathcal R} \hat z^\star. \]

• \(\mathcal C\) canonicalizes the original CVXPY model into affine-parametric QP data.
• \(\mathcal S\) calls a solver backend and returns the canonical primal-dual solution.
• \(\mathcal R\) retrieves the original named CVXPY decisions from the canonical decision vector.

Consequently, the solution map is

\[ \mathcal O = \mathcal R\circ\mathcal S\circ\mathcal C, \qquad \hat z^\star=\mathcal O(\hat y). \]

For a scalar training loss \(\ell\), the complete decision-focused computation is

\[ \ell\circ\mathcal O\circ f = \ell\circ\mathcal R\circ\mathcal S\circ\mathcal C\circ f. \]

Two differentiation targets

DiffAPQP exposes two layers because a training objective can depend on the optimization problem in two materially different ways.

Target	Mathematical quantity	DiffAPQP interface	Backward computation
Optimal decisions	\(\hat z^\star=\mathcal O(\hat y)\)	SolMapLayer	Full- or reduced-KKT adjoint solve
Optimal value	\(\alpha(\hat y)=f_0(\hat z^\star,\hat y)\)	ValueFuncLayer	Direct value-function derivative

Use the solution-map layer when the downstream loss needs dispatch, reserve, flow, or another optimal decision. Use the value-function layer when the loss needs only the optimal objective value.

Notation

Symbol	Meaning
\(x\)	Contextual input to the forecaster
\(\theta\)	Trainable forecaster parameters
\(y\)	Realized or true optimization parameters
\(\hat y=f(x,\theta)\)	Predicted optimization parameters
\(z\)	Decisions in the original domain-specific CVXPY model
\(\hat z^\star\)	Retrieved optimal decisions under \(\hat y\)
\(\tilde z\)	Canonical APQP decision vector
\(\tilde\nu\), \(\tilde\lambda\)	Canonical equality and inequality duals
\(\alpha(\hat y)\)	Optimal value function
\(\ell\)	Scalar training loss
\(N_d,N_p,N_{\mathrm{eq}},N_{\mathrm{in}}\)	Counts in the original domain model
\(n_d,n_{\mathrm{eq}},n_{\mathrm{in}}\)	Dimensions after canonicalization

The hat on \(\hat y\) emphasizes that the optimization parameters are commonly forecasts. The tilde distinguishes canonical variables from the original domain variables returned to the user.

Reading guide

1. Decision-focused learning introduces the forecasting and optimization chain and explains which layer matches each loss.
2. APQP and canonicalization defines the supported mathematical problem and its affine parameter-to-data maps.
3. Efficient forward pass explains solver flexibility, solver-data update, warm-starting, batching, and retrieval.
4. Solution-map differentiation derives the full and reduced KKT adjoints used by SolMapLayer.
5. Value-function differentiation derives the direct gradient used by ValueFuncLayer.
6. Numerical considerations discusses regularity, degeneracy, active-set detection, and stabilization.

For argument-level behavior, shapes, defaults, and return types, use the API overview and the two implementation references.