CVXR: Disciplined Convex Optimization

Description

An object-oriented modeling language for disciplined convex programming (DCP) as described in Fu, Narasimhan, and Boyd (2020, doi:10.18637/jss.v094.i14). It allows the user to formulate convex optimization problems in a natural way following mathematical convention and DCP rules. The system analyzes the problem, verifies its convexity, converts it into a canonical form, and hands it off to an appropriate solver to obtain the solution. This version uses the S7 object system for improved performance and maintainability.

Author(s)

Maintainer: Anqi Fu anqif@alumni.stanford.edu

Authors:

• Balasubramanian Narasimhan naras@stat.stanford.edu

• Steven Diamond

• John Miller

Other contributors:

• Stephen Boyd boyd@stanford.edu [contributor]

See Also

Useful links:

• https://cvxr.rbind.io

• https://www.cvxgrp.org/CVXR/

• Report bugs at https://github.com/cvxgrp/CVXR/issues

Positive Semidefinite Constraint Operator

Description

Creates a PSD constraint: e1 - e2 is positive semidefinite. This is the R equivalent of Python's A >> B.

Usage

e1 %>>% e2

Arguments

Value

A PSD constraint object.

See Also

PSD()

Examples

## Not run: 
X <- Variable(3, 3, symmetric = TRUE)
constr <- X %>>% diag(3)  # X - I is PSD

## End(Not run)

Negative Semidefinite Constraint Operator

Description

Creates an NSD constraint: e2 - e1 is positive semidefinite, i.e., e1 is NSD relative to e2. This is the R equivalent of Python's A << B.

Usage

e1 %<<% e2

Arguments

Value

A PSD constraint object.

See Also

PSD()

Examples

## Not run: 
X <- Variable(3, 3, symmetric = TRUE)
constr <- X %<<% diag(3)  # I - X is PSD (X is NSD relative to I)

## End(Not run)

Logical AND

Description

Returns 1 if and only if all arguments equal 1, and 0 otherwise. For two operands, can also be written with the & operator: x & y.

Usage

And(..., id = NULL)

Arguments

Value

An And expression.

See Also

Not(), Or(), Xor(), implies(), iff()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
y <- Variable(boolean = TRUE)
both <- x & y            # operator syntax
both <- And(x, y)        # functional syntax
all3 <- And(x, y, z)     # n-ary

## End(Not run)

Create a Constant Expression

Description

Wraps a numeric value as a CVXR constant for use in optimization expressions. Constants are typically created implicitly when combining numeric values with CVXR expressions via arithmetic operators.

Usage

Constant(value, name = NULL)

Arguments

Value

A Constant object (inherits from Leaf and Expression).

Examples

c1 <- Constant(5)
c2 <- Constant(matrix(1:6, 2, 3))

DCP Error condition

Description

Creates a custom R condition of class "DCPError" for disciplined convex programming violations.

Usage

DCPError(message, call = sys.call(-1L))

Arguments

Value

A condition object of class c("DCPError", "error", "condition")

Extract Diagonal from a Matrix

Description

Extracts the k-th diagonal of a square matrix as a column vector.

Usage

DiagMat(x, k = 0L, id = NULL)

Arguments

Value

A DiagMat expression of shape c(n - abs(k), 1).

See Also

DiagVec

Vector to Diagonal Matrix

Description

Constructs a diagonal matrix from a column vector. If k != 0, the vector is placed on the k-th super- or sub-diagonal.

Usage

DiagVec(x, k = 0L, id = NULL)

Arguments

Value

A DiagVec expression of shape c(n + abs(k), n + abs(k)).

See Also

DiagMat

Create an Equality Constraint

Description

Constrains two expressions to be equal elementwise: lhs = rhs. Typically created via the == operator on CVXR expressions.

Usage

Equality(lhs, rhs, constr_id = NULL)

Arguments

Value

An Equality constraint object.

See Also

Zero, Inequality

Create an Exponential Cone Constraint

Description

Constrains (x, y, z) to lie in the exponential cone:

K = \{(x,y,z) \mid y \exp(x/y) \le z,\; y > 0\}

Usage

ExpCone(x_expr, y_expr, z_expr, constr_id = NULL)

Arguments

Details

All three arguments must be affine, real, and have the same shape.

Value

An ExpCone constraint object.

FiniteSet Constraint

Description

Constrain each entry of an Expression to take a value in a given finite set of real numbers.

Usage

FiniteSet(expre, vec, ineq_form = FALSE, constr_id = NULL)

Arguments

Value

A FiniteSet constraint.

Create an Inequality Constraint

Description

Constrains the left-hand side to be less than or equal to the right-hand side elementwise: lhs \le rhs. Typically created via the <= operator on CVXR expressions.

Usage

Inequality(lhs, rhs, constr_id = NULL)

Arguments

Value

An Inequality constraint object.

See Also

Equality, NonPos, NonNeg

Create a Maximization Objective

Description

Specifies that the objective expression should be maximized. The expression must be concave and scalar for a DCP-compliant problem.

Usage

Maximize(expr)

Arguments

Value

A Maximize object.

See Also

Minimize, Problem

Examples

x <- Variable()
obj <- Maximize(-x^2 + 1)

Create a Minimization Objective

Description

Specifies that the objective expression should be minimized. The expression must be convex and scalar for a DCP-compliant problem.

Usage

Minimize(expr)

Arguments

Value

A Minimize object.

See Also

Maximize, Problem

Examples

x <- Variable()
obj <- Minimize(x^2 + 1)

Create a Non-Negative Constraint

Description

Constrains an expression to be non-negative elementwise: x \ge 0.

Usage

NonNeg(expr, constr_id = NULL)

Arguments

Value

A NonNeg constraint object.

See Also

NonPos, Inequality

Create a Non-Positive Constraint

Description

Constrains an expression to be non-positive elementwise: x \le 0.

Usage

NonPos(expr, constr_id = NULL)

Arguments

Value

A NonPos constraint object.

See Also

NonNeg, Inequality

Logical NOT

Description

Returns 1 - x, flipping 0 to 1 and 1 to 0. Can also be written with the ! operator: !x.

Usage

Not(x, id = NULL)

Arguments

Value

A Not expression.

See Also

And(), Or(), Xor(), implies(), iff()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
not_x <- !x          # operator syntax
not_x <- Not(x)      # functional syntax

## End(Not run)

Logical OR

Description

Returns 1 if and only if at least one argument equals 1, and 0 otherwise. For two operands, can also be written with the | operator: x | y.

Usage

Or(..., id = NULL)

Arguments

Value

An Or expression.

See Also

Not(), And(), Xor(), implies(), iff()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
y <- Variable(boolean = TRUE)
either <- x | y          # operator syntax
either <- Or(x, y)       # functional syntax
any3 <- Or(x, y, z)      # n-ary

## End(Not run)

Create a Positive Semidefinite Constraint

Description

Constrains a square matrix expression to be positive semidefinite (PSD): X \succeq 0. The expression must be square.

Usage

PSD(expr, constr_id = NULL)

Arguments

Value

A PSD constraint object.

Create a Parameter

Description

Constructs a parameter whose numeric value can be changed without re-canonicalizing the problem. Parameters are treated as constants for DCP purposes but their value can be updated between solves.

Usage

Parameter(
  shape = c(1L, 1L),
  name = NULL,
  value = NULL,
  id = NULL,
  latex_name = NULL,
  ...
)

Arguments

Value

A Parameter object (inherits from Leaf and Expression).

Examples

p <- Parameter()
value(p) <- 5
p_vec <- Parameter(3, nonneg = TRUE)
gamma <- Parameter(1, name = "gamma", latex_name = "\\gamma")

Create a 3D Power Cone Constraint

Description

Constrains (x, y, z) to lie in the 3D power cone:

x^\alpha \cdot y^{1-\alpha} \ge |z|, \quad x \ge 0, \; y \ge 0

Usage

PowCone3D(x_expr, y_expr, z_expr, alpha, constr_id = NULL)

Arguments

Value

A PowCone3D constraint object.

See Also

PowConeND

Create an N-Dimensional Power Cone Constraint

Description

