CVXR Functions

Functions

Here we describe the functions that can be applied to CVXR expressions. CVXR uses the function information in this section and the Disciplined Convex Programming tools to mark expressions with a sign and curvature.

Operators

The infix operators +, -, *, %*%, / are treated as functions. + and - are affine functions. * and / are affine in CVXR because expr1*expr2 and expr1 %*% expr2 are allowed only when one of the expressions is constant and expr1/expr2 is allowed only when expr2 is a scalar constant.

Indexing and slicing

All non-scalar expressions can be indexed using the syntax expr[i, j]. Indexing is an affine function. The syntax expr[i] can be used as a shorthand for expr[i, 1] when expr is a column vector. Similarly, expr[i] is shorthand for expr[1, i] when expr is a row vector.

Non-scalar expressions can also be sliced into using the standard R slicing syntax. For example, expr[i:j, r] selects rows i through j of column r and returns a vector.

CVXR supports advanced indexing using lists of indices or boolean arrays. The semantics are the same as in R. Any time R might return a numeric vector, CVXR returns a column vector.

Transpose

The transpose of any expression can be obtained using the syntax t(expr). Transpose is an affine function.

Power

For any CVXR expression expr, the power operator expr^p is equivalent to the function power(expr, p).

Scalar functions

A scalar function takes one or more scalars, vectors, or matrices as arguments and returns a scalar.

Function Meaning Domain Sign Curvature Monotonicity
geo_mean(x) geo_mean(x, p) p∈Rn+ p≠0 x1/n1⋯x1/nn (xp11⋯xpnn)11Tp x∈Rn+ positive concave incr.
harmonic_mean(x) n1x1+⋯+1xn x∈Rn+ positive concave incr.
lambda_max(X) λmax(X) X∈Sn unknown convex None
lambda_min(X) λmin(X) X∈Sn unknown concave None
lambda_sum_largest(X, k) k=1,…,n sum of k largest eigenvalues of X X∈Sn unknown convex None
lambda_sum_smallest(X, k) k=1,…,n sum of k smallesteigenvalues of X X∈Sn unknown concave None
log_det(X) log(det(X)) X∈Sn+ unknown concave None
log_sum_exp(X) log(∑ijeXij) X∈Rm×n unknown convex incr.
matrix_frac(x, P) xTP−1x x∈Rn P∈Sn++ positive convex None
max_entries(X) maxij{Xij} X∈Rm×n same as X convex incr.
min_entries(X) minij{Xij} X∈Rm×n same as X concave incr.
mixed_norm(X, p, q) (∑k(∑l|xk,l|p)q/p)1/q X∈Rm×n positive convex None
cvxr_norm(x) cvxr_norm(x, 2) √∑ix2i X∈Rn positive convex for xi≥0 for xi≤0
cvxr_norm(X, “fro”) √∑ijX2ij X∈Rm×n positive convex for Xij≥0 for Xij≤0
cvxr_norm(X, 1) ∑ij|Xij| X∈Rm×n positive convex for Xij≥0 for Xij≤0
cvxr_norm(X, “inf”) maxij{|Xij|} X∈Rm×n positive convex for Xij≥0 for Xij≤0
cvxr_norm(X, “nuc”) tr((XTX)1/2) X∈Rm×n positive convex None
cvxr_norm(X) cvxr_norm(X, 2) √λmax(XTX) X∈Rm×n positive convex None
p_norm(X, p) p≥1 or p = Inf ‖X‖p=(∑ij|Xij|p)1/p X∈Rm×n positive convex for Xij≥0 for Xij≤0
p_norm(X, p) p<1, p≠0 ‖X‖p=(∑ijXpij)1/p X∈Rm×n+ positive concave incr.
quad_form(x, P) constant P∈Sn+ xTPx x∈Rn positive convex for xi≥0 for xi≤0
quad_form(x, P) constant P∈Sn− xTPx x∈Rn negative concave for xi≥0 for xi≤0
quad_form(c, X) constant c∈Rn cTXc X∈Rn×n depends on c, X affine depends on c
quad_over_lin(X, y) (∑ijX2ij)/y X∈Rm×n y>0 positive convex for Xij≥0 for Xij≤0 decr. in y
sum_entries(X) ∑ijXij X∈Rm×n same as X affine incr.
sum_largest(X, k) k=1,2,… sum of k largest Xij X∈Rm×n same as X convex incr.
sum_smallest(X, k) k=1,2,… sum of k smallest Xij X∈Rm×n same as X concave incr.
sum_squares(X) ∑ijX2ij X∈Rm×n positive convex for Xij≥0 for Xij≤0
matrix_trace(X) tr(X) X∈Rn×n same as X affine incr.
tv(x) ∑i|xi+1−xi| x∈Rn positive convex None
tv(X) ∑ij‖[Xi+1,j−XijXi,j+1−Xij]‖2 X∈Rm×n positive convex None
tv(X1,…,Xk) ∑ij‖[X(1)i+1,j−X(1)ijX(1)i,j+1−X(1)ij⋮X(k)i+1,j−X(k)ijX(k)i,j+1−X(k)ij]‖2 X(i)∈Rm×n positive convex None

