# Differentiating Through a Cone Program with diffcp

# What `diffcp` is for

Suppose you have a convex optimization problem whose data — the constraint matrix, the offset, the objective coefficients — depend on some upstream quantity (a parameter, a model weight, a hyperparameter, the output of a previous computation). You solve the problem and get an optimum. How does that optimum change when the data changes?

`diffcp` answers that question. It treats the optimal solution as an implicit function of the problem data, and returns the derivative of that function — both in the forward direction (perturb the data, get the predicted change in the optimum) and as its adjoint (start from a downstream loss on the optimum and backpropagate to a gradient on the data).

Three concrete things you can do with it:

- Sensitivity analysis. Quantify how much each constraint or cost coefficient matters at the optimum.
- Hyperparameter learning. Solve a regularized problem inside a training loop and let gradient descent on the upstream loss learn the regularizer.
- End-to-end optimization layers. Embed a CVXR problem as a differentiable component of a larger model — see CVXR’s `Problem$backward()` and `Problem$derivative()` API, which internally calls `diffcp`.

The implementation is a port of the Python `diffcp` package (Agrawal, Barratt, Boyd, Busseti, Moursi, 2019); the numerical core (cone projections, Jacobians, the `M` operator, LSQR) is direct C++ from the upstream repository, called from R via RcppEigen.

    library(diffcp)
    library(Matrix)

# The mathematical setup

`diffcp` differentiates the primal–dual conic problem

\[ \begin{aligned} \text{minimize} &\quad c^\top x \\ \text{subject to} &\quad A x + s = b, \quad s \in K, \end{aligned} \]

where \(K\) is a Cartesian product of the standard cones (zero, the non-negative orthant, second-order, positive semidefinite, exponential, and the exponential dual). The dual variable attached to the cone constraint is \(y\); together \((x, y, s)\) is the primal–dual triple.

Differentiating “the optimum” turns out to mean something precise:

1. The KKT conditions can be lifted into a homogeneous self-dual embedding (Ye–Todd–Mizuno) in which optimality, primal infeasibility, and dual infeasibility all become statements about a single residual map \(N(z) = ((Q - I) \Pi(z) + I) z\), where \(Q\) is a skew-symmetric block of the data and \(\Pi\) is the projection onto \(\mathbb{R}^n \times K^\ast \times \mathbb{R}_+\).
2. At a regular point — informally, an optimum away from active-set transitions and degeneracies — the implicit-function theorem applies, and the optimum is a smooth function of the problem data.
3. The Jacobian of the optimum with respect to the data is then a bounded linear operator, computed by solving a linear system in \(M = (Q - I)\,D\Pi(z) + I\) using either a dense LDLT factorization or a matrix-free LSQR iteration.

This is the construction in Busseti, Moursi, and Boyd (2019); `diffcp` packages it into two callables.

# What the package computes

Calling `solve_and_derivative(A, b, c, cone_dict)` returns a list with five entries:

- `x`, `y`, `s` — the primal–dual optimum.
- `D(dA, db, dc)` — the forward derivative. Given a perturbation of the data, returns `(dx, dy, ds)`: the predicted change in the optimum, to first order.
- `DT(dx, dy, ds)` — the adjoint of `D`. Given a perturbation of the optimum (or, more usefully, a gradient of a downstream loss with respect to the optimum), returns `(dA, db, dc)`: the gradient of that loss with respect to the data.

Both are functions, not matrices. The dense mode materializes the Jacobian as an Eigen matrix and factors it once; the LSQR mode applies the Jacobian and its transpose matrix-free, never forming the dense object. The trade-off is per-call cost (`dense` is faster once `M` has been factored) versus memory and asymptotic scaling (`lsqr` is the only viable choice for very large problems).

# Worked example 1: a linear program

The smallest illustrative case: pick the cheapest non-negative mixture of three goods that sums to one,

\[ \min_{x \in \mathbb{R}^3} \; c^\top x \quad \text{subject to} \quad \mathbf{1}^\top x = 1,\; x \ge 0. \]

In SCS standard form \(Ax + s = b\), \(s \in K = \{0\} \times \mathbb{R}^3_+\) — one row for the equality (zero cone, \(s = 0\)) followed by three rows for the non-negativity constraints (the slack absorbs the inequality):

    A <- sparseMatrix(i = c(1, 2, 1, 3, 1, 4),
                      j = c(1, 1, 2, 2, 3, 3),
                      x = c(1, -1, 1, -1, 1, -1),
                      dims = c(4, 3))
    b <- c(1, 0, 0, 0)
    c <- c(1, 2, 3)
    cone_dict <- list(z = 1L, l = 3L)

    res <- solve_and_derivative(A, b, c, cone_dict, mode = "lsqr",
                                tol_gap_abs = 1e-10,
                                tol_gap_rel = 1e-10,
                                tol_feas    = 1e-10)
    res$x
    #> [1] 1.000000e+00 1.562233e-11 5.329854e-12