Constrains (W, z) to lie in the N-dimensional power cone:

\prod W_i^{\alpha_i} \ge |z|, \quad W \ge 0

where \alpha_i > 0 and \sum \alpha_i = 1.

Usage

PowConeND(W, z, alpha, axis = 2L, constr_id = NULL)

Arguments

Value

A PowConeND constraint object.

Known limitations

The R clarabel solver does not currently support the PowConeND cone specification. Problems involving PowConeND (e.g., exact geometric mean with more than 2 arguments) should use SCS or MOSEK as the solver, or use approximation-based atoms (e.g., geo_mean(x, approx = TRUE)).

See Also

PowCone3D

Create an Optimization Problem

Description

Constructs a convex optimization problem from an objective and a list of constraints. Use psolve to solve the problem.

Usage

Problem(objective, constraints = list())

Arguments

Value

A Problem object.

Known limitations

• Problems must contain at least one Variable. Zero-variable problems (e.g., minimizing a constant) will cause an internal error in the reduction pipeline.

Examples

x <- Variable(2)
prob <- Problem(Minimize(sum_entries(x)), list(x >= 1))

Create a Second-Order Cone Constraint

Description

Constrains \|X_i\|_2 \le t_i for each column or row i, where t is a vector and X is a matrix.

Usage

SOC(t, X, axis = 2L, constr_id = NULL)

Arguments

Value

An SOC constraint object.

Solver Error condition

Description

Creates a custom R condition of class "SolverError" for solver failures.

Usage

SolverError(message, call = sys.call(-1L))

Arguments

Value

A condition object of class c("SolverError", "error", "condition")

Create an Optimization Variable

Description

Constructs a variable to be used in a CVXR optimization problem. Variables are decision variables that the solver optimizes over.

Usage

Variable(shape = c(1L, 1L), name = NULL, var_id = NULL, latex_name = NULL, ...)

Arguments

Value

A Variable object (inherits from Leaf and Expression).

Examples

x <- Variable(3)        # 3x1 column vector
X <- Variable(c(2, 3))  # 2x3 matrix
y <- Variable(2, nonneg = TRUE)  # non-negative variable
z <- Variable(3, name = "z", latex_name = "\\mathbf{z}")  # custom LaTeX

Logical XOR

Description

For two arguments: result is 1 iff exactly one is 1. For n arguments: result is 1 iff an odd number are 1 (parity).

Usage

Xor(..., id = NULL)

Arguments

Details

Note: R's ^ operator is used for power(), so Xor is functional syntax only.

Value

A Xor expression.

See Also

Not(), And(), Or(), implies(), iff()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
y <- Variable(boolean = TRUE)
exclusive <- Xor(x, y)

## End(Not run)

Create a Zero Constraint

Description

Constrains an expression to equal zero elementwise: x = 0.

Usage

Zero(expr, constr_id = NULL)

Arguments

Value

A Zero constraint object.

See Also

Equality, NonPos, NonNeg

Convert a value to a CVXR Expression

Description

Wraps numeric vectors, matrices, and Matrix package objects as CVXR Constant objects. Values that are already CVXR expressions are returned unchanged.

Usage

as_cvxr_expr(x)

Arguments

Value

A CVXR expression (either the input unchanged or wrapped in Constant).

Matrix package interoperability

Objects from the Matrix package (dgCMatrix, dgeMatrix, ddiMatrix, sparseVector, etc.) are S4 classes. Because S4 dispatch preempts S7/S3 dispatch, raw Matrix objects cannot be used directly with CVXR operators (+, -, *, /, %*%, >=, ==, etc.).

Use as_cvxr_expr() to wrap a Matrix object as a CVXR Constant before combining it with CVXR variables or expressions. This preserves sparsity (unlike as.matrix(), which densifies).

Base R matrix and numeric objects work natively with CVXR operators — no wrapping is needed.

Examples

x <- Variable(3)

## Sparse Matrix needs as_cvxr_expr() for CVXR operator dispatch:
A <- Matrix::sparseMatrix(i = 1:3, j = 1:3, x = 1.0)
expr <- as_cvxr_expr(A) %*% x

## All operators work with wrapped Matrix objects:
y <- Variable(c(3, 3))
expr2 <- as_cvxr_expr(A) + y
constr <- as_cvxr_expr(A) >= y

## Base R matrix works natively (no wrapping needed):
D <- matrix(1:9, 3, 3)
expr3 <- D %*% x

Get Atom-Specific Domain Constraints

Description

Get Atom-Specific Domain Constraints

Usage

atom_domain(x, ...)

Arguments

Value

List of Constraint objects.

Get the Atoms in an Expression

Description

Get the Atoms in an Expression

Usage

atoms(x, ...)

Arguments

Value

List of atom objects.

List available solvers

Description

Returns the names of installed solvers that are not currently excluded. Use exclude_solvers() to temporarily disable solvers.

Usage

available_solvers()

exclude_solvers(solvers)

include_solvers(solvers)

set_excluded_solvers(solvers)

Arguments

Value

A character vector of solver names.

The current exclusion list (character vector), invisibly.

Functions

• exclude_solvers(): Add solvers to the exclusion list

• include_solvers(): Remove solvers from the exclusion list

• set_excluded_solvers(): Replace the entire exclusion list

See Also

installed_solvers(), exclude_solvers(), include_solvers(), set_excluded_solvers()

Construct a Block Matrix

Description

Takes a list of lists. Each internal list is stacked horizontally. The internal lists are stacked vertically.

Usage

bmat(block_lists)

Arguments

Value

An Expression representing the block matrix.

Broadcast two expressions for binary operations

Description

Broadcast two expressions for binary operations

Usage

broadcast_args(lh_expr, rh_expr)

Arguments

Value

List of two expressions with compatible shapes

Get the Canonical Form

Description

Get the Canonical Form

Usage

canonical_form(x, ...)

Arguments

Value

List with (expression, constraints).

Canonicalize an Expression

Description

Canonicalize an Expression

Usage

canonicalize(x, ...)

Arguments

Value

List with canonicalized expression and constraints.

Global Monthly and Annual Temperature Anomalies (degrees C), 1850-2015 (Relative to the 1961-1990 Mean) (May 2016)

Description

Global Monthly and Annual Temperature Anomalies (degrees C), 1850-2015 (Relative to the 1961-1990 Mean) (May 2016)

Usage

cdiac

Format

A data frame with 166 rows and 14 variables:

year

Year

jan

Anomaly for month of January

feb

Anomaly for month of February

mar

Anomaly for month of March

apr

Anomaly for month of April

may

Anomaly for month of May

jun

Anomaly for month of June

jul

Anomaly for month of July

aug

Anomaly for month of August

sep

Anomaly for month of September

oct

Anomaly for month of October

nov

Anomaly for month of November

dec

Anomaly for month of December

annual

Annual anomaly for the year

Source

https://ess-dive.lbl.gov/

References

https://ess-dive.lbl.gov/

Elementwise Ceiling

Description

Returns the ceiling (smallest integer >= x) of each element. This atom is quasiconvex and quasiconcave but NOT convex or concave, so it can only be used in DQCP problems (solved with qcp = TRUE).

Usage

ceil_expr(x)

Arguments

Value

A Ceil expression.

See Also

floor_expr

Condition number of a PSD matrix

Description

Computes the condition number lambda_max(A) / lambda_min(A) for a positive semidefinite matrix A. This is a quasiconvex atom.

Usage

condition_number(A)

Arguments

Value

An expression representing the condition number of A

Get the Sizes of Individual Cones

Description

Get the Sizes of Individual Cones

Usage

cone_sizes(x, ...)

Arguments

Value

Integer vector of cone sizes.

Elementwise Complex Conjugate

Description

Returns the complex conjugate of an expression. For real expressions this is a no-op. R's native Conj() dispatches here for CVXR expressions via the Complex S3 group handler.

Usage

conj_expr(expr)

Arguments

Value

A Conj_ atom.

Get the Constants in an Expression

Description

Get the Constants in an Expression

Usage

constants(x, ...)

Arguments

Value

List of Constant objects.

Get the Total Size of a Constraint

Description

Get the Total Size of a Constraint

