Skip to content

API Overview

DiffAPQP exposes two differentiable layers built on top of CVXPY problems. In a decision-focused learning pipeline, a forecaster produces optimization parameters \(\hat y=f(x,\theta)\) from contextual input \(x\) and trainable weights \(\theta\); DiffAPQP consumes \(\hat y\) and propagates gradients back through that forecaster.

from diffapqp import SolMapLayer, ValueFuncLayer

Pass the original cvxpy.Problem directly to either layer. Users do not need to derive or construct the APQP matrices manually; DiffAPQP validates and canonicalizes a compatible CVXPY formulation internally.

Layer Types

Value-Function Layer (ValueFuncLayer)

  • maps optimization parameters \(\hat y\) to the value \(\alpha(\hat y)=f_0(\hat z^\star,\hat y)\)
  • ideal when your training loss depends on objective value
  • backward pass uses value-function structure (envelope-theorem style)

Solution-Map Layer (SolMapLayer)

  • maps optimization parameters \(\hat y\) to optimal decisions \(\hat z^\star=\mathcal{O}(\hat y)\)
  • ideal when your loss depends on the optimizer output itself
  • backward pass solves an adjoint system (full KKT or reduced KKT)

Layer remains an exact alias of SolMapLayer for backward compatibility.

Shared Input Pattern

Both layers accept named batched parameter dictionaries:

{"q": q_batch, "h": h_batch, "b": b_batch}

Keys must match CVXPY parameter names in the original problem. Mathematically, each batch row supplies one value of \(\hat y\).

Warm-Start and Update

Both layers expose:

  • warm_start: reuse solver-native iterates
  • update: use solver data-update path when available

For modified solver update behavior, use the custom CVXPY fork and stable sample indices (idx_list) across successive calls. See Installation.

Theory primer

For mathematical background and practical stability notes:

See also