CVXR Functions

Author

Anqi Fu and Balasubramanian Narasimhan

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.

Comparison operators

The comparison operators ==, <=, and >= are overloaded to create constraint objects:

x == y   # Equality constraint
x <= y   # Inequality constraint (convex <= concave)
x >= y   # Inequality constraint (concave >= convex)

Note that strict inequalities < and > are not supported, nor is !=.

Semidefinite operators

The operators %>>% and %<<% create positive semidefinite (PSD) and negative semidefinite (NSD) constraints, respectively:

X %>>% 0   # X is PSD
X %<<% 0   # X is NSD

Warning

Beware of operator precedence: A - B %>>% 0 is parsed as A - (B %>>% 0). Use (A - B) %>>% 0 instead.

Boolean operators

The operators &, |, and ! are overloaded for boolean variables to create logical constraints:

x & y    # equivalent to And(x, y)
x | y    # equivalent to Or(x, y)
!x       # equivalent to Not(x)

R math and summary functions

CVXR overloads many standard R functions so they can be applied directly to expressions:

Math: abs(), exp(), log(), sqrt(), cumsum(), cummax(), cumprod(), ceiling(), floor(), log2(), log10(), log1p()
Summary: sum(), max(), min(), prod(), mean()
Complex: Re(), Im(), Conj(), Mod()
Masked from base/stats: norm(), outer(), sd(), var()

These dispatch to the corresponding CVXR atoms (e.g., abs(x) calls Abs, sum(x) calls SumEntries).

Note

R Math group functions not listed above (e.g., sign(), round(), sin(), cos()) are not supported and will produce a clear error message if used on CVXR expressions.

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.

Norms

Function	Meaning	Curvature	Sign	Domain
`norm1(x)`	$\sum_{i} \| x_{i} \|$	convex	$\geq 0$
`norm2(x)`	$\sqrt{\sum_{i} x_{i}^{2}}$	convex	$\geq 0$
`norm_inf(x)`	$max_{i} \| x_{i} \|$	convex	$\geq 0$
`p_norm(x, p)`, $p \geq 1$	${(\sum_{i} \| x_{i} \|^{p})}^{1 / p}$	convex	$\geq 0$
`p_norm(x, p)`, $0 < p < 1$	${(\sum_{i} \| x_{i} \|^{p})}^{1 / p}$	concave	$\geq 0$	$x \geq 0$
`cvxr_norm(X, "fro")`	$\sqrt{\sum_{i j} X_{i j}^{2}}$	convex	$\geq 0$
`cvxr_norm(X, "nuc")`	$\sum_{i} σ_{i} (X)$	convex	$\geq 0$
`norm_nuc(X)`	$\sum_{i} σ_{i} (X)$	convex	$\geq 0$
`cvxr_norm(X, 2)`	$σ_{max} (X)$	convex	$\geq 0$
`sigma_max(X)`	$σ_{max} (X)$	convex	$\geq 0$
`mixed_norm(X, p, q)`	${(\sum_{k} {(\sum_{j} \| X_{j k} \|^{p})}^{q / p})}^{1 / q}$	convex	$\geq 0$

Aggregation and reduction

Function	Meaning	Curvature	Sign	Domain
`sum_entries(X)`	$\sum_{i j} X_{i j}$	affine	unknown
`sum_squares(x)`	$\sum_{i} x_{i}^{2}$	convex	$\geq 0$
`sum_largest(x, k)`	sum of $k$ largest $x_{i}$	convex	unknown	$k \in {1, \dots, n}$
`sum_smallest(x, k)`	sum of $k$ smallest $x_{i}$	concave	unknown	$k \in {1, \dots, n}$
`max_entries(x)`	$max_{i} x_{i}$	convex	unknown
`min_entries(x)`	$min_{i} x_{i}$	concave	unknown
`prod_entries(x)`	$\prod_{i} x_{i}$	log-log concave	$\geq 0$	$x > 0$
`cvxr_mean(x)`	$\frac{1}{n} \sum_{i} x_{i}$	affine	unknown
`cvxr_var(x)`	$\frac{1}{n} \sum_{i} (x_{i} - \bar{x})^{2}$	convex	$\geq 0$
`cvxr_std(x)`	$\sqrt{\frac{1}{n} \sum_{i} (x_{i} - \bar{x})^{2}}$	convex	$\geq 0$
`ptp(x)`	$max (x) - min (x)$	convex	$\geq 0$
`cvar(x, β)`	conditional value-at-risk at level $β$	convex	unknown	$β \in (0, 1]$
`dotsort(x, w)`	$w_{[1]}^{T} x_{[1]} + \dots + w_{[n]}^{T} x_{[n]}$ (sorted)	convex	unknown	$w$ constant

Matrix and quadratic functions