Usage

constr_size(x, ...)

Arguments

Value

Integer.

Get Problem Constraints (read-only)

Description

Returns a copy of the problem's constraint list.

Usage

constraints(x)

Arguments

Details

Problem objects are immutable: constraints cannot be modified after construction. To change constraints, create a new Problem(). This matches CVXPY's design where problems are immutable except through Parameter value changes.

Value

A list of constraint objects.

See Also

Problem(), objective()

Examples

x <- Variable(2)
prob <- Problem(Minimize(sum_entries(x)), list(x >= 1))
length(constraints(prob))  # 1

1D discrete convolution

Description

1D discrete convolution

Usage

conv(a, b)

Arguments

Value

A Convolve atom

Cumulative maximum along an axis

Description

Cumulative maximum along an axis

Usage

cummax_expr(x, axis = 2L)

Arguments

Value

A Cummax atom

Cumulative sum along an axis

Description

Cumulative sum along an axis

Usage

cumsum_axis(x, axis = NULL)

Arguments

Value

A Cumsum atom

Get Expression Curvature

Description

Returns the DCP curvature of an expression as a string.

Usage

curvature(x)

Arguments

Value

Character: "CONSTANT", "AFFINE", "CONVEX", "CONCAVE", or "UNKNOWN".

See Also

is_convex(), is_concave(), is_affine(), is_constant()

Conditional Value at Risk (CVaR)

Description

CVaR at confidence level beta: average of the (1-beta) largest values.

Usage

cvar(x, beta)

Arguments

Value

An Expression representing the CVaR

Compute kth Order Differences of an Expression

Description

Takes in an expression and returns an expression with the kth order differences along the given axis. The output shape is the same as the input except the size along the specified axis is reduced by k.

Usage

cvxr_diff(x, k = 1L, axis = 2L)

Arguments

Value

An Expression representing the kth order differences.

Mean of an expression

Description

Computes the arithmetic mean of an expression along an axis.

Usage

cvxr_mean(x, axis = NULL, keepdims = FALSE)

Arguments

Value

An Expression representing the mean.

Compute a norm of an expression

Description

Compute a norm of an expression

Usage

cvxr_norm(x, p = 2, axis = NULL, keepdims = FALSE, max_denom = 1024L)

Arguments

Value

A norm atom

Outer product of two vectors

Description

Computes the outer product x %*% t(y). Both inputs must be vectors.

Usage

cvxr_outer(x, y)

Arguments

Value

An Expression of shape (length(x), length(y)).

Promote a scalar expression to the given shape

Description

Promote a scalar expression to the given shape

Usage

cvxr_promote(expr, shape)

Arguments

Value

The expression (unchanged if already the right shape) or a Promote atom

Standard deviation of an expression

Description

Computes the standard deviation of an expression.

Usage

cvxr_std(x, axis = NULL, keepdims = FALSE, ddof = 0)

std(x, axis = NULL, keepdims = FALSE, ddof = 0)

Arguments

Value

An Expression representing the standard deviation.

Variance of an expression

Description

Computes the variance. Only supports full reduction (axis = NULL).

Usage

cvxr_var(x, axis = NULL, keepdims = FALSE, ddof = 0)

Arguments

Value

An Expression representing the variance.

The difference x - y with domain x > y > 0

Description

Equivalent to x * one_minus_pos(y / x).

Usage

diff_pos(x, y)

Arguments

Value

A product expression

Distance ratio

Description

Computes norm(x - a)_2 / norm(x - b)_2, where a and b are constants. This is a quasiconvex atom.

Usage

dist_ratio(x, a, b)

Arguments

Value

An expression representing the distance ratio

Get the Domain Constraints of an Expression

Description

Get the Domain Constraints of an Expression

Usage

domain(x, ...)

Arguments

Value

List of constraints defining the domain.

Weighted sorted dot product

Description

Computes ⁠<sort(vec(X)), sort(vec(W))>⁠ where X is an expression and W is a constant. A generalization of sum_largest and sum_smallest.

Usage

dotsort(X, W)

Arguments

Value

A scalar convex Expression.

Check if DPP Scope is Active

Description

Check if DPP Scope is Active

Usage

dpp_scope_active()

Value

Logical; TRUE if a with_dpp_scope block is active.

Direct Standardization: Population

Description

Randomly generated data for direct standardization example. Sex was drawn from a Bernoulli distribution, and age was drawn from a uniform distribution on 10,\ldots,60. The response was drawn from a normal distribution with a mean that depends on sex and age, and a variance of 1.

Usage

dspop

Format

A data frame with 1000 rows and 3 variables:

y

Response variable

sex

Sex of individual, coded male (0) and female (1)

age

Age of individual

See Also

dssamp

Direct Standardization: Sample

Description

A sample of dspop for direct standardization example. The sample is skewed such that young males are overrepresented in comparison to the population.

Usage

dssamp

Format

A data frame with 100 rows and 3 variables:

y

Response variable

sex

Sex of individual, coded male (0) and female (1)

age

Age of individual

See Also

dspop

Get the Dual Cone Constraint

Description

Get the Dual Cone Constraint

Usage

dual_cone(x, ...)

Arguments

Value

A cone constraint representing the dual cone.

Get the Dual Residual

Description

Get the Dual Residual

Usage

dual_residual(x, ...)

Arguments

Value

Numeric residual.

Get the Dual Value of a Constraint

Description

Returns the dual variable value(s) associated with a constraint after solving. Returns NULL before the problem is solved.

Usage

dual_value(x)

Arguments

Value

A numeric matrix (single dual variable) or a list of numeric matrices (multiple dual variables), or NULL.

Create an entropy atom -x * log(x)

Description

Create an entropy atom -x * log(x)

Usage

entr(x)

Arguments

Value

An Entr atom

Conjugate-Transpose of an Expression

Description

Equivalent to CVXPY's .H property. For real expressions, returns t(x). For complex expressions, returns Conj(t(x)).

Usage

expr_H(x)

Arguments

Value

The conjugate-transpose expression.

Shallow Copy of an Expression Tree Node

Description

Shallow Copy of an Expression Tree Node

Usage

expr_copy(x, args = NULL, id_objects = NULL)

Arguments

Value

A copy of the object.

Get the Name of an Expression

Description

Get the Name of an Expression

Usage

expr_name(x, ...)

Arguments

Value

Character string.

Get the DCP Sign of an Expression

Description

Returns the sign of an expression under DCP analysis. Use this instead of sign(), which conflicts with the base R function.

Usage

expr_sign(x, ...)

Arguments

Value

Character string: "POSITIVE", "NEGATIVE", "ZERO", or "UNKNOWN".

Unity resolvent (I - X) inverse for positive square matrix X

Description

Log-log convex atom for DGP. Solve with psolve(problem, gp = TRUE).

Usage

eye_minus_inv(X)

Arguments

Value

An EyeMinusInv atom

Examples

X <- Variable(c(2, 2), pos = TRUE)
prob <- Problem(Minimize(sum(eye_minus_inv(X))), list(X <= 0.4))
## Not run: psolve(prob, gp = TRUE, solver = "SCS")

Elementwise Floor

Description

Returns the floor (largest integer <= x) of each element. This atom is quasiconvex and quasiconcave but NOT convex or concave, so it can only be used in DQCP problems (solved with qcp = TRUE).

Usage

floor_expr(x)

Arguments

Value

A Floor expression.

See Also

ceil_expr

Maximum generalized eigenvalue

Description

Computes the maximum generalized eigenvalue lambda_max(A, B). Requires A symmetric and B positive semidefinite. This is a quasiconvex atom.

Usage

gen_lambda_max(A, B)

Arguments

Value

An expression representing the maximum generalized eigenvalue

(Weighted) geometric mean of a vector

Description

(Weighted) geometric mean of a vector

Usage

geo_mean(x, p = NULL, max_denom = 1024L, approx = TRUE)

Arguments

Value

A GeoMean or GeoMeanApprox atom

Get Atom-Specific Data

Description

Get Atom-Specific Data

Usage

get_data(x, ...)

Arguments

Value

List of data.

Get Problem Data for a Solver (deprecated)