The optimum is \(x \approx (1, 0, 0)\) — all weight on the cheapest coordinate. Now the derivative. Suppose we slightly increase the cost of the first coordinate, holding everything else fixed:

    dA <- sparseMatrix(i = integer(0), j = integer(0), x = numeric(0),
                       dims = c(4, 3))
    db <- numeric(4)
    dc <- c(0.001, 0, 0)
    d <- res$D(dA, db, dc)
    d$dx
    #> [1] -2.274114e-16 -6.059404e-16  4.396755e-15

`D` reports that `dx` is essentially zero — the optimum is robust to a small bump in \(c_1\), because the constraint \(\mathbf{1}^\top x = 1\) pins coordinate 1 against \(x \ge 0\). (You’d see a non-trivial `dy` if you printed the dual perturbation.) The forward derivative agrees with finite-differencing the perturbed solve to within solver tolerance:

    res_pert <- solve_only(A, b, c + dc, cone_dict,
                           tol_gap_abs = 1e-10,
                           tol_gap_rel = 1e-10,
                           tol_feas    = 1e-10)
    max(abs(d$dx - (res_pert$x - res$x)))
    #> [1] 1.453855e-14

The agreement is at the level of the Clarabel solve tolerance, not the LSQR tolerance — the per-call derivative is the exact implicit-function-theorem answer at this point.

# Worked example 2: a second-order-cone program

A geometric example: project the simplex centroid onto a Lorentz cone,

\[ \min_{t,\, x} \; t \quad \text{subject to} \quad \|x\|_2 \le t,\; \mathbf{1}^\top x = 1. \]

The variables are \((t, x_1, x_2, x_3)\). The block \((t, x)\) lives in a single 4-dimensional second-order cone; the equality goes in a zero cone of size 1. Since \(t\) is being minimized against a norm constraint, the optimum lies on the cone boundary \(\|x\|_2 = t\), which is exactly the kind of active constraint that makes derivatives non-trivial.

    A <- sparseMatrix(
      i = c(2, 1, 3, 1, 4, 1, 5),
      j = c(1, 2, 2, 3, 3, 4, 4),
      x = c(-1, 1, -1, 1, -1, 1, -1),
      dims = c(5, 4))
    b <- c(1, 0, 0, 0, 0)
    c <- c(1, 0, 0, 0)
    cone_dict <- list(z = 1L, q = 4L)

    res <- solve_and_derivative(A, b, c, cone_dict, mode = "dense",
                                tol_gap_abs = 1e-10,
                                tol_gap_rel = 1e-10,
                                tol_feas    = 1e-10)
    res$x
    #> [1] 0.5773503 0.3333333 0.3333333 0.3333333

The optimum is \(x = (1/3, 1/3, 1/3)\), \(t = \sqrt{3}/3\), and the SOC constraint \(\|x\|_2 = t\) holds with equality. The cone projection’s Jacobian at a boundary point is the technical heart of `diffcp` — it’s a smoothed projector that interpolates between the identity (interior of the cone) and zero (interior of the polar cone). The package handles all the boundary geometry automatically; from the R side you just call `D` and `DT`.

# Worked example 3: a small semidefinite program

The minimum-eigenvalue SDP: find a unit-trace PSD matrix that minimizes \(\langle C, X \rangle\) for given \(C\). With \(C = \mathrm{diag}(1, 0, 0, 0, -1)\), the optimum is rank-one and puts all weight on the eigenvector of \(C\) with most-negative eigenvalue.

PSD support requires a vectorization convention. `diffcp` uses the SCS convention: lower-triangular column-major, with off-diagonals scaled by \(\sqrt{2}\). The package exports `vec_symm()` and `unvec_symm()` for round-trips between symmetric matrices and their packed vector form. The trace-coefficient row in the equality constraint is sparse — only the diagonal entries contribute, and we build it explicitly:

    DIM <- 5L
    n   <- DIM * (DIM + 1L) %/% 2L          # 15

    trace_row <- numeric(n)
    pos <- 1L
    for (col in seq_len(DIM)) {
      trace_row[pos] <- 1.0
      pos <- pos + (DIM - col + 1L)         # next diagonal in column-major lower-tri
    }

    A <- rbind(
      Matrix(matrix(trace_row, nrow = 1L), sparse = TRUE),
      -Diagonal(n))
    A <- as(A, "CsparseMatrix")
    b <- c(1.0, numeric(n))

    C <- matrix(0, DIM, DIM)
    C[1, 1] <- 1; C[DIM, DIM] <- -1
    c_vec <- vec_symm(C)

    cone_dict <- list(z = 1L, s = DIM)

    res <- solve_only(A, b, c_vec, cone_dict,
                      tol_gap_abs = 1e-10,
                      tol_gap_rel = 1e-10,
                      tol_feas    = 1e-10)
    X <- unvec_symm(res$x, DIM)
    sum(diag(X))
    #> [1] 1
    range(eigen(X, symmetric = TRUE, only.values = TRUE)$values)
    #> [1] -2.080584e-12  1.000000e+00