Function	Meaning	Curvature	Sign	Domain
`matrix_trace(X)`	$tr (X)$	affine	unknown
`log_det(X)`	$\log det (X)$	concave	unknown	$X \in S_{+ +}^{n}$
`lambda_max(X)`	$λ_{max} (X)$	convex	unknown	$X \in S^{n}$
`lambda_min(X)`	$λ_{min} (X)$	concave	unknown	$X \in S^{n}$
`lambda_sum_largest(X, k)`	sum of $k$ largest eigenvalues of $X$	convex	unknown	$X \in S^{n}$
`lambda_sum_smallest(X, k)`	sum of $k$ smallest eigenvalues of $X$	concave	unknown	$X \in S^{n}$
`matrix_frac(x, P)`	$x^{T} P^{- 1} x$	convex	$\geq 0$	$P ≻ 0$
`quad_form(x, P)`	$x^{T} P x$	convex ( $P ⪰ 0$ )	$\geq 0$	$P ⪰ 0$ or $P ⪯ 0$
`quad_over_lin(x, y)`	$∥ x ∥_{2}^{2} / y$	convex	$\geq 0$	$y > 0$
`tr_inv(X)`	$tr (X^{- 1})$	convex	$\geq 0$	$X ≻ 0$
`geo_mean(x)`	${(\prod_{i} x_{i})}^{1 / n}$	concave	$\geq 0$	$x \geq 0$
`harmonic_mean(x)`	$\frac{n}{\sum_{i} 1 / x_{i}}$	concave	$\geq 0$	$x > 0$
`log_sum_exp(x)`	$\log (\sum_{i} e^{x_{i}})$	convex	unknown
`scalar_product(x, c)`	$c^{T} x$ where $c$ is constant	affine	unknown
`vdot(x, y)`	$x^{T} y$	affine	unknown
`tv(x)` / `total_variation(x)`	$\sum_{i} \| x_{i + 1} - x_{i} \|$	convex	$\geq 0$
`inv_prod(x)`	$1 / \prod_{i} x_{i}$	convex	$\geq 0$	$x > 0$
`perspective(f, s)`	$s \cdot f (x / s)$	convex	varies	$s > 0$

Clarifications

The domain $S^{n}$ refers to the set of symmetric matrices. The domains $S_{+}^{n}$ and $S_{-}^{n}$ refer to the set of positive semi-definite and negative semi-definite matrices, respectively. Similarly, $S_{+ +}^{n}$ and $S_{- -}^{n}$ refer to the set of positive definite and negative definite matrices, respectively.

For a vector expression x, norm2(x) gives the Euclidean norm. For a matrix expression X, cvxr_norm(X, 2) and sigma_max(X) give the spectral norm (largest singular value).

