This action might not be possible to undo. Are you sure you want to continue?

# cvx Users’ Guide

**for cvx version 1.21
**

∗

Michael Grant

mcgrant@stanford.edu

Stephen Boyd

boyd@stanford.edu

April, 2011

∗

code commit 808, 2011-04-17 21:43:47; doc commit 806, 2011-02-25 11:00:44

1

Contents

1 Introduction 4

1.1 What is cvx? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2 What is disciplined convex programming? . . . . . . . . . . . . . . . 5

1.3 About this version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4 Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.5 What cvx is not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 A quick start 8

2.1 Least-squares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.2 Bound-constrained least-squares . . . . . . . . . . . . . . . . . . . . . 10

2.3 Other norms and functions . . . . . . . . . . . . . . . . . . . . . . . . 11

2.4 Other constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.5 An optimal trade-oﬀ curve . . . . . . . . . . . . . . . . . . . . . . . . 15

3 The basics 17

3.1 cvx begin and cvx end . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.2 Data types for variables . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.3 Objective functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.4 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.6 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.7 Dual variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.8 Expression holders . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4 The DCP ruleset 25

4.1 A taxonomy of curvature . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.2 Top-level rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.3 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.4 Expression rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.6 Compositions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.7 Monotonicity in nonlinear compositions . . . . . . . . . . . . . . . . . 31

4.8 Scalar quadratic forms . . . . . . . . . . . . . . . . . . . . . . . . . . 32

5 Adding new functions to the cvx atom library 34

5.1 New functions via the DCP ruleset . . . . . . . . . . . . . . . . . . . 34

5.2 New functions via partially speciﬁed problems . . . . . . . . . . . . . 35

6 Semideﬁnite programming using cvx 39

7 Geometric programming using cvx 41

7.1 Top-level rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

7.2 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7.3 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

2

8 Advanced topics 44

8.1 Solver selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

8.2 Controlling solver precision . . . . . . . . . . . . . . . . . . . . . . . . 44

8.3 Miscellaneous cvx commands . . . . . . . . . . . . . . . . . . . . . . 46

8.4 Assignments versus equality constraints . . . . . . . . . . . . . . . . . 47

8.5 Indexed dual variables . . . . . . . . . . . . . . . . . . . . . . . . . . 48

A Installation and compatibility 51

A.1 Basic instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

A.2 About SeDuMi and SDPT3 . . . . . . . . . . . . . . . . . . . . . . . 52

A.3 A Matlab 7.0 issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

B Operators, functions, and sets 54

B.1 Basic operators and linear functions . . . . . . . . . . . . . . . . . . . 54

B.2 Nonlinear functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

B.3 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

C cvx status messages 63

D Advanced solver topics 65

D.1 The successive approximation method . . . . . . . . . . . . . . . . . . 65

D.2 Irrational powers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

D.3 Overdetermined problems . . . . . . . . . . . . . . . . . . . . . . . . 66

E Acknowledgements 67

3

1 Introduction

1.1 What is cvx?

cvx is a modeling system for disciplined convex programming. Disciplined convex pro-

grams, or DCPs, are convex optimization problems that are described using a limited

set of construction rules, which enables them to be analyzed and solved eﬃciently.

cvx can solve standard problems such as linear programs (LPs), quadratic programs

(QPs), second-order cone programs (SOCPs), and semideﬁnite programs (SDPs);

but compared to directly using a solver for one or these types of problems, cvx can

greatly simplify the task of specifying the problem. cvx can also solve much more

complex convex optimization problems, including many involving nondiﬀerentiable

functions, such as

1

norms. You can use cvx to conveniently formulate and solve

constrained norm minimization, entropy maximization, determinant maximization,

and many other problems.

To use cvx eﬀectively, you need to know at least a bit about convex optimiza-

tion. For background on convex optimization, see the book Convex Optimization

[BV04], available on-line at www.stanford.edu/

∼

boyd/cvxbook/, or the Stanford

course EE364A, available at www.stanford.edu/class/ee364a/.

cvx is implemented in Matlab [Mat04], eﬀectively turning Matlab into an op-

timization modeling language. Model speciﬁcations are constructed using common

Matlab operations and functions, and standard Matlab code can be freely mixed with

these speciﬁcations. This combination makes it simple to perform the calculations

needed to form optimization problems, or to process the results obtained from their

solution. For example, it is easy to compute an optimal trade-oﬀ curve by forming

and solving a family of optimization problems by varying the constraints. As another

example, cvx can be used as a component of a larger system that uses convex opti-

mization, such as a branch and bound method, or an engineering design framework.

cvx also provides special modes to simplify the construction of problems from two

speciﬁc problem classes. In SDP mode, cvx applies a matrix interpretation to the

inequality operator, so that linear matrix inequalities (LMIs) and SDPs may be ex-

pressed in a more natural form. In GP mode, cvx accepts all of the special functions

and combination rules of geometric programming, including monomials, posynomi-

als, and generalized posynomials, and transforms such problems into convex form

so that they can be solved eﬃciently. For background on geometric programming,

see the tutorial paper [BKVH05], available at www.stanford.edu/

∼

boyd/papers/

gp tutorial.html.

cvx was designed by Michael Grant and Stephen Boyd, with input from Yinyu Ye;

and was implemented by Michael Grant [GBY06]. It incorporates ideas from earlier

work by L¨ofberg [L¨of05], Dahl and Vandenberghe [DV05], Crusius [Cru02], Wu and

Boyd [WB00], and many others. The modeling language follows the spirit of AMPL

[FGK99] or GAMS [BKMR98]; unlike these packages, however, cvx was designed

from the beginning to fully exploit convexity. The speciﬁc method for implementing

cvx in Matlab draws heavily from YALMIP [L¨of05]. We also hope to develop versions

of cvx for other platforms in the future.

4

1.2 What is disciplined convex programming?

Disciplined convex programming is a methodology for constructing convex optimiza-

tion problems proposed by Michael Grant, Stephen Boyd, and Yinyu Ye [GBY06,

Gra04]. It is meant to support the formulation and construction of optimization

problems that the user intends from the outset to be convex. Disciplined convex

programming imposes a set of conventions or rules, which we call the DCP ruleset.

Problems which adhere to the ruleset can be rapidly and automatically veriﬁed as

convex and converted to solvable form. Problems that violate the ruleset are rejected,

even when the problem is convex. That is not to say that such problems cannot be

solved using DCP; they just need to be rewritten in a way that conforms to the DCP

ruleset.

A detailed description of the DCP ruleset is given in '4, and it is important for

anyone who intends to actively use cvx to understand it. The ruleset is simple to

learn, and is drawn from basic principles of convex analysis. In return for accept-

ing the restrictions imposed by the ruleset, we obtain considerable beneﬁts, such as

automatic conversion of problems to solvable form, and full support for nondiﬀeren-

tiable functions. In practice, we have found that disciplined convex programs closely

resemble their natural mathematical forms.

1.3 About this version

Supported solvers. This version of cvx supports two core solvers, SeDuMi [Stu99]

and SDPT3 [TTT06], which is the default. Future versions of cvx may support other

solvers, such as MOSEK [MOS05] or CVXOPT [DV05]. SeDuMi and SDPT3 are

open-source interior-point solvers written in Matlab for LPs, SOCPs, SDPs, and

combinations thereof.

Problems handled exactly. cvx will convert the speciﬁed problem to an LP,

SOCP, or SDP, when all the functions in the problem speciﬁcation can be represented

in these forms. This includes a wide variety of functions, such as minimum and

maximum, absolute value, quadratic forms, the minimum and maximum eigenvalues

of a symmetric matrix, power functions x

p

, and

p

norms (both for p rational).

Problems handled with (good) approximations. For a few functions, cvx will

make a (good) approximation to transform the speciﬁed problem to one that can

be handled by a combined LP, SOCP, and SDP solver. For example, when a power

function or

p

-norm is used, with non-rational exponent p, cvx replaces p with a

nearby rational. The log of the normal cumulative distribution log Φ(x) is replaced

with an SDP-compatible approximation.

Problems handled with successive approximation. This version of cvx adds

support for a number of functions that cannot be exactly represented via LP, SOCP, or

SDP, including log, exp, log-sum-exp log(exp x

1

+ +exp x

n

), entropy, and Kullback-

Leibler divergence. These problems are handled by solving a sequence (typically just

5

a handful) of SDPs, which yields the solution to the full accuracy of the core solver.

On the other hand, this technique can be substantially slower than if the core solver

directly handled such functions. The successive approximation method is brieﬂy

described in Appendix D.1. Geometric problems are now solved in this manner as

well; in previous versions, an approximation was made.

Ultimately, we will interface cvx to a solver with native support for such functions,

which result in a large speedup in solving problems with these functions. Until then,

users should be aware that problems involving these functions can be slow to solve

using the current version of cvx. For this reason, when one of these functions is used,

the user will be warned that the successive approximate technique will be used.

We emphasize that most users do not need to know how cvx handles their problem;

what matters is what functions and operations can be handled. For a full list of

functions supported by cvx, see Appendix B, or use the online help function by

typing help cvx/builtins (for functions already in Matlab, such as sqrt or log) or

help cvx/functions (for functions not in Matlab, such as lambda_max).

1.4 Feedback

Please contact Michael Grant (mcgrant@stanford.edu) or Stephen Boyd (boyd@stanford.edu)

with your comments. If you discover what you think is a bug, please include the fol-

lowing in your communication, so we can reproduce and ﬁx the problem:

• the cvx model and supporting data that caused the error

• a copy of any error messages that it produced

• the cvx version number and build number

• the version number of Matlab that you are running

• the name and version of the operating system you are using

The latter three items can all be discovered by typing

cvx_version

at the MATLAB command prompt; simply copy its output into your email message.

1.5 What cvx is not

cvx is not meant to be a tool for checking if your problem is convex. You need

to know a bit about convex optimization to eﬀectively use cvx; otherwise you are

the proverbial monkey at the typewriter, hoping to (accidentally) type in a valid

disciplined convex program.

On the other hand, if cvx accepts your problem, you can be sure it is convex. In

conjunction with a course on (or self study of) convex optimization, cvx (especially,

its error messages) can be very helpful in learning some basic convex analysis. While

6

cvx will attempt to give helpful error messages when you violate the DCP ruleset, it

can sometimes give quite obscure error messages.

cvx is not meant for very large problems, so if your problem is very large (for

example, a large image processing problem), cvx is unlikely to work well (or at all).

For such problems you will likely need to directly call a solver, or to develop your

own methods, to get the eﬃciency you need.

For such problems cvx can play an important role, however. Before starting to

develop a specialized large-scale method, you can use cvx to solve scaled-down or

simpliﬁed versions of the problem, to rapidly experiment with exactly what problem

you want to solve. For image reconstruction, for example, you might use cvx to

experiment with diﬀerent problem formulations on 50 50 pixel images.

cvx will solve many medium and large scale problems, provided they have ex-

ploitable structure (such as sparsity), and you avoid for loops, which can be slow in

Matlab, and functions like log and exp that require successive approximation. If you

encounter diﬃculties in solving large problem instances, please do contact us; we may

be able to suggest an equivalent formulation that cvx can process more eﬃciently.

7

2 A quick start