Description

Usage

get_problem_data(x, solver = NULL, ...)

Arguments

Details

Use problem_data instead.

Value

A list with components data, chain, and inverse_data.

See Also

problem_data

Geometric matrix multiplication A diamond X

Description

Computes the geometric matrix product where (A diamond X)_ij = prod_k X_kj^A_ik. Log-log affine atom for DGP. Solve with psolve(problem, gp = TRUE).

Usage

gmatmul(A, X)

Arguments

Value

A Gmatmul atom

Examples

x <- Variable(2, pos = TRUE)
A <- matrix(c(1, 0, 0, 1), 2, 2)
prob <- Problem(Minimize(sum(gmatmul(A, x))), list(x >= 0.5))
## Not run: psolve(prob, gp = TRUE)

Get the Gradient of an Expression

Description

Get the Gradient of an Expression

Usage

grad(x, ...)

Arguments

Value

Gradient information.

Get the Graph Implementation of an Atom

Description

Get the Graph Implementation of an Atom

Usage

graph_implementation(x, arg_objs, shape, data = NULL, ...)

Arguments

Value

List with (expression, constraints).

Harmonic mean: n / sum(1/x_i)

Description

Harmonic mean: n / sum(1/x_i)

Usage

harmonic_mean(x)

Arguments

Value

An Expression representing the harmonic mean

Check if Expression Has a Quadratic Term

Description

Check if Expression Has a Quadratic Term

Usage

has_quadratic_term(x, ...)

Arguments

Value

Logical scalar.

Horizontal concatenation of expressions

Description

Horizontal concatenation of expressions

Usage

hstack(...)

Arguments

Value

An HStack atom

Create a Huber loss atom

Description

Create a Huber loss atom

Usage

huber(x, M = 1)

Arguments

Value

A Huber atom

Get Expression ID

Description

Returns the unique integer identifier for a CVXR object.

Usage

id(x)

Arguments

Value

An integer.

Logical Biconditional

Description

Logical biconditional: x <=> y. Returns 1 if and only if x and y have the same value. Equivalent to Not(Xor(x, y)).

Usage

iff(x, y)

Arguments

Value

A Not expression wrapping Xor.

See Also

implies(), Not(), And(), Or(), Xor()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
y <- Variable(boolean = TRUE)
expr <- iff(x, y)

## End(Not run)

Extract Imaginary Part of Expression

Description

Returns the imaginary part of a complex expression. R's native Im() dispatches here for CVXR expressions via the Complex S3 group handler.

Usage

imag_expr(expr)

Arguments

Value

An Imag_ atom.

Logical Implication

Description

Logical implication: x => y. Returns 1 unless x = 1 and y = 0. Equivalent to Or(Not(x), y).

Usage

implies(x, y)

Arguments

Value

An Or expression representing !x | y.

See Also

iff(), Not(), And(), Or(), Xor()

Examples

## Not run: 
x <- Variable(boolean = TRUE)
y <- Variable(boolean = TRUE)
expr <- implies(x, y)

## End(Not run)

Indicator function for constraints

Description

Creates an expression that equals 0 if all constraints are satisfied and +Inf otherwise. Use this to embed constraints into the objective.

Usage

indicator(constraints, err_tol = 0.001)

Arguments

Value

An Indicator expression

List installed solvers

Description

Returns the names of solvers whose R packages are available.

Usage

installed_solvers()

Value

A character vector of solver names.

Convert a value to a numeric matrix or sparse matrix

Description

Normalizes R values so the rest of CVXR can assume a consistent type. Scalars -> 1x1 matrix, vectors -> column matrix, logical -> numeric. Sparse matrices are kept sparse.

Usage

intf_convert(val)

Arguments

Value

A matrix or dgCMatrix

Check if a matrix is symmetric (and Hermitian for real case)

Description

Check if a matrix is symmetric (and Hermitian for real case)

Usage

intf_is_hermitian(val)

Arguments

Value

List with is_symmetric (logical) and is_hermitian (logical)

Check if a symmetric matrix is PSD within tolerance

Description

Check if a symmetric matrix is PSD within tolerance

Usage

intf_is_psd(val, tol = EIGVAL_TOL)

Arguments

Value

Logical

Check if a matrix is skew-symmetric (A + A^T == 0)

Description

Check if a matrix is skew-symmetric (A + A^T == 0)

Usage

intf_is_skew_symmetric(val)

Arguments

Value

Logical scalar

Check if a value is a sparse matrix

Description

Check if a value is a sparse matrix

Usage

intf_is_sparse(val)

Arguments

Value

Logical

Get the shape of a value as an integer vector c(nrow, ncol)

Description

Get the shape of a value as an integer vector c(nrow, ncol)

Usage

intf_shape(val)

Arguments

Value

Integer vector of length 2

Determine the sign of a numeric value

Description

Determine the sign of a numeric value

Usage

intf_sign(val)

Arguments

Value

List with is_nonneg (logical) and is_nonpos (logical)

Inverse position: x^{-1} (for x > 0)

Description

Inverse position: x^{-1} (for x > 0)

Usage

inv_pos(x)

Arguments

Value

A Power atom with p=-1

Reciprocal of product of entries

Description

Computes the reciprocal of the product of entries. Equivalent to geo_mean(x)^(-n) where n is the number of entries.

Usage

inv_prod(x, approx = TRUE)

Arguments

Value

A convex Expression representing the reciprocal product.

Check if an Expression is Affine

Description

Check if an Expression is Affine

Usage