Clarifications

The domain Sn refers to the set of symmetric matrices. The domains Sn+ and Sn− refer to the set of positive semi-definite and negative semi-definite matrices, respectively. Similarly, Sn++ and Sn−− refer to the set of positive definite and negative definite matrices, respectively.

For a vector expression x, cvxr_norm(x) and cvxr_norm(x, 2) give the Euclidean norm. For a matrix expression X, however, cvxr_norm(X) and cvxr_norm(X, 2) give the spectral norm.

The function cvxr_norm(X, "fro") is called the Frobenius norm and cvxr_norm(X, "nuc") the nuclear norm. The nuclear norm can also be defined as the sum of X’s singular values.

The functions max_entries and min_entries give the largest and smallest entry, respectively, in a single expression. These functions should not be confused with max_elemwise and min_elemwise (see elementwise). Use max_elemwise and min_elemwise to find the maximum or minimum of a list of scalar expressions.

The function sum_entries sums all the entries in a single expression. The built-in R sum should be used to add together a list of expressions. For example, the following code sums three expressions:

expr_sum <- sum(expr1, expr2, expr3)

Functions along an axis

The functions sum_entries, cvxr_norm, max_entries, and min_entries can be applied along an axis. Given an m by n expression expr, the syntax func(expr, axis=1) applies func to each row, returning a m by 1 expression. The syntax func(expr, axis=2) applies func to each column, returning a 1 by n expression. For example, the following code sums along the columns and rows of a matrix variable:

X <- Variable(5, 4)
row_sums <- sum_entries(X, axis=1) # Has size (5, 1)
col_sums <- sum_entries(X, axis=2) # Has size (1, 4)

Note that the use of axis differs from its use in CVXPY where axis=2 implies the columns. In CVXR, we align our implementation with the base::apply function. The default in most cases is axis = NA, which treats a matrix as one long vector, basically the same as apply with c(1,2). The exception is cumsum_axis (see below), which cannot take axis = NA; it will throw an error.

Elementwise functions

These functions operate on each element of their arguments. For example, if X is a 5 by 4 matrix variable, then abs(X) is a 5 by 4 matrix expression. abs(X)[1, 2] is equivalent to abs(X[1, 2]).

Elementwise functions that take multiple arguments, such as max_elemwise and multiply, operate on the corresponding elements of each argument. For example, if X and Y are both 3 by 3 matrix variables, then max_elemwise(X, Y) is a 3 by 3 matrix expression. max_elemwise(X, Y)[2, 1] is equivalent to max_elemwise(X[2, 1], Y[2, 1]). This means all arguments must have the same dimensions or be scalars, which are promoted.

