Package {diffcp}

diffcp: Differentiating Through Cone Programs

Description

R port of the Python diffcp package, mirroring Agrawal, Barratt, Boyd, Busseti, and Moursi (2019). Computes the derivative of the optimal solution map of a convex cone program with respect to its data, via the implicit-function theorem on the homogeneous self-dual embedding.

Details

If you use this package in published work, please cite both the R package and the original paper; see citation("diffcp") for the full pair of BibTeX entries.

Author(s)

Maintainer: Balasubramanian Narasimhan naras@stanford.edu

Authors:

• Akshay Agrawal

• Shane Barratt

• Stephen Boyd

• Enzo Busseti

• Walaa Moursi

See Also

Useful links:

• https://github.com/bnaras/diffcp

• Report bugs at https://github.com/bnaras/diffcp/issues

Cone tag constants

Description

String keys matching the SCS / Clarabel cone conventions. Used as names in the cone_dict argument to solve_only() and solve_and_derivative(), and in the ⁠(name, size)⁠ pairs returned by parse_cone_dict().

Usage

ZERO

EQ_DIM

POS

SOC

PSD

EXP

EXP_DUAL

CONES

Format

Character scalars (and one character vector, CONES).

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 6.

Details

• ZERO ("z"): zero cone (equality constraints).

• EQ_DIM: alias of ZERO.

• POS ("l"): nonnegative orthant.

• SOC ("q"): second-order cone.

• PSD ("s"): symmetric positive semidefinite cone.

• EXP ("ep"): primal exponential cone.

• EXP_DUAL ("ed"): dual exponential cone.

• CONES: the canonical SCS ordering of cone tags.

Parse an SCS-style cone dictionary into an ordered list

Description

Mirrors diffcp.cones.parse_cone_dict.

Usage

parse_cone_dict(cone_dict)

Arguments

Value

A list of list(name, size) pairs, in the canonical SCS cone order (CONES).

Projection onto a Cartesian product of cones

Description

Mirrors diffcp.cones.pi.

Usage

pi(x, cones, dual = FALSE)

Arguments

Value

A numeric vector of the same length as x.

Solve a cone program and return forward / adjoint derivative operators

Description

Mirrors diffcp.cone_program.solve_and_derivative. Solves minimize c^T x s.t. A x + s = b, s in K (with optional QP ⁠0.5 x^T P x⁠ term) and returns the optimal ⁠(x, y, s)⁠ together with closures D (forward) and DT (adjoint) that map perturbations of ⁠(A, b, c, [P])⁠ to perturbations of ⁠(x, y, s)⁠ and vice versa.

Usage

solve_and_derivative(
  A,
  b,
  c,
  cone_dict,
  P = NULL,
  solve_method = "Clarabel",
  mode = "lsqr",
  warm_start = NULL,
  ...
)

Arguments

Value

A list with elements x, y, s, info, D, DT. info is the solver-status block returned by the underlying solver (status, iter, solveTime, pobj, ...); see solve_only for the same shape.

Solve a cone program (forward only)

Description

Mirrors diffcp.cone_program.solve_only. Solves minimize c^T x (+ 0.5 x^T P x) subject to A x + s = b, s in K and returns the optimal ⁠(x, y, s)⁠. Unlike solve_and_derivative this function does not build the derivative closures.

Usage

solve_only(
  A,
  b,
  c,
  cone_dict,
  warm_start = NULL,
  solve_method = "Clarabel",
  P = NULL,
  ...
)

Arguments

Value

A list with elements x, y, s, info.

Inverse of vec_symm

Description

Inverse of vec_symm

Usage

unvec_symm(x, dim)

Arguments

Value

The corresponding ⁠n x n⁠ symmetric matrix.

Upstream Python diffcp pin

Description

Returns the upstream pin metadata for this R port: which cvxgrp/diffcp version / commit the R sources track, the date of that commit, and diffcp's own CVXPY runtime constraint. The authoritative record lives in inst/UPSTREAM.dcf and is read at call time.

Usage

upstream_info()

Value

A named character vector with one element per DCF field (Upstream, Version, Commit, ShortCommit, Date, URL, CVXPY, Snapshot, Notes).

Examples

upstream_info()
upstream_info()[["Version"]]

Symmetric vectorization (SCS convention)

Description

Returns a vectorized representation of a symmetric matrix X, with off-diagonal entries scaled by sqrt(2) to make the SCS-style dot product ⁠<vec_symm(A), vec_symm(B)> = trace(A B)⁠ hold.

Usage

vec_symm(X)

Arguments

Details

Mirrors diffcp.cones.vec_symm (Python).

Value

A numeric vector of length n*(n+1)/2.