Skip to content

DiffAPQP

DiffAPQP provides differentiable optimization layers for continuous affine-parametric quadratic and linear programs. It connects models written in CVXPY to PyTorch, supports batched forward solves through multiple solver backends, and differentiates either optimal decisions or optimal objective values.

Model directly in CVXPY

Write the optimization problem in its natural engineering form and pass the original cvxpy.Problem to DiffAPQP. The package validates, canonicalizes, and extracts the compatible APQP structure internally; users do not need to derive standard-form matrices manually.

Installation

Install the core package from PyPI:

python -m pip install diffapqp

This is sufficient for ordinary solves through the public CVXPY interface. DiffAPQP's explicit sample-indexed warm starts and in-place solver-data updates require the separately installed custom CVXPY fork. See Installation for that setup, optional solvers, and editable development installs.

Quick start

The following example defines a parameterized QP, solves two instances as a batch, and differentiates a loss through the optimal decisions:

import cvxpy as cp
import torch

from diffapqp import SolMapLayer

z = cp.Variable(2, name="z")
q = cp.Parameter(2, name="q")

problem = cp.Problem(
    cp.Minimize(0.5 * cp.sum_squares(z) + q @ z),
    [z >= 0, z <= 10],
)

layer = SolMapLayer(problem, max_n_cores=1)

q_batch = torch.tensor(
    [[-1.0, -2.0], [0.5, -1.5]],
    dtype=torch.double,
    requires_grad=True,
)

primal_dict, *_ = layer(
    {"q": q_batch},
    solver="OSQP",
    reduced_kkt=True,
)

loss = primal_dict["z"].square().mean()
loss.backward()

print(primal_dict["z"])
print(q_batch.grad)

param_dict uses the names of the original CVXPY parameters, and primal_dict uses the names of the original CVXPY variables. The leading tensor dimension is the batch dimension.

Choose a layer

DiffAPQP exposes two differentiation targets:

Training loss depends on Layer Differentiable output Backward method
Optimal decisions \(\hat z^\star\) SolMapLayer Named variables in primal_dict Full- or reduced-KKT adjoint
Optimal value \(\alpha(\hat y)\) ValueFuncLayer value_batch Direct value-function derivative

Layer remains an exact alias of SolMapLayer for backward compatibility. The API overview provides a compact comparison of the two interfaces.

Core capabilities

  • Automatic canonicalization: converts compatible named CVXPY models to affine-parametric QP/LP data internally.
  • Flexible forward solvers: uses CVXPY-compatible QP and conic solver backends independently of the backward method.
  • Batched execution: solves independent parameter instances concurrently with reusable per-slot problem structures.
  • Repeated-solve acceleration: supports solver warm starts and in-place data updates where the backend and CVXPY interface expose them.
  • Two backward strategies: provides full- and reduced-KKT adjoints for solution-map losses and a direct derivative for value-function losses.
  • Named outputs: restores optimal decisions to their original CVXPY names and shapes.

Current scope

DiffAPQP targets continuous, DCP- and QP-compliant problems in which:

  • the quadratic matrix \(P\) and constraint matrices \(A\) and \(G\) are constant;
  • parameters enter affinely through the linear objective, objective offset, or constraint right-hand sides;
  • parameterized problems satisfy CVXPY's DPP rules;
  • all public parameter and variable dictionaries use explicit CVXPY names.

Linear programs are supported as the special case \(P=0\). Parameterized quadratic or constraint matrices, nonlinear constraints, and integer or Boolean decisions are outside the current layer contract. See APQP and Canonicalization for the mathematical definition and accepted-problem assumptions.

Continue reading

  1. Installation: custom CVXPY support, optional solvers, and development environments.
  2. Solvers: forward backends, configured defaults, and warm-start/update coverage.
  3. API Overview: shared input conventions and layer selection.
  4. Theory Overview: decision-focused learning, canonicalization, forward acceleration, and backward derivations.
  5. Solution-Map Layer: complete SolMapLayer arguments, returns, lifecycle, and examples.
  6. Value-Function Layer: complete ValueFuncLayer behavior and direct-gradient interface.