APQP and Canonicalization¶

DiffAPQP supports continuous affine-parametric quadratic and linear programs written as ordinary CVXPY models. The user works with named, domain-specific variables and parameters; DiffAPQP constructs the canonical matrix form internally.

Original domain model¶

The original optimization problem may contain several scalar, vector, or matrix decisions, denoted collectively by \(z\), and several parameter blocks, denoted collectively by \(\hat y\):

\[ \begin{aligned} \min_z\quad &f_0(z,\hat y)\\ \text{subject to}\quad &h_k(z,\hat y)=0, &&k=1,\ldots,N_{\mathrm{eq}},\\ &f_j(z,\hat y)\le 0, &&j=1,\ldots,N_{\mathrm{in}}. \end{aligned} \]

This is the model users express in CVXPY. The symbols and shapes can retain their engineering meaning, such as generator schedules, bus injections, network flows, demand forecasts, or renewable forecasts.

Canonical APQP¶

A QP is affine-parametric when its linear objective coefficient, objective offset, and constraint right-hand sides depend affinely on the parameters. The canonical APQP used by DiffAPQP is

\[ \begin{aligned} \min_{\tilde z}\quad &f_0(\tilde z,\hat y) := \frac{1}{2}\tilde z^T P\tilde z +q(\hat y)^T\tilde z +c(\hat y)\\ \text{subject to}\quad &A\tilde z=b(\hat y) &&(\tilde\nu),\\ &G\tilde z\le h(\hat y) &&(\tilde\lambda), \end{aligned} \]

where \(P\succeq0\). The affine parameter-to-data maps are

\[ \begin{aligned} q(\hat y) &= \tilde q+\sum_{i=1}^{N_p}Q_i\hat y_i,\\ c(\hat y) &= \tilde c+\sum_{i=1}^{N_p}d_i^T\hat y_i,\\ b(\hat y) &= \tilde b+\sum_{i=1}^{N_p}B_i\hat y_i,\\ h(\hat y) &= \tilde h+\sum_{i=1}^{N_p}H_i\hat y_i. \end{aligned} \]

The matrices \(P\), \(A\), and \(G\) are constant across parameter values. For each parameter block \(\hat y_i\):

\(Q_i\) maps it into the linear objective coefficient;
\(d_i\) maps it into the scalar objective offset;
\(B_i\) maps it into the equality right-hand side;
\(H_i\) maps it into the inequality right-hand side.

The canonical dimensions are

\[ \tilde z\in\mathbb R^{n_d}, \qquad A\in\mathbb R^{n_{\mathrm{eq}}\times n_d}, \qquad G\in\mathbb R^{n_{\mathrm{in}}\times n_d}. \]

The equality and inequality duals are \(\tilde\nu\in\mathbb R^{n_{\mathrm{eq}}}\) and \(\tilde\lambda\in\mathbb R^{n_{\mathrm{in}}}\), respectively.

An affine-parametric LP is the special case \(P=0\).

Automatic canonicalization¶

DiffAPQP represents canonicalization by

\[ (P,q,A,b,G,h) = \mathcal C(\hat y). \]

During layer construction, DiffAPQP asks CVXPY to compile the original problem, validates the resulting QP structure, and extracts the constant data and the affine maps \(Q_i\), \(d_i\), \(B_i\), and \(H_i\). Matrix-shaped parameters and variables are flattened in CVXPY's column-major order.

No manual standardization required

The APQP equations describe DiffAPQP's internal representation. Users should formulate the engineering model naturally with CVXPY and pass the original cvxpy.Problem directly to SolMapLayer or ValueFuncLayer.

The standard-form solver produces \(\tilde z^\star\). DiffAPQP records how the canonical variable is assembled and retrieves each original named decision through a linear selection/permutation map:

\[ \hat z^\star = \mathcal R(\tilde z^\star). \]

This retrieval map is also used in the solution-map backward pass.

Power-system interpretation¶

Consider a simple economic-dispatch model with generator output \(p_g\) and predicted demand \(\hat p_d\):

\[ \begin{aligned} \min_{p_g}\quad &c_g^T p_g\\ \text{subject to}\quad &p_{\mathrm{bus}}=C_g p_g-C_d\hat p_d,\\ &\mathbf 1^T p_{\mathrm{bus}}=0,\\ &-\bar p_f\le M p_{\mathrm{bus}}\le\bar p_f,\\ &\underline p_g\le p_g\le\bar p_g. \end{aligned} \]

Here \(p_g\) is part of \(z\) and \(\hat p_d\) is part of \(\hat y\). After substitution:

\(P=0\) and \(q=c_g\);
power balance gives \(A=\mathbf 1^T C_g\) and \(b(\hat p_d)=\mathbf 1^T C_d\hat p_d\);
the upper line limit gives \(M C_g p_g\le\bar p_f+M C_d\hat p_d\);
the lower line limit gives \(-M C_g p_g\le\bar p_f-M C_d\hat p_d\).

Thus demand enters the equality and inequality right-hand sides through \(B_i\) and \(H_i\). A predicted market price would instead commonly enter the linear objective through \(Q_i\).

Supported CVXPY structure¶

The current implementation requires:

a minimization problem with at least one named parameter and named decision;
a continuous, DCP-compliant QP or LP;
DPP compliance when parameters are present;
a constant positive-semidefinite \(P\);
constant decision-coefficient matrices \(A\) and \(G\);
affine parameter dependence through \(q\), \(c\), \(b\), or \(h\);
canonical variables that preserve the names and flattened sizes of the original CVXPY variables.

Parameterized \(P\), \(A\), or \(G\), integer or Boolean decisions, and nonlinear constraints are outside the current layer contract. See the exact validation and shape rules in the SolMapLayer and ValueFuncLayer references.

Each batch row supplies one value of \(\hat y\). The values of \(q(\hat y)\), \(c(\hat y)\), \(b(\hat y)\), and \(h(\hat y)\) may differ by sample, but all samples share \(P\), \(A\), \(G\), and the same affine maps. This fixed structure enables the repeated-solve accelerations described in the efficient forward pass.