The function cvxr_norm(X, "fro") is called the Frobenius norm and cvxr_norm(X, "nuc") (or norm_nuc(X)) 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 functions). 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(c(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=0 implies the rows. In CVXR, we align our implementation with the base::apply function. The default in most cases is axis = NULL, 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 = NULL; 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	Curvature	Sign	Domain
`abs(x)`	$\| x \|$	convex	$\geq 0$
`entr(x)`	$- x \log x$	concave	unknown	$x > 0$
`exp(x)`	$e^{x}$	convex	$\geq 0$
`huber(x, M)`	$2 (\sqrt{1 + (x / M)^{2}} - 1) M^{2}$	convex	$\geq 0$	$M > 0$
`inv_pos(x)`	$1 / x$	convex	$\geq 0$	$x > 0$
`kl_div(x, y)`	$x \log (x / y) - x + y$	convex	$\geq 0$	$x > 0, y > 0$
`log(x)`	$\log x$	concave	unknown	$x > 0$
`log1p_atom(x)`	$\log (1 + x)$	concave	unknown	$x > - 1$
`log_normcdf(x)`	$\log Φ (x)$ ( $Φ$ = standard normal CDF)	concave	$\leq 0$
`logistic(x)`	$\log (1 + e^{x})$	convex	$\geq 0$
`loggamma(x)`	$\log Γ (x)$	convex	unknown	$x > 0$
`max_elemwise(x, y, ...)`	$max (x, y, \dots)$	convex	unknown
`min_elemwise(x, y, ...)`	$min (x, y, \dots)$	concave	unknown
`multiply(c, x)`	$c \cdot x$ ( $c$ constant)	affine	unknown
`neg(x)`	$max (- x, 0)$	convex	$\geq 0$
`pos(x)`	$max (x, 0)$	convex	$\geq 0$
`diff_pos(x, y)`	$max (x - y, 0)$	convex	$\geq 0$
`one_minus_pos(x)`	$max (1 - x, 0)$	convex	$\geq 0$
`power(x, 0)`	$1$	constant	$\geq 0$
`power(x, 1)`	$x$	affine	unknown
`power(x, p)`, $p \geq 1$	$x^{p}$	convex	$\geq 0$	$x \geq 0$
`power(x, p)`, $0 < p < 1$	$x^{p}$	concave	$\geq 0$	$x \geq 0$
`power(x, p)`, $p < 0$	$x^{p}$	convex	$\geq 0$	$x > 0$
`rel_entr(x, y)`	$x \log (x / y)$	convex	unknown	$x > 0, y > 0$
`scalene(x, α, β)`	$α \cdot pos (x) + β \cdot neg (x)$	convex	$\geq 0$	$α, β \geq 0$
`sqrt(x)`	$\sqrt{x}$	concave	$\geq 0$	$x \geq 0$
`square(x)`	$x^{2}$	convex	$\geq 0$
`xexp(x)`	$x e^{x}$	convex	unknown

DQCP elementwise functions

The following functions are quasiconvex or quasiconcave. They can be used in DQCP problems (pass qcp = TRUE to psolve()).

Function	Meaning	Curvature	Sign	Domain
`ceil_expr(x)`	$⌈ x ⌉$	quasiconvex	unknown
`floor_expr(x)`	$⌊ x ⌋$	quasiconcave	unknown

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	Curvature	Sign	Domain
`bmat(list(list(X, Y), ...))`	block matrix from list of lists	affine	unknown
`conv(c, x)`	$c * x$ (discrete convolution)	affine	unknown	$c$ constant
`cumsum_axis(x, axis)`	cumulative sum along axis	affine	unknown	axis required
`cummax_expr(x, axis)`	cumulative max along axis	convex	unknown	axis required
`cvxr_diff(x)`	$k$ th order differences	affine	unknown
`cvxr_outer(x, y)`	$x y^{T}$ (outer product)	affine (one arg constant)	unknown	one arg must be constant
`diag(x)` / `diag(X)`	diagonal vector $\leftrightarrow$ diagonal matrix	affine	unknown
`hstack(x, y, ...)`	horizontal stack	affine	unknown
`kronecker(X, Y)`	$X \otimes Y$ (Kronecker product)	affine	unknown	one arg must be constant
`reshape_expr(x, c(m, n))`	reshape to $m \times n$	affine	unknown
`upper_tri(X)`	upper triangular elements as vector	affine	unknown	$X$ square
`vec(X)`	vectorize (column-major)	affine	unknown
`vec_to_upper_tri(x)`	vector to upper triangular matrix	affine	unknown
`vstack(x, y, ...)`	vertical stack	affine	unknown

DGP-specific functions

The following functions are for use in Disciplined Geometric Programming (DGP) problems. They are log-log convex or log-log concave.

Function	Meaning	Curvature	Domain
`pf_eigenvalue(X)`	Perron-Frobenius eigenvalue	log-log convex	$X \geq 0$
`eye_minus_inv(X)`	$(I - X)^{- 1}$	log-log convex	spectral radius $< 1$
`resolvent(X, s)`	$(s I - X)^{- 1}$	log-log convex	spectral radius $< s$
`gmatmul(A, x)`	generalized matrix multiply (DGP)	log-log affine	$A$ constant, $x > 0$

Boolean logic atoms

The following atoms are used for boolean constraints in mixed-integer problems. They operate on boolean variables.

Function	Meaning	Domain
`And(x, y)`	$x \land y$	boolean variables
`Or(x, y)`	$x \lor y$	boolean variables
`Not(x)`	$\neg x$	boolean variables
`Xor(x, y)`	$x \oplus y$	boolean variables
`implies(x, y)`	$x \Rightarrow y$	boolean variables
`iff(x, y)`	$x \Leftrightarrow y$	boolean variables

Constraint constructors

These create constraint objects directly.

Function	Meaning
`SOC(t, x)`	$∥ x ∥_{2} \leq t$ (second-order cone)
`PSD(X)`	$X ⪰ 0$ (positive semidefinite)
`ExpCone(x, y, z)`	$y e^{x / y} \leq z, y > 0$ (exponential cone)
`PowCone3D(x, y, z, alpha)`	$∥ z ∥ \leq x^{α} y^{1 - α}$ (power cone)
`FiniteSet(x, S)`	$x \in S$ (finite set membership)

Session Info

R version 4.5.2 (2025-10-31)
Platform: aarch64-apple-darwin20
Running under: macOS Tahoe 26.3

Matrix products: default
BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: America/Los_Angeles
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] kableExtra_1.4.0

loaded via a namespace (and not attached):
 [1] vctrs_0.7.1        svglite_2.2.2      cli_3.6.5          knitr_1.51        
 [5] rlang_1.1.7        xfun_0.56          stringi_1.8.7      otel_0.2.0        
 [9] textshaping_1.0.4  jsonlite_2.0.0     glue_1.8.0         htmltools_0.5.9   
[13] scales_1.4.0       rmarkdown_2.30     evaluate_1.0.5     fastmap_1.2.0     
[17] yaml_2.3.12        lifecycle_1.0.5    stringr_1.6.0      compiler_4.5.2    
[21] RColorBrewer_1.1-3 htmlwidgets_1.6.4  rstudioapi_0.18.0  systemfonts_1.3.1 
[25] farver_2.1.2       digest_0.6.39      viridisLite_0.4.3  R6_2.6.1          
[29] dichromat_2.0-0.1  magrittr_2.0.4     tools_4.5.2        xml2_1.5.2