Once you have installed cvx (see 'A), you can start using it by entering a cvx speci-

ﬁcation into a Matlab script or function, or directly from the command prompt. To

delineate cvx speciﬁcations from surrounding Matlab code, they are preceded with

the statement cvx_begin and followed with the statement cvx_end. A speciﬁcation

can include any ordinary Matlab statements, as well as special cvx-speciﬁc commands

for declaring primal and dual optimization variables and specifying constraints and

objective functions.

Within a cvx speciﬁcation, optimization variables have no numerical value; in-

stead, they are special Matlab objects. This enables Matlab to distinguish between

ordinary commands and cvx objective functions and constraints. As Matlab reads

a cvx speciﬁcation, it builds an internal representation of the optimization problem.

If it encounters a violation of the rules of disciplined convex programming (such as

an invalid use of a composition rule or an invalid constraint), an error message is

generated. When Matlab reaches the cvx_end command, it completes the conversion

of the cvx speciﬁcation to a canonical form, and calls the underlying core solver to

solve it.

If the optimization is successful, the optimization variables declared in the cvx

speciﬁcation are converted from objects to ordinary Matlab numerical values that

can be used in any further Matlab calculations. In addition, cvx also assigns a few

other related Matlab variables. One, for example, gives the status of the problem

(i.e., whether an optimal solution was found, or the problem was determined to be

infeasible or unbounded). Another gives the optimal value of the problem. Dual

variables can also be assigned.

This processing ﬂow will become more clear as we introduce a number of simple

examples. We invite the reader to actually follow along with these examples in Mat-

lab, by running the quickstart script found in the examples subdirectory of the cvx

distribution. For example, if you are on Windows, and you have installed the cvx

distribution in the directory D:\Matlab\cvx, then you would type

cd D:\Matlab\cvx\examples

quickstart

at the Matlab command prompt. The script will automatically print key excerpts of

its code, and pause periodically so you can examine its output. (Pressing “Enter” or

“Return” resumes progress.) The line numbers accompanying the code excerpts in

this document correspond to the line numbers in the ﬁle quickstart.m.

2.1 Least-squares

We ﬁrst consider the most basic convex optimization problem, least-squares. In a

least-squares problem, we seek x ∈ R

n

that minimizes |Ax − b|

2

, where A ∈ R

m×n

is skinny and full rank (i.e., m ≥ n and Rank(A) = n). Let us create some test

problem data for m, n, A, and b in Matlab:

8

15 m = 16; n = 8;

16 A = randn(m,n);

17 b = randn(m,1);

(We chose small values of m and n to keep the output readable.) Then the least-

squares solution x = (A

T

A)

−1

A

T

b is easily computed using the backslash operator:

20 x_ls = A \ b;

Using cvx, the same problem can be solved as follows:

23 cvx_begin

24 variable x(n);

25 minimize( norm(A*x-b) );

26 cvx_end

(The indentation is used for purely stylistic reasons and is optional.) Let us examine

this speciﬁcation line by line:

• Line 23 creates a placeholder for the new cvx speciﬁcation, and prepares Matlab

to accept variable declarations, constraints, an objective function, and so forth.

• Line 24 declares x to be an optimization variable of dimension n. cvx requires

that all problem variables be declared before they are used in an objective

function or constraints.

• Line 25 speciﬁes an objective function to be minimized; in this case, the Eu-

clidean or

2

-norm of Ax −b.

• Line 26 signals the end of the cvx speciﬁcation, and causes the problem to be

solved.

The backslash form is clearly simpler—there is no reason to use cvx to solve a simple

least-squares problem. But this example serves as sort of a “Hello world!” program

in cvx; i.e., the simplest code segment that actually does something useful.

If you were to type x at the Matlab prompt after line 24 but before the cvx_end

command, you would see something like this:

x =

cvx affine expression (8x1 vector)

That is because within a speciﬁcation, variables have no numeric value; rather, they

are Matlab objects designed to represent problem variables and expressions involving

them. Similarly, because the objective function norm(A*x-b) involves a cvx variable,

it does not have a numeric value either; it is also represented by a Matlab object.

When Matlab reaches the cvx_end command, the least-squares problem is solved,

and the Matlab variable x is overwritten with the solution of the least-squares prob-

lem, i.e., (A

T

A)

−1

A

T

b. Now x is an ordinary length-n numerical vector, identical to

what would be obtained in the traditional approach, at least to within the accuracy

of the solver. In addition, two additional Matlab variables are created:

9

• cvx_optval, which contains the value of the objective function; i.e., |Ax−b|

2

;

• cvx_status, which contains a string describing the status of the calculation. In

this case, cvx_status would contain the string Solved. See Appendix C for a

list of the possible values of cvx_status and their meaning.

• cvx_slvtol: the tolerance level achieved by the solver.

• cvx_slvitr: the number of iterations taken by the solver.

All of these quantities, x, cvx_optval, and cvx_status, etc. may now be freely used

in other Matlab statements, just like any other numeric or string values.

1

There is not much room for error in specifying a simple least-squares problem,

but if you make one, you will get an error or warning message. For example, if you

replace line 25 with

maximize( norm(A*x-b) );

which asks for the norm to be maximized, you will get an error message stating that

a convex function cannot be maximized (at least in disciplined convex programming):

??? Error using ==> maximize

Disciplined convex programming error:

Objective function in a maximization must be concave.

2.2 Bound-constrained least-squares

Suppose we wish to add some simple upper and lower bounds to the least-squares

problem above: i.e., we wish to solve

minimize |Ax −b|

2

subject to l _ x _ u,

(1)

where l and u are given data, vectors with the same dimension as the variable x. The

vector inequality u _ v means componentwise, i.e., u

i

≤ v

i

for all i. We can no longer

use the simple backslash notation to solve this problem, but it can be transformed

into a quadratic program (QP), which can be solved without diﬃculty if you have

some form of QP software available.

Let us provide some numeric values for l and u:

47 bnds = randn(n,2);

48 l = min( bnds, [], 2 );

49 u = max( bnds, [], 2 );

Then if you have the Matlab Optimization Toolbox [Mat05], you can use the quadprog

function to solve the problem as follows:

1

If you type who or whos at the command prompt, you may see other, unfamiliar variables as

well. Any variable that begins with the preﬁx cvx is reserved for internal use by cvx itself, and

should not be changed.

10

53 x_qp = quadprog( 2*A’*A, -2*A’*b, [], [], [], [], l, u );

This actually minimizes the square of the norm, which is the same as minimizing the

norm itself. In contrast, the cvx speciﬁcation is given by

59 cvx_begin

60 variable x(n);

61 minimize( norm(A*x-b) );

62 subject to

63 x >= l;

64 x <= u;

65 cvx_end

Three new lines of cvx code have been added to the cvx speciﬁcation:

• The subject to statement on line 62 does nothing—cvx provides this state-

ment simply to make speciﬁcations more readable. It is entirely optional.

• Lines 63 and 64 represent the 2n inequality constraints l _ x _ u.

As before, when the cvx_end command is reached, the problem is solved, and the

numerical solution is assigned to the variable x. Incidentally, cvx will not transform

this problem into a QP by squaring the objective; instead, it will transform it into an

SOCP. The result is the same, and the transformation is done automatically.

In this example, as in our ﬁrst, the cvx speciﬁcation is longer than the Matlab

alternative. On the other hand, it is easier to read the cvx version and relate it

to the original problem. In contrast, the quadprog version requires us to know in

advance the transformation to QP form, including the calculations such as 2*A’*A

and -2*A’*b. For all but the simplest cases, a cvx speciﬁcation is simpler, more

readable, and more compact than equivalent Matlab code to solve the same problem.

2.3 Other norms and functions

Now let us consider some alternatives to the least-squares problem. Norm minimiza-

tion problems involving the

∞

or

1

norms can be reformulated as LPs, and solved

using a linear programming solver such as linprog in the Matlab Optimization Tool-

box (see, e.g., [BV04, '6.1]). However, because these norms are part of cvx’s base

library of functions, cvx can handle these problems directly.

For example, to ﬁnd the value of x that minimizes the Chebyshev norm |Ax−b|

∞

,

we can employ the linprog command from the Matlab Optimization Toolbox:

97 f = [ zeros(n,1); 1 ];

98 Ane = [ +A, -ones(m,1) ; ...

99 -A, -ones(m,1) ];

100 bne = [ +b; -b ];

101 xt = linprog(f,Ane,bne);

102 x_cheb = xt(1:n,:);

11

With cvx, the same problem is speciﬁed as follows:

108 cvx_begin

109 variable x(n);

110 minimize( norm(A*x-b,Inf) );

111 cvx_end

The code based on linprog, and the cvx speciﬁcation above will both solve the

Chebyshev norm minimization problem, i.e., each will produce an x that minimizes

|Ax−b|

∞

. Chebyshev norm minimization problems can have multiple optimal points,

however, so the particular x’s produced by the two methods can be diﬀerent. The

two points, however, must have the same value of |Ax −b|

∞

.

Similarly, to minimize the

1

norm | |

1

, we can use linprog as follows:

139 f = [ zeros(n,1); ones(m,1); ones(m,1) ];

140 Aeq = [ A, -eye(m), +eye(m) ];

141 lb = [ -Inf(n,1); zeros(m,1); zeros(m,1) ];

142 xzz = linprog(f,[],[],Aeq,b,lb,[]);

143 x_l1 = xzz(1:n,:);

The cvx version is, not surprisingly,

149 cvx_begin

150 variable x(n);

151 minimize( norm(A*x-b,1) );

152 cvx_end

cvx automatically transforms both of these problems into LPs, not unlike those gen-

erated manually for linprog.

The advantage that automatic transformation provides is magniﬁed if we consider

functions (and their resulting transformations) that are less well-known than the

∞

and

1

norms. For example, consider the norm

|Ax −b|

lgst,k

= [Ax −b[

[1]

+ +[Ax −b[

[k]

,

where [Ax −b[

[i]

denotes the ith largest element of the absolute values of the entries

of Ax − b. This is indeed a norm, albeit a fairly esoteric one. (When k = 1, it

reduces to the

∞

norm; when k = m, the dimension of Ax − b, it reduces to the

1

norm.) The problem of minimizing |Ax − b|

lgst,k

over x can be cast as an LP, but

the transformation is by no means obvious so we will omit it here. But this norm is

provided in the base cvx library, and has the name norm_largest, so to specify and

solve the problem using cvx is easy:

179 k = 5;

180 cvx_begin

181 variable x(n);

182 minimize( norm_largest(A*x-b,k) );

183 cvx_end

12

Unlike the

1

,

2

, or

∞

norms, this norm is not part of the standard Matlab distri-

bution. Once you have installed cvx, though, the norm is available as an ordinary

Matlab function outside a cvx speciﬁcation. For example, once the code above is

processed, x is a numerical vector, so we can type

cvx_optval

norm_largest(A*x-b,k)

The ﬁrst line displays the optimal value as determined by cvx; the second recomputes

the same value from the optimal vector x as determined by cvx.

The list of supported nonlinear functions in cvx goes well beyond norm and

norm_largest. For example, consider the Huber penalty minimization problem

minimize

¸

m

i=1

φ((Ax −b)

i

),

with variable x ∈ R

n

, where φ is the Huber penalty function

φ(z) =

[z[

2

[z[ ≤ 1

2[z[ −1 [z[ ≥ 1.

The Huber penalty function is convex, and has been provided in the cvx function

library. So solving the Huber penalty minimization problem in cvx is simple:

204 cvx_begin

205 variable x(n);

206 minimize( sum(huber(A*x-b)) );

207 cvx_end

cvx automatically transforms this problem into an SOCP, which the core solver then

solves. (The cvx user, however, does not need to know how the transformation is

carried out.)

2.4 Other constraints

We hope that, by now, it is not surprising that adding the simple bounds l _ x _ u

to the problems in '2.3 above is as simple as inserting the lines

x >= l;

x <= u;

before the cvx_end statement in each cvx speciﬁcation. In fact, cvx supports more

complex constraints as well. For example, let us deﬁne new matrices C and d in

Matlab as follows,

227 p = 4;

228 C = randn(p,n);

229 d = randn(p,1);

13

Now let us add an equality constraint and a nonlinear inequality constraint to the

original least-squares problem:

232 cvx_begin

233 variable x(n);

234 minimize( norm(A*x-b) );

235 subject to

236 C*x == d;

237 norm(x,Inf) <= 1;

238 cvx_end

Both of the added constraints conform to the DCP rules, and so are accepted by cvx.

After the cvx_end command, cvx converts this problem to an SOCP, and solves it.

Expressions using comparison operators (==, >=, etc.) behave quite diﬀerently

when they involve cvx optimization variables, or expressions constructed from cvx

optimization variables, than when they involve simple numeric values. For example,

because x is a declared variable, the expression C*x==d in line 236 above causes a

constraint to be included in the cvx speciﬁcation, and returns no value at all. On the

other hand, outside of a cvx speciﬁcation, if x has an appropriate numeric value—

for example immediately after the cvx_end command—that same expression would

return a vector of 1s and 0s, corresponding to the truth or falsity of each equality.

2

Likewise, within a cvx speciﬁcation, the statement norm(x,Inf)<=1 adds a nonlinear

constraint to the speciﬁcation; outside of it, it returns a 1 or a 0 depending on the

numeric value of x (speciﬁcally, whether its

∞

-norm is less than or equal to, or more

than, 1).

Because cvx is designed to support convex optimization, it must be able to verify

that problems are convex. To that end, cvx adopts certain construction rules that

govern how constraint and objective expressions are constructed. For example, cvx

requires that the left- and right- hand sides of an equality constraint be aﬃne. So a

constraint such as

norm(x,Inf) == 1;

results in the following error:

??? Error using ==> cvx.eq

Disciplined convex programming error:

Both sides of an equality constraint must be affine.

Inequality constraints of the form f(x) ≤ g(x) or g(x) ≥ f(x) are accepted only if f

can be veriﬁed as convex and g veriﬁed as concave. So a constraint such as

norm(x,Inf) >= 1;

2

In fact, immediately after the cvx end command above, you would likely ﬁnd that most if not all

of the values returned would be 0. This is because, as is the case with many numerical algorithms,

solutions are determined only to within some nonzero numeric tolerance. So the equality constraints

will be satisﬁed closely, but often not exactly.

14

results in the following error:

??? Error using ==> cvx.ge

Disciplined convex programming error:

The left-hand side of a ">=" inequality must be concave.

The speciﬁcs of the construction rules are discussed in more detail in '4 below. These

rules are relatively intuitive if you know the basics of convex analysis and convex

optimization.

2.5 An optimal trade-oﬀ curve

For our ﬁnal example in this section, let us show how traditional Matlab code and

cvx speciﬁcations can be mixed to form and solve multiple optimization problems.

The following code solves the problem of minimizing |Ax − b|

2

+ γ|x|

1

, for a loga-

rithmically spaced vector of (positive) values of γ. This gives us points on the optimal

trade-oﬀ curve between |Ax − b|

2

and |x|

1

. An example of this curve is given in

Figure 1.

268 gamma = logspace( -2, 2, 20 );

269 l2norm = zeros(size(gamma));

270 l1norm = zeros(size(gamma));

271 fprintf( 1, ’ gamma norm(x,1) norm(A*x-b)\n’ );

272 fprintf( 1, ’---------------------------------------\n’ );

273 for k = 1:length(gamma),

274 fprintf( 1, ’%8.4e’, gamma(k) );

275 cvx_begin

276 variable x(n);

277 minimize( norm(A*x-b)+gamma(k)*norm(x,1) );

278 cvx_end

279 l1norm(k) = norm(x,1);

280 l2norm(k) = norm(A*x-b);

281 fprintf( 1, ’ %8.4e %8.4e\n’, l1norm(k), l2norm(k) );

282 end

283 plot( l1norm, l2norm );

284 xlabel( ’norm(x,1)’ );

285 ylabel( ’norm(A*x-b)’ );

286 grid

Line 277 of this code segment illustrates one of the construction rules to be dis-

cussed in '4 below. A basic principle of convex analysis is that a convex function

can be multiplied by a nonnegative scalar, or added to another convex function, and

the result is then convex. cvx recognizes such combinations and allows them to be

used anywhere a simple convex function can be—such as an objective function to be

minimized, or on the appropriate side of an inequality constraint. So in our example,

the expression

15

0 0.5 1 1.5 2 2.5 3 3.5

2

2.2

2.4

2.6

2.8

3

3.2

3.4

3.6

norm(x,1)

n

o

r

m

(

A

*

x

−

b

)

Figure 1: An example trade-oﬀ curve from the quickstart demo, lines 268-286.

norm(A*x-b)+gamma(k)*norm(x,1)

on line 277 is recognized as convex by cvx, as long as gamma(k) is positive or zero. If

gamma(k) were negative, then this expression becomes the sum of a convex term and

a concave term, which causes cvx to generate the following error:

??? Error using ==> cvx.plus

Disciplined convex programming error:

Addition of convex and concave terms is forbidden.

16

3 The basics

3.1 cvx begin and cvx end

All cvx models must be preceded by the command cvx_begin and terminated with

the command cvx_end. All variable declarations, objective functions, and constraints

should fall in between.

The cvx_begin command accepts several modiﬁers that you may ﬁnd useful.

For instance, cvx_begin quiet prevents the model from producing any screen out-

put while it is being solved. Additionally, cvx_begin sdp and cvx_begin gp in-

voke special semideﬁnite and geometric programming modes, discussed in '6 and

'7, respectively. These modiﬁers may be combined when appropriate; for instance,

cvx_begin sdp quiet invokes SDP mode and silences the solver output.

3.2 Data types for variables

As mentioned above, all variables must be declared using the variable command

(or the variables command; see below) before they can be used in constraints or an

objective function.

Variables can be real or complex; and scalar, vector, matrix, or n-dimensional

arrays. In addition, matrices can have structure as well, such as symmetry or band-

edness. The structure of a variable is given by supplying a list of descriptive keywords

after the name and size of the variable. For example, the code segment

variable w(50) complex;

variable X(20,10);

variable Y(50,50) symmetric;

variable Z(100,100) hermitian toeplitz;

(inside a cvx speciﬁcation) declares that w is a complex 50-element vector variable, X

is a real 2010 matrix variable, Y is a real 5050 symmetric matrix variable, and Z is

a complex 100100 Hermitian Toeplitz matrix variable. The structure keywords can

be applied to n-dimensional arrays as well: each 2-dimensional “slice” of the array is

given the stated structure. The currently supported structure keywords are:

banded(lb,ub) complex diagonal hankel hermitian lower_bidiagonal

lower_hessenberg lower_triangular scaled_identity skew_symmetric

symmetric toeplitz tridiagonal upper_bidiagonal upper_hankel

upper_hessenberg upper_triangular

With a couple of exceptions, the structure keywords are self-explanatory:

• banded(lb,ub): the matrix is banded with a lower bandwidth lb and an upper

bandwidth ub. If both lb and ub are zero, then a diagonal matrix results. ub

can be omitted, in which case it is set equal to lb. For example, banded(1,1)

(or banded(1)) is a tridiagonal matrix.

17

• scaled_identity: the matrix is a (variable) multiple of the identity matrix.

This is the same as declaring it to be diagonal and Toeplitz.

• upper_hankel: The matrix is Hankel (i.e., constant along antidiagonals), and

zero below the central antidiagonal, i.e., for i + j > n + 1.

When multiple keywords are supplied, the resulting matrix structure is determined

by intersection; if the keywords conﬂict, then an error will result.

A variable statement can be used to declare only a single variable, which can

be a bit inconvenient if you have a lot of variables to declare. For this reason, the

variables statement is provided which allows you to declare multiple variables; i.e.,

variables x1 x2 x3 y1(10) y2(10,10,10);

The one limitation of the variables command is that it cannot declare complex or

structured arrays (e.g., symmetric, etc.). These must be declared one at a time, using

the singular variable command.

3.3 Objective functions

Declaring an objective function requires the use of the minimize or maximize func-

tion, as appropriate. (For the beneﬁt of our users with a British inﬂuence, the syn-

onyms minimise and maximise are provided as well.) The objective function in a call

to minimize must be convex; the objective function in a call to maximize must be

concave. At most one objective function may be declared in a given cvx speciﬁcation,

and the objective function must have a scalar value. (For the only exception to this

rule, see the section on deﬁning new functions in '5).

If no objective function is speciﬁed, the problem is interpreted as a feasibility

problem, which is the same as performing a minimization with the objective function

set to zero. In this case, cvx_optval is either 0, if a feasible point is found, or +Inf,

if the constraints are not feasible.

3.4 Constraints

The following constraint types are supported in cvx:

• Equality == constraints, where both the left- and right-hand sides are aﬃne

functions of the optimization variables.

• Less-than <=, < inequality constraints, where the left-hand expression is convex,

and the right-hand expression is concave.

• Greater-than >=, > constraints, where the left-hand expression is concave, and

the right-hand expression is convex.

In cvx, the strict inequalities < and > are accepted, but interpreted as the associated

nonstrict inequalities, <= and >=, respectively. We encourage you to use the nonstrict

18

forms <= and >=, since they are mathematically correct. (Future versions of cvx

might assign a slightly diﬀerent meaning to strict inequalities.)

These equality and inequality operators work for arrays. When both sides of

the constraint are arrays of the same size, the constraint is imposed elementwise. For

example, if a and b are mn matrices, then a<=b is interpreted by cvx as mn (scalar)

inequalities, i.e., each entry of a must be less than or equal to the corresponding entry

of b. cvx also handles cases where one side is a scalar and the other is an array. This

is interpreted as a constraint for each element of the array, with the (same) scalar

appearing on the other side. As an example, if a is an m n matrix, then a>=0 is

interpreted as mn inequalities: each element of the matrix must be nonnegative.

Note also the important distinction between =, which is an assignment, and ==,

which imposes an equality constraint (inside a cvx speciﬁcation); for more on this

distinction, see '8.4. Also note that the non-equality operator ~= may not be used in

a constraint; in any case, such constraints are rarely convex. Inequalities cannot be

used if either side is complex.

cvx also supports a set membership constraint; see '3.6.

3.5 Functions

The base cvx function library includes a variety of convex, concave, and aﬃne func-

tions which accept cvx variables or expressions as arguments. Many are common

Matlab functions such as sum, trace, diag, sqrt, max, and min, re-implemented as

needed to support cvx; others are new functions not found in Matlab. A complete

list of the functions in the base library can be found in 'B. It’s also possible to add

your own new functions; see '5.

An example of a function in the base library is quad_over_lin, which represents

the quadratic-over-linear function, deﬁned as f(x, y) = x

T

x/y, with domain R

n

R

++

, i.e., x is an arbitrary vector in R

n

, and y is a positive scalar. (The function also

accepts complex x, but we’ll consider real x to keep things simple.) The quadratic-

over-linear function is convex in x and y, and so can be used as an objective, in an

appropriate constraint, or in a more complicated expression. We can, for example,

minimize the quadratic-over-linear function of (Ax −b, c

T

x + d) using

minimize( quad_over_lin( A*x-b, c’*x+d ) );

inside a cvx speciﬁcation, assuming x is a vector optimization variable, A is a matrix,

b and c are vectors, and d is a scalar. cvx recognizes this objective expression as a

convex function, since it is the composition of a convex function (the quadratic-over-

linear function) with an aﬃne function.

You can also use the function quad_over_lin outside a cvx speciﬁcation. In

this case, it just computes its (numerical) value, given (numerical) arguments. It’s

not quite the same as the expression ((A*x-b)’*(A*x-b))/(c’*x+d), however. This

expression makes sense, and returns a real number, when c

T

x + d is negative; but

quad_over_lin(A*x-b,c’*x+d) returns +Inf if c

T

x + d > 0.

19

3.6 Sets

cvx supports the deﬁnition and use of convex sets. The base library includes the cone

of positive semideﬁnite nn matrices, the second-order or Lorentz cone, and various

norm balls. A complete list of sets supplied in the base library is given in 'B.

Unfortunately, the Matlab language does not have a set membership operator,

such as x in S, to denote x ∈ S. So in cvx, we use a slightly diﬀerent syntax to

require that an expression is in a set. To represent a set we use a function that

returns an unnamed variable that is required to be in the set. Consider, for example,

S

n

+

, the cone of symmetric positive semideﬁnite n n matrices. In cvx, we represent

this by the function semidefinite(n), which returns an unnamed new variable, that

is constrained to be positive semideﬁnite. To require that the matrix expression X

be symmetric positive semideﬁnite, we use the syntax X == semidefinite(n). The

literal meaning of this is that X is constrained to be equal to some unnamed variable,

which is required to be an n n symmetric positive semideﬁnite matrix. This is, of

course, equivalent to saying that X must be symmetric positive semideﬁnite.

As an example, consider the constraint that a (matrix) variable X is a correlation

matrix, i.e., it is symmetric, has unit diagonal elements, and is positive semideﬁnite.

In cvx we can declare such a variable and impose such constraints using

variable X(n,n) symmetric;

X == semidefinite(n);

diag(X) == ones(n,1);

The second line here imposes the constraint that X be positive semideﬁnite. (You can

read ‘==’ here as ‘is’, so the second line can be read as ‘X is positive semideﬁnite’.)

The lefthand side of the third line is a vector containing the diagonal elements of X,

whose elements we require to be equal to one. Incidentally, cvx allows us to simplify

the third line to

diag(X) == 1;

because cvx follows the Matlab convention of handling array/scalar comparisons by

comparing each element of the array independently with the scalar.

If this use of equality constraints to represent set membership remains confusing

or simply aesthetically displeasing, we have create a “pseudo-operator” <In> that

you can use in its place. So, for example, the semideﬁnite constraint above can be

replaced by

X <In> semidefinite(n);

This is exactly equivalent to using the equality constraint operator, but if you ﬁnd it

more pleasing, feel free to use it. Implementing this operator required some Matlab

trickery, so don’t expect to be able to use it outside of cvx models.

Sets can be combined in aﬃne expressions, and we can constrain an aﬃne expres-

sion to be in a convex set. For example, we can impose constraints of the form

A*X*A’-X == B*semidefinite(n)*B’;

20

where X is an n n symmetric variable matrix, and A and B are n n constant

matrices. This constraint requires that AXA

T

−X = BY B

T

, for some Y ∈ S

n

+

.

cvx also supports sets whose elements are ordered lists of quantities. As an ex-

ample, consider the second-order or Lorentz cone,

Q

m

= ¦ (x, y) ∈ R

m

R [ |x|

2

≤ y ¦ = epi | |

2

, (2)

where epi denotes the epigraph of a function. An element of Q

m

is an ordered list,

with two elements: the ﬁrst is an m-vector, and the second is a scalar. We can use this

cone to express the simple least-squares problem from '2.1 (in a fairly complicated

way) as follows:

minimize y

subject to (Ax −b, y) ∈ Q

m

.

(3)

cvx uses Matlab’s cell array facility to mimic this notation:

cvx_begin

variables x(n) y;

minimize( y );

subject to

{ A*x-b, y } <In> lorentz(m);

cvx_end

The function call lorentz(m) returns an unnamed variable (i.e., a pair consisting of

a vector and a scalar variable), constrained to lie in the Lorentz cone of length m. So

the constraint in this speciﬁcation requires that the pair { A*x-b, y } lies in the

appropriately-sized Lorentz cone.

3.7 Dual variables

When a disciplined convex program is solved, the associated dual problem is also

solved. (In this context, the original problem is called the primal problem.) The

optimal dual variables, each of which is associated with a constraint in the original

problem, give valuable information about the original problem, such as the sensitiv-

ities with respect to perturbing the constraints [BV04, Ch.5]. To get access to the

optimal dual variables in cvx, you simply declare them, and associate them with the

constraints. Consider, for example, the LP

minimize c

T

x

subject to Ax _ b,

with variable x ∈ R

n

, and m inequality constraints. The dual of this problem is

maximize −b

T

y

subject to c + A

T

y = 0

y _ 0,

where the dual variable y is associated with the inequality constraint Ax _ b in the

original LP. To represent the primal problem and this dual variable in cvx, we use

the following syntax:

21

n = size(A,2);

cvx_begin

variable x(n);

dual variable y;

minimize( c’ * x );

subject to

y : A * x <= b;

cvx_end

The line

dual variable y

tells cvx that y will represent the dual variable, and the line

y : A * x <= b;

associates it with the inequality constraint. Notice how the colon : operator is being

used in a diﬀerent manner than in standard Matlab, where it is used to construct

numeric sequences like 1:10. This new behavior is in eﬀect only when a dual variable

is present, so there should be no confusion or conﬂict. No dimensions are given for

y; they are automatically determined from the constraint with which it is associated.

For example, if m = 20, typing y at the Matlab command prompt immediately before

cvx_end yields

y =

cvx dual variable (20x1 vector)

It is not necessary to place the dual variable on the left side of the constraint; for

example, the line above can also be written in this way:

A * x <= b : y;

In addition, dual variables for inequality constraints will always be nonnegative, which

means that the sense of the inequality can be reversed without changing the dual

variable’s value; i.e.,

b >= A * x : y;

yields an identical result. For equality constraints, on the other hand, swapping the

left- and right- hand sides of an equality constraint will negate the optimal value of

the dual variable.

After the cvx_end statement is processed, and assuming the optimization was

successful, cvx assigns numerical values to x and y—the optimal primal and dual

variable values, respectively. Optimal primal and dual variables for this LP must

satisfy the complementary slackness conditions

y

i

(b −Ax)

i

= 0, i = 1, . . . , m. (4)

You can check this in Matlab with the line

22

y .* (b-A*x)

which prints out the products of the entries of y and b-A*x, which should be nearly

zero. This line must be executed after the cvx_end command (which assigns nu-

merical values to x and y); it will generate an error if it is executed inside the cvx

speciﬁcation, where y and b-A*x are still just abstract expressions.

If the optimization is not successful, because either the problem is infeasible or

unbounded, then x and y will have diﬀerent values. In the unbounded case, x will

contain an unbounded direction; i.e., a point x satisfying

c

T

x = −1, Ax _ 0, (5)

and y will be ﬁlled with NaN values, reﬂecting the fact that the dual problem is

infeasible. In the infeasible case, x is ﬁlled with NaN values, while y contains an

unbounded dual direction; i.e., a point y satisfying

b

T

y = −1, A

T

y = 0, y _ 0 (6)

Of course, the precise interpretation of primal and dual points and/or directions

depends on the structure of the problem. See references such as [BV04] for more on

the interpretation of dual information.

cvx also supports the declaration of indexed dual variables. These prove useful

when the number of constraints in a model (and, therefore, the number of dual

variables) depends upon the parameters themselves. For more information on indexed

dual variables, see '8.5.

3.8 Expression holders

Sometimes it is useful to store a cvx expression into a Matlab variable for future use.

For instance, consider the following cvx script:

variables x y

z = 2 * x - y;

square( z ) <= 3;

quad_over_lin( x, z ) <= 1;

The construction z = 2 * x - y is not an equality constraint; it is an assignment.

It is storing an intermediate calculation 2 * x - y, which is an aﬃne expression,

which is then used later in two diﬀerent constraints. We call z an expression holder

to diﬀerentiate it from a formally declared cvx variable. For more on the critical

diﬀerences between assignment and equality, see Section '8.4.

Often it will be useful to accumulate an array of expressions into a single Matlab

variable. Unfortunately, a somewhat technical detail of the Matlab object model can

cause problems in such cases. Consider this construction:

variable u(9);

x(1) = 1;

23

for k = 1 : 9,

x(k+1) = sqrt( x(k) + u(k) );

end

This seems reasonable enough: x should be a vector whose ﬁrst value is 1, and whose

subsequent values are concave cvx expressions. But if you try this in a cvx model,

Matlab will give you a rather cryptic error:

??? The following error occurred converting from cvx to double:

Error using ==> double

Conversion to double from cvx is not possible.

The reason this occurs is that the Matlab variable x is initialized as a numeric array

when the assignment x(1)=1 is made; and Matlab will not permit cvx objects to be

subsequently inserted into numeric arrays.

The solution is to explicitly declare x to be an expression holder before assigning

values to it. We have provided keywords expression and expressions for just this

purpose, for declaring a single or multiple expression holders for future assignment.

Once an expression holder has been declared, you may freely insert both numeric

and cvx expressions into it. For example, the previous example can be corrected as

follows:

variable u(9);

expression x(10);

x(1) = 1;

for k = 1 : 9,

x(k+1) = sqrt( x(k) + u(k) );

end

cvx will accept this construction without error. You can then use the concave ex-

pressions x(1), . . . , x(10) in any appropriate ways; for example, you could maximize

x(10).

The diﬀerences between a variable object and an expression object are quite

signiﬁcant. A variable object holds an optimization variable, and cannot be over-

written or assigned in the cvx speciﬁcation. (After solving the problem, however, cvx

will overwrite optimization variables with optimal values.) An expression object, on

the other hand, is initialized to zero, and should be thought of as a temporary place

to store cvx expressions; it can be assigned to, freely re-assigned, and overwritten in

a cvx speciﬁcation.

Of course, as our ﬁrst example shows, it is not always necessary to declare an

expression holder before it is created or used. But doing so provides an extra measure

of clarity to models, so we strongly recommend it.

24

4 The DCP ruleset

cvx enforces the conventions dictated by the disciplined convex programming ruleset,

or DCP ruleset for short. cvx will issue an error message whenever it encounters

a violation of any of the rules, so it is important to understand them before begin-

ning to build models. The rules are drawn from basic principles of convex analysis,

and are easy to learn, once you’ve had an exposure to convex analysis and convex

optimization.

The DCP ruleset is a set of suﬃcient, but not necessary, conditions for convexity.

So it is possible to construct expressions that violate the ruleset but are in fact

convex. As an example consider the entropy function, −

¸

n

i=1

x

i

log x

i

, deﬁned for

x > 0, which is concave. If it is expressed as

- sum( x .* log( x ) )

cvx will reject it, because its concavity does not follow from any of the composition

rules. (Speciﬁcally, it violates the no-product rule described in '4.4.) Problems

involving entropy, however, can be solved, by explicitly using the entropy function,

sum(entr( x ))

which is in the base cvx library, and thus recognized as concave by cvx. If a convex

(or concave) function is not recognized as convex or concave by cvx, it can be added

as a new atom; see '5.

As another example consider the function

√

x

2

+ 1 = |[x 1]|

2

, which is convex. If

it is written as

norm([x 1])

(assuming x is a scalar variable or aﬃne expression) it will be recognized by cvx

as a convex expression, and therefore can be used in (appropriate) constraints and

objectives. But if it is written as

sqrt(x^2+1)

cvx will reject it, since convexity of this function does not follow from the cvx ruleset.

4.1 A taxonomy of curvature

In disciplined convex programming, a scalar expression is classiﬁed by its curvature.

There are four categories of curvature: constant, aﬃne, convex, and concave. For a

function f : R

n

→ R deﬁned on all R

n

, the categories have the following meanings:

constant: f(αx + (1 −α)y) = f(x) ∀x, y ∈ R

n

, α ∈ R

aﬃne: f(αx + (1 −α)y) = αf(x) + (1 −α)f(y) ∀x, y ∈ R

n

, α ∈ R

convex: f(αx + (1 −α)y) ≤ αf(x) + (1 −α)f(y) ∀x, y ∈ R

n

, α ∈ [0, 1]

concave: f(αx + (1 −α)y) ≥ αf(x) + (1 −α)f(y) ∀x, y ∈ R

n

, α ∈ [0, 1]

25

Of course, there is signiﬁcant overlap in these categories. For example, constant

expressions are also aﬃne, and (real) aﬃne expressions are both convex and concave.

Convex and concave expressions are real by deﬁnition. Complex constant and

aﬃne expressions can be constructed, but their usage is more limited; for example,

they cannot appear as the left- or right-hand side of an inequality constraint.

4.2 Top-level rules

cvx supports three diﬀerent types of disciplined convex programs:

• A minimization problem, consisting of a convex objective function and zero or

more constraints.

• A maximization problem, consisting of a concave objective function and zero or

more constraints.

• A feasibility problem, consisting of one or more constraints.

4.3 Constraints

Three types of constraints may be speciﬁed in disciplined convex programs:

• An equality constraint, constructed using ==, where both sides are aﬃne.

• A less-than inequality constraint, using either <= or <, where the left side is

convex and the right side is concave.

• A greater-than inequality constraint, using either >= or >, where the left side is

concave and the right side is convex.

Non-equality constraints, constructed using ~=, are never allowed. (Such constraints

are not convex.)

One or both sides of an equality constraint may be complex; inequality constraints,

on the other hand, must be real. A complex equality constraint is equivalent to two

real equality constraints, one for the real part and one for the imaginary part. An

equality constraint with a real side and a complex side has the eﬀect of constraining

the imaginary part of the complex side to be zero.

As discussed in '3.6 above, cvx enforces set membership constraints (e.g., x ∈ S)

using equality constraints. The rule that both sides of an equality constraint must

be aﬃne applies to set membership constraints as well. In fact, the returned value of

set atoms like semidefinite() and lorentz() is aﬃne, so it is suﬃcient to simply

verify the remaining portion of the set membership constraint. For composite values

like { x, y }, each element must be aﬃne.

In this version, strict inequalities <, > are interpreted identically to nonstrict

inequalities >=, <=. Eventually cvx will ﬂag strict inequalities so that they can be

veriﬁed after the optimization is carried out.

26

4.4 Expression rules

So far, the rules as stated are not particularly restrictive, in that all convex programs

(disciplined or otherwise) typically adhere to them. What distinguishes disciplined

convex programming from more general convex programming are the rules governing

the construction of the expressions used in objective functions and constraints.

Disciplined convex programming determines the curvature of scalar expressions

by recursively applying the following rules. While this list may seem long, it is for

the most part an enumeration of basic rules of convex analysis for combining convex,

concave, and aﬃne forms: sums, multiplication by scalars, and so forth.

• A valid constant expression is

– any well-formed Matlab expression that evaluates to a ﬁnite value.

• A valid aﬃne expression is

– a valid constant expression;

– a declared variable;

– a valid call to a function in the atom library with an aﬃne result;

– the sum or diﬀerence of aﬃne expressions;

– the product of an aﬃne expression and a constant.

• A valid convex expression is

– a valid constant or aﬃne expression;

– a valid call to a function in the atom library with a convex result;

– an aﬃne scalar raised to a constant power p ≥ 1, p = 3, 5, 7, 9, ...;

– a convex scalar quadratic form ('4.8);

– the sum of two or more convex expressions;

– the diﬀerence between a convex expression and a concave expression;

– the product of a convex expression and a nonnegative constant;

– the product of a concave expression and a nonpositive constant;

– the negation of a concave expression.

• A valid concave expression is

– a valid constant or aﬃne expression;

– a valid call to a function in the atom library with a concave result;

– a concave scalar raised to a power p ∈ (0, 1);

– a concave scalar quadratic form ('4.8);

– the sum of two or more concave expressions;

27

– the diﬀerence between a concave expression and a convex expression;

– the product of a concave expression and a nonnegative constant;

– the product of a convex expression and a nonpositive constant;

– the negation of a convex expression.

If an expression cannot be categorized by this ruleset, it is rejected by cvx. For matrix

and array expressions, these rules are applied on an elementwise basis. We note that

the set of rules listed above is redundant; there are much smaller, equivalent sets of

rules.

Of particular note is that these expression rules generally forbid products between

nonconstant expressions, with the exception of scalar quadratic forms (see '4.8 below).

For example, the expression x*sqrt(x) happens to be a convex function of x, but

its convexity cannot be veriﬁed using the cvx ruleset, and so is rejected. (It can be

expressed as x^(3/2) or pow_p(x,3/2), however.) We call this the no-product rule,

and paying close attention to it will go a long way to insuring that the expressions

you construct are valid.

4.5 Functions

In cvx, functions are categorized in two attributes: curvature (constant, aﬃne, con-

vex, or concave) and monotonicity (nondecreasing, nonincreasing, or nonmonotonic).

Curvature determines the conditions under which they can appear in expressions ac-

cording to the expression rules given in '4.4 above. Monotonicity determines how

they can be used in function compositions, as we shall see in '4.6 below.

For functions with only one argument, the categorization is straightforward. Some

examples are given in the table below.

Function Meaning Curvature Monotonicity

sum( x )

¸

i

x

i

aﬃne nondecreasing

abs( x ) [x[ convex nonmonotonic

sqrt( x )

√

x concave nondecreasing

Following standard practice in convex analysis, convex functions are interpreted

as +∞ when the argument is outside the domain of the function, and concave func-

tions are interpreted as −∞ when the argument is outside its domain. In other

words, convex and concave functions in cvx are interpreted as their extended-valued

extensions.

This has the eﬀect of automatically constraining the argument of a function to be

in the function’s domain. For example, if we form sqrt(x+1) in a cvx speciﬁcation,

where x is a variable, then x will automatically be constrained to be larger than or

equal to −1. There is no need to add a separate constraint, x>=-1, to enforce this.

Monotonicity of a function is determined in the extended sense, i.e., including the

values of the argument outside its domain. For example, sqrt(x) is determined to be

nondecreasing since its value is constant (−∞) for negative values of its argument;

then jumps up to 0 for argument zero, and increases for positive values of its argument.

28

cvx does not consider a function to be convex or concave if it is so only over

a portion of its domain, even if the argument is constrained to lie in one of these

portions. As an example, consider the function 1/x. This function is convex for x > 0,

and concave for x < 0. But you can never write 1/x in cvx (unless x is constant),

even if you have imposed a constraint such as x>=1, which restricts x to lie in the

convex portion of function 1/x. You can use the cvx function inv_pos(x), deﬁned

as 1/x for x > 0 and ∞ otherwise, for the convex portion of 1/x; cvx recognizes this

function as convex and nonincreasing. In cvx, you can express the concave portion

of 1/x, where x is negative, using -inv_pos(-x), which will be correctly recognized

as concave and nonincreasing.

For functions with multiple arguments, curvature is always considered jointly, but

monotonicity can be considered on an argument-by-argument basis. For example,

quad_over_lin( x, y )

[x[

2

/y y > 0

+∞ y ≤ 0

convex, nonincreasing in y

is jointly convex in both arguments, but it is monotonic only in its second argument.

In addition, some functions are convex, concave, or aﬃne only for a subset of its

arguments. For example, the function

norm( x, p ) |x|

p

(1 ≤ p) convex in x, nonmonotonic

is convex only in its ﬁrst argument. Whenever this function is used in a cvx speci-

ﬁcation, then, the remaining arguments must be constant, or cvx will issue an error

message. Such arguments correspond to a function’s parameters in mathematical

terminology; e.g.,

f

p

(x) : R

n

→ R, f

p

(x) |x|

p

So it seems ﬁtting that we should refer to such arguments as parameters in this

context as well. Henceforth, whenever we speak of a cvx function as being convex,

concave, or aﬃne, we will assume that its parameters are known and have been given

appropriate, constant values.

4.6 Compositions

A basic rule of convex analysis is that convexity is closed under composition with an

aﬃne mapping. This is part of the DCP ruleset as well:

• A convex, concave, or aﬃne function may accept an aﬃne expression (of compat-

ible size) as an argument. The result is convex, concave, or aﬃne, respectively.

For example, consider the function square( x ), which is provided in the cvx atom

library. This function squares its argument; i.e., it computes x.*x. (For array ar-

guments, it squares each element independently.) It is in the cvx atom library, and

known to be convex, provided its argument is real. So if x is a real variable of

dimension n, a is a constant n-vector, and b is a constant, the expression

square( a’ * x + b )

29

is accepted by cvx, which knows that it is convex.

The aﬃne composition rule above is a special case of a more sophisticated compo-

sition rule, which we describe now. We consider a function, of known curvature and

monotonicity, that accepts multiple arguments. For convex functions, the rules are:

• If the function is nondecreasing in an argument, that argument must be convex.

• If the function is nonincreasing in an argument, that argument must be concave.

• If the function is neither nondecreasing or nonincreasing in an argument, that

argument must be aﬃne.

If each argument of the function satisﬁes these rules, then the expression is accepted

by cvx, and is classiﬁed as convex. Recall that a constant or aﬃne expression is

both convex and concave, so any argument can be aﬃne, including as a special case,

constant.

The corresponding rules for a concave function are as follows:

• If the function is nondecreasing in an argument, that argument must be concave.

• If the function is nonincreasing in an argument, that argument must be convex.

• If the function is neither nondecreasing or nonincreasing in an argument, that

argument must be aﬃne.

In this case, the expression is accepted by cvx, and classiﬁed as concave.

For more background on these composition rules, see [BV04, '3.2.4]. In fact, with

the exception of scalar quadratic expressions, the entire DCP ruleset can be thought

of as special cases of these six rules.

Let us examine some examples. The maximum function is convex and nonde-

creasing in every argument, so it can accept any convex expressions as arguments.

For example, if x is a vector variable, then

max( abs( x ) )

obeys the ﬁrst of the six composition rules and is therefore accepted by cvx, and

classiﬁed as convex.

As another example, consider the sum function, which is both convex and concave

(since it is aﬃne), and nondecreasing in each argument. Therefore the expressions

sum( square( x ) )

sum( sqrt( x ) )

are recognized as valid in cvx, and classiﬁed as convex and concave, respectively. The

ﬁrst one follows from the ﬁrst rule for convex functions; and the second one follows

from the ﬁrst rule for concave functions.

Most people who know basic convex analysis like to think of these examples in

terms of the more speciﬁc rules: a maximum of convex functions is convex, and a sum

of convex (concave) functions is convex (concave). But these rules are just special

30

cases of the general composition rules above. Some other well known basic rules that

follow from the general composition rules are: a nonnegative multiple of a convex

(concave) function is convex (concave); a nonpositive multiple of a convex (concave)

function is concave (convex).

Now we consider a more complex example in depth. Suppose x is a vector vari-

able, and A, b, and f are constants with appropriate dimensions. cvx recognizes the

expression

sqrt(f’*x) + min(4,1.3-norm(A*x-b))

as concave. Consider the term sqrt(f’*x). cvx recognizes that sqrt is concave and

f’*x is aﬃne, so it concludes that sqrt(f’*x) is concave. Now consider the second

term min(4,1.3-norm(A*x-b)). cvx recognizes that min is concave and nondecreas-

ing, so it can accept concave arguments. cvx recognizes that 1.3-norm(A*x-b) is

concave, since it is the diﬀerence of a constant and a convex function. So cvx con-

cludes that the second term is also concave. The whole expression is then recognized

as concave, since it is the sum of two concave functions.

The composition rules are suﬃcient but not necessary for the classiﬁcation to be

correct, so some expressions which are in fact convex or concave will fail to satisfy

them, and so will be rejected by cvx. For example, if x is a vector variable, the

expression

sqrt( sum( square( x ) ) )

is rejected by cvx, because there is no rule governing the composition of a concave

nondecreasing function with a convex function. Of course, the workaround is simple

in this case: use norm( x ) instead, since norm is in the atom library and known by

cvx to be convex.

4.7 Monotonicity in nonlinear compositions

Monotonicity is a critical aspect of the rules for nonlinear compositions. This has

some consequences that are not so obvious, as we shall demonstrate here by example.

Consider the expression

square( square( x ) + 1 )

where x is a scalar variable. This expression is in fact convex, since (x

2

+ 1)

2

=

x

4

+ 2x

2

+ 1 is convex. But cvx will reject the expression, because the outer square

cannot accept a convex argument. Indeed, the square of a convex function is not, in

general, convex: for example, (x

2

−1)

2

= x

4

−2x

2

+ 1 is not convex.

There are several ways to modify the expression above to comply with the ruleset.

One way is to write it as x^4 + 2*x^2 + 1, which cvx recognizes as convex, since

cvx allows positive even integer powers using the ^ operator. (Note that the same

technique, applied to the function (x

2

−1)

2

, will fail, since its second term is concave.)

Another approach is to use the alternate outer function square_pos, included in

the cvx library, which represents the function (x

+

)

2

, where x

+

= max¦0, x¦. Obvi-

ously, square and square_pos coincide when their arguments are nonnegative. But

31

square_pos is nondecreasing, so it can accept a convex argument. Thus, the expres-

sion

square_pos( square( x ) + 1 )

is mathematically equivalent to the rejected version above (since the argument to the

outer function is always positive), but it satisﬁes the DCP ruleset and is therefore

accepted by cvx.

This is the reason several functions in the cvx atom library come in two forms:

the “natural” form, and one that is modiﬁed in such a way that it is monotonic, and

can therefore be used in compositions. Other such “monotonic extensions” include

sum_square_pos and quad_pos_over_lin. If you are implementing a new function

yourself, you might wish to consider if a monotonic extension of that function would

also be useful.

4.8 Scalar quadratic forms

In its original form described in [Gra04, GBY06], the DCP ruleset forbids even the

use of simple quadratic expressions such as x * x (assuming x is a scalar variable).

For practical reasons, we have chosen to make an exception to the ruleset to allow for

the recognition of certain speciﬁc quadratic forms that map directly to certain convex

quadratic functions (or their concave negatives) in the cvx atom library:

conj( x ) .* x is replaced with square( x )

y’ * y is replaced with sum_square( y )

(A*x-b)’*Q*(Ax-b) is replaced with quad_form( A * x - b, Q )

cvx detects the quadratic expressions such as those on the left above, and determines

whether or not they are convex or concave; and if so, translates them to an equivalent

function call, such as those on the right above.

cvx examines each single product of aﬃne expressions, and each single squaring

of an aﬃne expression, checking for convexity; it will not check, for example, sums

of products of aﬃne expressions. For example, given scalar variables x and y, the

expression

x ^ 2 + 2 * x * y + y ^2

will cause an error in cvx, because the second of the three terms 2 * x * y, is neither

convex nor concave. But the equivalent expressions

( x + y ) ^ 2

( x + y ) * ( x + y )

will be accepted. cvx actually completes the square when it comes across a scalar

quadratic form, so the form need not be symmetric. For example, if z is a vector

variable, a, b are constants, and Q is positive deﬁnite, then

( z + a )’ * Q * ( z + b )

32

will be recognized as convex. Once a quadratic form has been veriﬁed by cvx, it

can be freely used in any way that a normal convex or concave expression can be, as

described in '4.4.

Quadratic forms should actually be used less frequently in disciplined convex pro-

gramming than in a more traditional mathematical programming framework, where

a quadratic form is often a smooth substitute for a nonsmooth form that one truly

wishes to use. In cvx, such substitutions are rarely necessary, because of its support

for nonsmooth functions. For example, the constraint

sum( ( A * x - b ) .^ 2 ) <= 1

is equivalently represented using the Euclidean norm:

norm( A * x - b ) <= 1

With modern solvers, the second form can be represented using a second-order cone

constraint—so the second form may actually be more eﬃcient. So we encourage you to

re-evaluate the use of quadratic forms in your models, in light of the new capabilities

aﬀorded by disciplined convex programming.

33

5 Adding new functions to the cvx atom library

cvx allows new convex and concave functions to be deﬁned and added to the atom

library, in two ways, described in this section. The ﬁrst method is simple, and can

(and should) be used by many users of cvx, since it requires only a knowledge of the

basic DCP ruleset. The second method is very powerful, but a bit complicated, and

should be considered an advanced technique, to be attempted only by those who are

truly comfortable with convex analysis, disciplined convex programming, and cvx in

its current state.

Please do let us know if you have implemented a convex or concave function that

you think would be useful to other users; we will be happy to incorporate it in a

future release.

5.1 New functions via the DCP ruleset

The simplest way to construct a new function that works within cvx is to construct it

using expressions that fully conform to the DCP ruleset. To illustrate this, consider

the convex deadzone function, deﬁned as

f(x) = max¦[x[ −1, 0¦ =

0 [x[ ≤ 1

x −1 x > 1

−1 −x x < −1

To implement this function in cvx, simply create a ﬁle deadzone.m containing

function y = deadzone( x )

y = max( abs( x ) - 1, 0 )

This function works just as you expect it would outside of cvx—i.e., when its argu-

ment is numerical. But thanks to Matlab’s operator overloading capability, it will

also work within cvx if called with an aﬃne argument. cvx will properly conclude

that the function is convex, because all of the operations carried out conform to the

rules of DCP: abs is recognized as a convex function; we can subtract a constant from

it, and we can take the maximum of the result and 0, which yields a convex function.

So we are free to use deadzone anywhere in a cvx speciﬁcation that we might use

abs, for example, because cvx knows that it is a convex function.

Let us emphasize that when deﬁning a function this way, the expressions you

use must conform to the DCP ruleset, just as they would if they had been inserted

directly into a cvx model. For example, if we replace max with min above; e.g.,

function y = deadzone_bad( x )

y = min( abs( x ) - 1, 0 )

then the modiﬁed function fails to meet the DCP ruleset. The function will work

outside of a cvx speciﬁcation, happily computing the value min¦[x[ − 1, 0¦ for a

numerical argument x. But inside a cvx speciﬁcation, invoked with a nonconstant

argument, it will not work, because it doesn’t follow the DCP composition rules.

34

5.2 New functions via partially speciﬁed problems

A more advanced method for deﬁning new functions in cvx relies on the following

basic result of convex analysis. Suppose that S ⊂ R

n

R

m

is a convex set and

g : (R

n

R

m

) → (R∪ +∞) is a convex function. Then

f : R

n

→ (R∪ +∞), f(x) inf ¦ g(x, y) [ ∃y, (x, y) ∈ S ¦ (7)

is also a convex function. (This rule is sometimes called the partial minimization

rule.) We can think of the convex function f as the optimal value of a family of

convex optimization problems, indexed or parametrized by x,

minimize g(x, y)

subject to (x, y) ∈ S

with optimization variable y.

One special case should be very familiar: if m = 1 and g(x, y) y, then

f(x) inf ¦ y [ ∃y, (x, y) ∈ S ¦

gives the classic epigraph representation of f:

epi f = S + (¦0¦ R

+

) ,

where 0 ∈ R

n

.

In cvx you can deﬁne a convex function in this very manner, that is, as the optimal

value of a parameterized family of disciplined convex programs. We call the under-

lying convex program in such cases an incomplete speciﬁcation—so named because

the parameters (that is, the function inputs) are unknown when the speciﬁcation is

constructed. The concept of incomplete speciﬁcations can at ﬁrst seem a bit compli-

cated, but it is very powerful mechanism that allows cvx to support a wide variety

of functions.

Let us look at an example to see how this works. Consider the unit-halfwidth

Huber penalty function h(x):

h : R → R, h(x)

x

2

[x[ ≤ 1

2[x[ −1 [x[ ≥ 1.

(8)

We can express the Huber function in terms of the following family of convex QPs,

parameterized by x:

minimize 2v + w

2

subject to [x[ ≤ v + w

w ≤ 1, v ≥ 0

(9)

with scalar variables v and w. The optimal value of this simple QP is equal to the

Huber penalty function of x. We note that the objective and constraint functions in

this QP are (jointly) convex in v, w and x.

We can implement the Huber penalty function in cvx as follows:

35

function cvx_optval = huber( x )

cvx_begin

variables w v;

minimize( w^2 + 2 * v );

subject to

abs( x ) <= w + v;

w <= 1; v >= 0;

cvx_end

If huber is called with a numeric value of x, then upon reaching the cvx_end state-

ment, cvx will ﬁnd a complete speciﬁcation, and solve the problem to compute the

result. cvx places the optimal objective function value into the variable cvx_optval,

and function returns that value as its output. Of course, it’s very ineﬃcient to com-

pute the Huber function of a numeric value x by solving a QP. But it does give the

correct value (up to the core solver accuracy).

What is most important, however, is that if huber is used within a cvx speciﬁca-

tion, with an aﬃne cvx expression for its argument, then cvx will do the right thing.

In particular, cvx will recognize the Huber function, called with aﬃne argument, as

a valid convex expression. In this case, the function huber will contain a special

Matlab object that represents the function call in constraints and objectives. Thus

the function huber can be used anywhere a traditional convex function can be used,

in constraints or objective functions, in accordance with the DCP ruleset.

There is a corresponding development for concave functions as well. Given a

convex set S as above, and a concave function g : (R

n

R

m

) → (R ∪ −∞), the

function

f : R → (R∪ −∞), f(x) sup ¦ g(x, y) [ ∃y, (x, y) ∈ S ¦ (10)

is concave. If g(x, y) y, then

f(x) sup ¦ y [ ∃y, (x, y) ∈ S ¦ (11)

gives the hypograph representation of f:

hypof = S −R

n

+

.

In cvx, a concave incomplete speciﬁcation is simply one that uses a maximize ob-

jective instead of a minimize objective; and if properly constructed, it can be used

anywhere a traditional concave function can be used within a cvx speciﬁcation.

For an example of a concave incomplete speciﬁcation, consider the function

f : R

n×n

→ R, f(X) = λ

min

(X + X

T

) (12)

Its hypograph can be represented using a single linear matrix inequality:

hypof = ¦ (X, t) [ f(X) ≥ t ¦ =

¸

(X, t) [ X + X

T

−tI _ 0

¸

(13)

So we can implement this function in cvx as follows:

36

function cvx_optval = lambda_min_symm( X )

n = size( X, 1 );

cvx_begin

variable y;

maximize( y );

subject to

X + X’ - y * eye( n ) == semidefinite( n );

cvx_end

If a numeric value of X is supplied, this function will return min(eig(X+X’)) (to within

numerical tolerances). However, this function can also be used in cvx constraints and

objectives, just like any other concave function in the atom library.

There are two practical issues that arise when deﬁning functions using incomplete

speciﬁcations, both of which we will illustrate using our huber example above. First of

all, as written the function works only with scalar values. To apply it (elementwise) to

a vector requires that we iterate through the elements in a for loop—a very ineﬃcient

enterprise, particularly in cvx. A far better approach is to extend the huber function

to handle vector inputs. This is, in fact, rather simple to do: we simply create a

multiobjective version of the problem:

function cvx_optval = huber( x )

sx = size( x );

cvx_begin

variables w( sx ) v( sx );

minimize( w .^ 2 + 2 * v );

subject to

abs( x ) <= w + v;

w <= 1; v >= 0;

cvx_end

This version of huber will in eﬀect create sx “instances” of the problem in parallel;

and when used in a cvx speciﬁcation, will be handled correctly.

The second issue is that if the input to huber is numeric, then direct computation

is a far more eﬃcient way to compute the result than solving a QP. (What is more,

the multiobjective version cannot be used with numeric inputs.) One solution is to

place both versions in one ﬁle, with an appropriate test to select the proper version

to use:

function cvx_optval = huber( x )

if isnumeric( x ),

xa = abs( x );

flag = xa < 1;

cvx_optval = flag .* xa.^2 + (~flag) * (2*xa-1);

else,

sx = size( x );

cvx_begin

37

variables w( sx ) v( sx );

minimize( w .^ 2 + 2 * v );

subject to

abs( x ) <= w + v;

w <= 1; v >= 0;

cvx_end

end

Alternatively, you can create two separate versions of the function, one for numeric

input and one for cvx expressions, and place the cvx version in a subdirectory called

@cvx. (Do not include this directory in your Matlab path; only include its parent.)

Matlab will automatically call the version in the @cvx directory when one of the

arguments is a cvx variable. This is the approach taken for the version of huber

found in the cvx atom library.

One good way to learn more about using incomplete speciﬁcations is to examine

some of the examples already in the cvx atom library. Good choices include huber,

inv_pos, lambda_min, lambda_max, matrix_frac, quad_over_lin, sum_largest,

and others. Some are a bit diﬃcult to read because of diagnostic or error-checking

code, but these are relatively simple.

38

6 Semideﬁnite programming using cvx

Those who are familiar with semideﬁnite programming (SDP) know that the con-

straints that utilize the set semidefinite(n) in '3.6 above are, in practice, typi-

cally expressed using linear matrix inequality (LMI) notation. For example, given

X = X

T

∈ R

n×n

, the constraint X _ 0 denotes that X ∈ S

n

+

; that is, that X is

positive semideﬁnite.

cvx provides a special SDP mode which allows this LMI convention to be employed

inside cvx models using Matlab’s standard inequality operators >=, <=, etc.. In order

to use it, one must simply begin a model with the statement cvx_begin sdp or

cvx_begin SDP instead of simply cvx_begin. When SDP mode is engaged, cvx

interprets certain inequality constraints in a diﬀerent manner. To be speciﬁc:

• Equality constraints are interpreted the same (i.e., elementwise).

• Inequality constraints involving vectors and scalars are interpreted the same;

i.e., elementwise.

• Inequality constraints involving non-square matrices are disallowed; attempt-

ing to use them causes an error. If you wish to do true elementwise com-

parison of matrices X and Y, use a vectorization operation X(:) <= Y(:) or

vec( X ) <= vec( Y ). (vec is a function provided by cvx that is equivalent

to the colon operation.)

• Inequality constraints involving real, square matrices are interpreted as follows:

X >= Y and X > Y become X - Y == semidefinite(n)

X <= Y and X < Y become Y - X == semidefinite(n)

If either side is complex, then the inequalities are interpreted as follows:

X >= Y and X > Y become X - Y == hermitian_semidefinite(n)

X <= Y and X < Y become Y - X == hermitian_semidefinite(n)

In the above, n=max(size(X,1),size(Y,1)).

• There is one additional restriction: both X and Y must be the same size, or one

must be the scalar zero. For example, if X and Y are matrices of size n,

X >= 1 or 1 >= Y illegal

X >= ones(n,n) or ones(n,n) >= Y legal

X >= 0 or 0 >= Y legal

In eﬀect, cvx enforces a stricter interpretation of the inequality operators for

LMI constraints.

39

• Note that LMI constraints enforce symmetry (real or Hermitian, as appropriate)

on their inputs. Unlike SDPSOL [WB00], cvx does not extract the symmetric

part for you: you must take care to insure symmetry yourself. Since cvx sup-

ports the declaration of symmetric matrices, this is reasonably straightforward.

If cvx cannot determine that an LMI is symmetric, a warning will be issued.

• A dual variable, if supplied, will be applied to the converted equality constraint.

It will be given a positive semideﬁnite value if an optimal point is found.

So, for example, the cvx model found in the ﬁle examples/closest_toeplitz_sdp.m,

cvx_begin

variable Z(n,n) hermitian toeplitz

dual variable Q

minimize( norm( Z - P, ’fro’ ) )

Z == hermitian_semidefinite( n ) : Q;

cvx_end

can also be written as follows:

cvx_begin sdp

variable Z(n,n) hermitian toeplitz

dual variable Q

minimize( norm( Z - P, ’fro’ ) )

Z >= 0 : Q;

cvx_end

Many other examples in the cvx example library utilize semideﬁnite constraints; and

all of them use SDP mode. To ﬁnd them, simply search for the text cvx_begin sdp

in the examples/ subdirectory tree using your favorite ﬁle search tool. One of these

examples is reproduced in '8.5.

Since semideﬁnite programming is popular, some may wonder why SDP mode is

not the default behavior. The reason for this is that we place a strong emphasis

on maintaining consistency between Matlab’s native behavior and that of cvx; and

the use of the >=, <=, >, < operators to create LMIs represents a deviation from

that ideal. For example, the expression Z >= 0 in the example above constrains

the variable Z to be positive semideﬁnite. But after the model has been solved and

Z has been replaced with a numeric value, the expression Z >= 0 will test for the

elementwise nonnegativity of Z. To verify that the numeric value of Z is, in fact,

positive semideﬁnite, you must perform a test like min(eig(Z)) >= 0.

40

7 Geometric programming using cvx

Geometric programs (GPs) are special mathematical programs that can be converted

to convex form using a change of variables. The convex form of GPs can be expressed

as DCPs, but cvx also provides a special mode that allows a GP to be speciﬁed in

its native form. cvx will automatically perform the necessary conversion, compute

a numerical solution, and translate the results back to the original problem. For a

tutorial on geometric programming, we refer the reader to [BKVH05].

To utilize GP mode, you must begin your cvx speciﬁcation with the command

cvx_begin gp or cvx_begin GP instead of simply cvx_begin. For example, the

following code, found in the example library at gp/max_volume_box.m, determines

the maximum volume box subject to various area and ratio constraints:

cvx_begin gp

variables w h d

maximize( w * h * d )

subject to

2*(h*w+h*d) <= Awall;

w*d <= Afloor;

h/w >= alpha;

h/w <= beta;

d/w >= gamma;

d/w <= delta;

cvx_end

As the example illustrates, cvx supports the construction of monomials and posyn-

omials using addition, multiplication, division (when appropriate), and powers. In

addition, cvx supports the construction of generalized geometric programs (GGPs),

by permitting the use of generalized posynomials wherever posynomials are permitted

in standard GP [BKVH05].

The solvers used in this version of cvx do not support geometric programming

natively. Instead, they are solved using the successive approximation technique de-

scribed in Appendix D.1. This means that solving GPs can be slow, but for small

and medium sized problems, the method works well.

In the remainder of this section, we will describe speciﬁc rules that apply when

constructing models in GP mode.

7.1 Top-level rules

cvx supports three types of geometric programs:

• A minimization problem, consisting of a generalized posynomial objective and

zero or more constraints.

• A maximization problem, consisting of a monomial objective and zero or more

constraints.

41

• A feasibility problem, consisting of one or more constraints.

The asymmetry between minimizations and maximizations—speciﬁcally, that only

monomial objectives are allowed in the latter—is an unavoidable artifact of the ge-

ometry of GPs and GGPs.

7.2 Constraints

Three types of constraints may be speciﬁed in geometric programs:

• An equality constraint, constructed using ==, where both sides are monomials.

• A less-than inequality constraint <=, < where the left side is a generalized posyn-

omial and the right side is a monomial.

• A greater-than inequality constraint >=, > where the left side is a monomial and

the right side is a generalized posynomial.

As with DCPs, non-equality constraints are not permitted.

7.3 Expressions

The basic building blocks of generalized geometric programming are monomials,

posynomials, and generalized posynomials. A valid monomial is

• a declared variable;

• the product of two or more monomials;

• the ratio of two monomials;

• a monomial raised to a real power; or

• a call to one of the following functions with monomial arguments: prod, cumprod,

geo_mean, sqrt.

A valid posynomial expression is

• a valid monomial;

• the sum of two or more posynomials;

• the product of two or more posynomials;

• the ratio of a posynomial and a monomial;

• a posynomial raised to a positive integral power; or

• a call to one of the following functions with posynomial arguments: sum, cumsum,

mean, prod, cumprod.

42

A valid generalized posynomial expression is

• a valid posynomial;

• the sum of two or more generalized posynomials;

• the product of two or more generalized posynomials;

• the ratio of a generalized posynomial and a monomial;

• a generalized posynomial raised to a positive real power; or

• a call to one of the following functions with arguments that are generalized

posynomials: sum, cumsum, mean, prod, cumprod, geo_mean, sqrt, norm,

sum_largest, norm_largest.

It is entirely possible to create and manipulate arrays of monomials, posynomials,

and/or generalized posynomials in cvx, in which case these rules extend in an ob-

vious manner. For example, the product of two monomial matrices produces either

a posynomial matrix or a monomial matrix, depending upon the structure of said

matrices.

43

8 Advanced topics

In this section we describe a number of the more advanced capabilities of cvx. We

recommend that you skip this section at ﬁrst, until you are comfortable with the basic

capabilities described above.

8.1 Solver selection

cvx currently supports two solvers: SeDuMi and SDPT3. With an exception discussed

below, SeDuMi is used by default. We have found that SeDuMi is faster and more

reliable for most problems, but for your application you may ﬁnd otherwise. To select

SDPT3 as your default solver instead, simply type

12 cvx_solver sdpt3

at the command line. To revert to SDPT3, type

13 cvx_solver sedumi

To see which solver is currently selected, simply type

14 cvx_solver

If you issue this command inside a model, it will change the solver being used only

for that model; the default will be preserved. If you issue this command outside of a

model, it will change the solver used for all future models.

Both solvers are being actively maintained by their authors. If you are having

diﬃculty with one solver, try the other. If you encounter a problem that one solver

can handle but the other cannot, please send us a bug report and we will forward the

results to the authors of SeDuMI or SDPT3.

8.2 Controlling solver precision

Numerical methods for convex optimization are not exact; they compute their results

to within a predeﬁned numerical precision or tolerance. Upon solution of your model,

the tolerance level the solver has achieved is returned in the cvx_slvtol variable.

Attempts to interpret this tolerance level in any absolute sense are not recommended.

For one thing, each solver computes it diﬀerently. For another, it depends heavily

on the considerable transformations that cvx applies to your model before delivering

it to the solver. So while you may ﬁnd its value interesting we strongly discourage

dependence upon it within your applications.

The tolerance levels that cvx selects by default have been inherited from the

underlying solvers being used, with minor modiﬁcations. cvx actually considers three

diﬀerent tolerance levels

solver

≤

standard

≤

reduced

when solving a model:

• The solver tolerance

solver

is the level requested of the solver. The solver will

stop as soon as it achieves this level, or until no further progress is possible.

44

• The standard tolerance

standard

is the level at which cvx considers the model

solved to full precision.

• The reduced tolerance

reduced

is the level at which cvx considers the model

“inaccurately” sovled, returning a status with the Inaccurate/ preﬁx. If this

tolerance cannot be achieved, cvx returns a status of Failed, and the values of

the variables should not be considered reliable.

(See Appendix C for more information about the status messages.) Typically,

solver

=

standard

, but setting

standard

<

solver

has a useful interpretation: it allows the solver

to search for more accurate solutions without causing an Inaccurate/ or Failed

condition if it cannot do so. The default values of [

solver

,

standard

,

reduced

] are set to

[

1/2

,

1/2

,

1/4

], where = 2.22 10

−16

is the machine precision. This should be quite

suﬃcient for most applications.

If you wish to modify the tolerances, you may do so using the cvx_precision

command. There are three ways to invoke this command. Called with no arguments

it will return the current tolerance levels as a 3-element row vector.

Calling cvx_precision with a string argument allows you to select from a set of

predeﬁned precision modes:

• cvx_precision low: [

3/8

,

1/4

,

1/4

]

• cvx_precision medium: [

1/2

,

3/8

,

1/4

]

• cvx_precision default: [

1/2

,

1/2

,

1/4

]

• cvx_precision high: [

3/4

,

3/4

,

3/8

]

• cvx_precision best: [0,

1/2

,

1/4

]

In function mode, these calls look like cvx_precision(’low’), etc. Note that the

best precision settings sets the solver target to zero, which means that the solver

continues as long as it can make progress. It will often be slower than default, but

it is just as reliable, and sometimes produces more accurate solutions.

Finally, the cvx_precision command can be called with a scalar, a length-2

vector, or a length-3 vector. If you pass it a scalar, it will set the solver and standard

tolerances to that value, and it will compute a default reduced precision value for

you. Roughly speaking, that reduced precision will be the square root of the standard

precision, with some bounds imposed to make sure that it stays reasonable. If you

supply two values, the smaller will be used for the solver and standard tolerances,

and the larger for the reduced tolerance. If you supply three values, their values will

be sorted, and each tolerance will be set separately.

The cvx_precision command can be used either within a cvx model or outside

of it; and its behavior diﬀers in each case. If you call it from within a model, e.g.,

cvx_begin

cvx_precision high

...

cvx_end

45

then the setting you choose will apply only until cvx_end is reached. If you call it

outside a model, e.g.,

cvx_precision high

cvx_begin

...

cvx_end

then the setting you choose will apply globally; that is, to any subsequent models

that are created and solved. The local approach should be preferred in an application

where multiple models are constructed and solved at diﬀerent levels of precision.

If you call cvx_precision in function mode, either with a string or a numeric

value, it will return as its output the previous precision vector—the same result you

would obtain if you called it with no arguments. This may seem confusing at ﬁrst,

but this is done so that you can save the previous value in a variable, and restore it

at the end of your calculations; e.g.,

cvxp = cvx_precision( ’high’ );

cvx_begin

...

cvx_end

cvx_precision( cvxp );

This is considered good coding etiquette in a larger application where multiple cvx

models at multiple precision levels may be employed. Of course, a simpler but equally

courteous approach is to call cvx_precision within the cvx model, as described

above, so that its eﬀect lasts only for that model.

8.3 Miscellaneous cvx commands

• cvx_problem: typing this within a cvx speciﬁcation provides a summary of the

current problem. Note that this will contain a lot of information that you may

not recognize—cvx performs its conversion to canonical form as the problem is

entered, generating extra temporary variables and constraints in the process.

• cvx_clear: typing this resets the cvx system, clearing any and all problems

from memory, but without erasing any of your numeric data. This is useful if

you make a mistake and need to start over. But note that in current versions

of cvx, you can simply start another model with cvx_begin, and the previous

model will be erased (with a warning).

• cvx_quiet: typing cvx_quiet(true) suppresses screen output from the solver.

Typing cvx_quiet(false) restores the screen output. In each case, it returns a

logical value representing the previous state of the quiet ﬂag, so you can restore

that state later if you wish—which is good practice if you wish to share your

code with others.

46

• cvx_pause: typing cvx_pause(true) causes cvx to pause and wait for keyboard

input before and after the solver is called. Useful primarily for demo purposes.

Typing cvx_pause(false) resets the behavior. In each case, it returns a logical

value representing the previous state of the pause ﬂag, so you can restore that

state later if you wish.

• cvx_where: returns the directory where the cvx distribution has been installed—

assuming that the Matlab path has been set to include that distribution. Useful

if you want to ﬁnd certain helpful subdirectories, such as doc, examples, etc.

• cvx_version: returns a description of the cvx version number, build number,

and hardware platform you are currently using. If you encounter a bug in cvx,

please run this function and copy its output into your email message along with

a description of your problem.

8.4 Assignments versus equality constraints

Anyone who has used the C or Matlab languages for a suﬃciently long time un-

derstands the diﬀerences between assignments, which employ a single equals sign =

operator, and an equality, which employs the double equal == operator. In cvx, this

distinction is particularly important; confusing the two operators can have serious

consequences. Even when the distinction is well understood, there are important

caveats to using assignments in cvx that we address here as well.

The consequences of inadvertently using assignments within a cvx speciﬁcation

can cause subtle but critical problems. For example, let A, C ∈ R

n×n

and b ∈ R be

given, and consider the simple SDP

minimize Tr(CX)

subject to Tr(AX) = b

X _ 0

(14)

Suppose that we tried to express this problem in cvx as follows:

1 n = 5;

2 A = randn(n,n); C = randn(n,n); b = randn;

3 cvx_begin

4 variable X(n,n) symmetric;

5 minimize( trace( C * X ) );

6 subject to

7 trace( A * X ) == b;

8 X = semidefinite(n);

9 cvx_end

At ﬁrst glance, line 8 may look like it constrains X to be positive semideﬁnite; but

it is an assignment, not an equality constraint. So X is actually overwritten with an

anonymous, positive semideﬁnite variable, and the original X is not constrained all!

47

Fortunately, this particular error is easily caught and prevented by cvx. When

cvx_end is reached, cvx examines each declared variable to verify that it still points

to the variable object it was originally assigned upon declaration. If it does not, it

will issue an error like this:

??? Error using ==> cvx_end

The following cvx variable(s) have been overwritten:

X

This is often an indication that an equality constraint was

written with one equals ’=’ instead of two ’==’. The model

must be rewritten before cvx can proceed.

We hope that this check will prevent at least some typographical errors from having

frustrating consequences in your models.

Of course, this single check does not prevent you from using all assignments

inside your cvx speciﬁcations, only those that overwrite formally declared variables.

As discussed in '3.8, other kinds of assignments are permitted, and may be genuinely

useful. But in our view they should be used sparingly. For instance, consider the ﬁrst

example from '3.8:

variables x y

z = 2 * x - y;

square( z ) <= 3;

quad_over_lin( x, z ) <= 1;

The following alternative formulation, which declares z as a formal variable, is nu-

merically equivalent:

variables x y z

z == 2 * x - y;

square( z ) <= 3;

quad_over_lin( x, z ) <= 1;

We recommend taking this approach whenever possible. Declaring intermediate cal-

culations as variables provides an extra measure of clarity in your models, and it

exposes more of the model’s structure to the solver, possibly improving performance.

8.5 Indexed dual variables

In some models, the number of constraints depends on the model parameters—not

just their sizes. It is straightforward to build such models in cvx using, say, a Matlab

for loop. In order to assign each of these constraints a separate dual variable, we

must ﬁnd a way to adjust the number of dual variables as well. For this reason,

cvx supports indexed dual variables. In reality, they are simply standard Matlab cell

arrays whose entries are cvx dual variable objects.

48

Let us illustrate by example how to declare and use indexed dual variables. Con-

sider the following semideﬁnite program:

minimize

¸

n

i=1

(n −i)X

ii

subject to

¸

n

i=1

X

i,i+k

= b

k

, k = 1, 2, . . . , n

X _ 0

(15)

([Stu99]). This problem minimizes a weighted sum of the main diagonal of a positive

semideﬁnite matrix, while holding the sums along each diagonal constant. The pa-

rameters of the problem are the elements of the vector b ∈ R

n

, and the optimization

variable is a symmetric matrix X ∈ R

n×n

. The cvx version of this model is

cvx_begin

variable X( n, n ) symmetric

minimize( ( n - 1 : -1 : 0 ) * diag( X ) );

for k = 0 : n-1,

sum( diag( X, k ) ) == b( k+1 );

end

X == semidefinite(n);

cvx_end

If we wish to obtain dual information for the n simple equality constraints, we need

a way to assign each constraint in the for loop a separate dual variable. This is

accomplished as follows:

cvx_begin

variable X( n, n ) symmetric

dual variables y{n}

minimize( ( n - 1 : -1 : 0 ) * diag( X ) );

for k = 0 : n-1,

sum( diag( X, k ) ) == b( k+1 ) : y{k+1};

end

X == semidefinite(n);

cvx_end

The statement

dual variables y{n}

allocates a cell array of n dual variables, and stores the result in the Matlab vari-

able Z. The equality constraint in the for loop has been augmented with a reference

to y{k+1}, so that each constraint is assigned a separate dual variable. When the

cvx_end command is issued, cvx will compute the optimal values of these dual vari-

ables, and deposit them into an n-element cell array y.

This example admittedly is a bit simplistic. With a bit of careful arrangement, it

is possible to rewrite this model so that the n equality constraints can be combined

into a single vector constraint, which in turn would require only a single vector dual

49

variable.

3

For a more complex example that is not amenable to such a simpliﬁcation,

see the ﬁle

examples/cvxbook/Ch07_statistical_estim/cheb.m

in the cvx distribution. In that problem, each constraint in the for loop is a linear

matrix inequality, not a scalar linear equation; so the indexed dual variables are

symmetric matrices, not scalars.

3

Indeed, a future version of cvx will support the use of the Matlab function spdiags, which will

reduce the entire for loop to the single constraint spdiags(X,0:n-1)==b.

50

A Installation and compatibility

cvx requires Matlab 6.5.2 or later. (Previous versions of cvx supported Matlab 6.1,

but this has been discontinued.) Primary cvx development is performed using an

Intel-based Mac running Matlab 7.5, with additional development performed on the

following platforms and Matlab versions:

• Mac (32-bit): Matlab 7.3, 7.5, 7.9

• Mac (64-bit): Matlab 7.9

• Windows (32-bit): Matlab 6.5.2, 7.5, 7.9

• Linux (32-bit): Matlab 6.5.2, 7.5, 7.9

• Linux (64-bit): Matlab 7.3, 7.5, 7.9

For purposes of testing and support, we have access to most other versions of Matlab

for Windows, Linux, and Mac (both Intel and PowerPC).

We strongly recommend against using version 7.0.x of Matlab on any platform.

Version 7.0.0 has exhibited numerical problems for at least one user; the problems

were eliminated by upgrading. We have also identiﬁed another issue using cvx with

Matlab 7.0.1 and 7.0.4; workarounds are provided in 'A.3 below.

Precompiled MEX ﬁles are included for all of the above platforms. For other

platforms (e.g., Solaris), cvx will attempt to compile the MEX ﬁles will be compiled

during the setup process. While cvx is quite likely to work for these platforms, we

are unable to provide support. In particular you are responsible for making sure that

your system is set up to compile MEX ﬁles.

A.1 Basic instructions

1. Retrieve the latest version of cvx from http://www.stanford.edu/

∼

boyd/cvx.

You can download the package as either a .zip ﬁle or a .tar.gz ﬁle.

2. If you have been running a previous version of cvx, remove it or rename it to,

say, cvx_old—before proceeding. DO NOT allow the new version of cvx to be

unpacked on top of the old.

3. Unpack the ﬁle anywhere you like; a directory called cvx will be created. There

is one important exception: do not place cvx in Matlab’s own toolbox directory.

4. Start Matlab.

5. Change the current directory to the location of cvx. For example, if you un-

packed cvx.zip into the directory C:\Matlab\personal, then you would type

cd C:\Matlab\personal\cvx

51

at the Matlab command prompt. Alternatively, if you unpacked cvx.tar.gz

into the directory ~/matlab on a Linux machine, then you would type

cd ~/matlab/cvx

at the Matlab command prompt.

6. Type the command

cvx_setup

at the Matlab prompt. This does two things: it sets the Matlab search path

so it can ﬁnd all of the cvx program ﬁles, and it runs a simple test problem to

verify the installation. If all goes well, the command will output the line

No errors! cvx has been successfully installed.

(among others). If this message is not displayed, or any warnings or errors are

generated, then there is a problem with the cvx installation. Try installing the

package again; and if that fails, send us a bug report and tell us about it.

7. If you plan to use cvx regularly, you will need to save the current Matlab path

for subsequent Matlab sessions. Follow the instructions provided by cvx_setup

to accomplish that.

A.2 About SeDuMi and SDPT3

The cvx distribution includes copies of the solvers SeDuMi and SDPT3 in the direc-

tories cvx/sedumi and cvx/sdpt3, respectively. We strongly recommend that you

use our versions of these solvers, and remove any other versions that you have in your

Matlab path.

A.3 A Matlab 7.0 issue

The techniques that cvx use to embed a new modeling language inside Matlab seem

to cause some confusion for Matlab 7.0, speciﬁcally version 7.0.4 (R14SP2). We are

reasonably conﬁdent that the issue is due to a bug in Matlab itself. It does not occur

in version 6.5.2 or 7.1 and later. It may occur in earlier versions of Matlab 7.0 as well

(R14,R14SP1).

The bug is this: in some circumstances, a .m-ﬁle containing a cvx model will cause

an error that looks like this:

??? Error: File: thrusters.m Line: 43 Column: 5

"p" was previously used as a variable,

conflicting with its use here as the name of a function.

The ﬁle name, line/column numbers, and variable name may diﬀer, but the error

message remains the same. The example that produced this particular error is a

simple inequality constraint

52

p >= -5;

where p is a cvx variable previously declared with a variable statement. Interest-

ingly, a diﬀerent inequality constraint

u >= 0

in the same model causes no complaint. So we cannot oﬀer you a precise set of

circumstances that cause the error.

Fortunately, the workaround is very simple: simply remove all of the extra space

in the constraint. In this example, changing the constraint to

p>=-5;

eliminates the error. You may still indent the constraint as you wish—just remove

the intermediate spaces.

We have no idea why this workaround works, but it does—reliably.

53

B Operators, functions, and sets

B.1 Basic operators and linear functions

Matlab’s standard arithmetic operations for addition +, subtraction -, multiplication

* .*, division / \ ./ ./ .\, and exponentiation ^ .^ have been overloaded to work

in cvx whenever appropriate—that is, whenever their use is consistent with both

standard mathematical and Matlab conventions and the DCP ruleset. For example:

• Two cvx expressions can be added together if they are of the same dimension

(or one is scalar) and have the same curvature (i.e., both are convex, concave,

or aﬃne).

• A cvx expression can be multiplied or divided by a scalar constant. If the

constant is positive, the curvature is preserved; if it is negative, curvature is

reversed.

• An aﬃne column vector cvx expression can be multiplied by a constant matrix

of appropriate dimensions; or it can be left-divided by a non-singular constant

matrix of appropriate dimension.

Numerous other combinations are possible, of course. For example, the use of the

exponentiation operators ^ .^ are somewhat limited; see 'B.2 below.

Matlab’s basic matrix manipulation and arithmetic operations have been extended

to work with cvx expressions as well, including:

• Concatenation: [ A, B ; C, D ]

• Indexing: x(n+1:end), X([3,4],:), etc.

• Indexed assignment, including deletion: y(2:4) = 1, Z(1:4,:) = [], etc.

• Transpose and conjugate transpose: Z.’, y’

A number of Matlab’s basic functions have been extended to work with cvx expres-

sions as well:

conj conv cumsum diag dot find fliplr flipud flipdim horzcat

hankel ipermute kron permute repmat reshape rot90 sparse sum

trace tril triu toeplitz vertcat

Most should behave identically with cvx expressions as they do with numeric ex-

pressions. Those that perform some sort of summation, such as cumsum, sum, or

multiplication, such as conv, dot or kron, can only be used in accordance with the

disciplined convex programming rules. For example, kron(X,Y) is valid only if either

X or Y is constant; and trace(Z) is valid only if the elements along the diagonal have

the same curvature.

54

B.2 Nonlinear functions

What follows are two lists of nonlinear functions supported by cvx: ﬁrst, a list of

standard Matlab functions extended to work with cvx; and second, a list of new

functions created speciﬁcally for use in cvx.

In some cases, limitations of the underlying solvers place certain restrictions or

caveats on their use:

• Functions marked with a dagger (†) are not supported natively by the solvers

that cvx uses. They are handled using a successive approximation method,

which makes multiple calls to the underlying solver, achieving the same ﬁnal

precision. (See 'D.1 for details.) If you use one of these functions, you will be

warned that successive approximation will be used.

• Functions involving powers (e.g., x^p) and p-norms (e.g., norm(x,p)) are marked

with a star (). cvx represents these functions exactly when p is a rational num-

ber. For irrational values of p, a nearby rational is selected using Matlab’s rat

function. See 'D.2 for details.

B.2.1 Built-in functions

• abs: absolute value for real and complex arrays. Convex.

• † exp: exponential. Convex and nondecreasing.

• † log: logarithm. Concave and nondecreasing.

• max: maximum. Convex and nondecreasing.

• min: minimum. Concave and nondecreasing.

• norm: norms for real and complex vectors and matrices. Convex. The one-

argument version norm(x) computes the 2-norm for vectors and induced 2-norm

(maximum singular value) for matrices. The two-argument version norm(x,p)

is supported as follows:

– For vectors, all p ≥ 1 are accepted, but see Appendix D.2 for more details

about how cvx handles values other than 1, 2, and Inf.

– For matrices, p must be 1, 2, Inf, or ’Fro’.

• polyval: polynomial evaluation. polyval(p,x), where p is a vector of length

n, computes

p(1) * x.^(n-1) + p(2) * x.^(n-2) + ... + p(n-1) * x + p(n)

This function can be used in cvx in two ways:

55

– If p is a variable and x is a constant, then polyval(x,p) computes a linear

combination of the elements of p. The combination must satisfy the DCP

rules for addition and scaling.

– If p is a constant and x is a variable, then polyval(x,p) constructs a

polynomial function of the variable x. The polynomial must be aﬃne,

convex, or concave, and x must be real and aﬃne.

• power: x^p and x.^p, where x is a real variable and and p is a real constant.

For x^p, x and p must be scalars. Only those values of p which can reasonably

and unambiguously interpreted as convex or concave are accepted:

– p = 0. Constant. x.^p is identically 1.

– 0 < p < 1. Concave. The argument x must be concave (or aﬃne), and is

implicitly constrained to be nonnegative.

– p = 1. Aﬃne. x.^p is then x.

– p ∈ ¦2, 4, 6, 8, ...¦. Convex. Argument x must be aﬃne.

– p > 1, p ∈ ¦2, 3, 4, 5, ...¦. Convex. Argument x must be aﬃne, and is

implicitly constrained to be nonnegative.

Negative and odd integral values of p are not permitted, but see the functions

pow_p, pow_pos, and pow_abs in the next section for useful alternatives.

• † power: p.^x and p^x, where p is a real constant and x is a real variable. For

p^x, p and x must be scalars. Valid values of p include:

– p ∈ ¦0, 1¦. Constant.

– 0 < p < 1. Convex and nonincreasing; x must be concave.

– p > 1. Convex and nondecreasing; x must be convex.

Negative values of p are not permitted.

• sqrt: square root. Implicitly constrains its argument to be nonnegative. Con-

cave and nondecreasing.

B.2.2 New nonlinear functions

Even though these functions were developed speciﬁcally for cvx, they work outside

of a cvx speciﬁcation as well, when supplied with numeric arguments.

• berhu(x,M): The reversed Huber function (hence, Berhu), deﬁned as [x[ for

[x[ ≤ M, and ([x[

2

+ M

2

)/2M for [x[ ≥ M. Convex. If M is omitted, M = 1

is assumed; but if supplied, it must be a positive constant. Also callable with

three arguments as berhu(x,M,t), which computes t+t*berhu(x/t,M), useful

for concomitant scale estimation (see [Owe06]).

56

• det_inv: determinant of inverse of a symmetric (or Hermitian) positive deﬁnite

matrix, det X

−1

, which is the same as the product of the inverses of the eigenval-

ues. When used inside a cvx speciﬁcation, det_inv constrains the matrix to be

symmetric (if real) or Hermitian (if complex) and positive semideﬁnite. When

used with numerical arguments, det_inv returns +Inf if these constraints are

not met. Convex.

• det_rootn: n-th root of the determinant of a semideﬁnite matrix, (det X)

1/n

.

When used inside a cvx speciﬁcation, det_rootn constrains the matrix to be

symmetric (if real) or Hermitian (if complex) and positive semideﬁnite. When

used with numerical arguments, det_rootn returns -Inf if these constraints

are not met. Concave.

• det_root2n: the 2n-th root of the determinant of a semideﬁnite matrix; i.e.,

det_root2n(X)=sqrt(det_rootn(X)). Concave. Maintained solely for back-

compatibility purposes.

• † entr, the elementwise entropy function: entr(x)=-x.*log(x). Concave.

Returns -Inf when called with a constant argument that has a negative entry.

• geo_mean: the geometric mean of a vector, (

¸

n

k=1

x

k

)

1/n

. When used inside a

cvx speciﬁcation, geo_mean constrains the elements of the vector to be non-

negative. When used with numerical arguments, geo_mean returns -Inf if any

element is negative. Concave and increasing.

• huber(x,M), deﬁned as 2M[x[ −M

2

for [x[ ≥ M, and [x[

2

for [x[ ≤ M. Convex.

If M is omitted, then M = 1 is assumed; but if it supplied, it must be a positive

constant. Also callable as huber(x,M,t), which computes t+t*huber(x/t,M),

useful for concomitant scale estimation (see [Owe06]).

• huber_circ(x,M), the circularly symmetric Huber function, deﬁned as |x|

2

for |x|

2

≤ M, and 2M|x|

2

− M

2

for |x|

2

≥ M. Same (and implemented) as

huber_pos(norm(x),M). Convex.

• huber_pos(x,M). Same as Huber function for nonnegative x; zero for negative

x. Convex and nondecreasing.

• inv_pos, inverse of the positive portion, 1/ max¦x, 0¦. Inside cvx speciﬁcation,

imposes constraint that its argument is positive. Outside cvx speciﬁcation,

returns +∞ if x ≤ 0. Convex and decreasing.

• † kl_div, elementwise Kullback-Leibler distance, kl_div(x,y)=x.*log(x./y)-x+y,

for x, y nonnegative, with x(i) zero whenever y(i) is zero. Convex. Outside

cvx speciﬁcation, returns +∞ if arguments aren’t in the domain.

• lambda_max: maximum eigenvalue of a real symmetric or complex Hermitian

matrix. Inside cvx, imposes constraint that its argument is symmetric (if real)

or Hermitian (if complex). Convex.

57

• lambda_min: minimum eigenvalue of a real symmetric or complex Hermitian

matrix. Inside cvx, imposes constraint that its argument is symmetric (if real)

or Hermitian (if complex). Concave.

• lambda_sum_largest(X,k): sum of the largest k values of a real symmetric or

complex Hermitian matrix. Inside cvx, imposes constraint that its argument is

symmetric (if real) or Hermitian (if complex). Convex.

• lambda_sum_smallest(X,k): sum of the smallest k values of a real symmetric

or complex Hermitian matrix. Inside cvx, imposes constraint that its argument

is symmetric (if real) or Hermitian (if complex). Concave.

• log_det: log of determinant of a positive deﬁnite matrix, log det(X). When

used inside a cvx speciﬁcation, log_det constrains its argument to be symmet-

ric (if real) or Hermitian (if complex) and positive deﬁnite. With numerical

argument, log_det returns -Inf if these constraints are not met. Concave.

• log_normcdf(x): logarithm of cumulative distribution function of standard

normal random variable. Concave and increasing. The current implementation

is a fairly crude SDP-representable approximation, with modest accuracy over

the interval [−4, 4]; we intend to replace it with a much better approximation

at some point.

• † log_sum_exp(x): the logarithm of the sum of the elementwise exponentials

of x. Convex and nondecreasing. This is used internally in expert GP mode,

but can also be used in standard DCPs.

• logsumexp_sdp: a polynomial approximation to the log-sum-exp function with

global absolute accuracy. This approximation is used in default GP mode, but

can also be used in standard DCPs.

• matrix_frac(x,Y): matrix fractional function, x

T

Y

−1

x. In cvx, imposes con-

straint that Y is symmetric (or Hermitian) and positive deﬁnite; outside cvx,

returns +∞ unless Y = Y

T

~ 0. Convex.

• norm_largest( x, k ), for real and complex vectors, returns the sum of the

largest k magnitudes in the vector x. Convex.

• norm_nuc(X), is the sum of the singular values of a real or complex matrix X.

(This is the dual of the usual spectral matrix norm, i.e., the largest singular

value.) Convex.

• norms( x, p, dim ) and norms_largest( x, k, dim ). Computes vector

norms along a speciﬁed dimension of a matrix or N-d array. Useful for sum-of-

norms and max-of-norms problems. Convex.

• poly_env( p, x ). Computes the value of the convex or concave envelope

of the polynomial described by p (in the polyval sense). p must be a real

58

−1.5 −1 −0.5 0 0.5 1 1.5

−0.2

0

0.2

0.4

0.6

0.8

1

1.2

1.4

1.6

(x

2

−1)

2

envelope

Figure 2: The polynomial function p(x) = x

4

−2x

2

+ 1 and its convex envelope.

constant vector whose length n is 0, 1, 2, 3, or some other odd length; and x

must be real and aﬃne. The sign of the ﬁrst nonzero element of p determines

whether a convex (positive) or concave (negative) envelope is constructed. For

example, consider the function p(x) (x

2

−1)

2

= x

4

−2x

2

+1, depicted along

with its convex envelope in Figure 2. The two coincide when [x[ ≥ 1, but

deviate when [x[ < 1. Attempting to call polyval([1,0,2,0,1],x) in a cvx

model would yield an error, but a call to poly_env([1,0,2,0,1],x) yields a

valid representation of the envelope. For convex or concave polynomials, this

function produces the same result as polyval.

• pos: max¦x, 0¦, for real x. Convex and increasing.

• pow_abs(x,p): [x[

p

for x ∈ R or x ∈ C and p ≥ 1. Convex. If p is irrational,

a nearby rational value is chosen; see Appendix D.2 for details.

• pow_pos(x,p): max¦x, 0¦

p

for x ∈ R and p ≥ 1. Convex and nondecreasing.

If p is irrational, a nearby rational value is chosen; see Appendix D.2 for details.

• pow_p(x,p), for x ∈ R and real constant p computes nonnegative convex and

59

concave branches of the power function:

p ≤ 0 : f

p

(x)

x

p

x > 0

+∞ x ≤ 0

convex, nonincreasing

0 <p ≤ 1 : f

p

(x)

x

p

x ≥ 0

−∞ x < 0

concave, nondecreasing

p ≥ 1 : f

p

(x)

x

p

x ≥ 0

+∞ x < 0

convex, nonmonotonic

• quad_form(x,P), x

T

Px for real x and symmetric P, and x

H

Px for complex x

and Hermitian P. Convex in x for P constant and positive semideﬁnite; concave

in x for P constant and negative semideﬁnite. This function is provided since

cvx will not recognize x’*P*x as convex (even when P is positive semideﬁnite).

• quad_over_lin, x

T

x/y for x ∈ R

n

, y > 0; for x ∈ C

n

, y > 0: x

∗

x/y. In cvx

speciﬁcation, adds constraint that y > 0. Outside cvx speciﬁcation, returns

+∞ if y ≤ 0. Convex, and decreasing in y.

• quad_pos_over_lin: sum_square_pos( x ) / y for x ∈ R

n

, y > 0. Convex,

increasing in x, and decreasing in y.

• † rel_entr: Scalar relative entropy: rel_entr(x,y)=x.*log(x/y). Convex.

• sigma_max: maximum singular value of real or complex matrix. Same as norm.

Convex.

• square: x

2

for x ∈ R. Convex.

• square_abs: [x[

2

for x ∈ R or x ∈ C.

• square_pos: max¦x, 0¦

2

for x ∈ R. Convex and increasing.

• sum_largest(x,k) sum of the largest k values, for real vector x. Convex and

increasing.

• sum_smallest(x,k), sum of the smallest k values, i.e., -sum_largest(-x,k).

Concave and decreasing.

• sum_square: sum( square( x ) ). Convex.

• sum_square_abs: sum( square_abs( x ) ). Convex.

• sum_square_pos: sum( square_pos( x ) ); works only for real values. Con-

vex and increasing.

• trace_inv(X), trace of the inverse of an SPD matrix X, which is the same as

the sum of the inverses of the eigenvalues. Convex. Outside of cvx, returns

+Inf if argument is not positive deﬁnite.

60

• trace_sqrtm(X), trace of the matrix squareroot of a positive semideﬁnite ma-

trix X. which is the same as the sum of the squareroots of the eigenvalues.

Concave. Outside of cvx, returns +Inf if argument is not positive semideﬁnite.

B.3 Sets

cvx currently supports the following sets; in each case, n is a positive integer constant.

• nonnegative(n):

R

n

+

¦ x ∈ R

n

[ x

i

≥ 0, i = 1, 2, . . . , n¦

• simplex(n):

R

n

1+

¦ x ∈ R

n

[ x

i

≥ 0, i = 1, 2, . . . , n,

¸

i

x

i

= 1 ¦

• lorentz(n):

Q

n

¦ (x, y) ∈ R

n

R [ |x|

2

≤ y ¦

• rotated_lorentz(n):

Q

n

r

¦ (x, y, z) ∈ R

n

RR [ |x|

2

≤

√

yz, y, z ≥ 0 ¦

• complex_lorentz(n):

Q

n

c

¦ (x, y) ∈ C

n

R [ |x|

2

≤ y ¦

• rotated_complex_lorentz(n):

Q

n

rc

¦ (x, y, z) ∈ C

n

RR [ |x|

2

≤

√

yz, y, z ≥ 0 ¦

• semidefinite(n):

S

n

+

¸

X ∈ R

n×n

[ X = X

T

, X _ 0

¸

• hermitian_semidefinite(n):

H

n

+

¸

Z ∈ C

n×n

[ Z = Z

H

, X _ 0

¸

• nonneg_poly_coeffs(n): The cone of all coeﬃcients of nonnegative polyno-

mials of degree n; n must be even:

P

+,n

p ∈ R

n+1

[

n

¸

i=0

p

i+1

x

n−i

≥ 0 ∀x ∈ R

¸

61

• convex_poly_coeffs(n): The cone of all coeﬃcients of convex polynomials of

degree n; n must be even:

P

+,n

p ∈ R

n+1

[

n−2

¸

i=0

(n −i)(n −i −1)p

i+1

x

n−i−2

≥ 0 ∀x ∈ R

¸

• exponential_cone:

E cl

¸

(x, y, z) ∈ RRR [ y > 0, ye

x/y

≤ z

¸

• geo_mean_cone(n):

G

n

cl

(x, y) ∈ R

n

R

n

R

n

[ x ≥ 0, (

n

¸

i=1

x

i

)

1/n

≥ y

¸

62

C cvx status messages

After a complete cvx speciﬁcation has been entered and the cvx_end command issued,

the solver is called to generate a numerical result. The solver can produce one of ﬁve

exit conditions, which are indicated by the value of the string variable cvx_status.

The nominal values of cvx_status, and the resulting values of the other variables,

are as follows:

• Solved: A complementary (primal and dual) solution has been found. The

primal and dual variables are replaced with their computed values, and the the

optimal value of the problem is placed in cvx_optval (which, by convention, is

0 for feasibility problems).

• Unbounded: The problem has been proven to be unbounded below through the

discovery of an unbounded primal direction. This direction is stored in the

primal variables. The value of cvx_optval is set to -Inf for minimizations,

and +Inf for maximizations. Feasibility problems by construction cannot be

unbounded below.

It is important to understand that the unbounded primal direction is very likely

not a feasible point. If a feasible point is required, the problem should be re-

solved as a feasibility problem by omitting the objective.

• Infeasible: The problem has been proven to be infeasible through the discov-

ery of an unbounded dual direction. Appropriate components of this direction

are stored in the dual variables. The values of the primal variables are ﬁlled with

NaNs. The value of cvx_optval is set to +Inf for minimizations and feasibility

problems, and -Inf for maximizations.

In some cases, the solver is unable to achieve the numerical certainty it requires to

make one of the above determinations—but is able to draw a weaker conclusion by

relaxing those tolerances somewhat; see '8.2. In such cases, one of the following

results is returned:

• Inaccurate/Solved: The problem is likely to have a complementary solution.

• Inaccurate/Unbounded: The problem is likely to be unbounded.

• Inaccurate/Infeasible: The problem is likely to be infeasible.

The values of the primal and dual variables, and of cvx_optval, are updated identi-

cally to the “accurate” cases. Two ﬁnal results are also possible:

• Failed: The solver failed to make suﬃcient progress towards a solution. The

values of cvx_optval and primal and dual variables are ﬁlled with NaNs. This

result can occur because of numerical problems within SeDuMi, often because

the problem is particularly “nasty” in some way (e.g., a non-zero duality gap).

63

• Overdetermined: The presolver has determined that the problem has more

equality constraints than variables, which means that the coeﬃcient matrix

of the equality constraints is singular. In practice, such problems are often,

but not always, infeasible. Unfortunately, solvers typically cannot handle such

problems, so a precise conclusion cannot be reached.

The situations that most commonly produce an Overdetermined result are discussed

in 'D.3 below.

64

D Advanced solver topics

D.1 The successive approximation method

Prior to version 1.2, the functions requested most often to be added to the cvx

function library were those from the exponential family, including exp, log, and

various entropy functions. Unfortunately, cvx utilizes symmetric primal/dual solvers

that simply cannot support those functions natively; and a variety of practical factors

has delayed the use of other types of solvers with cvx.

For this reason, we have constructed a successive approximation method that

allows symmetric primal/dual solvers to support the exponential family of functions.

The precise nature of the method will be published elsewhere, but we can provide

a highly simpliﬁed description here. First, we construct a global approximation for

exp (or log, etc..) which is accurate within a neighborhood of some center point

x

0

. Solving this approximation yields an approximate optimal point ¯ x. We shift the

center point x

0

towards ¯ x, construct a new approximation, and solve again. This

process is repeated until [¯ x −x

0

[ is small enough to conclude that our approximation

is accurate enough to represent the original model. Again, this is a highly simpliﬁed

description of the approach; for instance, we actually employ both the primal and

dual solutions to guide our judgements for shifting x

0

and terminating.

So far, we have been pleased with the eﬀectiveness of the successive approximation

method. Nevertheless, we believe that it is necessary to issue a warning when it is used

so that users understand its experimental nature. Therefore, the ﬁrst time that you

solve a problem that will require successive approximation, cvx will issue a warning

saying so. If you wish to suppress this warning, insert the command

cvx_expert true

into your model before the ﬁrst use of such features.

D.2 Irrational powers

In order to implement power expressions like x

p

and p-norms |x|

p

for 1 < p < ∞, cvx

uses an SDP-compatible method described in [AG01], and enhanced by the authors

of cvx. This approach is exact—as long as the exponent p is rational. To determine

integral values p

n

, p

d

such that p

n

/p

d

= p, cvx uses Matlab’s rat function with its

default tolerance of 10

−6

. There is currently no way to change this tolerance. See the

documentation for rat for more details.

The complexity of the SDP implementation depends on roughly on the size of the

values p

n

and p

d

. Let us introduce a more precise measure of this complexity. For

p = 2, a constraint x

p

≤ y can be represented with exactly one 2 2 LMI:

x

2

≤ y =⇒

¸

y x

x 1

_ 0.

For other values of p = p

n

/p

d

, cvx generates a number of 22 LMIs that depends on

both p

n

and p

d

; we denote this number by k(p

n

, p

d

). (A number of internal variables

65

and equality constraints are also generated, but we ignore them for this analysis.) An

empirical study has shown that for p = p

n

/p

d

> 1, cvx achieves

k(p

n

, p

d

) ≤ log

2

p

n

+ α(p

n

),

where the α(p

n

) term grows very slowly compared to the log

2

term. Indeed, for

p

n

≤ 4096, we have veriﬁed that α(p

n

) is usually 1 or 2, but occasionally 0 or 3.

Similar results are obtained for 0 < p < 1 and p < 0.

The cost of this SDP representation is relatively small for nearly all useful values of

p. Nevertheless, cvx issues a warning whenever k(p

n

, p

d

) > 10 to insure that the user is

not surprised by any unexpected slowdown. In the event that this threshold does not

suit you, you may change it using the command cvx_power_warning(thresh), where

thresh is the desired cutoﬀ value. Setting the threshold to Inf disables it completely.

As with the command cvx_precision, you can place a call to cvx_power_warning

within a model to change the threshold for a single model; or outside of a model

to make a global change. The command always returns the previous value of the

threshold, so you can save it and restore it upon completion of your model, if you wish.

You can query the current value by calling cvx_power_warning with no arguments.

D.3 Overdetermined problems

This status message Overdetermined commonly occurs when structure in a variable

or set is not properly recognized. For example, consider the problem of ﬁnding the

smallest diagonal addition to a matrix W ∈ R

n×n

to make it positive semideﬁnite:

minimize Trace D

subject to W + D _ 0

D diagonal

(16)

In cvx, this problem might be expressed as follows:

n = size(W,1);

cvx_begin

variable D(n,n) diagonal;

minimize( trace( D ) );

subject to

W + D == semidefinite(n);

cvx_end

If we apply this speciﬁcation to the matrix W=randn(5,5), a warning is issued,

Warning: Overdetermined equality constraints;

problem is likely infeasible.

and the variable cvx_status is set to Overdetermined.

What has happened here is that the unnamed variable returned by statement

semidefinite(n) is symmetric, but W is ﬁxed and unsymmetric. Thus the problem,

66

as stated, is infeasible. But there are also n

2

equality constraints here, and only

n + n ∗ (n + 1)/2 unique degrees of freedom—thus the problem is overdetermined.

The following modiﬁed version of the speciﬁcation corrects this problem by extracting

the symmetric part of W:

n = size(W,1);

cvx_begin

variable D(n,n) diagonal;

minimize( trace( D ) );

subject to

0.5 * ( W + W’ ) + D == semidefinite(n);

cvx_end

E Acknowledgements

We wish to thank the following people for their contributions to the development of

cvx: Toh Kim Chuan, Laurent El Ghaoui, Arpita Ghosh, Siddharth Joshi, Johan

L¨ofberg, Almir Mutapcic, Michael Overton and his students, Art Owen, Rahul Pan-

icker, Imre Polik, Jo¨elle Skaf, Lieven Vandenberghe, Argyris Zymnis. We are also

grateful to the many students in several universities who have (perhaps unwittingly)

served as beta testers by using cvx in their classwork. We thank Igal Sason for catch-

ing many typos in an earlier version of this document, and generally helping us to

improve its clarity.

67

References

[AG01] F. Alizadeh and D. Goldfarb. Second-order cone programming. Techni-

cal Report RRR 51-2001, RUTCOR, Rutgers University, November 2001.

Available at http://rutcor.rutgers.edu/pub/rrr/reports2001/51.ps.

[BKMR98] A. Brooke, D. Kendrick, A. Meeraus, and R. Raman. GAMS: A User’s

Guide. The Scientiﬁc Press, South San Francisco, 1998. Available at http:

//www.gams.com/docs/gams/GAMSUsersGuide.pdf.

[BKVH05] S. Boyd, S. J. Kim, L. Vandenberghe, and A. Hassibi. A tutorial on

geometric programming. Optimization and Engineering, 2005. Available at

http://www.stanford.edu/

∼

boyd/gp tutorial.html.

[BV04] S. Boyd and L. Vandenberghe. Convex Optimization. Cambridge Univer-

sity Press, 2004. Available at http://www.stanford.edu/

∼

boyd/cvxbook.

html.

[Cru02] C. Crusius. A Parser/Solver for Convex Optimization Problems. PhD

thesis, Stanford University, 2002.

[DV05] J. Dahl and L. Vandenberghe. CVXOPT: A Python Package for Convex

Optimization. Available at http://www.ee.ucla.edu/

∼

vandenbe/cvxopt,

2005.

[FGK99] R. Fourer, D. Gay, and B. Kernighan. AMPL: A Modeling Language for

Mathematical Programming. Duxbury Press, December 1999.

[GBY06] M. Grant, S. Boyd, and Y. Ye. Disciplined convex programming. In L. Lib-

erti and N. Maculan, editors, Global Optimization: from Theory to Im-

plementation, Nonconvex Optimization and Its Applications, pages 155–

210. Springer, New York, 2006. Available at http://www.stanford.edu/

∼

boyd/disc cvx prog.html.

[Gra04] M. Grant. Disciplined Convex Programming. PhD thesis, Department of

Electrical Engineering, Stanford University, December 2004. See http:

//www.stanford.edu/

∼

boyd/disc cvx prog.html.

[L¨of05] J. L¨ofberg. YALMIP version 3 (software package). http://control.ee.

ethz.ch/

∼

joloef/yalmip.php, September 2005.

[Mat04] The MathWorks, Inc. MATLAB (software package). http://www.

mathworks.com, 2004.

[Mat05] The MathWorks, Inc. MATLAB optimization toolbox (software package).

http://www.mathworks.com/products/optimization/, 2005.

[MOS05] MOSEK ApS. Mosek (software package). http://www.mosek.com, Febru-

ary 2005.

68

[Owe06] A. Owen. A robust hybrid of lasso and ridge regression. Technical report,

Department of Statistics, Stanford University, October 2006. Author’s in-

ternal draft.

[Stu99] J. Sturm. Using SeDuMi 1.02, a MATLAB toolbox for optimization over

symmetric cones. Optimization Methods and Software, 11:625–653, 1999.

Software available at http://sedumi.mcmaster.ca/.

[TTT06] K. Toh, R. T¨ ut¨ unc¨ u, and M. Todd. SDPT3 4.0 (beta) (software package).

http://www.math.nus.edu.sg/

∼

mattohkc/sdpt3.html, July 2006.

[WB00] S.-P. Wu and S. Boyd. SDPSOL: A parser/solver for semideﬁnite programs

with matrix structure. In L. El Ghaoui and S.-I. Niculescu, editors, Recent

Advances in LMI Methods for Control, chapter 4, pages 79–91. SIAM, 2000.

Available at http://www.stanford.edu/

∼

boyd/sdpsol.html.

69

Index

aﬃne function, 28

AMPL, 4

array variable, 17

assignment, 47

banded matrix variable, 17

bug report, 6

complex variable, 17

composition, 29

concave

function, 28

constraint, 11, 13, 18

bounds, 11, 13, 18

equality, 14, 18, 47

inequality, 14, 18

nonconvex, 14, 16

set, 20

convex

function, 28

cvx, 4

functions, 54

installing, 51

operators, 54

precision, 63

status messages, 63

cvx begin, 8

cvx clear, 46

cvx end, 8

cvx expert, 65

cvx optval, 10, 18

cvx pause, 46

cvx power warning, 65

cvx precision, 44

cvx problem, 46

cvx quiet, 46

cvx slvitr, 10

cvx slvtol, 10, 44

cvx solver, 44

cvx status, 10

cvx version, 46

cvx where, 46

CVXOPT, 5

DCP, 4, 5

ruleset, 5, 25

deadzone function, 34

deﬁning new function, 34

diagonal matrix variable, 17

disciplined convex programming, see DCP

dual variable, 21

epigraph, 35

equality constraint, 47

examples, 8

expression, 23

expression holder, 23

expressions, 23

feasibility, 18, 26

feedback, 6

function, 19

cvx library, 54

aﬃne, 28

composition, 29

concave, 28

convex, 28

deadzone, 34

deﬁning new, 34

epigraph, 35

generalized posynomial, 41

Huber, 35

hypograph, 36

monomial, 41

monotonicity, 28

objective, 9

posynomial, 41

quadratic, 32

GAMS, 4

generalized geometric programming, see

GGP

geometric program, see GP

geometric programming mode, 41

GGP, 41

70

GP, 4, 41

mode, 4, 41

Hermitian matrix variable, 17

Huber function, 35

hypograph, 36

inequality

constraint, 18

matrix, 39, 40

infeasible problem, 23

installing cvx, 51

Lagrange multipler, 21

least squares, 8

linear

matrix inequality, see LMI

program, see LP

linprog, 11

LMI, 39

Lorentz cone, see second-order cone

LP, 4, 5

Matlab, 4

maximize, 10, 18

minimize, 9, 18

mode

GP, 41

SDP, 39

monotonicity, 28

MOSEK, 5

nondecreasing, 28

nonincreasing, 28

norm, 9

norm(,1), 12

norm(,Inf), 12, 14

objective function, 9, 18

nonconvex, 10

operators, 54

output

suppressing, 46

overdetermined problem, 66

platforms, 51

posynomial, 41

powers, 65

precision, 63

changing, 44

problem

dual, 21

feasibility, 18, 26

infeasible, 23

overdetermined, 66

python, 4

QP, 4

quadratic form, 32

quadratic program, see QP

SDP, 4, 5, 20, 39

mode, 4, 39

SDPT3, 5, 44

second-order cone, 21

second-order cone program, see SOCP

SeDuMi, 5, 44

semidefinite, 20

semideﬁnite program, see SDP

semideﬁnite programming mode, 39

set, 20

SOCP, 4, 5, 21

solver

changing, 44

status messages, 63

successive approximation, 65

symmetric matrix variable, 17

Toeplitz matrix variable, 17

trade-oﬀ curve, 15

variable

array, 17

banded matrix, 17

complex, 17

declaring, 17

diagonal matrix, 17

Hermitian matrix, 17

structure, 17

symmetric matrix, 17

Toeplitz matrix, 17

variable, 9, 17

variables, 17, 18

71

version information, 5

YALMIP, 4

72

Contents

1 Introduction 1.1 What is cvx? . . . . . . . 1.2 What is disciplined convex 1.3 About this version . . . . 1.4 Feedback . . . . . . . . . . 1.5 What cvx is not . . . . . . . . . . . . . . . programming? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4 5 5 6 6 8 8 10 11 13 15 17 17 17 18 18 19 20 21 23 25 25 26 26 27 28 29 31 32 34 34 35 39 41 41 42 42

2 A quick start 2.1 Least-squares . . . . . . . . . . 2.2 Bound-constrained least-squares 2.3 Other norms and functions . . . 2.4 Other constraints . . . . . . . . 2.5 An optimal trade-oﬀ curve . . . 3 The 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 4 The 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 basics cvx begin and cvx end Data types for variables Objective functions . . . Constraints . . . . . . . Functions . . . . . . . . Sets . . . . . . . . . . . Dual variables . . . . . . Expression holders . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

DCP ruleset A taxonomy of curvature . . . . . . . . Top-level rules . . . . . . . . . . . . . . Constraints . . . . . . . . . . . . . . . Expression rules . . . . . . . . . . . . . Functions . . . . . . . . . . . . . . . . Compositions . . . . . . . . . . . . . . Monotonicity in nonlinear compositions Scalar quadratic forms . . . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

5 Adding new functions to the cvx atom library 5.1 New functions via the DCP ruleset . . . . . . . . . . . . . . . . . . . 5.2 New functions via partially speciﬁed problems . . . . . . . . . . . . . 6 Semideﬁnite programming using cvx 7 Geometric programming using cvx 7.1 Top-level rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

8 Advanced topics 8.1 Solver selection . . . . . . . . . . . . . 8.2 Controlling solver precision . . . . . . . 8.3 Miscellaneous cvx commands . . . . . 8.4 Assignments versus equality constraints 8.5 Indexed dual variables . . . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

44 44 44 46 47 48 51 51 52 52 54 54 55 61 63 65 65 65 66 67

A Installation and compatibility A.1 Basic instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2 About SeDuMi and SDPT3 . . . . . . . . . . . . . . . . . . . . . . . A.3 A Matlab 7.0 issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . B Operators, functions, and sets B.1 Basic operators and linear functions . . . . . . . . . . . . . . . . . . . B.2 Nonlinear functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.3 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C cvx status messages D Advanced solver topics D.1 The successive approximation method . . . . . . . . . . . . . . . . . . D.2 Irrational powers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.3 Overdetermined problems . . . . . . . . . . . . . . . . . . . . . . . . E Acknowledgements

3

cvx can greatly simplify the task of specifying the problem. it is easy to compute an optimal trade-oﬀ curve by forming and solving a family of optimization problems by varying the constraints. including many involving nondiﬀerentiable functions. such as a branch and bound method. 4 . As another example. Model speciﬁcations are constructed using common Matlab operations and functions. or DCPs. and many others. and generalized posynomials. cvx can be used as a component of a larger system that uses convex optimization. see the book Convex Optimization [BV04]. which enables them to be analyzed and solved eﬃciently. available at www. and transforms such problems into convex form so that they can be solved eﬃciently. For background on convex optimization. cvx applies a matrix interpretation to the inequality operator. and many other problems. In SDP mode. however. you need to know at least a bit about convex optimization.html. The modeling language follows the spirit of AMPL [FGK99] or GAMS [BKMR98]. In GP mode. quadratic programs (QPs). second-order cone programs (SOCPs).1 Introduction What is cvx? cvx is a modeling system for disciplined convex programming. with input from Yinyu Ye.stanford. and semideﬁnite programs (SDPs).stanford. The speciﬁc method for implementing cvx in Matlab draws heavily from YALMIP [L¨f05].edu/∼boyd/cvxbook/. cvx can solve standard problems such as linear programs (LPs). Dahl and Vandenberghe [DV05]. entropy maximization. It incorporates ideas from earlier work by L¨fberg [L¨f05]. but compared to directly using a solver for one or these types of problems. unlike these packages. so that linear matrix inequalities (LMIs) and SDPs may be expressed in a more natural form. cvx can also solve much more complex convex optimization problems. Crusius [Cru02]. available on-line at www. For background on geometric programming. This combination makes it simple to perform the calculations needed to form optimization problems. determinant maximization. or the Stanford course EE364A. or to process the results obtained from their solution. and was implemented by Michael Grant [GBY06]. cvx is implemented in Matlab [Mat04]. Wu and o o Boyd [WB00]. are convex optimization problems that are described using a limited set of construction rules. such as 1 norms. or an engineering design framework. You can use cvx to conveniently formulate and solve constrained norm minimization. and standard Matlab code can be freely mixed with these speciﬁcations.edu/class/ee364a/. posynomials. cvx was designed from the beginning to fully exploit convexity. available at www. see the tutorial paper [BKVH05]. cvx accepts all of the special functions and combination rules of geometric programming. To use cvx eﬀectively. cvx was designed by Michael Grant and Stephen Boyd. including monomials. eﬀectively turning Matlab into an optimization modeling language.stanford. For example.edu/∼boyd/papers/ gp tutorial. cvx also provides special modes to simplify the construction of problems from two speciﬁc problem classes. Disciplined convex programs. We also hope to develop versions o of cvx for other platforms in the future.1 1.

These problems are handled by solving a sequence (typically just 5 . The ruleset is simple to learn. and it is important for anyone who intends to actively use cvx to understand it. power functions xp . cvx will convert the speciﬁed problem to an LP. SOCPs. SDPs. and is drawn from basic principles of convex analysis. Stephen Boyd. when all the functions in the problem speciﬁcation can be represented in these forms. such as MOSEK [MOS05] or CVXOPT [DV05]. A detailed description of the DCP ruleset is given in §4. such as minimum and maximum. exp. The log of the normal cumulative distribution log Φ(x) is replaced with an SDP-compatible approximation. which is the default. Gra04]. even when the problem is convex.1. or SDP. This version of cvx supports two core solvers. we obtain considerable beneﬁts. the minimum and maximum eigenvalues of a symmetric matrix. For a few functions. when a power function or p -norm is used. This includes a wide variety of functions. absolute value.2 What is disciplined convex programming? Disciplined convex programming is a methodology for constructing convex optimization problems proposed by Michael Grant. and combinations thereof. 1. and p norms (both for p rational). or SDP. and full support for nondiﬀerentiable functions. Future versions of cvx may support other solvers. Problems handled with successive approximation. Problems that violate the ruleset are rejected. which we call the DCP ruleset. quadratic forms. For example. including log. SeDuMi [Stu99] and SDPT3 [TTT06]. In practice. Problems which adhere to the ruleset can be rapidly and automatically veriﬁed as convex and converted to solvable form. SOCP. This version of cvx adds support for a number of functions that cannot be exactly represented via LP. we have found that disciplined convex programs closely resemble their natural mathematical forms.3 About this version Supported solvers. In return for accepting the restrictions imposed by the ruleset. SOCP. That is not to say that such problems cannot be solved using DCP. and SDP solver. Disciplined convex programming imposes a set of conventions or rules. Problems handled exactly. and Yinyu Ye [GBY06. cvx replaces p with a nearby rational. SeDuMi and SDPT3 are open-source interior-point solvers written in Matlab for LPs. entropy. with non-rational exponent p. such as automatic conversion of problems to solvable form. cvx will make a (good) approximation to transform the speciﬁed problem to one that can be handled by a combined LP. they just need to be rewritten in a way that conforms to the DCP ruleset. log-sum-exp log(exp x1 +· · ·+exp xn ). Problems handled with (good) approximations. It is meant to support the formulation and construction of optimization problems that the user intends from the outset to be convex. SOCP. and KullbackLeibler divergence.

4 Feedback Please contact Michael Grant (mcgrant@stanford. On the other hand. We emphasize that most users do not need to know how cvx handles their problem. its error messages) can be very helpful in learning some basic convex analysis. or use the online help function by typing help cvx/builtins (for functions already in Matlab. so we can reproduce and ﬁx the problem: • the cvx model and supporting data that caused the error • a copy of any error messages that it produced • the cvx version number and build number • the version number of Matlab that you are running • the name and version of the operating system you are using The latter three items can all be discovered by typing cvx_version at the MATLAB command prompt. when one of these functions is used. an approximation was made.edu) with your comments. if cvx accepts your problem. which yields the solution to the full accuracy of the core solver. For this reason. otherwise you are the proverbial monkey at the typewriter. you can be sure it is convex. If you discover what you think is a bug. we will interface cvx to a solver with native support for such functions. On the other hand. You need to know a bit about convex optimization to eﬀectively use cvx. users should be aware that problems involving these functions can be slow to solve using the current version of cvx. in previous versions.edu) or Stephen Boyd (boyd@stanford. hoping to (accidentally) type in a valid disciplined convex program. While 6 . 1. cvx (especially. which result in a large speedup in solving problems with these functions. Ultimately. this technique can be substantially slower than if the core solver directly handled such functions. The successive approximation method is brieﬂy described in Appendix D. see Appendix B.5 What cvx is not cvx is not meant to be a tool for checking if your problem is convex.1. simply copy its output into your email message. such as sqrt or log) or help cvx/functions (for functions not in Matlab.a handful) of SDPs. For a full list of functions supported by cvx. please include the following in your communication. what matters is what functions and operations can be handled. such as lambda_max). the user will be warned that the successive approximate technique will be used. In conjunction with a course on (or self study of) convex optimization. Until then. Geometric problems are now solved in this manner as well. 1.

cvx will attempt to give helpful error messages when you violate the DCP ruleset. to get the eﬃciency you need. For such problems cvx can play an important role. however. you might use cvx to experiment with diﬀerent problem formulations on 50 × 50 pixel images. cvx is not meant for very large problems. or to develop your own methods. to rapidly experiment with exactly what problem you want to solve. please do contact us. provided they have exploitable structure (such as sparsity). and functions like log and exp that require successive approximation. Before starting to develop a specialized large-scale method. you can use cvx to solve scaled-down or simpliﬁed versions of the problem. cvx is unlikely to work well (or at all). which can be slow in Matlab. For such problems you will likely need to directly call a solver. cvx will solve many medium and large scale problems. for example. If you encounter diﬃculties in solving large problem instances. a large image processing problem). we may be able to suggest an equivalent formulation that cvx can process more eﬃciently. 7 . it can sometimes give quite obscure error messages. so if your problem is very large (for example. For image reconstruction. and you avoid for loops.

for example.) The line numbers accompanying the code excerpts in this document correspond to the line numbers in the ﬁle quickstart. they are preceded with the statement cvx_begin and followed with the statement cvx_end. the optimization variables declared in the cvx speciﬁcation are converted from objects to ordinary Matlab numerical values that can be used in any further Matlab calculations. Let us create some test problem data for m. by running the quickstart script found in the examples subdirectory of the cvx distribution.. For example. As Matlab reads a cvx speciﬁcation. 2. Within a cvx speciﬁcation. To delineate cvx speciﬁcations from surrounding Matlab code. In addition. then you would type cd D:\Matlab\cvx\examples quickstart at the Matlab command prompt. and pause periodically so you can examine its output. an error message is generated. you can start using it by entering a cvx speciﬁcation into a Matlab script or function. least-squares. cvx also assigns a few other related Matlab variables. they are special Matlab objects. This enables Matlab to distinguish between ordinary commands and cvx objective functions and constraints.1 Least-squares We ﬁrst consider the most basic convex optimization problem.2 A quick start Once you have installed cvx (see §A). n. If the optimization is successful. it completes the conversion of the cvx speciﬁcation to a canonical form. where A ∈ Rm×n is skinny and full rank (i. if you are on Windows. When Matlab reaches the cvx_end command.e. A. and you have installed the cvx distribution in the directory D:\Matlab\cvx. gives the status of the problem (i. or the problem was determined to be infeasible or unbounded). A speciﬁcation can include any ordinary Matlab statements.. If it encounters a violation of the rules of disciplined convex programming (such as an invalid use of a composition rule or an invalid constraint). and b in Matlab: 8 . and calls the underlying core solver to solve it. or directly from the command prompt. instead. In a least-squares problem. (Pressing “Enter” or “Return” resumes progress. it builds an internal representation of the optimization problem. optimization variables have no numerical value. m ≥ n and Rank(A) = n). This processing ﬂow will become more clear as we introduce a number of simple examples. Dual variables can also be assigned. Another gives the optimal value of the problem. The script will automatically print key excerpts of its code.m.e. we seek x ∈ Rn that minimizes Ax − b 2 . One. We invite the reader to actually follow along with these examples in Matlab. whether an optimal solution was found. as well as special cvx-speciﬁc commands for declaring primal and dual optimization variables and specifying constraints and objective functions.

it is also represented by a Matlab object. • Line 25 speciﬁes an objective function to be minimized. i. n = 8. Now x is an ordinary length-n numerical vector. (AT A)−1 AT b. an objective function. two additional Matlab variables are created: 9 . and so forth. and the Matlab variable x is overwritten with the solution of the least-squares problem. The backslash form is clearly simpler—there is no reason to use cvx to solve a simple least-squares problem. If you were to type x at the Matlab prompt after line 24 but before the cvx_end command.e. because the objective function norm(A*x-b) involves a cvx variable. the same problem can be solved as follows: 23 24 25 26 cvx_begin variable x(n). you would see something like this: x = cvx affine expression (8x1 vector) That is because within a speciﬁcation. in this case. the simplest code segment that actually does something useful. Similarly. constraints. In addition.. • Line 26 signals the end of the cvx speciﬁcation. and prepares Matlab to accept variable declarations. b = randn(m. variables have no numeric value. When Matlab reaches the cvx_end command.15 16 17 m = 16. identical to what would be obtained in the traditional approach. minimize( norm(A*x-b) ).. A = randn(m. • Line 24 declares x to be an optimization variable of dimension n. But this example serves as sort of a “Hello world!” program in cvx.) Let us examine this speciﬁcation line by line: • Line 23 creates a placeholder for the new cvx speciﬁcation. i. cvx requires that all problem variables be declared before they are used in an objective function or constraints.1). the Euclidean or 2 -norm of Ax − b. they are Matlab objects designed to represent problem variables and expressions involving them. it does not have a numeric value either. rather. at least to within the accuracy of the solver.n). Using cvx.) Then the leastsquares solution x = (AT A)−1 AT b is easily computed using the backslash operator: 20 x_ls = A \ b. and causes the problem to be solved. (We chose small values of m and n to keep the output readable.e. the least-squares problem is solved. cvx_end (The indentation is used for purely stylistic reasons and is optional.

2 ). 1 10 .1 There is not much room for error in specifying a simple least-squares problem. but it can be transformed into a quadratic program (QP). ui ≤ vi for all i. 2 ). [].. i. and cvx_status. []. Any variable that begins with the preﬁx cvx is reserved for internal use by cvx itself. you can use the quadprog function to solve the problem as follows: If you type who or whos at the command prompt. cvx_optval. • cvx_slvtol: the tolerance level achieved by the solver. • cvx_slvitr: the number of iterations taken by the solver. which asks for the norm to be maximized.2). you will get an error message stating that a convex function cannot be maximized (at least in disciplined convex programming): ??? Error using ==> maximize Disciplined convex programming error: Objective function in a maximization must be concave. etc. you may see other. which contains the value of the objective function. i. The vector inequality u v means componentwise. All of these quantities. vectors with the same dimension as the variable x.. you will get an error or warning message. Then if you have the Matlab Optimization Toolbox [Mat05].. if you replace line 25 with maximize( norm(A*x-b) ). may now be freely used in other Matlab statements. which contains a string describing the status of the calculation. We can no longer use the simple backslash notation to solve this problem. • cvx_status.e. (1) where l and u are given data. l = min( bnds. In this case. cvx_status would contain the string Solved. just like any other numeric or string values. For example. u = max( bnds.2 Bound-constrained least-squares Suppose we wish to add some simple upper and lower bounds to the least-squares problem above: i. but if you make one. Let us provide some numeric values for l and u: 47 48 49 bnds = randn(n. we wish to solve minimize Ax − b 2 subject to l x u.e. 2.e. x. Ax − b 2 . unfamiliar variables as well. See Appendix C for a list of the possible values of cvx_status and their meaning. and should not be changed. which can be solved without diﬃculty if you have some form of QP software available.• cvx_optval.

1 ]. For all but the simplest cases.bne). which is the same as minimizing the norm itself. For example. This actually minimizes the square of the norm. more readable. the problem is solved. the cvx speciﬁcation is longer than the Matlab alternative. As before. as in our ﬁrst.1]).3 Other norms and functions Now let us consider some alternatives to the least-squares problem. bne = [ +b.:). to ﬁnd the value of x that minimizes the Chebyshev norm Ax−b ∞ . the quadprog version requires us to know in advance the transformation to QP form. cvx can handle these problems directly. it will transform it into an SOCP.. []. §6. In contrast. The result is the same. cvx will not transform this problem into a QP by squaring the objective. cvx_end Three new lines of cvx code have been added to the cvx speciﬁcation: • The subject to statement on line 62 does nothing—cvx provides this statement simply to make speciﬁcations more readable. subject to x >= l. [].1) ].. On the other hand. In contrast. minimize( norm(A*x-b) ).g. -ones(m. . because these norms are part of cvx’s base library of functions. and more compact than equivalent Matlab code to solve the same problem. when the cvx_end command is reached. the cvx speciﬁcation is given by 59 60 61 62 63 64 65 cvx_begin variable x(n). it is easier to read the cvx version and relate it to the original problem. []. x_cheb = xt(1:n. 11 f Ane . and solved using a linear programming solver such as linprog in the Matlab Optimization Toolbox (see. Norm minimization problems involving the ∞ or 1 norms can be reformulated as LPs. = [ +A. -A. It is entirely optional. -ones(m.1) .Ane. -b ].53 x_qp = quadprog( 2*A’*A. l. and the numerical solution is assigned to the variable x. In this example. xt = linprog(f. a cvx speciﬁcation is simpler. • Lines 63 and 64 represent the 2n inequality constraints l x u. 2. and the transformation is done automatically. we can employ the linprog command from the Matlab Optimization Toolbox: 97 98 99 100 101 102 = [ zeros(n.. [].1). e. [BV04. u ). Incidentally. instead. including the calculations such as 2*A’*A and -2*A’*b. -2*A’*b. However. x <= u.

k) ).[].b. zeros(m. it reduces to the 1 norm. Similarly. each will produce an x that minimizes Ax−b ∞ . however. (When k = 1. The cvx version is. The advantage that automatic transformation provides is magniﬁed if we consider functions (and their resulting transformations) that are less well-known than the ∞ and 1 norms. however.1). minimize( norm(A*x-b.With cvx. linprog(f.k = |Ax − b|[1] + · · · + |Ax − b|[k] .[]). but the transformation is by no means obvious so we will omit it here.1). it reduces to the ∞ norm. minimize( norm_largest(A*x-b. and the cvx speciﬁcation above will both solve the Chebyshev norm minimization problem. we can use linprog as follows: 139 140 141 142 143 f Aeq lb xzz x_l1 = = = = = [ zeros(n.. xzz(1:n.1). cvx_end cvx automatically transforms both of these problems into LPs. the dimension of Ax − b. cvx_end 12 . This is indeed a norm. to minimize the 1 norm · 1 . must have the same value of Ax − b ∞ .Inf) ). +eye(m) ]. ones(m.:). cvx_end The code based on linprog. cvx_begin variable x(n). [ A.1) ]. and has the name norm_largest. not surprisingly.k over x can be cast as an LP.) The problem of minimizing Ax − b lgst. [ -Inf(n.1). when k = m. not unlike those generated manually for linprog. albeit a fairly esoteric one. The two points. For example.e. minimize( norm(A*x-b.lb.[]. so the particular x’s produced by the two methods can be diﬀerent. Chebyshev norm minimization problems can have multiple optimal points.1) ). But this norm is provided in the base cvx library. consider the norm Ax − b lgst. so to specify and solve the problem using cvx is easy: 179 180 181 182 183 k = 5. ones(m. zeros(m. i. 149 150 151 152 cvx_begin variable x(n).Aeq.1) ]. the same problem is speciﬁed as follows: 108 109 110 111 cvx_begin variable x(n). where |Ax − b|[i] denotes the ith largest element of the absolute values of the entries of Ax − b. -eye(m).

though. the norm is available as an ordinary Matlab function outside a cvx speciﬁcation. (The cvx user.3 above is as simple as inserting the lines x >= l. C = randn(p.k) The ﬁrst line displays the optimal value as determined by cvx. before the cvx_end statement in each cvx speciﬁcation. For example. 13 . cvx supports more complex constraints as well. and has been provided in the cvx function library. The list of supported nonlinear functions in cvx goes well beyond norm and norm_largest. consider the Huber penalty minimization problem minimize m i=1 φ((Ax − b)i ). it is not surprising that adding the simple bounds l to the problems in §2. In fact. minimize( sum(huber(A*x-b)) ). x is a numerical vector. 2 . however. x <= u.) 2. this norm is not part of the standard Matlab distribution. does not need to know how the transformation is carried out. cvx_end cvx automatically transforms this problem into an SOCP. The Huber penalty function is convex. by now. 227 228 229 p = 4. with variable x ∈ Rn . d = randn(p.Unlike the 1 . so we can type cvx_optval norm_largest(A*x-b. So solving the Huber penalty minimization problem in cvx is simple: 204 205 206 207 cvx_begin variable x(n).n). For example. the second recomputes the same value from the optimal vector x as determined by cvx. where φ is the Huber penalty function φ(z) = |z|2 |z| ≤ 1 2|z| − 1 |z| ≥ 1. or ∞ norms.1). Once you have installed cvx. which the core solver then solves. let us deﬁne new matrices C and d in Matlab as follows. For example.4 Other constraints x u We hope that. once the code above is processed.

because x is a declared variable. as is the case with many numerical algorithms. cvx requires that the left. cvx converts this problem to an SOCP. For example. Inequality constraints of the form f (x) ≤ g(x) or g(x) ≥ f (x) are accepted only if f can be veriﬁed as convex and g veriﬁed as concave. So a constraint such as norm(x. whether its ∞ -norm is less than or equal to. it returns a 1 or a 0 depending on the numeric value of x (speciﬁcally. 1). On the other hand. within a cvx speciﬁcation. Expressions using comparison operators (==. Because cvx is designed to support convex optimization.Now let us add an equality constraint and a nonlinear inequality constraint to the original least-squares problem: 232 233 234 235 236 237 238 cvx_begin variable x(n). but often not exactly. immediately after the cvx end command above.) behave quite diﬀerently when they involve cvx optimization variables. To that end.Inf) <= 1. For example. 2 14 .eq Disciplined convex programming error: Both sides of an equality constraint must be affine.hand sides of an equality constraint be aﬃne. So the equality constraints will be satisﬁed closely.Inf) >= 1.Inf) == 1. if x has an appropriate numeric value— for example immediately after the cvx_end command—that same expression would return a vector of 1s and 0s. cvx_end Both of the added constraints conform to the DCP rules. etc. >=. In fact. solutions are determined only to within some nonzero numeric tolerance. This is because. corresponding to the truth or falsity of each equality. outside of it.Inf)<=1 adds a nonlinear constraint to the speciﬁcation. and so are accepted by cvx. you would likely ﬁnd that most if not all of the values returned would be 0. than when they involve simple numeric values. norm(x.and right. So a constraint such as norm(x. subject to C*x == d. and returns no value at all.2 Likewise. or more than. or expressions constructed from cvx optimization variables. the expression C*x==d in line 236 above causes a constraint to be included in the cvx speciﬁcation. outside of a cvx speciﬁcation. it must be able to verify that problems are convex. and solves it. results in the following error: ??? Error using ==> cvx. the statement norm(x. cvx adopts certain construction rules that govern how constraint and objective expressions are constructed. minimize( norm(A*x-b) ). After the cvx_end command.

1) ). ylabel( ’norm(A*x-b)’ ). l1norm(k). This gives us points on the optimal trade-oﬀ curve between Ax − b 2 and x 1 . The speciﬁcs of the construction rules are discussed in more detail in §4 below.4e %8. grid Line 277 of this code segment illustrates one of the construction rules to be discussed in §4 below. An example of this curve is given in Figure 1. ’ gamma norm(x. fprintf( 1. The following code solves the problem of minimizing Ax − b 2 + γ x 1 . minimize( norm(A*x-b)+gamma(k)*norm(x. gamma(k) ).results in the following error: ??? Error using ==> cvx. ’%8.1) norm(A*x-b)\n’ ). for k = 1:length(gamma). fprintf( 1. 2. cvx recognizes such combinations and allows them to be used anywhere a simple convex function can be—such as an objective function to be minimized. 2. cvx_end l1norm(k) = norm(x.4e’. or on the appropriate side of an inequality constraint.1). 20 ). ’---------------------------------------\n’ ). ’ %8. l2norm(k) = norm(A*x-b). for a logarithmically spaced vector of (positive) values of γ. or added to another convex function. xlabel( ’norm(x. fprintf( 1.ge Disciplined convex programming error: The left-hand side of a ">=" inequality must be concave. and the result is then convex. fprintf( 1. the expression 15 . cvx_begin variable x(n). l2norm = zeros(size(gamma)). A basic principle of convex analysis is that a convex function can be multiplied by a nonnegative scalar. l1norm = zeros(size(gamma)). end plot( l1norm.5 An optimal trade-oﬀ curve For our ﬁnal example in this section. let us show how traditional Matlab code and cvx speciﬁcations can be mixed to form and solve multiple optimization problems. 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 gamma = logspace( -2.4e\n’. l2norm(k) ).1)’ ). These rules are relatively intuitive if you know the basics of convex analysis and convex optimization. l2norm ). So in our example.

5 2 norm(x.plus Disciplined convex programming error: Addition of convex and concave terms is forbidden.5 3 3.6 3.3. If gamma(k) were negative.4 3.1) on line 277 is recognized as convex by cvx. 16 .2 3 2. which causes cvx to generate the following error: ??? Error using ==> cvx.8 2.6 2.4 2. norm(A*x-b)+gamma(k)*norm(x.2 2 norm(A*x−b) 0 0. lines 268-286. as long as gamma(k) is positive or zero. then this expression becomes the sum of a convex term and a concave term.5 1 1.5 Figure 1: An example trade-oﬀ curve from the quickstart demo.1) 2.

Variables can be real or complex. 17 . or n-dimensional arrays.1) (or banded(1)) is a tridiagonal matrix. objective functions. For example. X is a real 20×10 matrix variable. The currently supported structure keywords are: banded(lb. If both lb and ub are zero. and scalar. All variable declarations. the code segment variable variable variable variable w(50) complex. the structure keywords are self-explanatory: • banded(lb. The structure of a variable is given by supplying a list of descriptive keywords after the name and size of the variable. Y(50. For example.1 The basics cvx begin and cvx end All cvx models must be preceded by the command cvx_begin and terminated with the command cvx_end.ub) complex diagonal hankel hermitian lower_bidiagonal lower_hessenberg lower_triangular scaled_identity skew_symmetric symmetric toeplitz tridiagonal upper_bidiagonal upper_hankel upper_hessenberg upper_triangular With a couple of exceptions. (inside a cvx speciﬁcation) declares that w is a complex 50-element vector variable. such as symmetry or bandedness.100) hermitian toeplitz. and Z is a complex 100 × 100 Hermitian Toeplitz matrix variable. cvx_begin sdp and cvx_begin gp invoke special semideﬁnite and geometric programming modes. X(20. and constraints should fall in between. The structure keywords can be applied to n-dimensional arrays as well: each 2-dimensional “slice” of the array is given the stated structure. vector. see below) before they can be used in constraints or an objective function.10). Y is a real 50×50 symmetric matrix variable. Additionally. matrices can have structure as well.2 Data types for variables As mentioned above. respectively. for instance. 3. cvx_begin sdp quiet invokes SDP mode and silences the solver output.3 3. matrix. For instance. In addition.50) symmetric. These modiﬁers may be combined when appropriate.ub): the matrix is banded with a lower bandwidth lb and an upper bandwidth ub. discussed in §6 and §7. all variables must be declared using the variable command (or the variables command. banded(1. then a diagonal matrix results. Z(100. cvx_begin quiet prevents the model from producing any screen output while it is being solved. in which case it is set equal to lb. ub can be omitted. The cvx_begin command accepts several modiﬁers that you may ﬁnd useful.

< inequality constraints. <= and >=. > constraints. In cvx. or +Inf.. The one limitation of the variables command is that it cannot declare complex or structured arrays (e.• scaled_identity: the matrix is a (variable) multiple of the identity matrix. if the constraints are not feasible. and the right-hand expression is convex. the strict inequalities < and > are accepted. 3..4 Constraints The following constraint types are supported in cvx: • Equality == constraints. This is the same as declaring it to be diagonal and Toeplitz. if the keywords conﬂict. as appropriate.e. using the singular variable command.10. We encourage you to use the nonstrict 18 .and right-hand sides are aﬃne functions of the optimization variables. 3.g. constant along antidiagonals). For this reason. A variable statement can be used to declare only a single variable. which is the same as performing a minimization with the objective function set to zero. (For the beneﬁt of our users with a British inﬂuence. see the section on deﬁning new functions in §5). • Less-than <=..e. When multiple keywords are supplied. At most one objective function may be declared in a given cvx speciﬁcation..3 Objective functions Declaring an objective function requires the use of the minimize or maximize function. then an error will result. where the left-hand expression is convex. cvx_optval is either 0.e. the synonyms minimise and maximise are provided as well. If no objective function is speciﬁed. variables x1 x2 x3 y1(10) y2(10. respectively.). • upper_hankel: The matrix is Hankel (i. etc. (For the only exception to this rule. the variables statement is provided which allows you to declare multiple variables.10).) The objective function in a call to minimize must be convex. symmetric. the problem is interpreted as a feasibility problem. if a feasible point is found. i. where the left-hand expression is concave. In this case. These must be declared one at a time. the resulting matrix structure is determined by intersection. for i + j > n + 1. and the objective function must have a scalar value. • Greater-than >=. which can be a bit inconvenient if you have a lot of variables to declare. where both the left. and the right-hand expression is concave. i. but interpreted as the associated nonstrict inequalities. and zero below the central antidiagonal. the objective function in a call to maximize must be concave.

concave. and y is a positive scalar.. and min. for more on this distinction. in an appropriate constraint.) These equality and inequality operators work for arrays.forms <= and >=. if a and b are m×n matrices. As an example. and returns a real number. We can. since they are mathematically correct. i. It’s not quite the same as the expression ((A*x-b)’*(A*x-b))/(c’*x+d). with the (same) scalar appearing on the other side. when cT x + d is negative. b and c are vectors. trace. cvx recognizes this objective expression as a convex function. it just computes its (numerical) value. c’*x+d ) ).4. It’s also possible to add your own new functions. 3. others are new functions not found in Matlab. sqrt. In this case.c’*x+d) returns +Inf if cT x + d > 0. 19 . A is a matrix.e. which imposes an equality constraint (inside a cvx speciﬁcation). minimize the quadratic-over-linear function of (Ax − b. A complete list of the functions in the base library can be found in §B. This is interpreted as a constraint for each element of the array. each entry of a must be less than or equal to the corresponding entry of b. max. assuming x is a vector optimization variable. which is an assignment. Also note that the non-equality operator ~= may not be used in a constraint. (Future versions of cvx might assign a slightly diﬀerent meaning to strict inequalities. with domain Rn × R++ . deﬁned as f (x.6.) The quadraticover-linear function is convex in x and y.5 Functions The base cvx function library includes a variety of convex. Inequalities cannot be used if either side is complex. and d is a scalar. but we’ll consider real x to keep things simple. and aﬃne functions which accept cvx variables or expressions as arguments. re-implemented as needed to support cvx. cvx also handles cases where one side is a scalar and the other is an array. given (numerical) arguments. if a is an m × n matrix. such constraints are rarely convex. y) = xT x/y. x is an arbitrary vector in Rn . cvx also supports a set membership constraint. however. An example of a function in the base library is quad_over_lin. then a<=b is interpreted by cvx as mn (scalar) inequalities. or in a more complicated expression. cT x + d) using minimize( quad_over_lin( A*x-b. but quad_over_lin(A*x-b. since it is the composition of a convex function (the quadratic-overlinear function) with an aﬃne function. You can also use the function quad_over_lin outside a cvx speciﬁcation. and ==. and so can be used as an objective.e. Many are common Matlab functions such as sum. When both sides of the constraint are arrays of the same size. which represents the quadratic-over-linear function. (The function also accepts complex x. then a>=0 is interpreted as mn inequalities: each element of the matrix must be nonnegative. see §8. For example. diag. Note also the important distinction between =.. see §3. see §5. i. inside a cvx speciﬁcation. for example. This expression makes sense. the constraint is imposed elementwise. in any case.

we use the syntax X == semidefinite(n). we can impose constraints of the form A*X*A’-X == B*semidefinite(n)*B’. Sets can be combined in aﬃne expressions. consider the constraint that a (matrix) variable X is a correlation matrix. In cvx we can declare such a variable and impose such constraints using variable X(n. diag(X) == ones(n. and we can constrain an aﬃne expression to be in a convex set. Consider. the Matlab language does not have a set membership operator. so the second line can be read as ‘X is positive semideﬁnite’. equivalent to saying that X must be symmetric positive semideﬁnite. the semideﬁnite constraint above can be replaced by X <In> semidefinite(n). To represent a set we use a function that returns an unnamed variable that is required to be in the set. If this use of equality constraints to represent set membership remains confusing or simply aesthetically displeasing. we have create a “pseudo-operator” <In> that you can use in its place. because cvx follows the Matlab convention of handling array/scalar comparisons by comparing each element of the array independently with the scalar. This is.6 Sets cvx supports the deﬁnition and use of convex sets.1). and various norm balls. for example. X == semidefinite(n). which returns an unnamed new variable. Incidentally. of course. So in cvx. As an example. has unit diagonal elements. Sn . feel free to use it. Implementing this operator required some Matlab trickery. for example. So. that is constrained to be positive semideﬁnite. cvx allows us to simplify the third line to diag(X) == 1. (You can read ‘==’ here as ‘is’. we represent + this by the function semidefinite(n). In cvx. The literal meaning of this is that X is constrained to be equal to some unnamed variable. and is positive semideﬁnite. to denote x ∈ S.n) symmetric. whose elements we require to be equal to one. The base library includes the cone of positive semideﬁnite n × n matrices.. so don’t expect to be able to use it outside of cvx models. To require that the matrix expression X be symmetric positive semideﬁnite.3.) The lefthand side of the third line is a vector containing the diagonal elements of X. but if you ﬁnd it more pleasing. This is exactly equivalent to using the equality constraint operator. i.e. the second-order or Lorentz cone. it is symmetric. A complete list of sets supplied in the base library is given in §B. we use a slightly diﬀerent syntax to require that an expression is in a set. the cone of symmetric positive semideﬁnite n × n matrices. which is required to be an n × n symmetric positive semideﬁnite matrix. Unfortunately. such as x in S. For example. 20 . The second line here imposes the constraint that X be positive semideﬁnite.

cvx_end The function call lorentz(m) returns an unnamed variable (i. and associate them with the constraints. for some Y ∈ Sn . As an example. 3.) The optimal dual variables.where X is an n × n symmetric variable matrix. each of which is associated with a constraint in the original problem. This constraint requires that AXAT − X = BY B T .7 Dual variables When a disciplined convex program is solved. To represent the primal problem and this dual variable in cvx. Consider. you simply declare them. a pair consisting of a vector and a scalar variable). for example. y) ∈ Rm × R | x 2 ≤ y } = epi · 2. constrained to lie in the Lorentz cone of length m. we use the following syntax: 21 . So the constraint in this speciﬁcation requires that the pair { A*x-b. give valuable information about the original problem. y } lies in the appropriately-sized Lorentz cone. with variable x ∈ Rn . An element of Qm is an ordered list. such as the sensitivities with respect to perturbing the constraints [BV04. minimize( y ). and A and B are n × n constant matrices. cvx uses Matlab’s cell array facility to mimic this notation: cvx_begin variables x(n) y. where the dual variable y is associated with the inequality constraint Ax b in the original LP. Ch. the LP minimize cT x subject to Ax b. We can use this cone to express the simple least-squares problem from §2. the original problem is called the primal problem. consider the second-order or Lorentz cone. + cvx also supports sets whose elements are ordered lists of quantities. (In this context. subject to { A*x-b. y) ∈ Qm . Qm = { (x. To get access to the optimal dual variables in cvx. The dual of this problem is maximize −bT y subject to c + AT y = 0 y 0.5].1 (in a fairly complicated way) as follows: minimize y (3) subject to (Ax − b. y } <In> lorentz(m). the associated dual problem is also solved. and m inequality constraints.. and the second is a scalar. (2) where epi denotes the epigraph of a function.e. with two elements: the ﬁrst is an m-vector.

swapping the left. subject to y : A * x <= b. This new behavior is in eﬀect only when a dual variable is present. For equality constraints. yields an identical result. minimize( c’ * x ). cvx_begin variable x(n). In addition. cvx assigns numerical values to x and y—the optimal primal and dual variable values. they are automatically determined from the constraint with which it is associated. m. . and assuming the optimization was successful. dual variable y. . and the line y : A * x <= b. which means that the sense of the inequality can be reversed without changing the dual variable’s value. You can check this in Matlab with the line 22 i = 1.2). (4) . for example. For example. where it is used to construct numeric sequences like 1:10.e. Optimal primal and dual variables for this LP must satisfy the complementary slackness conditions yi (b − Ax)i = 0. on the other hand. .hand sides of an equality constraint will negate the optimal value of the dual variable. typing y at the Matlab command prompt immediately before cvx_end yields y = cvx dual variable (20x1 vector) It is not necessary to place the dual variable on the left side of the constraint.. . Notice how the colon : operator is being used in a diﬀerent manner than in standard Matlab. associates it with the inequality constraint. i. cvx_end The line dual variable y tells cvx that y will represent the dual variable. if m = 20. the line above can also be written in this way: A * x <= b : y. b >= A * x : y. so there should be no confusion or conﬂict.n = size(A. No dimensions are given for y. dual variables for inequality constraints will always be nonnegative. After the cvx_end statement is processed.and right. respectively.

y .* (b-A*x) which prints out the products of the entries of y and b-A*x, which should be nearly zero. This line must be executed after the cvx_end command (which assigns numerical values to x and y); it will generate an error if it is executed inside the cvx speciﬁcation, where y and b-A*x are still just abstract expressions. If the optimization is not successful, because either the problem is infeasible or unbounded, then x and y will have diﬀerent values. In the unbounded case, x will contain an unbounded direction; i.e., a point x satisfying cT x = −1, Ax 0, (5)

and y will be ﬁlled with NaN values, reﬂecting the fact that the dual problem is infeasible. In the infeasible case, x is ﬁlled with NaN values, while y contains an unbounded dual direction; i.e., a point y satisfying bT y = −1, AT y = 0, y 0 (6)

Of course, the precise interpretation of primal and dual points and/or directions depends on the structure of the problem. See references such as [BV04] for more on the interpretation of dual information. cvx also supports the declaration of indexed dual variables. These prove useful when the number of constraints in a model (and, therefore, the number of dual variables) depends upon the parameters themselves. For more information on indexed dual variables, see §8.5.

3.8

Expression holders

Sometimes it is useful to store a cvx expression into a Matlab variable for future use. For instance, consider the following cvx script: variables x y z = 2 * x - y; square( z ) <= 3; quad_over_lin( x, z ) <= 1; The construction z = 2 * x - y is not an equality constraint; it is an assignment. It is storing an intermediate calculation 2 * x - y, which is an aﬃne expression, which is then used later in two diﬀerent constraints. We call z an expression holder to diﬀerentiate it from a formally declared cvx variable. For more on the critical diﬀerences between assignment and equality, see Section §8.4. Often it will be useful to accumulate an array of expressions into a single Matlab variable. Unfortunately, a somewhat technical detail of the Matlab object model can cause problems in such cases. Consider this construction: variable u(9); x(1) = 1; 23

for k = 1 : 9, x(k+1) = sqrt( x(k) + u(k) ); end This seems reasonable enough: x should be a vector whose ﬁrst value is 1, and whose subsequent values are concave cvx expressions. But if you try this in a cvx model, Matlab will give you a rather cryptic error: ??? The following error occurred converting from cvx to double: Error using ==> double Conversion to double from cvx is not possible. The reason this occurs is that the Matlab variable x is initialized as a numeric array when the assignment x(1)=1 is made; and Matlab will not permit cvx objects to be subsequently inserted into numeric arrays. The solution is to explicitly declare x to be an expression holder before assigning values to it. We have provided keywords expression and expressions for just this purpose, for declaring a single or multiple expression holders for future assignment. Once an expression holder has been declared, you may freely insert both numeric and cvx expressions into it. For example, the previous example can be corrected as follows: variable u(9); expression x(10); x(1) = 1; for k = 1 : 9, x(k+1) = sqrt( x(k) + u(k) ); end cvx will accept this construction without error. You can then use the concave expressions x(1), . . . , x(10) in any appropriate ways; for example, you could maximize x(10). The diﬀerences between a variable object and an expression object are quite signiﬁcant. A variable object holds an optimization variable, and cannot be overwritten or assigned in the cvx speciﬁcation. (After solving the problem, however, cvx will overwrite optimization variables with optimal values.) An expression object, on the other hand, is initialized to zero, and should be thought of as a temporary place to store cvx expressions; it can be assigned to, freely re-assigned, and overwritten in a cvx speciﬁcation. Of course, as our ﬁrst example shows, it is not always necessary to declare an expression holder before it is created or used. But doing so provides an extra measure of clarity to models, so we strongly recommend it.

24

4

The DCP ruleset

cvx enforces the conventions dictated by the disciplined convex programming ruleset, or DCP ruleset for short. cvx will issue an error message whenever it encounters a violation of any of the rules, so it is important to understand them before beginning to build models. The rules are drawn from basic principles of convex analysis, and are easy to learn, once you’ve had an exposure to convex analysis and convex optimization. The DCP ruleset is a set of suﬃcient, but not necessary, conditions for convexity. So it is possible to construct expressions that violate the ruleset but are in fact convex. As an example consider the entropy function, − n xi log xi , deﬁned for i=1 x > 0, which is concave. If it is expressed as - sum( x .* log( x ) ) cvx will reject it, because its concavity does not follow from any of the composition rules. (Speciﬁcally, it violates the no-product rule described in §4.4.) Problems involving entropy, however, can be solved, by explicitly using the entropy function, sum(entr( x )) which is in the base cvx library, and thus recognized as concave by cvx. If a convex (or concave) function is not recognized as convex or concave by cvx, it can be added as a new atom; see §5. √ As another example consider the function x2 + 1 = [x 1] 2 , which is convex. If it is written as norm([x 1]) (assuming x is a scalar variable or aﬃne expression) it will be recognized by cvx as a convex expression, and therefore can be used in (appropriate) constraints and objectives. But if it is written as sqrt(x^2+1) cvx will reject it, since convexity of this function does not follow from the cvx ruleset.

4.1

A taxonomy of curvature

In disciplined convex programming, a scalar expression is classiﬁed by its curvature. There are four categories of curvature: constant, aﬃne, convex, and concave. For a function f : Rn → R deﬁned on all Rn , the categories have the following meanings: constant: aﬃne: convex: concave: f (αx + (1 − α)y) = f (x) ∀x, y ∈ Rn , α ∈ R f (αx + (1 − α)y) = αf (x) + (1 − α)f (y) ∀x, y ∈ Rn , α ∈ R f (αx + (1 − α)y) ≤ αf (x) + (1 − α)f (y) ∀x, y ∈ Rn , α ∈ [0, 1] f (αx + (1 − α)y) ≥ αf (x) + (1 − α)f (y) ∀x, y ∈ Rn , α ∈ [0, 1]

25

constant expressions are also aﬃne. where both sides are aﬃne. consisting of one or more constraints. 4. strict inequalities <. • A greater-than inequality constraint. For example. so it is suﬃcient to simply verify the remaining portion of the set membership constraint. An equality constraint with a real side and a complex side has the eﬀect of constraining the imaginary part of the complex side to be zero. constructed using ~=. using either >= or >. for example. inequality constraints. the returned value of set atoms like semidefinite() and lorentz() is aﬃne. > are interpreted identically to nonstrict inequalities >=. and (real) aﬃne expressions are both convex and concave. are never allowed. • A maximization problem. x ∈ S) using equality constraints. consisting of a concave objective function and zero or more constraints.2 Top-level rules cvx supports three diﬀerent types of disciplined convex programs: • A minimization problem. For composite values like { x. As discussed in §3. cvx enforces set membership constraints (e. Complex constant and aﬃne expressions can be constructed. The rule that both sides of an equality constraint must be aﬃne applies to set membership constraints as well. where the left side is concave and the right side is convex. Eventually cvx will ﬂag strict inequalities so that they can be veriﬁed after the optimization is carried out. In this version. A complex equality constraint is equivalent to two real equality constraints. y }. 26 . <=. • A feasibility problem. they cannot appear as the left. on the other hand. using either <= or <. one for the real part and one for the imaginary part.or right-hand side of an inequality constraint. Non-equality constraints. 4..Of course. where the left side is convex and the right side is concave. must be real.6 above.g. • A less-than inequality constraint. there is signiﬁcant overlap in these categories. Convex and concave expressions are real by deﬁnition. each element must be aﬃne.) One or both sides of an equality constraint may be complex. constructed using ==. but their usage is more limited. consisting of a convex objective function and zero or more constraints.3 Constraints Three types of constraints may be speciﬁed in disciplined convex programs: • An equality constraint. (Such constraints are not convex. In fact.

– the product of a concave expression and a nonpositive constant. 9. – a concave scalar quadratic form (§4. – a valid call to a function in the atom library with an aﬃne result. • A valid aﬃne expression is – a valid constant expression.8). • A valid constant expression is – any well-formed Matlab expression that evaluates to a ﬁnite value. – the sum of two or more concave expressions. – a convex scalar quadratic form (§4. 27 . – the sum or diﬀerence of aﬃne expressions. it is for the most part an enumeration of basic rules of convex analysis for combining convex. concave. – the product of a convex expression and a nonnegative constant.8). in that all convex programs (disciplined or otherwise) typically adhere to them. 7. p = 3. 1). and so forth. • A valid concave expression is – a valid constant or aﬃne expression. While this list may seem long. . – a declared variable. Disciplined convex programming determines the curvature of scalar expressions by recursively applying the following rules. the rules as stated are not particularly restrictive. – the product of an aﬃne expression and a constant. 5. – the negation of a concave expression.. – a valid call to a function in the atom library with a concave result. • A valid convex expression is – a valid constant or aﬃne expression. – a concave scalar raised to a power p ∈ (0.4 Expression rules So far. What distinguishes disciplined convex programming from more general convex programming are the rules governing the construction of the expressions used in objective functions and constraints.. and aﬃne forms: sums.. – a valid call to a function in the atom library with a convex result.4. multiplication by scalars. – the diﬀerence between a convex expression and a concave expression. – the sum of two or more convex expressions. – an aﬃne scalar raised to a constant power p ≥ 1.

nonincreasing. it is rejected by cvx. 4. – the product of a convex expression and a nonpositive constant. as we shall see in §4. then jumps up to 0 for argument zero.6 below. – the negation of a convex expression. (It can be expressed as x^(3/2) or pow_p(x. Of particular note is that these expression rules generally forbid products between nonconstant expressions. there are much smaller. convex and concave functions in cvx are interpreted as their extended-valued extensions.5 Functions In cvx. For example. but its convexity cannot be veriﬁed using the cvx ruleset. convex functions are interpreted as +∞ when the argument is outside the domain of the function. aﬃne. equivalent sets of rules. where x is a variable.3/2). If an expression cannot be categorized by this ruleset.. with the exception of scalar quadratic forms (see §4. including the values of the argument outside its domain.e. then x will automatically be constrained to be larger than or equal to −1. 28 . these rules are applied on an elementwise basis. Some examples are given in the table below. – the product of a concave expression and a nonnegative constant. Monotonicity determines how they can be used in function compositions. x>=-1. In other words. There is no need to add a separate constraint. For matrix and array expressions. and increases for positive values of its argument. however.) We call this the no-product rule. and concave functions are interpreted as −∞ when the argument is outside its domain. the expression x*sqrt(x) happens to be a convex function of x. Monotonicity of a function is determined in the extended sense. i. For example. convex. For example. or concave) and monotonicity (nondecreasing.8 below). and so is rejected. and paying close attention to it will go a long way to insuring that the expressions you construct are valid. to enforce this. or nonmonotonic). sqrt(x) is determined to be nondecreasing since its value is constant (−∞) for negative values of its argument.4 above.– the diﬀerence between a concave expression and a convex expression. We note that the set of rules listed above is redundant. the categorization is straightforward. functions are categorized in two attributes: curvature (constant. Curvature determines the conditions under which they can appear in expressions according to the expression rules given in §4. For functions with only one argument. Function Meaning Curvature Monotonicity sum( x ) aﬃne nondecreasing i xi abs( x ) |x| convex nonmonotonic √ sqrt( x ) x concave nondecreasing Following standard practice in convex analysis. This has the eﬀect of automatically constraining the argument of a function to be in the function’s domain. if we form sqrt(x+1) in a cvx speciﬁcation.

concave. fp (x) x p So it seems ﬁtting that we should refer to such arguments as parameters in this context as well.g.) It is in the cvx atom library.. or aﬃne only for a subset of its arguments. provided its argument is real. This function squares its argument. For functions with multiple arguments. and known to be convex. As an example.*x. but monotonicity can be considered on an argument-by-argument basis. concave. or aﬃne function may accept an aﬃne expression (of compatible size) as an argument. a is a constant n-vector. or aﬃne. Whenever this function is used in a cvx speciﬁcation. fp (x) : Rn → R. e. This function is convex for x > 0. This is part of the DCP ruleset as well: • A convex. Such arguments correspond to a function’s parameters in mathematical terminology. and b is a constant. you can express the concave portion of 1/x. For example. whenever we speak of a cvx function as being convex. y ) |x|2 /y +∞ y>0 y≤0 convex.. the expression square( a’ * x + b ) 29 . then. some functions are convex. even if the argument is constrained to lie in one of these portions. or aﬃne. which restricts x to lie in the convex portion of function 1/x. respectively. quad_over_lin( x. constant values. For example. it squares each element independently. and concave for x < 0. but it is monotonic only in its second argument. nonincreasing in y is jointly convex in both arguments. But you can never write 1/x in cvx (unless x is constant). 4. In cvx. So if x is a real variable of dimension n. concave. the remaining arguments must be constant. curvature is always considered jointly. consider the function square( x ). (For array arguments. You can use the cvx function inv_pos(x). The result is convex. it computes x. nonmonotonic is convex only in its ﬁrst argument.e.6 Compositions A basic rule of convex analysis is that convexity is closed under composition with an aﬃne mapping. which is provided in the cvx atom library. Henceforth. cvx recognizes this function as convex and nonincreasing. p ) x p (1 ≤ p) convex in x. where x is negative. even if you have imposed a constraint such as x>=1. using -inv_pos(-x). i. consider the function 1/x. For example. In addition. the function norm( x.cvx does not consider a function to be convex or concave if it is so only over a portion of its domain. concave. deﬁned as 1/x for x > 0 and ∞ otherwise. or cvx will issue an error message. we will assume that its parameters are known and have been given appropriate. which will be correctly recognized as concave and nonincreasing. for the convex portion of 1/x.

including as a special case. and classiﬁed as convex and concave. The corresponding rules for a concave function are as follows: • If the function is nondecreasing in an argument. For example. We consider a function.2. which knows that it is convex. and is classiﬁed as convex. and a sum of convex (concave) functions is convex (concave). The maximum function is convex and nondecreasing in every argument. • If the function is neither nondecreasing or nonincreasing in an argument. the rules are: • If the function is nondecreasing in an argument. that accepts multiple arguments. with the exception of scalar quadratic expressions.is accepted by cvx. and classiﬁed as concave. Therefore the expressions sum( square( x ) ) sum( sqrt( x ) ) are recognized as valid in cvx. and the second one follows from the ﬁrst rule for concave functions. Recall that a constant or aﬃne expression is both convex and concave. then max( abs( x ) ) obeys the ﬁrst of the six composition rules and is therefore accepted by cvx. The aﬃne composition rule above is a special case of a more sophisticated composition rule. In this case. The ﬁrst one follows from the ﬁrst rule for convex functions. that argument must be aﬃne. of known curvature and monotonicity. • If the function is nonincreasing in an argument. which we describe now. the entire DCP ruleset can be thought of as special cases of these six rules. • If the function is nonincreasing in an argument. For convex functions. If each argument of the function satisﬁes these rules. • If the function is neither nondecreasing or nonincreasing in an argument. which is both convex and concave (since it is aﬃne). then the expression is accepted by cvx. that argument must be aﬃne. consider the sum function. constant. that argument must be concave. Most people who know basic convex analysis like to think of these examples in terms of the more speciﬁc rules: a maximum of convex functions is convex. In fact. if x is a vector variable. and nondecreasing in each argument.4]. see [BV04. For more background on these composition rules. As another example. the expression is accepted by cvx. that argument must be convex. so any argument can be aﬃne. §3. so it can accept any convex expressions as arguments. respectively. that argument must be concave. and classiﬁed as convex. that argument must be convex. Let us examine some examples. But these rules are just special 30 .

But cvx will reject the expression.3-norm(A*x-b) is concave. This has some consequences that are not so obvious. and f are constants with appropriate dimensions. But 31 .cases of the general composition rules above. Now consider the second term min(4. cvx recognizes that min is concave and nondecreasing. cvx recognizes the expression sqrt(f’*x) + min(4. and so will be rejected by cvx.1. This expression is in fact convex. cvx recognizes that sqrt is concave and f’*x is aﬃne. b. Consider the term sqrt(f’*x).3-norm(A*x-b)). so some expressions which are in fact convex or concave will fail to satisfy them. because the outer square cannot accept a convex argument. For example. One way is to write it as x^4 + 2*x^2 + 1. so it concludes that sqrt(f’*x) is concave. The whole expression is then recognized as concave. Suppose x is a vector variable. so it can accept concave arguments. since it is the sum of two concave functions. applied to the function (x2 −1)2 . the square of a convex function is not.1. There are several ways to modify the expression above to comply with the ruleset. which represents the function (x+ )2 . Of course. Obviously. because there is no rule governing the composition of a concave nondecreasing function with a convex function. (x2 − 1)2 = x4 − 2x2 + 1 is not convex. as we shall demonstrate here by example. The composition rules are suﬃcient but not necessary for the classiﬁcation to be correct. since its second term is concave. in general. since norm is in the atom library and known by cvx to be convex. Now we consider a more complex example in depth. if x is a vector variable. and A. square and square_pos coincide when their arguments are nonnegative. where x+ = max{0.3-norm(A*x-b)) as concave. Consider the expression square( square( x ) + 1 ) where x is a scalar variable. Indeed. the expression sqrt( sum( square( x ) ) ) is rejected by cvx. a nonpositive multiple of a convex (concave) function is concave (convex). Some other well known basic rules that follow from the general composition rules are: a nonnegative multiple of a convex (concave) function is convex (concave).) Another approach is to use the alternate outer function square_pos. since (x2 + 1)2 = x4 + 2x2 + 1 is convex. (Note that the same technique. the workaround is simple in this case: use norm( x ) instead. convex: for example. will fail.7 Monotonicity in nonlinear compositions Monotonicity is a critical aspect of the rules for nonlinear compositions. included in the cvx library. 4. x}. cvx recognizes that 1. which cvx recognizes as convex. So cvx concludes that the second term is also concave. since it is the diﬀerence of a constant and a convex function. since cvx allows positive even integer powers using the ^ operator.

translates them to an equivalent function call.b. b are constants. and Q is positive deﬁnite. checking for convexity. Q ) cvx detects the quadratic expressions such as those on the left above. and if so. This is the reason several functions in the cvx atom library come in two forms: the “natural” form. a. we have chosen to make an exception to the ruleset to allow for the recognition of certain speciﬁc quadratic forms that map directly to certain convex quadratic functions (or their concave negatives) in the cvx atom library: conj( x ) .square_pos is nondecreasing. sums of products of aﬃne expressions. given scalar variables x and y. the DCP ruleset forbids even the use of simple quadratic expressions such as x * x (assuming x is a scalar variable). you might wish to consider if a monotonic extension of that function would also be useful. For practical reasons. the expression x ^ 2 + 2 * x * y + y ^2 will cause an error in cvx. and one that is modiﬁed in such a way that it is monotonic. cvx examines each single product of aﬃne expressions. if z is a vector variable. Thus. such as those on the right above. so it can accept a convex argument. it will not check. For example. because the second of the three terms 2 * x * y. and can therefore be used in compositions. so the form need not be symmetric. but it satisﬁes the DCP ruleset and is therefore accepted by cvx. is neither convex nor concave. If you are implementing a new function yourself. For example. for example. Other such “monotonic extensions” include sum_square_pos and quad_pos_over_lin. and determines whether or not they are convex or concave. the expression square_pos( square( x ) + 1 ) is mathematically equivalent to the rejected version above (since the argument to the outer function is always positive). But the equivalent expressions ( x + y ) ^ 2 ( x + y ) * ( x + y ) will be accepted.* x is replaced with square( x ) y’ * y is replaced with sum_square( y ) (A*x-b)’*Q*(Ax-b) is replaced with quad_form( A * x . then ( z + a )’ * Q * ( z + b ) 32 . and each single squaring of an aﬃne expression. 4.8 Scalar quadratic forms In its original form described in [Gra04. GBY06]. cvx actually completes the square when it comes across a scalar quadratic form.

because of its support for nonsmooth functions.will be recognized as convex. where a quadratic form is often a smooth substitute for a nonsmooth form that one truly wishes to use. In cvx. as described in §4. in light of the new capabilities aﬀorded by disciplined convex programming. the constraint sum( ( A * x . Once a quadratic form has been veriﬁed by cvx.b ) . such substitutions are rarely necessary.^ 2 ) <= 1 is equivalently represented using the Euclidean norm: norm( A * x . Quadratic forms should actually be used less frequently in disciplined convex programming than in a more traditional mathematical programming framework. the second form can be represented using a second-order cone constraint—so the second form may actually be more eﬃcient. For example.b ) <= 1 With modern solvers. it can be freely used in any way that a normal convex or concave expression can be.4. 33 . So we encourage you to re-evaluate the use of quadratic forms in your models.

0 ) then the modiﬁed function fails to meet the DCP ruleset.g. if we replace max with min above. we can subtract a constant from it. just as they would if they had been inserted directly into a cvx model. since it requires only a knowledge of the basic DCP ruleset.. simply create a ﬁle deadzone. But inside a cvx speciﬁcation. cvx will properly conclude that the function is convex. we will be happy to incorporate it in a future release.m containing function y = deadzone( x ) y = max( abs( x ) .e.1. To illustrate this. which yields a convex function. Please do let us know if you have implemented a convex or concave function that you think would be useful to other users. for example. it will also work within cvx if called with an aﬃne argument. consider the convex deadzone function. because all of the operations carried out conform to the rules of DCP: abs is recognized as a convex function. when its argument is numerical.1. because it doesn’t follow the DCP composition rules. described in this section. 0 ) This function works just as you expect it would outside of cvx—i. For example. So we are free to use deadzone anywhere in a cvx speciﬁcation that we might use abs. it will not work. disciplined convex programming. The second method is very powerful.1 New functions via the DCP ruleset The simplest way to construct a new function that works within cvx is to construct it using expressions that fully conform to the DCP ruleset. 0} for a numerical argument x. but a bit complicated. The ﬁrst method is simple. invoked with a nonconstant argument.5 Adding new functions to the cvx atom library cvx allows new convex and concave functions to be deﬁned and added to the atom library. 34 . and cvx in its current state. deﬁned as |x| ≤ 1 0 x−1 x>1 f (x) = max{|x| − 1. in two ways. happily computing the value min{|x| − 1. and should be considered an advanced technique.. function y = deadzone_bad( x ) y = min( abs( x ) . e. the expressions you use must conform to the DCP ruleset. 5. The function will work outside of a cvx speciﬁcation. 0} = −1 − x x < −1 To implement this function in cvx. because cvx knows that it is a convex function. Let us emphasize that when deﬁning a function this way. But thanks to Matlab’s operator overloading capability. and can (and should) be used by many users of cvx. and we can take the maximum of the result and 0. to be attempted only by those who are truly comfortable with convex analysis.

w and x. The optimal value of this simple QP is equal to the Huber penalty function of x. the function inputs) are unknown when the speciﬁcation is constructed. h(x) x2 |x| ≤ 1 2|x| − 1 |x| ≥ 1. The concept of incomplete speciﬁcations can at ﬁrst seem a bit complicated. y) | ∃y. indexed or parametrized by x. We call the underlying convex program in such cases an incomplete speciﬁcation—so named because the parameters (that is. Consider the unit-halfwidth Huber penalty function h(x): h : R → R. Then f : Rn → (R ∪ +∞). (x. In cvx you can deﬁne a convex function in this very manner. that is. then gives the classic epigraph representation of f : epi f = S + ({0} × R+ ) .5. (x. (This rule is sometimes called the partial minimization rule. One special case should be very familiar: if m = 1 and g(x. as the optimal value of a parameterized family of disciplined convex programs. where 0 ∈ Rn . minimize g(x. y) ∈ S } y. Suppose that S ⊂ Rn × Rm is a convex set and g : (Rn × Rm ) → (R ∪ +∞) is a convex function. v ≥ 0 with scalar variables v and w. We can implement the Huber penalty function in cvx as follows: 35 . (8) We can express the Huber function in terms of the following family of convex QPs. y) ∈ S with optimization variable y. y) f (x) inf { y | ∃y. y) ∈ S } (7) is also a convex function. Let us look at an example to see how this works. f (x) inf { g(x.2 New functions via partially speciﬁed problems A more advanced method for deﬁning new functions in cvx relies on the following basic result of convex analysis. parameterized by x: minimize 2v + w2 subject to |x| ≤ v + w (9) w ≤ 1. y) subject to (x.) We can think of the convex function f as the optimal value of a family of convex optimization problems. but it is very powerful mechanism that allows cvx to support a wide variety of functions. We note that the objective and constraint functions in this QP are (jointly) convex in v.

and solve the problem to compute the result. as a valid convex expression.function cvx_optval = huber( x ) cvx_begin variables w v. cvx will ﬁnd a complete speciﬁcation. What is most important. then upon reaching the cvx_end statement. and function returns that value as its output. cvx_end If huber is called with a numeric value of x. cvx will recognize the Huber function. y) ∈ S } (10) gives the hypograph representation of f : hypo f = S − Rn . minimize( w^2 + 2 * v ). t) | X + X T − tI 0 (13) So we can implement this function in cvx as follows: 36 . then cvx will do the right thing. There is a corresponding development for concave functions as well. called with aﬃne argument. and a concave function g : (Rn × Rm ) → (R ∪ −∞). y) ∈ S } (11) f (x) sup { g(x. the function f : R → (R ∪ −∞). f (X) = λmin (X + X T ) (12) Its hypograph can be represented using a single linear matrix inequality: hypo f = { (X. Given a convex set S as above. y) | ∃y. and if properly constructed. consider the function f : Rn×n → R. + In cvx. a concave incomplete speciﬁcation is simply one that uses a maximize objective instead of a minimize objective. In particular. (x. t) | f (X) ≥ t } = (X. with an aﬃne cvx expression for its argument. v >= 0. In this case. is concave. then f (x) sup { y | ∃y. y) y. in accordance with the DCP ruleset. Thus the function huber can be used anywhere a traditional convex function can be used. But it does give the correct value (up to the core solver accuracy). (x. however. For an example of a concave incomplete speciﬁcation. it can be used anywhere a traditional concave function can be used within a cvx speciﬁcation. in constraints or objective functions. subject to abs( x ) <= w + v. w <= 1. is that if huber is used within a cvx speciﬁcation. If g(x. cvx places the optimal objective function value into the variable cvx_optval. it’s very ineﬃcient to compute the Huber function of a numeric value x by solving a QP. Of course. the function huber will contain a special Matlab object that represents the function call in constraints and objectives.

and when used in a cvx speciﬁcation. cvx_begin variables w( sx ) v( sx ). v >= 0. in fact. First of all. will be handled correctly. (What is more.^ 2 + 2 * v ). with an appropriate test to select the proper version to use: function cvx_optval = huber( x ) if isnumeric( x ). cvx_begin variable y. w <= 1. as written the function works only with scalar values. To apply it (elementwise) to a vector requires that we iterate through the elements in a for loop—a very ineﬃcient enterprise. particularly in cvx. A far better approach is to extend the huber function to handle vector inputs. cvx_end If a numeric value of X is supplied. then direct computation is a far more eﬃcient way to compute the result than solving a QP. cvx_end This version of huber will in eﬀect create sx “instances” of the problem in parallel. However. The second issue is that if the input to huber is numeric. subject to X + X’ .* xa. both of which we will illustrate using our huber example above. maximize( y ). the multiobjective version cannot be used with numeric inputs. sx = size( x ).function cvx_optval = lambda_min_symm( X ) n = size( X. rather simple to do: we simply create a multiobjective version of the problem: function cvx_optval = huber( x ) sx = size( x ). 1 ). this function can also be used in cvx constraints and objectives. minimize( w . There are two practical issues that arise when deﬁning functions using incomplete speciﬁcations.y * eye( n ) == semidefinite( n ). This is. just like any other concave function in the atom library.) One solution is to place both versions in one ﬁle. this function will return min(eig(X+X’)) (to within numerical tolerances). cvx_begin 37 . cvx_optval = flag . xa = abs( x ). flag = xa < 1. subject to abs( x ) <= w + v.^2 + (~flag) * (2*xa-1). else.

sum_largest. Good choices include huber. you can create two separate versions of the function. 38 . This is the approach taken for the version of huber found in the cvx atom library.variables w( sx ) v( sx ). lambda_min. quad_over_lin. and others.^ 2 + 2 * v ). w <= 1. cvx_end end Alternatively. only include its parent. and place the cvx version in a subdirectory called @cvx. minimize( w . Some are a bit diﬃcult to read because of diagnostic or error-checking code. (Do not include this directory in your Matlab path. but these are relatively simple. One good way to learn more about using incomplete speciﬁcations is to examine some of the examples already in the cvx atom library. v >= 0. inv_pos. lambda_max.) Matlab will automatically call the version in the @cvx directory when one of the arguments is a cvx variable. subject to abs( x ) <= w + v. one for numeric input and one for cvx expressions. matrix_frac.

• Inequality constraints involving non-square matrices are disallowed . use a vectorization operation X(:) <= Y(:) or vec( X ) <= vec( Y ).X == semidefinite(n) If either side is complex. attempting to use them causes an error.Y == hermitian_semidefinite(n) Y ... If you wish to do true elementwise comparison of matrices X and Y. In order to use it. <=. typically expressed using linear matrix inequality (LMI) notation. 39 . cvx enforces a stricter interpretation of the inequality operators for LMI constraints.n) >= Y legal X >= 0 or 0 >= Y legal In eﬀect. (vec is a function provided by cvx that is equivalent to the colon operation. if X and Y are matrices of size n.6 Semideﬁnite programming using cvx Those who are familiar with semideﬁnite programming (SDP) know that the constraints that utilize the set semidefinite(n) in §3. When SDP mode is engaged. square matrices are interpreted as follows: X >= Y and X > Y become X <= Y and X < Y become X .. one must simply begin a model with the statement cvx_begin sdp or cvx_begin SDP instead of simply cvx_begin.size(Y. i. or one must be the scalar zero. then the inequalities are interpreted as follows: X >= Y and X > Y become X <= Y and X < Y become X . that X is + positive semideﬁnite. that is. To be speciﬁc: • Equality constraints are interpreted the same (i. For example.e. elementwise). cvx provides a special SDP mode which allows this LMI convention to be employed inside cvx models using Matlab’s standard inequality operators >=. in practice.) • Inequality constraints involving real.Y == semidefinite(n) Y .1)).n) or ones(n. n=max(size(X. cvx interprets certain inequality constraints in a diﬀerent manner.e. the constraint X 0 denotes that X ∈ Sn .6 above are.1). elementwise. given X = X T ∈ Rn×n . • Inequality constraints involving vectors and scalars are interpreted the same. • There is one additional restriction: both X and Y must be the same size.X == hermitian_semidefinite(n) In the above. etc. X >= 1 or 1 >= Y illegal X >= ones(n. For example.

<=. For example.m. simply search for the text cvx_begin sdp in the examples/ subdirectory tree using your favorite ﬁle search tool. >. To verify that the numeric value of Z is. But after the model has been solved and Z has been replaced with a numeric value. some may wonder why SDP mode is not the default behavior. the cvx model found in the ﬁle examples/closest_toeplitz_sdp. Since semideﬁnite programming is popular. you must perform a test like min(eig(Z)) >= 0.• Note that LMI constraints enforce symmetry (real or Hermitian. It will be given a positive semideﬁnite value if an optimal point is found.n) hermitian toeplitz dual variable Q minimize( norm( Z . and the use of the >=. ’fro’ ) ) Z >= 0 : Q.n) hermitian toeplitz dual variable Q minimize( norm( Z . • A dual variable.P. the expression Z >= 0 will test for the elementwise nonnegativity of Z. this is reasonably straightforward. If cvx cannot determine that an LMI is symmetric.P. ’fro’ ) ) Z == hermitian_semidefinite( n ) : Q. cvx_end Many other examples in the cvx example library utilize semideﬁnite constraints. cvx_begin variable Z(n. a warning will be issued. will be applied to the converted equality constraint. The reason for this is that we place a strong emphasis on maintaining consistency between Matlab’s native behavior and that of cvx. cvx_end can also be written as follows: cvx_begin sdp variable Z(n. if supplied.5. the expression Z >= 0 in the example above constrains the variable Z to be positive semideﬁnite. cvx does not extract the symmetric part for you: you must take care to insure symmetry yourself. for example. in fact. < operators to create LMIs represents a deviation from that ideal. and all of them use SDP mode. One of these examples is reproduced in §8. Unlike SDPSOL [WB00]. as appropriate) on their inputs. positive semideﬁnite. Since cvx supports the declaration of symmetric matrices. 40 . To ﬁnd them. So.

and translate the results back to the original problem. consisting of a monomial objective and zero or more constraints. d/w >= gamma. consisting of a generalized posynomial objective and zero or more constraints. by permitting the use of generalized posynomials wherever posynomials are permitted in standard GP [BKVH05]. found in the example library at gp/max_volume_box. For example.7 Geometric programming using cvx Geometric programs (GPs) are special mathematical programs that can be converted to convex form using a change of variables. compute a numerical solution. • A maximization problem. h/w >= alpha. but for small and medium sized problems. cvx supports the construction of monomials and posynomials using addition. The convex form of GPs can be expressed as DCPs. we refer the reader to [BKVH05]. The solvers used in this version of cvx do not support geometric programming natively. 7. and powers. you must begin your cvx speciﬁcation with the command cvx_begin gp or cvx_begin GP instead of simply cvx_begin.1 Top-level rules cvx supports three types of geometric programs: • A minimization problem. multiplication. In addition. h/w <= beta. the following code. In the remainder of this section. cvx supports the construction of generalized geometric programs (GGPs). they are solved using the successive approximation technique described in Appendix D.1. cvx will automatically perform the necessary conversion. This means that solving GPs can be slow. For a tutorial on geometric programming. w*d <= Afloor. determines the maximum volume box subject to various area and ratio constraints: cvx_begin gp variables w h d maximize( w * h * d ) subject to 2*(h*w+h*d) <= Awall. To utilize GP mode.m. d/w <= delta. cvx_end As the example illustrates. division (when appropriate). the method works well. but cvx also provides a special mode that allows a GP to be speciﬁed in its native form. Instead. 41 . we will describe speciﬁc rules that apply when constructing models in GP mode.

7. • the product of two or more monomials. constructed using ==. cumsum. A valid monomial is • a declared variable. cumprod. • the ratio of a posynomial and a monomial. • the ratio of two monomials. sqrt. • A less-than inequality constraint <=. > where the left side is a monomial and the right side is a generalized posynomial. that only monomial objectives are allowed in the latter—is an unavoidable artifact of the geometry of GPs and GGPs. posynomials. • A greater-than inequality constraint >=. 7. The asymmetry between minimizations and maximizations—speciﬁcally.3 Expressions The basic building blocks of generalized geometric programming are monomials.2 Constraints Three types of constraints may be speciﬁed in geometric programs: • An equality constraint.• A feasibility problem. cumprod. or • a call to one of the following functions with monomial arguments: prod. • the sum of two or more posynomials. • a monomial raised to a real power. As with DCPs. or • a call to one of the following functions with posynomial arguments: sum. and generalized posynomials. prod. 42 . mean. < where the left side is a generalized posynomial and the right side is a monomial. • a posynomial raised to a positive integral power. non-equality constraints are not permitted. consisting of one or more constraints. A valid posynomial expression is • a valid monomial. • the product of two or more posynomials. where both sides are monomials. geo_mean.

mean. prod. norm. in which case these rules extend in an obvious manner. • the ratio of a generalized posynomial and a monomial. cumprod. posynomials. geo_mean. • the sum of two or more generalized posynomials. cumsum. the product of two monomial matrices produces either a posynomial matrix or a monomial matrix. norm_largest. • a generalized posynomial raised to a positive real power. and/or generalized posynomials in cvx.A valid generalized posynomial expression is • a valid posynomial. depending upon the structure of said matrices. sum_largest. • the product of two or more generalized posynomials. or • a call to one of the following functions with arguments that are generalized posynomials: sum. It is entirely possible to create and manipulate arrays of monomials. 43 . For example. sqrt.

1 Solver selection cvx currently supports two solvers: SeDuMi and SDPT3.2 Controlling solver precision Numerical methods for convex optimization are not exact. 8. We recommend that you skip this section at ﬁrst. SeDuMi is used by default. The solver will stop as soon as it achieves this level. or until no further progress is possible. please send us a bug report and we will forward the results to the authors of SeDuMI or SDPT3. The tolerance levels that cvx selects by default have been inherited from the underlying solvers being used. We have found that SeDuMi is faster and more reliable for most problems. with minor modiﬁcations. it will change the solver being used only for that model. they compute their results to within a predeﬁned numerical precision or tolerance. the default will be preserved. it depends heavily on the considerable transformations that cvx applies to your model before delivering it to the solver. but for your application you may ﬁnd otherwise. try the other. With an exception discussed below. 8. simply type 14 cvx_solver If you issue this command inside a model. it will change the solver used for all future models. cvx actually considers three diﬀerent tolerance levels solver ≤ standard ≤ reduced when solving a model: • The solver tolerance solver is the level requested of the solver. So while you may ﬁnd its value interesting we strongly discourage dependence upon it within your applications. 44 . To select SDPT3 as your default solver instead. To revert to SDPT3. If you issue this command outside of a model. simply type 12 cvx_solver sdpt3 at the command line. until you are comfortable with the basic capabilities described above. For one thing. each solver computes it diﬀerently. the tolerance level the solver has achieved is returned in the cvx_slvtol variable. Upon solution of your model. For another. type 13 cvx_solver sedumi To see which solver is currently selected. Both solvers are being actively maintained by their authors. Attempts to interpret this tolerance level in any absolute sense are not recommended. If you encounter a problem that one solver can handle but the other cannot.8 Advanced topics In this section we describe a number of the more advanced capabilities of cvx. If you are having diﬃculty with one solver.

cvx_end 45 . these calls look like cvx_precision(’low’). a length-2 vector. 3/4 . you may do so using the cvx_precision command. it will set the solver and standard tolerances to that value. solver = standard . Note that the best precision settings sets the solver target to zero. returning a status with the Inaccurate/ preﬁx. standard . Called with no arguments it will return the current tolerance levels as a 3-element row vector. where = 2. reduced ] are set to [ 1/2 . the smaller will be used for the solver and standard tolerances. but setting standard < solver has a useful interpretation: it allows the solver to search for more accurate solutions without causing an Inaccurate/ or Failed condition if it cannot do so.) Typically. 1/4 1/2 . There are three ways to invoke this command. with some bounds imposed to make sure that it stays reasonable.. cvx returns a status of Failed. Finally. ] ] • cvx_precision default: [ • cvx_precision high: [ 3/4 1/2 1/2 1/4 . that reduced precision will be the square root of the standard precision. which means that the solver continues as long as it can make progress. cvx_begin cvx_precision high . e. (See Appendix C for more information about the status messages. If you call it from within a model. If you pass it a scalar. and it will compute a default reduced precision value for you.. . If you supply two values. and each tolerance will be set separately. 1/2 . Calling cvx_precision with a string argument allows you to select from a set of predeﬁned precision modes: • cvx_precision low: [ 3/8 .• The standard tolerance solved to full precision. but it is just as reliable. and the larger for the reduced tolerance. This should be quite suﬃcient for most applications.. and its behavior diﬀers in each case. . 1/4 3/8 ] 1/4 • cvx_precision medium: [ . 1/2 . The cvx_precision command can be used either within a cvx model or outside of it. and sometimes produces more accurate solutions.g. The default values of [ solver .22 × 10−16 is the machine precision. the cvx_precision command can be called with a scalar. 3/8 ] • cvx_precision best: [0. and the values of the variables should not be considered reliable. If this tolerance cannot be achieved. or a length-3 vector. 1/4 ]. standard is the level at which cvx considers the model • The reduced tolerance reduced is the level at which cvx considers the model “inaccurately” sovled. their values will be sorted. 1/4 ] In function mode. If you supply three values. If you wish to modify the tolerances. It will often be slower than default. Roughly speaking. etc. .

.. This is useful if you make a mistake and need to start over. This may seem confusing at ﬁrst. it will return as its output the previous precision vector—the same result you would obtain if you called it with no arguments. e. you can simply start another model with cvx_begin. so you can restore that state later if you wish—which is good practice if you wish to share your code with others. Typing cvx_quiet(false) restores the screen output.. 46 .g. clearing any and all problems from memory. But note that in current versions of cvx. Of course. to any subsequent models that are created and solved. but without erasing any of your numeric data. it returns a logical value representing the previous state of the quiet ﬂag. cvx_begin . The local approach should be preferred in an application where multiple models are constructed and solved at diﬀerent levels of precision. and the previous model will be erased (with a warning). and restore it at the end of your calculations. cvx_end then the setting you choose will apply globally.g. cvx_precision high cvx_begin . If you call cvx_precision in function mode. generating extra temporary variables and constraints in the process. Note that this will contain a lot of information that you may not recognize—cvx performs its conversion to canonical form as the problem is entered. as described above.3 Miscellaneous cvx commands • cvx_problem: typing this within a cvx speciﬁcation provides a summary of the current problem. • cvx_clear: typing this resets the cvx system. e. cvxp = cvx_precision( ’high’ ).. that is. cvx_end cvx_precision( cvxp ). • cvx_quiet: typing cvx_quiet(true) suppresses screen output from the solver. but this is done so that you can save the previous value in a variable. a simpler but equally courteous approach is to call cvx_precision within the cvx model. In each case.. If you call it outside a model. so that its eﬀect lasts only for that model. This is considered good coding etiquette in a larger application where multiple cvx models at multiple precision levels may be employed.then the setting you choose will apply only until cvx_end is reached. either with a string or a numeric value. 8..

• cvx_pause: typing cvx_pause(true) causes cvx to pause and wait for keyboard input before and after the solver is called. and consider the simple SDP minimize Tr(CX) subject to Tr(AX) = b X 0 Suppose that we tried to express this problem in cvx as follows: 1 2 3 4 5 6 7 8 9 (14) n = 5.n). build number. cvx_begin variable X(n. Useful if you want to ﬁnd certain helpful subdirectories. such as doc. which employs the double equal == operator. it returns a logical value representing the previous state of the pause ﬂag. For example. If you encounter a bug in cvx. In cvx. and an equality. and hardware platform you are currently using. C ∈ Rn×n and b ∈ R be given.n) symmetric. Typing cvx_pause(false) resets the behavior. and the original X is not constrained all! 47 . etc. there are important caveats to using assignments in cvx that we address here as well. Even when the distinction is well understood.n). The consequences of inadvertently using assignments within a cvx speciﬁcation can cause subtle but critical problems. C = randn(n. A = randn(n.4 Assignments versus equality constraints Anyone who has used the C or Matlab languages for a suﬃciently long time understands the diﬀerences between assignments. 8. not an equality constraint. So X is actually overwritten with an anonymous. In each case. Useful primarily for demo purposes. this distinction is particularly important. • cvx_version: returns a description of the cvx version number. subject to trace( A * X ) == b. cvx_end At ﬁrst glance. minimize( trace( C * X ) ). X = semidefinite(n). which employ a single equals sign = operator. so you can restore that state later if you wish. line 8 may look like it constrains X to be positive semideﬁnite. confusing the two operators can have serious consequences. let A. but it is an assignment. examples. • cvx_where: returns the directory where the cvx distribution has been installed— assuming that the Matlab path has been set to include that distribution. please run this function and copy its output into your email message along with a description of your problem. b = randn. positive semideﬁnite variable.

If it does not. only those that overwrite formally declared variables. z ) <= 1. When cvx_end is reached. cvx supports indexed dual variables. a Matlab for loop.8: variables x y z = 2 * x . which declares z as a formal variable. we must ﬁnd a way to adjust the number of dual variables as well. We recommend taking this approach whenever possible. square( z ) <= 3.y. cvx examines each declared variable to verify that it still points to the variable object it was originally assigned upon declaration. consider the ﬁrst example from §3. 48 . possibly improving performance. Declaring intermediate calculations as variables provides an extra measure of clarity in your models. It is straightforward to build such models in cvx using.8. this particular error is easily caught and prevented by cvx. Of course. z ) <= 1. other kinds of assignments are permitted. In reality.Fortunately. But in our view they should be used sparingly. We hope that this check will prevent at least some typographical errors from having frustrating consequences in your models. As discussed in §3. The following alternative formulation. square( z ) <= 3. say. they are simply standard Matlab cell arrays whose entries are cvx dual variable objects. In order to assign each of these constraints a separate dual variable.y. For instance. quad_over_lin( x. and it exposes more of the model’s structure to the solver. it will issue an error like this: ??? Error using ==> cvx_end The following cvx variable(s) have been overwritten: X This is often an indication that an equality constraint was written with one equals ’=’ instead of two ’==’. this single check does not prevent you from using all assignments inside your cvx speciﬁcations. 8. The model must be rewritten before cvx can proceed. For this reason. and may be genuinely useful. quad_over_lin( x.5 Indexed dual variables In some models. is numerically equivalent: variables x y z z == 2 * x . the number of constraints depends on the model parameters—not just their sizes.

while holding the sums along each diagonal constant. sum( diag( X. 2. k ) ) == b( k+1 ) : y{k+1}. and stores the result in the Matlab variable Z. n ) symmetric minimize( ( n .i+k = bk . which in turn would require only a single vector dual 49 .Let us illustrate by example how to declare and use indexed dual variables. When the cvx_end command is issued. end X == semidefinite(n). The parameters of the problem are the elements of the vector b ∈ Rn . n (15) 0 ([Stu99]). cvx_end If we wish to obtain dual information for the n simple equality constraints. The cvx version of this model is cvx_begin variable X( n. we need a way to assign each constraint in the for loop a separate dual variable. With a bit of careful arrangement.1 : -1 : 0 ) * diag( X ) ). The equality constraint in the for loop has been augmented with a reference to y{k+1}. and the optimization variable is a symmetric matrix X ∈ Rn×n . k = 1. cvx will compute the optimal values of these dual variables. for k = 0 : n-1. sum( diag( X. . it is possible to rewrite this model so that the n equality constraints can be combined into a single vector constraint. so that each constraint is assigned a separate dual variable. cvx_end The statement dual variables y{n} allocates a cell array of n dual variables. k ) ) == b( k+1 ). . . This is accomplished as follows: cvx_begin variable X( n. Consider the following semideﬁnite program: minimize subject to X n i=1 (n − i)Xii n i=1 Xi. and deposit them into an n-element cell array y. This problem minimizes a weighted sum of the main diagonal of a positive semideﬁnite matrix. This example admittedly is a bit simplistic. .1 : -1 : 0 ) * diag( X ) ). n ) symmetric dual variables y{n} minimize( ( n . for k = 0 : n-1. end X == semidefinite(n).

each constraint in the for loop is a linear matrix inequality.variable. 3 Indeed. In that problem. not scalars. not a scalar linear equation.3 For a more complex example that is not amenable to such a simpliﬁcation. which will reduce the entire for loop to the single constraint spdiags(X. so the indexed dual variables are symmetric matrices. 50 .0:n-1)==b. a future version of cvx will support the use of the Matlab function spdiags.m in the cvx distribution. see the ﬁle examples/cvxbook/Ch07_statistical_estim/cheb.

then you would type cd C:\Matlab\personal\cvx 51 .9 • Linux (64-bit): Matlab 7. cvx will attempt to compile the MEX ﬁles will be compiled during the setup process. (Previous versions of cvx supported Matlab 6. workarounds are provided in §A. a directory called cvx will be created. For other platforms (e. There is one important exception: do not place cvx in Matlab’s own toolbox directory. cvx_old—before proceeding. 7.) Primary cvx development is performed using an Intel-based Mac running Matlab 7.3. Solaris). We strongly recommend against using version 7. Version 7.0. While cvx is quite likely to work for these platforms.9 • Linux (32-bit): Matlab 6.5. Start Matlab. You can download the package as either a . 3.9 For purposes of testing and support. Change the current directory to the location of cvx. if you unpacked cvx.0. 7. 7. we have access to most other versions of Matlab for Windows. If you have been running a previous version of cvx. say.1 and 7.g. and Mac (both Intel and PowerPC).1.5.5. Retrieve the latest version of cvx from http://www.9 • Mac (64-bit): Matlab 7. Unpack the ﬁle anywhere you like.1 Basic instructions 1. 7.3. 4.5.edu/∼boyd/cvx.zip ﬁle or a . Linux. 5. remove it or rename it to.2.zip into the directory C:\Matlab\personal. with additional development performed on the following platforms and Matlab versions: • Mac (32-bit): Matlab 7. For example.2 or later. 7. the problems were eliminated by upgrading.0. In particular you are responsible for making sure that your system is set up to compile MEX ﬁles.0. we are unable to provide support.5. 2.0 has exhibited numerical problems for at least one user.5.tar. A.x of Matlab on any platform. DO NOT allow the new version of cvx to be unpacked on top of the old.stanford. Precompiled MEX ﬁles are included for all of the above platforms. 7. We have also identiﬁed another issue using cvx with Matlab 7.5.5. 7.4..3 below.2.gz ﬁle. 7.9 • Windows (32-bit): Matlab 6. but this has been discontinued.A Installation and compatibility cvx requires Matlab 6.

If this message is not displayed. then you would type cd ~/matlab/cvx at the Matlab command prompt. and if that fails.at the Matlab command prompt. and it runs a simple test problem to verify the installation. The example that produced this particular error is a simple inequality constraint 52 . A. and variable name may diﬀer. Type the command cvx_setup at the Matlab prompt. (among others).3 A Matlab 7.gz into the directory ~/matlab on a Linux machine.0 issue The techniques that cvx use to embed a new modeling language inside Matlab seem to cause some confusion for Matlab 7. If you plan to use cvx regularly. It does not occur in version 6. you will need to save the current Matlab path for subsequent Matlab sessions. a .1 and later.0 as well (R14. the command will output the line No errors! cvx has been successfully installed. Alternatively.0. The ﬁle name. speciﬁcally version 7. A.2 or 7. but the error message remains the same.m Line: 43 Column: 5 "p" was previously used as a variable. line/column numbers.2 About SeDuMi and SDPT3 The cvx distribution includes copies of the solvers SeDuMi and SDPT3 in the directories cvx/sedumi and cvx/sdpt3. respectively.tar.m-ﬁle containing a cvx model will cause an error that looks like this: ??? Error: File: thrusters. The bug is this: in some circumstances.0. then there is a problem with the cvx installation. if you unpacked cvx.5.4 (R14SP2). and remove any other versions that you have in your Matlab path. We strongly recommend that you use our versions of these solvers.R14SP1). This does two things: it sets the Matlab search path so it can ﬁnd all of the cvx program ﬁles. Try installing the package again. It may occur in earlier versions of Matlab 7. 6. We are reasonably conﬁdent that the issue is due to a bug in Matlab itself. Follow the instructions provided by cvx_setup to accomplish that. If all goes well. send us a bug report and tell us about it. 7. conflicting with its use here as the name of a function. or any warnings or errors are generated.

changing the constraint to p>=-5. eliminates the error. 53 . In this example. So we cannot oﬀer you a precise set of circumstances that cause the error. a diﬀerent inequality constraint u >= 0 in the same model causes no complaint. Interestingly. but it does—reliably. Fortunately. We have no idea why this workaround works.p >= -5. where p is a cvx variable previously declared with a variable statement. the workaround is very simple: simply remove all of the extra space in the constraint. You may still indent the constraint as you wish—just remove the intermediate spaces.

including: • Concatenation: [ A. multiplication * . D ] • Indexing: x(n+1:end). and exponentiation ^ . kron(X. etc.B B. For example. the curvature is preserved. Matlab’s basic matrix manipulation and arithmetic operations have been extended to work with cvx expressions as well. B . whenever their use is consistent with both standard mathematical and Matlab conventions and the DCP ruleset. etc. such as cumsum.. see §B. Z(1:4. Those that perform some sort of summation. or it can be left-divided by a non-singular constant matrix of appropriate dimension. and sets Basic operators and linear functions Matlab’s standard arithmetic operations for addition +. y’ A number of Matlab’s basic functions have been extended to work with cvx expressions as well: conj conv cumsum diag dot find fliplr flipud flipdim horzcat hankel ipermute kron permute repmat reshape rot90 sparse sum trace tril triu toeplitz vertcat Most should behave identically with cvx expressions as they do with numeric expressions.4].:) = [].e. and trace(Z) is valid only if the elements along the diagonal have the same curvature./ . division / \ .:). such as conv. 54 .^ have been overloaded to work in cvx whenever appropriate—that is. can only be used in accordance with the disciplined convex programming rules. dot or kron. • A cvx expression can be multiplied or divided by a scalar constant. For example: • Two cvx expressions can be added together if they are of the same dimension (or one is scalar) and have the same curvature (i. concave. of course. subtraction -.\. C. both are convex. If the constant is positive. For example. functions. the use of the exponentiation operators ^ . • Transpose and conjugate transpose: Z. • Indexed assignment./ .*.’. Numerous other combinations are possible.2 below. curvature is reversed. if it is negative.Y) is valid only if either X or Y is constant. including deletion: y(2:4) = 1.1 Operators.^ are somewhat limited. sum. or aﬃne). • An aﬃne column vector cvx expression can be multiplied by a constant matrix of appropriate dimensions. or multiplication. X([3.

p)) are marked with a star ( ).B.g. which makes multiple calls to the underlying solver. • max: maximum. a list of standard Matlab functions extended to work with cvx. norm(x. B. The two-argument version norm(x.^(n-2) + . For irrational values of p. • Functions involving powers (e. Concave and nondecreasing.^(n-1) + p(2) * x. p must be 1.) If you use one of these functions. + p(n-1) * x + p(n) This function can be used in cvx in two ways: 55 . • min: minimum.. achieving the same ﬁnal precision.2 for more details about how cvx handles values other than 1. Convex and nondecreasing. and second. where p is a vector of length n. • norm: norms for real and complex vectors and matrices. See §D. but see Appendix D. Convex and nondecreasing. • † log: logarithm. – For matrices. a nearby rational is selected using Matlab’s rat function. x^p) and p-norms (e.2 Nonlinear functions What follows are two lists of nonlinear functions supported by cvx: ﬁrst. you will be warned that successive approximation will be used. and Inf. Concave and nondecreasing. cvx represents these functions exactly when p is a rational number. • polyval: polynomial evaluation. (See §D. Convex.p) is supported as follows: – For vectors.1 for details. computes p(1) * x.2. limitations of the underlying solvers place certain restrictions or caveats on their use: • Functions marked with a dagger (†) are not supported natively by the solvers that cvx uses. 2. Inf.2 for details. Convex. or ’Fro’. all p ≥ 1 are accepted. polyval(p. The oneargument version norm(x) computes the 2-norm for vectors and induced 2-norm (maximum singular value) for matrices..g. They are handled using a successive approximation method. In some cases.. 2. • † exp: exponential.1 Built-in functions • abs: absolute value for real and complex arrays..x). a list of new functions created speciﬁcally for use in cvx.

• power: x^p and x. but see the functions pow_p. 4.p) constructs a polynomial function of the variable x. it must be a positive constant. – 0 < p < 1. – p ∈ {2. then polyval(x. For p^x. Valid values of p include: – p ∈ {0.t). Negative and odd integral values of p are not permitted. pow_pos. but if supplied. – p = 1. x and p must be scalars. . 3. and is implicitly constrained to be nonnegative. Aﬃne. Convex and nonincreasing. and pow_abs in the next section for useful alternatives.. 1}. Convex. then polyval(x.. The polynomial must be aﬃne.p) computes a linear combination of the elements of p. and x must be real and aﬃne. 6. • sqrt: square root. Concave.M): The reversed Huber function (hence. and (|x|2 + M 2 )/2M for |x| ≥ M . useful for concomitant scale estimation (see [Owe06]). Convex.}. Also callable with three arguments as berhu(x. M = 1 is assumed.^p is then x. • berhu(x. x must be convex.. x must be concave. For x^p. which computes t+t*berhu(x/t. Convex and nondecreasing. Concave and nondecreasing.^x and p^x. .^p is identically 1.M. – 0 < p < 1. 56 .. where x is a real variable and and p is a real constant. Argument x must be aﬃne. or concave. Convex. Only those values of p which can reasonably and unambiguously interpreted as convex or concave are accepted: – p = 0. Implicitly constrains its argument to be nonnegative.– If p is a variable and x is a constant. and is implicitly constrained to be nonnegative. Berhu). Constant. when supplied with numeric arguments. x.2 New nonlinear functions Even though these functions were developed speciﬁcally for cvx. Negative values of p are not permitted. Constant. p ∈ {2. they work outside of a cvx speciﬁcation as well. If M is omitted. – p > 1. 8. p and x must be scalars. – If p is a constant and x is a variable.M).}. where p is a real constant and x is a real variable. convex. B. Argument x must be aﬃne. – p > 1. The combination must satisfy the DCP rules for addition and scaling. x.^p. The argument x must be concave (or aﬃne). • † power: p. 4. 5. deﬁned as |x| for |x| ≤ M .2.

imposes constraint that its argument is symmetric (if real) or Hermitian (if complex). When used with numerical arguments. and |x|2 for |x| ≤ M . Convex. (det X)1/n . det_inv constrains the matrix to be symmetric (if real) or Hermitian (if complex) and positive semideﬁnite. with x(i) zero whenever y(i) is zero. then M = 1 is assumed. which is the same as the product of the inverses of the eigenvalues. Concave. Convex and nondecreasing. 1/ max{x./y)-x+y. Also callable as huber(x. geo_mean returns -Inf if any element is negative. the elementwise entropy function: entr(x)=-x. and 2M x 2 − M 2 for x 2 ≥ M . det_inv returns +Inf if these constraints are not met. for x.t). • huber_pos(x. kl_div(x. 0}. Maintained solely for backcompatibility purposes. zero for negative x.M). • geo_mean: the geometric mean of a vector.y)=x. Convex. When used inside a k=1 cvx speciﬁcation. i. Convex and decreasing. • lambda_max: maximum eigenvalue of a real symmetric or complex Hermitian matrix. deﬁned as 2M |x| − M 2 for |x| ≥ M . Concave and increasing. Inside cvx.M). det_rootn returns -Inf if these constraints are not met. it must be a positive constant.*log(x). ( n xk ) .• det_inv: determinant of inverse of a symmetric (or Hermitian) positive deﬁnite matrix. Outside cvx speciﬁcation. Convex. which computes t+t*huber(x/t. imposes constraint that its argument is positive. When used with numerical arguments. • det_rootn: n-th root of the determinant of a semideﬁnite matrix. 57 1/n . but if it supplied..e. geo_mean constrains the elements of the vector to be nonnegative. Concave. det X −1 . • det_root2n: the 2n-th root of the determinant of a semideﬁnite matrix. • huber_circ(x. Convex. the circularly symmetric Huber function. When used inside a cvx speciﬁcation.*log(x. returns +∞ if x ≤ 0.M). • † entr. deﬁned as x 2 for x 2 ≤ M . Inside cvx speciﬁcation.M. When used inside a cvx speciﬁcation. y nonnegative. When used with numerical arguments. Returns -Inf when called with a constant argument that has a negative entry. Convex. If M is omitted. det_root2n(X)=sqrt(det_rootn(X)). returns +∞ if arguments aren’t in the domain.M). Concave. Same (and implemented) as huber_pos(norm(x).M). Outside cvx speciﬁcation. det_rootn constrains the matrix to be symmetric (if real) or Hermitian (if complex) and positive semideﬁnite. inverse of the positive portion. elementwise Kullback-Leibler distance. useful for concomitant scale estimation (see [Owe06]). • huber(x. Same as Huber function for nonnegative x. • † kl_div. • inv_pos.

for real and complex vectors. The current implementation is a fairly crude SDP-representable approximation. • logsumexp_sdp: a polynomial approximation to the log-sum-exp function with global absolute accuracy. but can also be used in standard DCPs. This approximation is used in default GP mode. Convex. • matrix_frac(x. Useful for sum-ofnorms and max-of-norms problems.) Convex. imposes constraint that its argument is symmetric (if real) or Hermitian (if complex). Concave. imposes constraint that its argument is symmetric (if real) or Hermitian (if complex). i. 4]. • norm_nuc(X). • poly_env( p. When used inside a cvx speciﬁcation. Concave and increasing. Inside cvx. • norms( x.• lambda_min: minimum eigenvalue of a real symmetric or complex Hermitian matrix. k. dim ). Inside cvx. returns the sum of the largest k magnitudes in the vector x. imposes constraint that its argument is symmetric (if real) or Hermitian (if complex). log_det constrains its argument to be symmetric (if real) or Hermitian (if complex) and positive deﬁnite. In cvx. • † log_sum_exp(x): the logarithm of the sum of the elementwise exponentials of x. Concave. • norm_largest( x. p must be a real 58 . (This is the dual of the usual spectral matrix norm. • lambda_sum_largest(X.k): sum of the smallest k values of a real symmetric or complex Hermitian matrix. k ).k): sum of the largest k values of a real symmetric or complex Hermitian matrix.. xT Y −1 x. Concave. Inside cvx. dim ) and norms_largest( x. With numerical argument. Convex. This is used internally in expert GP mode.Y): matrix fractional function. returns +∞ unless Y = Y T 0. • lambda_sum_smallest(X. imposes constraint that Y is symmetric (or Hermitian) and positive deﬁnite. Computes the value of the convex or concave envelope of the polynomial described by p (in the polyval sense). the largest singular value. x ). Computes vector norms along a speciﬁed dimension of a matrix or N-d array. log_det returns -Inf if these constraints are not met. log det(X). • log_normcdf(x): logarithm of cumulative distribution function of standard normal random variable. we intend to replace it with a much better approximation at some point. Convex. p.e. is the sum of the singular values of a real or complex matrix X. • log_det: log of determinant of a positive deﬁnite matrix. Convex and nondecreasing. with modest accuracy over the interval [−4. but can also be used in standard DCPs. Convex. outside cvx.

1.2 for details.2 −1. Convex and nondecreasing.1]. For convex or concave polynomials. 2. see Appendix D. The two coincide when |x| ≥ 1. a nearby rational value is chosen.1.5 (x2−1)2 envelope −1 −0. see Appendix D.2 0 −0.0. depicted along with its convex envelope in Figure 2.0.2 for details. but a call to poly_env([1. • • • pow_abs(x.5 0 0. 0}p for x ∈ R and p ≥ 1. for real x. The sign of the ﬁrst nonzero element of p determines whether a convex (positive) or concave (negative) envelope is constructed.p): max{x. Convex and increasing.8 0.2 1 0.4 1.5 Figure 2: The polynomial function p(x) = x4 − 2x2 + 1 and its convex envelope.p).x) in a cvx model would yield an error.4 0.p): |x|p for x ∈ R or x ∈ C and p ≥ 1. 3. but deviate when |x| < 1. If p is irrational.0.1]. this function produces the same result as polyval. for x ∈ R and real constant p computes nonnegative convex and 59 . • pos: max{x. 0}.6 1. Attempting to call polyval([1. or some other odd length.x) yields a valid representation of the envelope. consider the function p(x) (x2 − 1)2 = x4 − 2x2 + 1. pow_p(x.6 0. Convex.5 1 1.0. and x must be real and aﬃne. For example. If p is irrational.2. a nearby rational value is chosen. pow_pos(x.2. constant vector whose length n is 0.

y)=x. • sum_smallest(x. y > 0.concave branches of the power function: p≤0: 0 <p ≤ 1 : p≥1: fp (x) fp (x) fp (x) xp x>0 +∞ x ≤ 0 xp x≥0 −∞ x < 0 xp x≥0 +∞ x < 0 convex. Convex. xT P x for real x and symmetric P . y > 0: x∗ x/y. -sum_largest(-x. Convex and increasing. Convex. nondecreasing convex. and decreasing in y. This function is provided since cvx will not recognize x’*P*x as convex (even when P is positive semideﬁnite). trace of the inverse of an SPD matrix X. returns +Inf if argument is not positive deﬁnite. Convex. • quad_pos_over_lin: sum_square_pos( x ) / y for x ∈ Rn . Concave and decreasing. nonincreasing concave. Convex. • quad_over_lin. Convex. • square_abs: |x|2 for x ∈ R or x ∈ C. Convex in x for P constant and positive semideﬁnite. Convex and increasing. Convex. • † rel_entr: Scalar relative entropy: rel_entr(x. • sum_square: sum( square( x ) ). Convex. • trace_inv(X). and xH P x for complex x and Hermitian P . • square: x2 for x ∈ R.. Convex.k). Outside of cvx.P). adds constraint that y > 0. returns +∞ if y ≤ 0. • sum_square_pos: sum( square_pos( x ) ). xT x/y for x ∈ Rn .*log(x/y).e. Convex and increasing. for x ∈ Cn . for real vector x. sum of the smallest k values. i. • sigma_max: maximum singular value of real or complex matrix. concave in x for P constant and negative semideﬁnite. and decreasing in y. Same as norm. 0}2 for x ∈ R.k) sum of the largest k values. works only for real values. y > 0. • square_pos: max{x.k). • sum_largest(x. nonmonotonic • quad_form(x. increasing in x. Outside cvx speciﬁcation. • sum_square_abs: sum( square_abs( x ) ). which is the same as the sum of the inverses of the eigenvalues. 60 . In cvx speciﬁcation.

. z) ∈ Rn × R × R | x 2 { x ∈ Rn | xi ≥ 0. . n. returns +Inf if argument is not positive semideﬁnite.3 Sets cvx currently supports the following sets. n must be even: n P+. . y. z) ∈ Cn × R × R | x 2 ≤ √ yz. . Concave. in each case. • nonnegative(n): Rn + • simplex(n): Rn 1+ • lorentz(n): Qn • rotated_lorentz(n): Qn r { (x. . 2. z ≥ 0 } • semidefinite(n): Sn + X ∈ Rn×n | X = X T . which is the same as the sum of the squareroots of the eigenvalues. n is a positive integer constant. i = 1. B.n p∈R n+1 | i=0 pi+1 xn−i ≥ 0 ∀x ∈ R 61 . i = 1. . . n } { x ∈ Rn | xi ≥ 0. Outside of cvx. . y) ∈ Rn × R | x 2 ≤ y} ≤ √ yz. z ≥ 0 } • complex_lorentz(n): Qn c { (x. i xi = 1 } { (x. X 0 • nonneg_poly_coeffs(n): The cone of all coeﬃcients of nonnegative polynomials of degree n. y. y) ∈ Cn × R | x 2 ≤ y} • rotated_complex_lorentz(n): Qn rc { (x. 2.• trace_sqrtm(X). y. y. X 0 • hermitian_semidefinite(n): Hn + Z ∈ Cn×n | Z = Z H . trace of the matrix squareroot of a positive semideﬁnite matrix X.

n p ∈ Rn+1 | i=0 (n − i)(n − i − 1)pi+1 xn−i−2 ≥ 0 ∀x ∈ R • exponential_cone: E cl (x. n must be even: n−2 P+. yex/y ≤ z • geo_mean_cone(n): n Gn cl (x. ( i=1 n n n xi )1/n ≥ y 62 . y) ∈ R × R × R | x ≥ 0. z) ∈ R × R × R | y > 0. y.• convex_poly_coeffs(n): The cone of all coeﬃcients of convex polynomials of degree n.

Feasibility problems by construction cannot be unbounded below. The nominal values of cvx_status. • Infeasible: The problem has been proven to be infeasible through the discovery of an unbounded dual direction. • Inaccurate/Unbounded: The problem is likely to be unbounded. This result can occur because of numerical problems within SeDuMi. It is important to understand that the unbounded primal direction is very likely not a feasible point. the problem should be resolved as a feasibility problem by omitting the objective. • Inaccurate/Infeasible: The problem is likely to be infeasible. The primal and dual variables are replaced with their computed values. are as follows: • Solved: A complementary (primal and dual) solution has been found. • Unbounded: The problem has been proven to be unbounded below through the discovery of an unbounded primal direction. and the the optimal value of the problem is placed in cvx_optval (which. and of cvx_optval. and +Inf for maximizations. If a feasible point is required. The values of cvx_optval and primal and dual variables are ﬁlled with NaNs. which are indicated by the value of the string variable cvx_status. one of the following results is returned: • Inaccurate/Solved: The problem is likely to have a complementary solution. The value of cvx_optval is set to -Inf for minimizations. The values of the primal and dual variables. Appropriate components of this direction are stored in the dual variables. The values of the primal variables are ﬁlled with NaNs. by convention. The value of cvx_optval is set to +Inf for minimizations and feasibility problems.C cvx status messages After a complete cvx speciﬁcation has been entered and the cvx_end command issued. and the resulting values of the other variables..g. a non-zero duality gap). is 0 for feasibility problems). The solver can produce one of ﬁve exit conditions. the solver is called to generate a numerical result. This direction is stored in the primal variables. the solver is unable to achieve the numerical certainty it requires to make one of the above determinations—but is able to draw a weaker conclusion by relaxing those tolerances somewhat. are updated identically to the “accurate” cases. 63 . and -Inf for maximizations. In such cases. see §8. Two ﬁnal results are also possible: • Failed: The solver failed to make suﬃcient progress towards a solution. often because the problem is particularly “nasty” in some way (e.2. In some cases.

infeasible. In practice.• Overdetermined: The presolver has determined that the problem has more equality constraints than variables. 64 . which means that the coeﬃcient matrix of the equality constraints is singular. Unfortunately. solvers typically cannot handle such problems. so a precise conclusion cannot be reached. The situations that most commonly produce an Overdetermined result are discussed in §D. such problems are often.3 below. but not always.

Unfortunately. Solving this approximation yields an approximate optimal point x. and various entropy functions. cvx will issue a warning saying so. There is currently no way to change this tolerance. To determine integral values pn .2 Irrational powers In order to implement power expressions like xp and p-norms x p for 1 < p < ∞.2. including exp. the functions requested most often to be added to the cvx function library were those from the exponential family. The complexity of the SDP implementation depends on roughly on the size of the values pn and pd . See the documentation for rat for more details. pd ). we have been pleased with the eﬀectiveness of the successive approximation method. we have constructed a successive approximation method that allows symmetric primal/dual solvers to support the exponential family of functions. So far. Let us introduce a more precise measure of this complexity. we denote this number by k(pn . D.D D. but we can provide a highly simpliﬁed description here. For other values of p = pn /pd . insert the command cvx_expert true into your model before the ﬁrst use of such features. For this reason. The precise nature of the method will be published elsewhere. cvx uses Matlab’s rat function with its default tolerance of 10−6 . etc. For p = 2. This approach is exact—as long as the exponent p is rational. log. cvx utilizes symmetric primal/dual solvers that simply cannot support those functions natively.) which is accurate within a neighborhood of some center point x0 . (A number of internal variables 65 . construct a new approximation. this is a highly simpliﬁed description of the approach.1 Advanced solver topics The successive approximation method Prior to version 1. and enhanced by the authors of cvx. cvx generates a number of 2 × 2 LMIs that depends on both pn and pd . Therefore. Nevertheless. and solve again. We shift the ¯ center point x0 towards x. we actually employ both the primal and dual solutions to guide our judgements for shifting x0 and terminating.. and a variety of practical factors has delayed the use of other types of solvers with cvx. First. This ¯ process is repeated until |¯ − x0 | is small enough to conclude that our approximation x is accurate enough to represent the original model. we believe that it is necessary to issue a warning when it is used so that users understand its experimental nature. a constraint xp ≤ y can be represented with exactly one 2 × 2 LMI: x2 ≤ y =⇒ y x x 1 0. pd such that pn /pd = p. cvx uses an SDP-compatible method described in [AG01]. for instance. the ﬁrst time that you solve a problem that will require successive approximation. we construct a global approximation for exp (or log. Again. If you wish to suppress this warning.

Setting the threshold to Inf disables it completely. In the event that this threshold does not suit you. but we ignore them for this analysis. minimize( trace( D ) ). where the α(pn ) term grows very slowly compared to the log2 term. Thus the problem. a warning is issued. you may change it using the command cvx_power_warning(thresh). for pn ≤ 4096. For example. problem is likely infeasible. You can query the current value by calling cvx_power_warning with no arguments.and equality constraints are also generated. subject to W + D == semidefinite(n). cvx achieves k(pn . or outside of a model to make a global change.5).n) diagonal. consider the problem of ﬁnding the smallest diagonal addition to a matrix W ∈ Rn×n to make it positive semideﬁnite: minimize Trace D subject to W + D 0 D diagonal In cvx.1). The cost of this SDP representation is relatively small for nearly all useful values of p. Similar results are obtained for 0 < p < 1 and p < 0. this problem might be expressed as follows: n = size(W. As with the command cvx_precision. cvx_end If we apply this speciﬁcation to the matrix W=randn(5. and the variable cvx_status is set to Overdetermined. D. Warning: Overdetermined equality constraints. pd ) ≤ log2 pn + α(pn ). 66 (16) . if you wish. we have veriﬁed that α(pn ) is usually 1 or 2.) An empirical study has shown that for p = pn /pd > 1. cvx_begin variable D(n. Nevertheless. Indeed. What has happened here is that the unnamed variable returned by statement semidefinite(n) is symmetric. cvx issues a warning whenever k(pn . but occasionally 0 or 3.3 Overdetermined problems This status message Overdetermined commonly occurs when structure in a variable or set is not properly recognized. pd ) > 10 to insure that the user is not surprised by any unexpected slowdown. you can place a call to cvx_power_warning within a model to change the threshold for a single model. so you can save it and restore it upon completion of your model. The command always returns the previous value of the threshold. but W is ﬁxed and unsymmetric. where thresh is the desired cutoﬀ value.

Arpita Ghosh. But there are also n2 equality constraints here. Rahul Pano icker. is infeasible. Lieven Vandenberghe. Imre Polik. Michael Overton and his students. Almir Mutapcic. cvx_end E Acknowledgements We wish to thank the following people for their contributions to the development of cvx: Toh Kim Chuan. minimize( trace( D ) ). Siddharth Joshi. cvx_begin variable D(n. and only n + n ∗ (n + 1)/2 unique degrees of freedom—thus the problem is overdetermined. Laurent El Ghaoui.n) diagonal. and generally helping us to improve its clarity.1). Art Owen. Argyris Zymnis. Johan L¨fberg.5 * ( W + W’ ) + D == semidefinite(n).as stated. The following modiﬁed version of the speciﬁcation corrects this problem by extracting the symmetric part of W : n = size(W. subject to 0. 67 . We are also e grateful to the many students in several universities who have (perhaps unwittingly) served as beta testers by using cvx in their classwork. Jo¨lle Skaf. We thank Igal Sason for catching many typos in an earlier version of this document.

The Scientiﬁc Press. December 2004. 2005.stanford. September 2005. Available at http://www. Grant. PhD thesis. Kendrick. editors. Duxbury Press.edu/pub/rrr/reports2001/51. http://www. pages 155– 210. Goldfarb.php. Springer. GAMS: A User’s Guide. Available at http://rutcor. 2004. CVXOPT: A Python Package for Convex Optimization. MATLAB (software package). mathworks.edu/ ∼boyd/disc cvx prog. Dahl and L. and A. A tutorial on geometric programming. [GBY06] M. 2005. D.html. Kim.edu/∼vandenbe/cvxopt. 2002. Meeraus.ee.stanford. S. 1998. Disciplined Convex Programming.rutgers.pdf. 2004. Available at http://www. S. Brooke. February 2005.References [AG01] F. Global Optimization: from Theory to Implementation. [Gra04] M. Second-order cone programming. Optimization and Engineering. 68 . Vandenberghe. PhD thesis. D.ee. Mosek (software package). A Parser/Solver for Convex Optimization Problems. In L.com. L. Vandenberghe. and Y. Inc. Boyd. http://www.edu/∼boyd/gp tutorial. [BKVH05] S. MATLAB optimization toolbox (software package). and R.ucla. C. L¨fberg. Hassibi.html. South San Francisco. [BV04] S. Raman. Convex Optimization. http://www. html.ps.html. Boyd. Kernighan. YALMIP version 3 (software package). November 2001. J.edu/∼boyd/disc cvx prog.edu/∼boyd/cvxbook.mosek. [Mat05] The MathWorks. J. Cambridge University Press. December 1999. Department of Electrical Engineering. Stanford University. A. Vandenberghe. Ye. Available at http://www. Disciplined convex programming. RUTCOR. Alizadeh and D. [MOS05] MOSEK ApS. AMPL: A Modeling Language for Mathematical Programming. o ethz. J. Maculan. See http: //www. Inc. and B.stanford. Available at http: //www.gams. Gay.com/products/optimization/. Grant. Technical Report RRR 51-2001. 2006. Liberti and N.stanford. [L¨f05] o [Mat04] The MathWorks. 2005.com. Crusius. http://control. [BKMR98] A. [Cru02] [DV05] [FGK99] R. Fourer. New York. Boyd and L.com/docs/gams/GAMSUsersGuide. Available at http://www. Rutgers University. Nonconvex Optimization and Its Applications. Stanford University.ch/∼joloef/yalmip.mathworks.

[Owe06] A.math.edu/∼boyd/sdpsol.-P.ca/.sg/∼mattohkc/sdpt3. 69 .0 (beta) (software package). Recent Advances in LMI Methods for Control. Department of Statistics. Sturm. Boyd. Optimization Methods and Software. Software available at http://sedumi. 11:625–653. Owen. and M. Stanford University.mcmaster. 1999. In L. July 2006. editors. Technical report. [WB00] S. pages 79–91.02. T¨t¨nc¨.stanford. SDPT3 4. R. Toh. [Stu99] J. Using SeDuMi 1. a MATLAB toolbox for optimization over symmetric cones. [TTT06] K.-I.html.html. Wu and S.nus. Niculescu. Todd. October 2006. SDPSOL: A parser/solver for semideﬁnite programs with matrix structure. Author’s internal draft. A robust hybrid of lasso and ridge regression. chapter 4.edu. Available at http://www. El Ghaoui and S. SIAM. uu u http://www. 2000.

46 cvx slvitr. 34 deﬁning new function. 54 aﬃne. 18 cvx pause. 13. 17 disciplined convex programming. 47 banded matrix variable. 6 complex variable. 23 expressions. 51 operators. 4. 41 Huber. 29 concave function. 28 cvx. 13. 35 equality constraint. 17 composition. 35 generalized posynomial. 41 GGP. 23 expression holder. 6 function. 36 monomial. see DCP dual variable. 28 deadzone. 21 epigraph. 11. 5 DCP. 5 ruleset. 18 nonconvex. 17 assignment. 54 installing. 10. 28 objective. see GP geometric programming mode. see GGP geometric program. 8 expression. 20 convex function. 25 deadzone function. 32 GAMS. 47 inequality. 4 array variable. 8 cvx expert. 4 functions. 44 cvx solver. 34 deﬁning new.Index aﬃne function. 41 quadratic. 44 cvx status. 28 constraint. 47 examples. 29 concave. 8 cvx clear. 65 cvx optval. 28 convex. 63 status messages. 41 70 . 23 feasibility. 19 cvx library. 18. 44 cvx problem. 46 cvx end. 54 precision. 26 feedback. 14. 5. 46 CVXOPT. 18. 10. 35 hypograph. 65 cvx precision. 18 equality. 9 posynomial. 41 monotonicity. 46 cvx power warning. 10 cvx slvtol. 34 diagonal matrix variable. 14. 34 epigraph. 18 bounds. 28 composition. 4 generalized geometric programming. 46 cvx quiet. 11. 10 cvx version. 63 cvx begin. 28 AMPL. 16 set. 14. 17 bug report. 46 cvx where.

see LP linprog. 18 nonconvex. 63 changing. 9. 41 powers. 54 output suppressing. 51 posynomial. 44 semidefinite. 17 banded matrix. 20 semideﬁnite program. 17 trade-oﬀ curve. 10 operators. 9 norm(·. 17 structure. 44 status messages. 18 minimize. see second-order cone LP. 5 Matlab. 4 QP. 9. 21 least squares. 5. 5 nondecreasing. 35 hypograph. 41 mode. 15 variable array. 36 inequality constraint. 39 mode. 10. 41 Hermitian matrix variable. 39. 21 solver changing. 14 objective function. 17 Toeplitz matrix variable. 5. 5. 17 variables. 44 problem dual. 41 SDP. 23 overdetermined. see LMI program. 9. 39 SDPT3. 4. 12 norm(·.1). 28 MOSEK. 28 nonincreasing. 4 quadratic form. 46 overdetermined problem. 28 norm. 18 71 . 39 monotonicity. 17 symmetric matrix. 40 infeasible problem. 4. 21 feasibility. see QP SDP. 66 platforms. 17 declaring. 4 maximize. 17 complex. 4. 11 LMI. see SDP semideﬁnite programming mode. 18 mode GP. 4. 65 symmetric matrix variable. 17 Toeplitz matrix. 39 Lorentz cone. 66 python. 17 variable. 4. see SOCP SeDuMi. 65 precision. 17 Hermitian matrix. 8 linear matrix inequality. 18 matrix. 17 Huber function. 4. 5. 32 quadratic program. 17 diagonal matrix.GP. 17.Inf). 20. 20 SOCP. 51 Lagrange multipler. 26 infeasible. 12. 44 second-order cone. 39 set. 21 second-order cone program. 23 installing cvx. 63 successive approximation. 18.

version information. 5 YALMIP. 4 72 .