Package {sparsediff}

sparsediff: R interface to the SparseDiffEngine differentiation backend

Description

R bindings to the 'SparseDiffEngine' C library — the sparse Jacobian and Hessian differentiation backend used by 'CVXPY' for its Disciplined Nonlinear Programming (DNLP) extension. This package is the R analog of the 'sparsediffpy' Python package and wraps the same C library (pinned at the upstream v0.3.0 release).

Author(s)

Maintainer: Balasubramanian Narasimhan naras@stanford.edu

Authors:

• Daniel Cederberg (Author of the bundled SparseDiffEngine C library) [copyright holder]

• William Zijie Zhang (Author of the bundled SparseDiffEngine C library) [copyright holder]

See Also

Useful links:

• https://bnaras.github.io/sparsediff/

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

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

Bundled SparseDiffEngine version

Description

Returns the version string of the SparseDiffEngine C library bundled with this package.

Usage

engine_version()

Value

A character scalar, e.g. "0.3.0".

Examples

engine_version()

Affine and shape atoms

Description

Affine combinations and shape manipulations of expressions. These have constant (zero) second derivatives but participate in the Jacobian.

Arguments

Details

sd_add

elementwise sum of two expressions.

sd_sum

sum reduction along axis.

sd_trace

matrix trace.

sd_transpose

matrix transpose.

sd_diag_vec

diagonal matrix from a vector.

sd_diag_mat

diagonal vector from a matrix.

sd_upper_tri

the strict upper-triangular entries.

sd_promote

promote a scalar to shape d1 x d2.

sd_reshape

reshape to d1 x d2 (column-major).

sd_broadcast

broadcast to d1 x d2.

sd_index

select entries by 0-based flat indices.

sd_hstack, sd_vstack

horizontal / vertical stacking.

Value

An expression handle.

See Also

sparsediff-elementwise, sparsediff-matrix

Bivariate atoms

Description

Functions of two expression arguments.

Arguments

Details

sd_elementwise_mult

elementwise (Hadamard) product.

sd_matmul

matrix product x y.

sd_quad_over_lin

the quadratic-over-linear \lVert x \rVert^2 / y.

sd_rel_entr

elementwise relative entropy x \log(x / y).

sd_rel_entr_first_scalar, sd_rel_entr_second_scalar

relative entropy with a scalar first or second argument broadcast against the other.

Value

An expression handle.

See Also

sparsediff-elementwise, sparsediff-reduction

Elementwise atoms

Description

Smooth elementwise functions of a single expression. Each returns an expression of the same shape as its argument.

Arguments

Details

sd_exp, sd_log

exponential and natural logarithm.

sd_sin, sd_cos, sd_tan

trigonometric functions.

sd_sinh, sd_tanh, sd_asinh, sd_atanh

hyperbolic and inverse-hyperbolic functions.

sd_logistic

the logistic \log(1 + e^x).

sd_xexp

x e^x.

sd_normal_cdf

the standard normal CDF.

sd_entr

the elementwise entropy -x \log x.

sd_power

the power x^p.

sd_neg

negation -x.

Value

An expression handle.

See Also

sparsediff-affine, sparsediff-bivariate

Leaf expressions: variables and parameters

Description

Create the leaves of an expression graph. A variable is a slice of the differentiation vector; a parameter is fixed data that can be updated between evaluations (see sd_register_params).

Arguments

Value

An expression handle.

See Also

sparsediff-elementwise, sd_problem

Parameter- and constant-matrix atoms

Description

Operations that combine an expression with fixed data — a registered parameter node or a constant matrix — so the data can flow through the differentiated graph (and, for parameters, be updated between evaluations).

Arguments

Details

sd_scalar_mult, sd_vector_mult

multiply a child by a scalar / vector parameter.

sd_convolve

convolution of a parameter kernel with a child.

sd_quad_form

the quadratic form x^\top Q x with sparse constant Q.

sd_left_matmul, sd_right_matmul

left / right product with a sparse constant matrix A.

sd_left_matmul_dense, sd_right_matmul_dense

left / right product with a dense constant matrix.

Value

An expression handle.

See Also

sd_parameter, sd_register_params

Sparse derivative oracle

Description

Initialise and evaluate the value, gradient, sparse constraint Jacobian and sparse lower-triangular Lagrangian Hessian of a problem built with sd_problem.

Arguments

Details

Evaluation is ordered: a forward pass first (sd_objective_forward / sd_constraint_forward) populates the node values at u, after which sd_gradient, sd_jacobian_values and sd_hessian_values read them. Sparsity patterns are structural — fixed once the corresponding sd_init_* routine has run — so they are queried once and reused, while the values are recomputed at each new point. Row and column indices are 0-based (the engine convention; a higher-level modelling layer such as CVXR translates them to 1-based as needed).

Value

sd_init_derivatives, sd_init_jacobian, sd_init_jacobian_coo, sd_init_hessian_coo

called for their side effect; return NULL invisibly.

sd_objective_forward

the scalar objective value at u.

sd_constraint_forward

the constraint vector at u.

sd_gradient

the objective gradient, length n_vars.

sd_jacobian_sparsity, sd_hessian_sparsity

a list with integer rows/cols (0-based COO indices) and nrow/ncol.

sd_jacobian_values

the constraint-Jacobian nonzeros, matching the Jacobian sparsity order.

sd_hessian_values

the nonzeros of \sigma\nabla^2 f + \sum_i w_i \nabla^2 g_i, lower triangle, matching the Hessian sparsity order.

See Also

sd_problem

Assemble a differentiable problem

Description

Combine an objective expression and a list of constraint expressions (built with the sd_* atom constructors) into a single problem object whose value and sparse derivatives can be evaluated repeatedly.

Arguments

Details

The typical lifecycle is: build expressions with the sd_* constructors, assemble them with sd_problem(), initialise the derivative structures once (sd_init_derivatives and friends), then evaluate the objective/constraints and their sparse derivatives at as many primal points as needed. When the problem has parameters, register them once with sd_register_params() and push new values with sd_update_params() to re-evaluate without rebuilding the graph (the DPP-style fast path).

Value

sd_problem() returns an external-pointer problem handle. The handle owns the underlying expression graph and frees it when garbage collected. sd_register_params() and sd_update_params() are called for their side effect and return NULL invisibly.

See Also

sd_init_derivatives for the evaluation oracle, sd_variable and the atom constructors for building expressions.

Product-reduction atoms

Description

Multiplicative reductions of an expression.

Arguments

Details

sd_prod

product of all entries.

sd_prod_axis_zero

column-wise products (reduce down rows).

sd_prod_axis_one

row-wise products (reduce across columns).

Value

An expression handle.

See Also

sparsediff-affine