`X` has trace 1 (to solver tolerance) and is PSD (smallest eigenvalue \(\ge -10^{-9}\)). Behind the scenes, when the solve goes through Clarabel — which packs PSD entries in upper-triangular column-major order, opposite to SCS — `diffcp` permutes the rows of \(A\) and the entries of \(b\) on the way in, and inverse-permutes the dual \(y\) and slack \(s\) on the way out, so the user-facing convention stays SCS throughout.

# A practical sensitivity-analysis example

Here is the canonical use case: shadow prices. Take a small LP — a profit-maximizing production plan with a labor and a materials budget — and ask, given the optimum, by how much would the profit change per extra unit of labor? That number is the dual variable on the labor constraint. `diffcp` lets you compute the same sensitivity for any perturbation of the data, including ones that have no closed-form dual interpretation.

We solve

\[ \max_{x_1, x_2 \ge 0}\; 3 x_1 + 5 x_2 \quad \text{s.t.}\quad 2 x_1 + x_2 \le 100,\; x_1 + 3 x_2 \le 90, \]

and ask: how does the optimum respond to a small change in the labor-budget right-hand side, \(b_1 = 100\)?

We rewrite the maximization as a minimization of \(-c^\top x\), and encode the two budget inequalities and the two non-negativity inequalities as four rows of a non-negative orthant slack constraint:

    A_lp <- sparseMatrix(i = c(1, 2, 3,  1, 2, 4),
                         j = c(1, 1, 1,  2, 2, 2),
                         x = c(2, 1, -1, 1, 3, -1),
                         dims = c(4, 2))
    b_lp <- c(100, 90, 0, 0)
    c_lp <- c(-3, -5)
    cones_lp <- list(l = 4L)

    res <- solve_and_derivative(A_lp, b_lp, c_lp, cones_lp, mode = "dense",
                                tol_gap_abs = 1e-10, tol_gap_rel = 1e-10,
                                tol_feas    = 1e-10)
    res$x      # optimal production plan
    #> [1] 42 16
    -sum(c_lp * res$x)   # max profit
    #> [1] 206

The optimum makes \(x_1 = 42\), \(x_2 = 16\), profit \(= 206\). Now use `D` to ask how the optimal \(x\) would change if we got one extra unit of labor (\(\Delta b_1 = 1\)):

    dA <- sparseMatrix(i = integer(0), j = integer(0), x = numeric(0),
                       dims = c(4, 2))
    db <- c(1, 0, 0, 0)
    dc <- numeric(2)
    d  <- res$D(dA, db, dc)
    d$dx                       # change in optimal production
    #> [1]  0.6 -0.2
    -sum(c_lp * d$dx)          # change in profit
    #> [1] 0.8

`d$dx` says that an extra unit of labor increases \(x_1\) by 0.6 and decreases \(x_2\) by 0.2, and the corresponding profit change is \(0.8\) per unit of labor: the labor-budget shadow price, recovered from `D` rather than from the dual variable \(y\).

The advantage of going through `D` instead of the dual: it generalizes. We can ask the same question about non-trivial perturbations of \(A\) (a productivity gain on a particular input), `c` (a price change on a particular product), or any combination. The dual variable answers only the canonical RHS-perturbation question; `D` answers all of them through the same single call.

`DT` answers the opposite question. Suppose we have a downstream loss \(L(x^\ast)\) — say, a smooth function of the optimum with known gradient \(\partial L / \partial x^\ast\). The adjoint computes the gradient of \(L\) with respect to every data entry \((A, b, c)\) in one shot:

    ## Suppose dL/dx* is given (e.g. from autodiff in a larger model).
    dL_dx <- c(1.0, -0.5)
    dL_dy <- numeric(length(res$y))
    dL_ds <- numeric(length(res$s))
    da    <- res$DT(dL_dx, dL_dy, dL_ds)
    da$db                 # gradient of L w.r.t. each entry of b
    #> [1]  7.000000e-01 -4.000000e-01 -6.162066e-12 -2.615830e-12
    da$dc                 # gradient of L w.r.t. each entry of c
    #> [1] 3.130882e-10 1.741558e-10

In a training loop you’d feed `da$db` and `da$dc` straight into a parameter update.

# Forward versus adjoint: when to use each