is_affine(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Concave

Description

Check if Atom is Concave

Usage

is_atom_concave(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Convex

Description

Check if Atom is Convex

Usage

is_atom_convex(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Log-Log Concave

Description

Check if Atom is Log-Log Concave

Usage

is_atom_log_log_concave(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Log-Log Convex

Description

Check if Atom is Log-Log Convex

Usage

is_atom_log_log_convex(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Quasiconcave

Description

Check if Atom is Quasiconcave

Usage

is_atom_quasiconcave(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Quasiconvex

Description

Check if Atom is Quasiconvex

Usage

is_atom_quasiconvex(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Complex

Description

Check if Expression is Complex

Usage

is_complex(x, ...)

Arguments

Value

Logical scalar.

Check if an Expression is Concave

Description

Check if an Expression is Concave

Usage

is_concave(x, ...)

Arguments

Value

Logical scalar.

Check if an Expression is Constant

Description

Check if an Expression is Constant

Usage

is_constant(x, ...)

Arguments

Value

Logical scalar.

Check if an Expression is Convex

Description

Check if an Expression is Convex

Usage

is_convex(x, ...)

Arguments

Value

Logical scalar.

Check if an Expression is DCP-Compliant

Description

Tests whether an expression follows the Disciplined Convex Programming (DCP) rules.

Usage

is_dcp(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Decreasing in an Argument

Description

Check if Atom is Decreasing in an Argument

Usage

is_decr(x, idx, ...)

Arguments

Value

Logical scalar.

Check if a Constraint is DGP-Compliant

Description

Check if a Constraint is DGP-Compliant

Usage

is_dgp(x, ...)

Arguments

Value

Logical scalar.

Check DPP Compliance

Description

Determines whether an expression or problem satisfies the rules of Disciplined Parameterized Programming (DPP). A DPP-compliant problem enables caching the compilation across parameter value changes.

Usage

is_dpp(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is DQCP-Compliant

Description

Tests whether an expression follows the Disciplined Quasiconvex Programming (DQCP) rules.

Usage

is_dqcp(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Hermitian

Description

Check if Expression is Hermitian

Usage

is_hermitian(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Imaginary

Description

Check if Expression is Imaginary

Usage

is_imag(x, ...)

Arguments

Value

Logical scalar.

Check if Atom is Increasing in an Argument

Description

Check if Atom is Increasing in an Argument

Usage

is_incr(x, idx, ...)

Arguments

Value

Logical scalar.

Check if Expression is Log-Log Affine

Description

Check if Expression is Log-Log Affine

Usage

is_log_log_affine(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Log-Log Concave

Description

Check if Expression is Log-Log Concave

Usage

is_log_log_concave(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Log-Log Convex

Description

Check if Expression is Log-Log Convex

Usage

is_log_log_convex(x, ...)

Arguments

Value

Logical scalar.

Check if a Problem is a Linear Program

Description

Check if a Problem is a Linear Program

Usage

is_lp(x, ...)

Arguments

Value

Logical scalar.

Is the Expression a Matrix?

Description

Returns TRUE if the expression has both dimensions greater than 1.

Usage

is_matrix(x)

Arguments

Value

Logical.

See Also

size(), is_scalar(), is_vector()

Check if a Problem is Mixed-Integer

Description

Returns TRUE if any variable in the problem has a boolean or integer attribute.

Usage

is_mixed_integer(problem)

Arguments

Value

Logical scalar.

Check if Expression is Non-Negative

Description

Check if Expression is Non-Negative

Usage

is_nonneg(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Non-Positive

Description

Check if Expression is Non-Positive

Usage

is_nonpos(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Negative Semidefinite

Description

Check if Expression is Negative Semidefinite

Usage

is_nsd(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Parameter-Affine

Description

Returns TRUE if the expression is affine in parameters and contains no decision variables.

Usage

is_param_affine(expr)

Arguments

Value

Logical scalar.

Check if Expression is Parameter-Free

Description

Returns TRUE if the expression contains no parameters.

Usage

is_param_free(expr)

Arguments

Value

Logical scalar.

Check if Expression is Strictly Positive

Description

Check if Expression is Strictly Positive

Usage

is_pos(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Positive Semidefinite

Description

Check if Expression is Positive Semidefinite

Usage

is_psd(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Piecewise Linear

Description

Check if Expression is Piecewise Linear

Is the Expression Piecewise Linear?

Usage

is_pwl(x, ...)

Arguments

Value

Logical scalar.

Logical.

Check if a Problem is a Quadratic Program

Description

Check if a Problem is a Quadratic Program

Usage

is_qp(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Quadratic or Piecewise Affine

Description

Check if Expression is Quadratic or Piecewise Affine

Usage

is_qpwa(x, ...)

Arguments

Value

Logical scalar.

Check if an Expression is Quadratic

Description

Check if an Expression is Quadratic

Usage

is_quadratic(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Quasiconcave

Description

Check if Expression is Quasiconcave

Usage

is_quasiconcave(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Quasiconvex

Description

Check if Expression is Quasiconvex

Usage

is_quasiconvex(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Quasilinear

Description

Check if Expression is Quasilinear

Usage

is_quasilinear(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Real

Description

Check if Expression is Real

Usage

is_real(x, ...)

Arguments

Value

Logical scalar.

Is the Expression a Scalar?

Description

Is the Expression a Scalar?

Usage

is_scalar(x)

Arguments

Value

Logical.

See Also

size(), is_vector(), is_matrix()

Check if Expression is Skew-Symmetric

Description

Tests whether X + t(X) == 0 (real matrices only). CVXPY SOURCE: expression.py line 470-473

Usage

is_skew_symmetric(x, ...)

Arguments

Value

Logical scalar.

Check if Expression is Symmetric

Description

Check if Expression is Symmetric

Usage

is_symmetric(x, ...)

Arguments

Value

Logical scalar.

Is the Expression a Vector?

Description

Returns TRUE if the expression has at most one dimension greater than 1.

Usage

is_vector(x)

Arguments

Value

Logical.

See Also

size(), is_scalar(), is_matrix()

Check if Expression is Zero

Description

Check if Expression is Zero

Usage

is_zero(x, ...)

Arguments

Value

Logical scalar.

KL Divergence: x*log(x/y) - x + y

Description

KL Divergence: x*log(x/y) - x + y

Usage

kl_div(x, y)

Arguments

Value

A KlDiv atom

Kronecker product of two expressions

Description

Kronecker product of two expressions

Usage

kron(a, b)

Arguments

Value

A Kron atom

Maximum eigenvalue

Description

Maximum eigenvalue

Usage

lambda_max(A)

Arguments

Value

An expression representing the maximum eigenvalue of A

Minimum eigenvalue

Description

Minimum eigenvalue

Usage

lambda_min(A)

Arguments

Value

An expression representing the minimum eigenvalue of A

Sum of largest k eigenvalues

Description

Sum of largest k eigenvalues

Usage

lambda_sum_largest(A, k)

Arguments

Value

An expression representing the sum of the k largest eigenvalues

Sum of smallest k eigenvalues

Description

Sum of smallest k eigenvalues

Usage

lambda_sum_smallest(A, k)

Arguments

Value

An expression representing the sum of the k smallest eigenvalues

Length of a Vector (Last Nonzero Index)

Description

Returns the index of the last nonzero element of a vector (1-based). This atom is quasiconvex but NOT convex, so it can only be used in DQCP problems (solved with qcp = TRUE).

Usage

length_expr(x)

Arguments

Value

A Length expression (scalar).

See Also

ceil_expr, floor_expr

Append a child LinOp to the args list

Description

Append a child LinOp to the args list

Usage

linop_args_push_back(ptr, child_ptr)

Arguments

Create a new C++ LinOp external pointer

Description

Create a new C++ LinOp external pointer

Usage

linop_new()

Value

An external pointer to a C++ LinOp object.

Set the data dimensionality on a LinOp

Description

Set the data dimensionality on a LinOp

Usage

linop_set_data_ndim(ptr, value)

Arguments

Set dense data on a LinOp

Description

Set dense data on a LinOp

Usage

linop_set_dense_data(ptr, value)

Arguments

Set a LinOp data sub-tree on a LinOp

Description

Set a LinOp data sub-tree on a LinOp

Usage

linop_set_linop_data(ptr, data_ptr)

Arguments

Set sparse data on a LinOp

Description

Set sparse data on a LinOp

Usage

linop_set_sparse_data(ptr, value)

Arguments

Set the type of a LinOp

Description

Set the type of a LinOp

Usage

linop_set_type(ptr, type)

Arguments

Push a dimension to the LinOp size vector

Description

Push a dimension to the LinOp size vector

Usage

linop_size_push_back(ptr, value)

Arguments

Push a slice (index vector) to a LinOp

Description

Push a slice (index vector) to a LinOp

Usage

linop_slice_push_back(ptr, int_vector)

Arguments

Log(1 + x) – elementwise

Description

Log(1 + x) – elementwise

Usage

log1p_atom(x)

log1p_expr(x)

Arguments

Value

A Log1p atom

Log-determinant

Description

Computes log(det(A)) for PSD matrix A.

Usage

log_det(A)

Arguments

Value

An expression representing log(det(A))

Elementwise log of the standard normal CDF

Description

Quadratic approximation of log(pnorm(x)) with modest accuracy over the range -4 to 4.

Usage

log_normcdf(x)

Arguments

Value

A concave Expression representing log(Phi(x)).

Log-sum-exp: log(sum(exp(x)))

Description

Log-sum-exp: log(sum(exp(x)))

Usage

log_sum_exp(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A LogSumExp atom

Elementwise log of the gamma function

Description

Piecewise linear approximation of log(gamma(x)). Has modest accuracy over the full range, approaching perfect accuracy as x goes to infinity.

Usage

loggamma(x)

Arguments

Value

A convex Expression representing log(gamma(x)).

Logistic function: log(1 + exp(x)) – elementwise

Description

Logistic function: log(1 + exp(x)) – elementwise

Usage

logistic(x)

Arguments

Value

A Logistic atom

Make a CSC sparse diagonal matrix

Description

Make a CSC sparse diagonal matrix

Usage

make_sparse_diagonal_matrix(size, diagonal = NULL)

Arguments

Value

a compressed sparse column diagonal matrix

Standard R Functions for CVXR Expressions

Description

CVXR registers methods so that standard R functions create the appropriate atoms when applied to Expression objects.

For CVXR expressions, computes the matrix/vector norm atom. For other inputs, falls through to norm.

For CVXR expressions, computes the standard deviation atom (ddof=0 by default, matching CVXPY/numpy convention). For numeric inputs, falls through to sd.

For CVXR expressions, computes the variance atom (ddof=0 by default). For numeric inputs, falls through to var.

For CVXR expressions, computes the outer product of two vectors. For other inputs, falls through to outer.

Usage

norm(x, type = "2", ...)

sd(x, ...)

var(x, ...)

outer(X, Y, ...)

Arguments

Value

An Expression or numeric value.

An Expression or numeric value.

An Expression or numeric value.

An Expression or matrix.

Math group (elementwise, via S3 group generic)

abs(x)

Absolute value (convex, nonneg)

exp(x)

Exponential (convex, positive)

log(x)

Natural logarithm (concave, domain x >= 0)

sqrt(x)

Square root via power(x, 0.5) (concave)

log1p(x)

log(1+x) compound expression (concave)

log2(x), log10(x)

Base-2/10 logarithm

cumsum(x)

Cumulative sum (affine)

cummax(x)

Cumulative max (convex)

cumprod(x)

Cumulative product

ceiling(x), floor(x)

Round up/down (MIP)

Summary group (via S3 group generic)

sum(x)

Sum all entries (affine)

max(x)

Maximum entry (convex)

min(x)

Minimum entry (concave)

S3 generic methods

mean(x)

Arithmetic mean; pass axis/keepdims via ...

diff(x)

First-order differences; also cvxr_diff

Masking wrappers

These mask the base/stats versions and dispatch on argument type:

norm(x)

2-norm; use type for "1", "I" (infinity), "F" (Frobenius)

sd(x)

Standard deviation (ddof=0 for expressions)

var(x)

Variance (ddof=0 for expressions)

outer(X, Y)

Outer product of two vector expressions

Advanced usage

For axis-aware reductions, keepdims, or other options not available through the standard interface, use the explicit functions: cvxr_norm, cvxr_mean, cvxr_diff, cvxr_std, cvxr_var, cvxr_outer.

See Also

power, sum_entries, max_entries, min_entries

cvxr_norm for the full-featured version with axis and keepdims arguments

cvxr_std for the full-featured version

cvxr_var for the full-featured version

cvxr_outer for the CVXR-specific version

Matrix fractional function

Description

Computes \mathrm{trace}(X^T P^{-1} X). If P is a constant matrix, uses a QuadForm shortcut for efficiency.

Usage

matrix_frac(X, P)

Arguments

Value

An expression representing \mathrm{trace}(X^T P^{-1} X)

Trace of a square matrix expression

Description

Trace of a square matrix expression

Usage

matrix_trace(x)

Arguments

Value

A Trace atom (scalar)

Elementwise maximum of expressions

Description

Elementwise maximum of expressions

Usage

max_elemwise(...)

Arguments

Value

A Maximum atom

Maximum entry of an expression

Description

Maximum entry of an expression

Usage

max_entries(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A MaxEntries atom

Elementwise minimum of expressions

Description

Elementwise minimum of expressions

Usage

min_elemwise(...)

Arguments

Value

A Minimum atom

Minimum entry of an expression

Description

Minimum entry of an expression

Usage

min_entries(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A MinEntries atom

Mixed norm (L_{p,q} norm): column-wise p-norm, then q-norm

Description

Mixed norm (L_{p,q} norm): column-wise p-norm, then q-norm

Usage

mixed_norm(X, p = 2, q = 1)

Arguments

Value

An Expression representing the mixed norm

Sign of a product of two expressions

Description

Determines whether the product of two expressions is nonnegative, nonpositive, or unknown, using the sign multiplication table.

Usage

mul_sign(lh_expr, rh_expr)

Arguments

Value

Named logical vector c(is_nonneg, is_nonpos)

Elementwise multiplication (deprecated)

Description

Usage

multiply(x, y)

Arguments

Details

Use the * operator instead: x * y.

Value

An Expression representing the elementwise product.

Get Expression Name

Description

Returns a human-readable string representation of a CVXR expression, variable, or constraint.

Usage

name(x)

Arguments

Value

A character string.

Examples

x <- Variable(2, name = "x")
name(x)  # "x"
name(x + 1)  # "x + 1"

Negative part: -min(x, 0)

Description

Negative part: -min(x, 0)

Usage

neg(x)

Arguments

Value

A negated Minimum atom

L1 norm of an expression

Description

L1 norm of an expression

Usage

norm1(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A Norm1 atom

Euclidean norm (deprecated alias)

Description

Usage

norm2(x)

Arguments

Details

Use p_norm(x, 2) instead.

Value

An Expression representing the L2 norm.

See Also

p_norm()

L-infinity norm of an expression

Description

L-infinity norm of an expression

Usage

norm_inf(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A NormInf atom

Nuclear norm (sum of singular values)

Description

Nuclear norm (sum of singular values)

Usage

norm_nuc(A)

Arguments

Value

An expression representing the nuclear norm of A

Get the Number of Cones in a Constraint

Description

Get the Number of Cones in a Constraint

Usage

num_cones(x, ...)

Arguments

Value

Integer.

Compute the Numeric Value of an Atom

Description

Compute the Numeric Value of an Atom

Usage

numeric_value(x, values, ...)

Arguments

Value

Numeric value.

Get Problem Objective (read-only)

Description

Returns the problem's objective.

Usage

objective(x)

Arguments

Details

Problem objects are immutable: the objective cannot be modified after construction. To change the objective, create a new Problem().

Value

A Minimize or Maximize object.

See Also

Problem(), constraints()

Examples

x <- Variable(2)
prob <- Problem(Minimize(sum_entries(x)), list(x >= 1))
objective(prob)

The difference 1 - x with domain (0, 1)

Description

Log-log concave atom for DGP. Solve with psolve(problem, gp = TRUE).

Usage

one_minus_pos(x)

Arguments

Value

A OneMInusPos atom

Examples

x <- Variable(pos = TRUE)
prob <- Problem(Maximize(one_minus_pos(x)), list(x >= 0.1, x <= 0.5))
## Not run: psolve(prob, gp = TRUE)

General p-norm of an expression

Description

General p-norm of an expression

Usage

p_norm(
  x,
  p = 2,
  axis = NULL,
  keepdims = FALSE,
  max_denom = 1024L,
  approx = TRUE
)

Arguments

Value

A Pnorm, PnormApprox, Norm1, or NormInf atom

Get the Parameters in an Expression

Description

Get the Parameters in an Expression

Usage

parameters(x, ...)

Arguments

Value

List of Parameter objects.

Partial trace of a tensor product expression

Description

Assumes expr is a 2D square matrix representing a Kronecker product of length(dims) subsystems. Returns the partial trace over the subsystem at index axis (1-indexed).

Usage

partial_trace(expr, dims, axis = 1L)

Arguments

Value

An Expression representing the partial trace

Partial transpose of a tensor product expression

Description

Assumes expr is a 2D square matrix representing a Kronecker product of length(dims) subsystems. Returns the partial transpose with the transpose applied to the subsystem at index axis (1-indexed).

Usage

partial_transpose(expr, dims, axis = 1L)

Arguments

Value

An Expression representing the partial transpose

Perspective Transform

Description

Creates the perspective transform of a scalar convex or concave expression. Given a scalar expression f(x) and a nonneg variable s, the perspective is s * f(x/s).

Usage

perspective(f, s, f_recession = NULL)

Arguments

Value

A Perspective expression.

Perron-Frobenius eigenvalue of a positive matrix

Description

Log-log convex atom for DGP. Solve with psolve(problem, gp = TRUE).

Usage

pf_eigenvalue(X)

Arguments

Value

A PfEigenvalue atom (scalar)

Examples

X <- Variable(c(2, 2), pos = TRUE)
prob <- Problem(Minimize(pf_eigenvalue(X)),
                list(X[1,1] >= 0.1, X[2,2] >= 0.1))
## Not run: psolve(prob, gp = TRUE)

Positive part: max(x, 0)

Description

Positive part: max(x, 0)

Usage

pos(x)

Arguments

Value

A Maximum atom

Create a Power atom

Description

Create a Power atom

Usage

power(x, p, max_denom = 1024L, approx = TRUE)

Arguments

Value

A Power or PowerApprox atom

Note

sqrt(x) on a CVXR expression dispatches to Power(x, 0.5) via the Math group generic. See math_atoms for all standard R function dispatch.

Get Problem Data for a Solver

Description

Returns the problem data that would be passed to a specific solver, along with the reduction chain and inverse data for solution retrieval.

Usage

problem_data(x, solver = NULL, ...)

Arguments

Value

A list with components data, chain, and inverse_data.

Get the Raw Solution Object (deprecated)

Description

Usage

problem_solution(x)

Arguments

Details

Use solution instead.

Value

A Solution object, or NULL if the problem has not been solved.

See Also

solution

Get the Solution Status of a Problem (deprecated)

Description

Usage

problem_status(x)

Arguments

Details

Use status instead.

Value

Character string, or NULL if the problem has not been solved.

See Also

status

Unpack Solver Results into a Problem

Description

Inverts the reduction chain and unpacks the raw solver solution into the original problem's variables and constraints. This is step 3 of the decomposed solve pipeline:

1. problem_data() – compile the problem

2. solve_via_data(chain, data) – call the solver

3. problem_unpack_results() – invert and unpack

Usage

problem_unpack_results(problem, solution, chain, inverse_data)

Arguments

Details

After calling this function, variable values are available via value() and constraint duals via dual_value().

Value

The problem object (invisibly), with solution unpacked.

See Also

problem_data, solve_via_data

Product of entries along an axis

Description

Used in DGP (geometric programming) context. Solve with psolve(problem, gp = TRUE).

Usage

prod_entries(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A Prod atom

Examples

x <- Variable(3, pos = TRUE)
prob <- Problem(Minimize(prod_entries(x)), list(x >= 2))
## Not run: psolve(prob, gp = TRUE)

Project a Value onto the Domain of a Leaf

Description

Project a Value onto the Domain of a Leaf

Usage

project(x, val, ...)

Arguments

Value

The projected value.

Solve a Convex Optimization Problem

Description

Solves the problem and returns the optimal objective value. After solving, variable values can be retrieved with value, constraint dual values with dual_value, and solver information with solver_stats.

Usage

psolve(
  problem,
  solver = NULL,
  gp = FALSE,
  qcp = FALSE,
  verbose = FALSE,
  warm_start = FALSE,
  feastol = NULL,
  reltol = NULL,
  abstol = NULL,
  num_iter = NULL,
  ...
)

Arguments

Value

The optimal objective value (numeric scalar), or Inf / -Inf for infeasible / unbounded problems.

See Also

Problem, status, solver_stats, solver_default_param

Examples

x <- Variable()
prob <- Problem(Minimize(x), list(x >= 5))
result <- psolve(prob, solver = "CLARABEL")

Peak-to-peak (range): max(x) - min(x)

Description

Computes the range of values along an axis: max(x) - min(x). The result is always nonnegative.

Usage

ptp(x, axis = NULL, keepdims = FALSE)

Arguments

Value

An Expression representing max(x) - min(x).

Quadratic form x^T P x

Description

When x is constant, returns t(Conj(x)) %*% P %*% x (affine in P). When P is constant, returns a QuadForm atom (quadratic in x). At least one of x or P must be constant.

Usage

quad_form(x, P, assume_PSD = FALSE)

Arguments

Value

A QuadForm atom or an affine Expression

Sum of squares divided by a scalar

Description

Sum of squares divided by a scalar

Usage

quad_over_lin(x, y, axis = NULL, keepdims = FALSE)

Arguments

Value

A QuadOverLin atom

Extract Real Part of Expression

Description

Returns the real part of a complex expression. R's native Re() dispatches here for CVXR expressions via the Complex S3 group handler.

Usage

real_expr(expr)

Arguments

Value

A Real_ atom.

Check if a Reduction Accepts a Problem

Description

Check if a Reduction Accepts a Problem

Usage

reduction_accepts(x, problem, ...)

Arguments

Value

Logical scalar.

Apply a Reduction to a Problem

Description

Apply a Reduction to a Problem

Usage

reduction_apply(x, problem, ...)

Arguments

Value

List with (new_problem, inverse_data).

Invert a Solution through a Reduction

Description

Invert a Solution through a Reduction

Usage

reduction_invert(x, solution, inverse_data, ...)

Arguments

Value

A solution to the original problem.

Relative Entropy: x*log(x/y)

Description

Relative Entropy: x*log(x/y)

Usage

rel_entr(x, y)

Arguments

Value

A RelEntr atom

Reshape an expression to a new shape

Description

Reshape an expression to a new shape

Usage

reshape_expr(x, dim, order = "F")

Arguments

Value

A Reshape expression.

Get the Residual of a Constraint

Description

Returns the residual of a constraint, measuring how much the constraint is violated or satisfied.

Usage

residual(x, ...)

Arguments

Value

Numeric array, or NULL if expression has no value.

Resolvent inverse(sI - X)

Description

Equivalent to (1/s) * eye_minus_inv(X / s).

Usage

resolvent(X, s)

Arguments

Value

An expression for the resolvent

Save Dual Variable Values from Solver Output

Description

Save Dual Variable Values from Solver Output

Usage

save_dual_value(x, val)

Arguments

Value

Invisible constraint (side effect: sets dual variable values).

Scalar product (alias for vdot)

Description

Scalar product (alias for vdot)

Usage

scalar_product(x, y)

Arguments

Value

A scalar Expression representing sum(x * y).

Scalene penalty: alpha * pos(x) + beta * neg(x)

Description

Scalene penalty: alpha * pos(x) + beta * neg(x)

Usage

scalene(x, alpha, beta)

Arguments

Value

An Expression representing the scalene penalty

Set a Label on a Constraint

Description

Attaches a human-readable label to a constraint for use in visualizations and pretty-printing. Labels are visualization-only and never affect the solver pipeline.

Usage

set_label(constraint, label)

Arguments

Details

Because R uses copy-on-modify semantics, you must either assign the result back or use set_label fluently when building constraint lists.

Value

The modified constraint (invisibly).

Examples

## Not run: 
x <- Variable(3, name = "x")

# Assign back
con <- (x >= 0)
con <- set_label(con, "non-negativity")

# Fluent use in constraint lists
constraints <- list(
  set_label(x >= 1, "lower bound"),
  set_label(sum_entries(x) <= 10, "budget")
)

## End(Not run)

Infer Shape from Arguments

Description

Infer Shape from Arguments

Usage

shape_from_args(x, ...)

Arguments

Value

Integer vector of shape dimensions.

Maximum singular value

Description

Maximum singular value

Usage

sigma_max(A)

Arguments

Value

An expression representing the maximum singular value of A

Infer Sign from Arguments

Description

Infer Sign from Arguments

Usage

sign_from_args(x, ...)

Arguments

Value

Character string: sign constant.

Get Expression Size

Description

Returns the total number of elements in the expression.

Usage

size(x)

Arguments

Value

An integer (product of shape dimensions).

See Also

is_scalar(), is_vector(), is_matrix()

Smith Form Annotation for an Expression Node

Description

Returns LaTeX-math annotation data for visualizing the canonicalization pipeline. Each atom class can override this to provide a custom LaTeX name, definition, and conic form. The default stub auto-generates from class metadata.

Usage

smith_annotation(expr, aux_var = "t", child_vars = character(0), ...)

Arguments

Value

A list with components: latex_name, latex_definition, conic, doc_topic, developer.

Get the Raw Solution Object

Description

Returns the raw Solution object from the most recent solve, containing primal and dual variable values, status, and solver attributes.

Usage

solution(x)

Arguments

Value

A Solution object, or NULL if the problem has not been solved.

Solve via Raw Data

Description

Calls the solver on pre-compiled problem data (step 2 of the decomposed solve pipeline). Dispatches on x: when x is a SolvingChain, delegates to the terminal solver with proper cache management.

Usage

solve_via_data(
  x,
  data,
  warm_start = FALSE,
  verbose = FALSE,
  solver_opts = list(),
  ...
)

Arguments

Value

Solver-specific result (a named list).

See Also

problem_data, problem_unpack_results

Solver Name Constants

Description

Character string constants identifying the available solvers.

Usage

SCS_SOLVER

OSQP_SOLVER

CLARABEL_SOLVER

HIGHS_SOLVER

MOSEK_SOLVER

GUROBI_SOLVER

GLPK_SOLVER

GLPK_MI_SOLVER

ECOS_SOLVER

ECOS_BB_SOLVER

CPLEX_SOLVER

CVXOPT_SOLVER

PIQP_SOLVER

Format

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 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.

Value

A character string.

Standard Solver Parameter Mappings

Description

Returns a named list mapping standard CVXR parameter names (reltol, abstol, feastol, num_iter) to solver-specific parameter names and their default values. Used internally by psolve to translate standard parameters into solver-native names.

Usage

solver_default_param()

Value

A named list keyed by solver name (e.g. "CLARABEL", "OSQP"). Each element is a list of standard parameter mappings, where each mapping has name (solver-native parameter name) and value (default value).

See Also

psolve

Get Solver Name

Description

Get Solver Name

Usage

solver_name(x, ...)

Arguments

Value

Character string with solver name.

Get Solver Statistics

Description

Returns solver statistics from the most recent solve, including solve time, setup time, and iteration count.

Usage

solver_stats(x)

Arguments

Value

A SolverStats object, or NULL if the problem has not been solved.

Square of an expression: x^2

Description

Square of an expression: x^2

Usage

square(x)

Arguments

Value

A Power atom with p=2

Get the Solution Status of a Problem

Description

Returns the status string from the most recent solve, such as "optimal", "infeasible", or "unbounded".

Usage

status(x)

Arguments

Value

Character string, or NULL if the problem has not been solved.

See Also

OPTIMAL, INFEASIBLE, UNBOUNDED

Solution Status Constants

Description

Character string constants representing the possible solution statuses returned by problem_status.

Usage

OPTIMAL

INFEASIBLE

UNBOUNDED

SOLVER_ERROR

OPTIMAL_INACCURATE

INFEASIBLE_INACCURATE

UNBOUNDED_INACCURATE

USER_LIMIT

INFEASIBLE_OR_UNBOUNDED

Format

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 1.

An object of class character of length 1.

Value

A character string.

See Also

status, psolve

Sum the entries of an expression

Description

Sum the entries of an expression

Usage

sum_entries(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A SumEntries expression.

Sum of k largest entries

Description

Sum of k largest entries

Usage

sum_largest(x, k)

Arguments

Value

A SumLargest atom

Sign of a sum of expressions

Description

Determines whether the sum of a list of expressions is nonnegative, nonpositive, or unknown.

Usage

sum_signs(exprs)

Arguments

Value

Named logical vector c(is_nonneg, is_nonpos)

Sum of k smallest entries

Description

Sum of k smallest entries

Usage

sum_smallest(x, k)

Arguments

Value

An Expression equal to -SumLargest(-x, k)

Sum of squares (= quad_over_lin(x, 1))

Description

Sum of squares (= quad_over_lin(x, 1))

Usage

sum_squares(x, axis = NULL, keepdims = FALSE)

Arguments

Value

A QuadOverLin atom

Convert CVXR Object to LaTeX

Description

Renders a CVXR Problem, Expression, or Constraint as a LaTeX string. Problem-level output uses the optidef package (mini*/maxi* environments) and atom macros from dcp.sty (shipped as system.file("sty", "dcp.sty", package = "CVXR")).

Usage

to_latex(x, ...)

Arguments

Value

A character string containing LaTeX code.

Examples

x <- Variable(3, name = "x")
cat(to_latex(p_norm(x, 2)))
# \cvxnorm{x}_2

Total variation of a vector or matrix

Description

Computes total variation using L1 norm of discrete gradients for vectors and L2 norm of discrete gradients for matrices.

Usage

total_variation(value, ...)

Arguments

Value

An Expression representing the total variation

Trace of matrix inverse

Description

Computes \mathrm{tr}(X^{-1}) for PSD matrix X.

Usage

tr_inv(X)

Arguments

Value

An expression representing \mathrm{tr}(X^{-1})

Deep Copy of an Expression Tree

Description

Deep Copy of an Expression Tree

Usage

tree_copy(x, id_objects = NULL)

Arguments

Value

A deep copy of the entire expression tree.

Total variation (deprecated alias)

Description

Usage

tv(...)

Arguments

Details

Use total_variation() instead.

See Also

total_variation()

Unpack Results (backward-compatible alias)

Description

Usage

unpack_results(problem, solution, chain, inverse_data)

Arguments

Details

Use problem_unpack_results() instead. This alias exists for backward compatibility with older CVXR examples.

Value

The problem object (invisibly), with solution unpacked.

See Also

problem_unpack_results()

Update Parameters for DPP Fast Path

Description

Update Parameters for DPP Fast Path

Usage

update_parameters(x, problem, ...)

Arguments

Value

NULL (called for side effects).

Extract strict upper triangle of a square matrix

Description

Extract strict upper triangle of a square matrix

Usage

upper_tri(x)

Arguments

Value

An UpperTri atom (column vector)

Validate Arguments to an Atom

Description

Validate Arguments to an Atom

Usage

validate_arguments(x, ...)

Arguments

Value

Invisible NULL (or error if invalid).

Get the Numeric Value of an Expression

Description

Returns the numeric value of a CVXR expression, variable, or constant. For variables, the value is set after solving a problem.

Usage

value(x, ...)

Arguments

Value

A numeric matrix, or NULL if no value has been set.

Set the Value of a Leaf Expression

Description

Assigns a numeric value to a Variable or Parameter.

Usage

value(x) <- value

Arguments

Value

The modified object (invisibly).

Get the Variables in an Expression

Description

Get the Variables in an Expression

Usage

variables(x, ...)

Arguments

Value

List of Variable objects.

Vector dot product (inner product)

Description

Computes the inner product: sum of element-wise products after flattening. Returns a scalar expression.

Usage

vdot(x, y)

Arguments

Value

A scalar Expression representing sum(x * y).

Vectorize an expression (column vector)

Description

Reshapes an expression into a column vector of shape (n*m, 1).

Usage

vec(x)

Arguments

Value

A Reshape atom (column vector).

Reshape a vector into an upper triangular matrix

Description

Inverts upper_tri. Takes a flat vector and returns an upper triangular matrix (row-major order, matching CVXPY convention).

Usage

vec_to_upper_tri(expr, strict = FALSE)

Arguments

Value

An Expression representing the upper triangular matrix.

Get the Violation of a Constraint

Description

Returns the scalar violation (distance to feasibility) of a constraint.

Usage

violation(x, ...)

Arguments

Value

Numeric scalar.

Visualize the Canonicalization Pipeline of a CVXR Problem

Description

Displays the Smith form decomposition of a convex optimization problem, showing each stage of the DCP canonicalization pipeline: expression tree, Smith form, relaxed Smith form, conic form, and (optionally) standard cone form and solver data.

Usage

visualize(
  problem,
  output = c("text", "json", "html", "latex", "tikz"),
  solver = NULL,
  digits = 4L,
  file = NULL,
  open = interactive(),
  doc_base = "https://cvxr.rbind.io/reference/"
)

Arguments

Value

For "text": invisible model list. For "json": a JSON string (or list if jsonlite not available). For "html": the file path (invisibly). For other formats: the rendered output (Phase 2+).

Examples

## Not run: 
x <- Variable(3, name = "x")
prob <- Problem(Minimize(p_norm(x, 2)), list(x >= 1))
visualize(prob)                          # Stages 0-3 only
visualize(prob, solver = TRUE)           # Stages 0-5, default solver
visualize(prob, solver = "Clarabel")     # Stages 0-5, specific solver
visualize(prob, output = "html", solver = TRUE)

## End(Not run)

Vertical concatenation of expressions

Description

Vertical concatenation of expressions

Usage

vstack(...)

Arguments

Value

A VStack atom

Execute Expression Within DPP Scope

Description

Within this scope, Parameter objects are treated as affine (not constant) for curvature analysis. This is used internally by is_dpp() to check DPP compliance.

Usage

with_dpp_scope(expr)

Arguments

Value

The result of evaluating expr.

x * exp(x) – elementwise

Description

x * exp(x) – elementwise

Usage

xexp(x)

Arguments

Value

An Xexp atom