Function Meaning Domain Sign Curvature Monotonicity
abs(x) |x| x∈R positive convex for x≥0 for x≤0
entr(x) −xlog(x) x>0 unknown concave None
exp(x) ex x∈R positive convex incr.
huber(x, M=1) M≥0 {x2|x|≤M2M|x|−M2|x|>M x∈R positive convex for x≥0 for x≤0
inv_pos(x) 1/x x>0 positive convex decr.
kl_div(x, y) xlog(x/y)−x+y x>0 y>0 positive convex None
log(x) log(x) x>0 unknown concave incr.
log1p(x) log(x+1) x>−1 same as x concave incr.
logistic(x) log(1+ex) x∈R positive convex incr.
max_elemwise(x1, …, xk) max{x1,…,xk} xi∈R max(sign(x1)) convex incr.
min_elemwise(x1, …, xk) min{x1,…,xk} xi∈R min(sign(x1)) concave incr.
multiply(c, x) c∈R c*x x∈R sign(cx) affine depends on c
neg(x) max{−x,0} x∈R positive convex decr.
pos(x) max{x,0} x∈R positive convex incr.
power(x, 0) 1 x∈R positive constant
power(x, 1) x x∈R same as x affine incr.
power(x, p) p=2,4,8,… xp x∈R positive convex for x≥0 for x≤0
power(x, p) p<0 xp x>0 positive convex decr.
power(x, p) 0<p<1 xp x≥0 positive concave incr.
power(x, p) p>1, p≠2,4,8,… xp x≥0 positive convex incr.
scalene(x, alpha, beta) alpha≥0 beta≥0 αpos(x)+βneg(x) x∈R positive convex for x≥0 for x≤0
sqrt(x) √x x≥0 positive concave incr.
square(x) x2 x∈R positive convex for x≥0 for x≤0

Vector/matrix functions

A vector/matrix function takes one or more scalars, vectors, or matrices as arguments and returns a vector or matrix.

Function Meaning Domain Sign Curvature Monotonicity
bmat([[X11, …, X1q], …, [Xp1, …, Xpq]]) [X(1,1)⋯X(1,q)⋮⋮X(p,1)⋯X(p,q)] X(i,j)∈Rmi×nj sign(∑ijX(i,j)11) affine incr.
conv(c, x) c∈Rm c∗x x∈Rn sign(c1x1) affine depends on c
cumsum_axis(X, axis=1) cumulative sum along given axis. X∈Rm×n same as X affine incr.
diag(x) [x1⋱xn] x∈Rn same as x affine incr.
diag(X) [X11⋮Xnn] X∈Rn×n same as X affine incr.
diff(X, k=1, axis=1) k∈0,1,2,… kth order differences (argument k is actually named differences and lag can also be used) along given axis X∈Rm×n same as X affine incr.
hstack(X1, …, Xk) [X(1)⋯X(k)] X(i)∈Rm×ni sign(∑iX(i)11) affine incr.
kronecker(C, X) C∈Rp×q [C11X⋯C1qX⋮⋮Cp1X⋯CpqX] X∈Rm×n sign(C11X11) affine depends on C
reshape_expr_expr(X, c( m’, n’)) X′∈Rm′×n′ X∈Rm×n m′n′=mn same as X affine incr.
vec(X) x′∈Rmn X∈Rm×n same as X affine incr.
vstack(X1, …, Xk) [X(1)⋮X(k)] X(i)∈Rmi×n sign(∑iX(i)11) affine incr.

Clarifications

The input to bmat is a list of lists of CVXR expressions. It constructs a block matrix. The elements of each inner list are stacked horizontally, and then the resulting block matrices are stacked vertically.

The output y of conv(c, x) has size n+m−1 and is defined as y[k]=∑kj=0c[j]x[k−j].

The output x of vec(X) is the matrix X flattened in column-major order into a vector. Formally, x′i=Ximodm,⌊i/m⌋.

The output X of reshape_expr(X, c(m', n')) is the matrix X cast into an m′×n′ matrix. The entries are taken from X in column-major order and stored in X′ in column-major order. Formally, X′ij=vec(X)m′j+i.