Both `D` and `DT` access the same underlying Jacobian, but their cost profile differs:

- `D(dA, db, dc)` is right-multiplication by the Jacobian. Cost is one solve of the same linear system per call. Use `D` when you have a small number of perturbation directions (e.g., parameter sweeps) and want to forecast the effect on the optimum.
- `DT(dx, dy, ds)` is right-multiplication by the Jacobian’s transpose. Same per-call cost, but the answer is a gradient with respect to all data entries simultaneously. Use `DT` when you have an upstream gradient on the optimum (typically from an autodiff system) and need to propagate it through the conic optimization.

`mode = "dense"` factors `M` once on the first call and amortizes the cost across subsequent `D` / `DT` invocations on the same problem, which is the right choice when you’ll evaluate either operator many times.

# Choosing `dense` versus `lsqr`

`solve_and_derivative` accepts two modes for the inner linear-algebra step:

- `mode = "lsqr"` (default): matrix-free conjugate-gradient- style iterative solve against the `M` operator. Memory is \(O(\text{nnz}(A))\); iteration count grows with the conditioning of \(M\). Appropriate for large sparse problems.
- `mode = "dense"`: build \(M\) as a dense matrix, factor with Eigen’s LDLT, and reuse the factorization across `D` / `DT` calls. Cost is \(O(N^3)\) once, \(O(N^2)\) per call, where \(N = m + n + 1\). Appropriate for small problems and for workflows that re-apply `D` / `DT` many times.

Both modes produce the same answer to within solver tolerance. The dense path matches Python’s \((M^\top M).\mathrm{ldlt}().\mathrm{solve}(M^\top \cdot \mathrm{rhs})\) bit-for-bit; the LSQR path agrees with the dense path to roughly \(10^{-6}\) at the default `atol = btol = 1e-8`.

# Conventions

- PSD vectorization. `vec_symm()` packs the lower triangle in column-major order with off-diagonals scaled by \(\sqrt{2}\) (the SCS convention). `unvec_symm()` is the inverse. This scaling makes the inner product \(\langle \mathrm{vec}(A), \mathrm{vec}(B) \rangle\) equal \(\mathrm{tr}(AB)\) for symmetric \(A, B\), which is what the cone-projection Jacobian expects.
- PSD with Clarabel. Clarabel uses upper-triangular column- major; `diffcp` permutes rows of \(A\) and entries of \(b\) to Clarabel order on the way in and inverse-permutes the dual \(y\) and slack \(s\) on the way out. The user-facing convention is SCS throughout.
- Exponential cones. Each `ep` cone consumes three rows of \(A\) (one cone per `count`); the dual `ed` cone is handled separately or recovered via Moreau’s decomposition, \(\Pi_{K^\ast}(x) = x + \Pi_K(-x)\).
- Quadratic objectives. `solve_only(P = P)` accepts a positive-semidefinite `P` for the forward solve. The derivative path through `solve_and_derivative` does not support `P` directly; CVXR’s reduction chain canonicalizes QPs into auxiliary-variable conic problems before reaching the solver, so the loss is invisible at the CVXR layer.

# Connection to CVXR

R users typically don’t call `diffcp` directly. CVXR (≥ 1.8.2) exposes a higher-level API:

    library(CVXR)
    p <- Parameter(); x <- Variable(); value(p) <- 3
    prob <- Problem(Minimize((x - 2 * p)^2), list(x >= 0))
    psolve(prob, requires_grad = TRUE)
    backward(prob)
    gradient(p)             # 2  (since x* = 2p)
    delta(p) <- 1e-3
    derivative(prob)
    delta(x)                # 0.002

The `requires_grad = TRUE` flag routes the solve through the DIFFCP solver wrapper, which calls `diffcp::solve_and_derivative` under the hood. CVXR then handles the chain rule through any problem reductions (DGP log-transform, Complex2Real splitting, parameter canonicalization) and reports gradients keyed by `Parameter` rather than by raw data entries.

When you want the lower-level data-perturbation interface — for research, for fixtures that bypass CVXR canonicalization, or for problems already in conic standard form — `diffcp` is the right entry point.

# Citation

If you use `diffcp` in academic work, please cite both the R package and the original paper. See `citation("diffcp")` for the canonical BibTeX entries.

- R package

  > Narasimhan, B.; Agrawal, A.; Barratt, S.; Boyd, S.; Busseti, E.; Moursi, W. diffcp: Differentiating Through Cone Programs. R package, 2026. https://github.com/bnaras/diffcp

- Original paper

  > Agrawal, A.; Barratt, S.; Boyd, S.; Busseti, E.; Moursi, W. “Differentiating through a cone program.” Journal of Applied and Numerical Optimization, 1(2), 107–115, 2019.