Decision-Focused Learning¶

Decision-focused learning trains a predictive model according to the quality of the downstream decisions it induces, rather than prediction error alone. DiffAPQP provides the differentiable optimization layer in this forecasting and decision-making chain.

Forecast followed by optimization¶

Let a forecaster produce

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

where \(x\) contains contextual information, \(\theta\) contains trainable weights, and \(\hat y\) may represent predicted demand, renewable generation, reserve requirements, or market prices.

The prediction is passed to a domain-specific optimization problem:

\[ \begin{aligned} \min_{z_{1:N_d}}\quad &f_0(z_{1:N_d},\hat y_{1:N_p})\\ \text{subject to}\quad &h_k(z_{1:N_d},\hat y_{1:N_p})=0, &&k=1,\ldots,N_{\mathrm{eq}},\\ &f_j(z_{1:N_d},\hat y_{1:N_p})\le 0, &&j=1,\ldots,N_{\mathrm{in}}. \end{aligned} \]

The compact solution-map notation is

\[ \hat z^\star=\mathcal O(\hat y), \]

and the associated value function is

\[ \alpha(\hat y) := f_0(\hat z^\star,\hat y). \]

Users write this optimization in its natural engineering form with CVXPY. Canonicalization converts a compatible model to the APQP representation required by DiffAPQP.

Decision-focused objective¶

For a dataset \(\mathcal D\) of contextual inputs and realized outcomes, a generic decision-focused objective is

\[ \min_\theta \frac{1}{N_{\mathcal D}} \sum_{(x,y)\in\mathcal D} \ell\big(\hat z^{1,\star},\ldots,\hat z^{m,\star},y,\hat y\big), \qquad \hat y=f(x,\theta). \]

The optimization outputs remain in the PyTorch computational graph. The chain rule therefore propagates the loss gradient through the optimization layer and then through the forecaster:

\[ \mathrm D_\theta\ell = \mathrm D_{\hat z^\star}\ell\, \mathrm D_{\hat y}\mathcal O(\hat y)\, \mathrm D_\theta f(x,\theta). \]

The middle factor is the differentiable-optimization contribution. It is the focus of solution-map differentiation.

Closed-loop decision losses¶

A closed-loop loss evaluates decisions produced by one or more optimization stages. In a forecast--economic-dispatch--redispatch chain, for example,

\[ \hat z^{\mathrm{ed},\star} = \mathcal O^{\mathrm{ed}}(\hat y), \qquad \hat z^{\mathrm{rd},\star} = \mathcal O^{\mathrm{rd}}(\hat z^{\mathrm{ed},\star},y). \]

The loss may combine dispatch and redispatch costs:

\[ \ell_{\mathrm{closed}} = \ell\big( \hat z^{\mathrm{ed},\star}, \hat z^{\mathrm{rd},\star} \big). \]

Because the loss depends on optimal decisions, this setting requires SolMapLayer. Its backward pass solves either the full or reduced KKT adjoint.

Counterfactual value losses¶

A counterfactual loss can compare the objective induced by predicted parameters with an oracle objective computed from the realized parameters:

\[ \ell_{\mathrm{value}} = \left( \alpha(\hat y)-\alpha(y) \right)^2. \]

If \(\alpha(y)\) is precomputed, only \(\alpha(\hat y)\) participates in the training graph. Because the loss depends directly on the optimal value, ValueFuncLayer can use the direct value-function derivative and avoid a KKT adjoint solve.

Choosing the layer¶

Loss requires	Recommended layer	Reason
Original optimal decisions \(\hat z^\star\)	`SolMapLayer`	Returns autograd-connected named primal variables
Only the optimal value \(\alpha(\hat y)\)	`ValueFuncLayer`	Avoids solution-map Jacobian and adjoint KKT solve

The distinction affects only the differentiation target. Both layers share the same APQP canonicalization and forward-solve structure.