<h1>The Basics<aclass="headerlink"href="#the-basics"title="Permalink to this headline">¶</a></h1>
<divclass="section"id="cvx-begin-and-cvx-end">
<spanid="begin-end"></span><h2><ttclass="docutils literal"><spanclass="pre">cvx_begin</span></tt> and <ttclass="docutils literal"><spanclass="pre">cvx_end</span></tt><aclass="headerlink"href="#cvx-begin-and-cvx-end"title="Permalink to this headline">¶</a></h2>
<p>All CVX models must be preceded by the command <ttclass="docutils literal"><spanclass="pre">cvx_begin</span></tt> and
terminated with the command <ttclass="docutils literal"><spanclass="pre">cvx_end</span></tt>. All variable declarations,
objective functions, and constraints should fall in between.
The cvx_begin command may include one more more modifiers:</p>
<p>These modifiers may be combined when appropriate; for instance, <ttclass="docutils literal"><spanclass="pre">cvx_begin</span><spanclass="pre">sdp</span><spanclass="pre">quiet</span></tt>
invokes SDP mode and silences the solver output.</p>
</div>
<divclass="section"id="variables">
<spanid="id1"></span><h2>Variables<aclass="headerlink"href="#variables"title="Permalink to this headline">¶</a></h2>
<p>All variables must be declared using the
<ttclass="docutils literal"><spanclass="pre">variable</span></tt> command (or <ttclass="docutils literal"><spanclass="pre">variables</span></tt> command; see below)
before they can be used in constraints or an objective function.
A <ttclass="docutils literal"><spanclass="pre">variable</span></tt> command includes the name of the variable, an optional
dimension list, and one or more keywords that provide additional
information about the content or structure of the variable.</p>
<p>Variables can be real or complex scalars, vectors, matrices, or
<spanclass="math">\(n\)</span>-dimensional arrays. For instance,</p>
<divclass="highlight-none"><divclass="highlight"><pre>variable X
variable Y(20,10)
variable Z(5,5,5)
</pre></div>
</div>
<p>declares a total of 326 (scalar) variables: a scalar <ttclass="docutils literal"><spanclass="pre">X</span></tt>, a 20x10 matrix <ttclass="docutils literal"><spanclass="pre">Y</span></tt> (containing 200 scalar variables),
and a 5x5x5 array <ttclass="docutils literal"><spanclass="pre">Z</span></tt> (containing 125 scalar variables).</p>
<p>Variable declarations can also include one or more <em>keywords</em> to denote various
structures or conditions on the variable. For instance, to declare a complex
variable, use the <ttclass="docutils literal"><spanclass="pre">complex</span></tt> keyword:</p>
<p>Nonnegative variables and symmetric/Hermitian positive semidefinite (PSD) matrices can
be specified with the <ttclass="docutils literal"><spanclass="pre">nonnegative</span></tt> and <ttclass="docutils literal"><spanclass="pre">semidefinite</span></tt> keywords, respectively:</p>
<p>In this example, <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a nonnegative vector, and <ttclass="docutils literal"><spanclass="pre">Z</span></tt> is a real symmetric PSD matrix
and <ttclass="docutils literal"><spanclass="pre">Q``is</span><spanclass="pre">a</span><spanclass="pre">complex</span><spanclass="pre">Hermitian</span><spanclass="pre">PSD</span><spanclass="pre">matrix.</span><spanclass="pre">As</span><spanclass="pre">we</span><spanclass="pre">will</span><spanclass="pre">see</span><spanclass="pre">below,</span><spanclass="pre">``hermitian</span><spanclass="pre">semidefinite</span></tt>
would be an equivalent choice for this third case.</p>
<p>For MIDCPs, the <ttclass="docutils literal"><spanclass="pre">integer</span></tt> and <ttclass="docutils literal"><spanclass="pre">binary</span></tt> keywords are used to declare integer
<p>The underscores can actually be omitted; so, for example, <ttclass="docutils literal"><spanclass="pre">lower</span><spanclass="pre">triangular</span></tt>
is acceptable as well. These keywords are self-explanatory with a couple of exceptions:</p>
<p>The one limitation of the <ttclass="docutils literal"><spanclass="pre">variables</span></tt> command is that it cannot
declare complex, integer, or structured variables.
These must be declared one at a time, using the singular <ttclass="docutils literal"><spanclass="pre">variable</span></tt>
command.</p>
</div>
<divclass="section"id="objective-functions">
<spanid="objectives"></span><h2>Objective functions<aclass="headerlink"href="#objective-functions"title="Permalink to this headline">¶</a></h2>
<p>Declaring an objective function requires the use of the <ttclass="docutils literal"><spanclass="pre">minimize</span></tt> or
<ttclass="docutils literal"><spanclass="pre">maximize</span></tt> function, as appropriate. (For the benefit of our users whose
English favors it, the synonyms <ttclass="docutils literal"><spanclass="pre">minimise</span></tt> and <ttclass="docutils literal"><spanclass="pre">maximise</span></tt> 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
<p>At most one objective function may be declared in a
CVX specification, and it must have a scalar value.</p>
<p>If no objective function is specified, the problem is interpreted as a
<em>feasibility problem</em>, 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.</p>
</div>
<divclass="section"id="constraints">
<spanid="id2"></span><h2>Constraints<aclass="headerlink"href="#constraints"title="Permalink to this headline">¶</a></h2>
<p>The following constraint types are supported in CVX:</p>
<ulclass="simple">
<li>Equality <ttclass="docutils literal"><spanclass="pre">==</span></tt> constraints, where both the left- and right-hand
sides are affine expressions.</li>
<li>Less-than <ttclass="docutils literal"><spanclass="pre"><=</span></tt> inequality constraints, where the left-hand
expression is convex, and the right-hand expression is concave.</li>
<li>Greater-than <ttclass="docutils literal"><spanclass="pre">>=</span></tt> constraints, where the left-hand expression is
concave, and the right-hand expression is convex.</li>
</ul>
<p>The non-equality operator <ttclass="docutils literal"><spanclass="pre">~=</span></tt> may <em>never</em> be
used in a constraint; in any case, such constraints are rarely convex.
The latest version of CVX now allows you to chain inequalities
together; <em>e.g.</em>, <ttclass="docutils literal"><spanclass="pre">l</span><spanclass="pre"><=</span><spanclass="pre">x</span><spanclass="pre"><=</span><spanclass="pre">u</span></tt>. (Previous versions did not allow chained
inequalities.)</p>
<p>Note the important distinction between the single equals <ttclass="docutils literal"><spanclass="pre">=</span></tt>, which is an
assignment, and the double equals <ttclass="docutils literal"><spanclass="pre">==</span></tt>, which denotes equality; for more
on this distinction, see <aclass="reference internal"href="#assignment"><em>Assignment and expression holders</em></a> below.</p>
<p>Strict inequalities <ttclass="docutils literal"><spanclass="pre"><</span></tt> and <ttclass="docutils literal"><spanclass="pre">></span></tt> are accepted as well, but they are interpreted
identically to their nonstrict counterparts. We strongly discourage their use, and
a future version of CVX may remove them altogether. For the reasoning behind
this, please see the fuller discussion in <aclass="reference internal"href="dcp.html#strict"><em>Strict inequalities</em></a>.</p>
<p>Inequality and equality constraints are applied in an elementwise fashion,
matching the behavior of MATLAB itself. For instance, if <ttclass="docutils literal"><spanclass="pre">A</span></tt> and <ttclass="docutils literal"><spanclass="pre">B</span></tt> are
<spanclass="math">\(m \times n\)</span> arrays, then <ttclass="docutils literal"><spanclass="pre">A<=B</span></tt> is
interpreted as <spanclass="math">\(mn\)</span> (scalar) inequalities <ttclass="docutils literal"><spanclass="pre">A(i,j)<=B(i,j)</span></tt>. When one
side or the other is a scalar, that value is replicated; for instance,
<ttclass="docutils literal"><spanclass="pre">A>0</span></tt> is interpreted as <ttclass="docutils literal"><spanclass="pre">A(i,j)>=0</span></tt>.</p>
<p>The elementwise treatment of inequalities is altered in
<aclass="reference internal"href="sdp.html#sdp-mode"><em>semidefinite programming mode</em></a>; see that section for more details.</p>
<p>CVX also supports a <em>set membership</em> constraint; see <aclass="reference internal"href="#sets"><em>Set membership</em></a> below.</p>
</div>
<divclass="section"id="functions">
<spanid="id3"></span><h2>Functions<aclass="headerlink"href="#functions"title="Permalink to this headline">¶</a></h2>
<p>The base CVX function library includes a variety of convex,
concave, and affine functions 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 <aclass="reference internal"href="funcref.html#funcref"><em>Reference guide</em></a>. It is
also possible to add your own new functions; see
<aclass="reference internal"href="advanced.html#newfunc"><em>Adding new functions to the atom library</em></a>.</p>
<p>An example of a function in the base library is the quadratic-over-linear
function <ttclass="docutils literal"><spanclass="pre">quad_over_lin</span></tt>:</p>
f(x,y) = \begin{cases} x^T x / y & y > 0 \\ +\infty & y \leq 0 \end{cases}\end{split}\]</div>
<p>(The function also accepts complex <spanclass="math">\(x\)</span>, but we’ll consider
real <spanclass="math">\(x\)</span> to keep things simple.) The quadratic-over-linear
function is convex in <spanclass="math">\(x\)</span> and <spanclass="math">\(y\)</span>, 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 <spanclass="math">\((Ax-b,c^Tx+d)\)</span> using</p>
<divclass="highlight-none"><divclass="highlight"><pre>minimize( quad_over_lin( A * x - b, c' * x + d ) );
</pre></div>
</div>
<p>inside a CVX specification, 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 affine function.</p>
<p>You can also use the function <ttclass="docutils literal"><spanclass="pre">quad_over_lin</span></tt><em>outside</em> a CVX
specification. In this case, it just computes its (numerical) value,
given (numerical) arguments. If <ttclass="docutils literal"><spanclass="pre">c'*x+d</span></tt> is positive, then the
result is numerically equivalent tp</p>
<divclass="highlight-none"><divclass="highlight"><pre>( ( A * x - b )' * ( A * x - b ) ) / ( c' * x + d )
</pre></div>
</div>
<p>However, the <ttclass="docutils literal"><spanclass="pre">quad_over_lin</span></tt> function also
performs a domain check, so it returns <ttclass="docutils literal"><spanclass="pre">Inf</span></tt> if <ttclass="docutils literal"><spanclass="pre">c'*x+d</span></tt> is zero or negative.</p>
</div>
<divclass="section"id="set-membership">
<spanid="sets"></span><h2>Set membership<aclass="headerlink"href="#set-membership"title="Permalink to this headline">¶</a></h2>
<p>CVX supports the definition and use of convex sets. The base
library includes the cone of positive semidefinite <spanclass="math">\(n \times n\)</span>
matrices, the second-order or Lorentz cone,
and various norm balls. A complete list of sets supplied in the base library
is given in <aclass="reference internal"href="funcref.html#sets-ref"><em>Sets</em></a>.</p>
<p>Unfortunately, the Matlab language does not have a set membership
operator, such as <ttclass="docutils literal"><spanclass="pre">x</span><spanclass="pre">in</span><spanclass="pre">S</span></tt>, to denote <spanclass="math">\(x \in S\)</span>. So in CVX,
we use a slightly different syntax to require that an expression is in a
set. To represent a set we use a <em>function</em> that returns an unnamed
variable that is required to be in the set. Consider, for example,
<spanclass="math">\(\mathbf{S}^n_+\)</span>, the cone of symmetric positive semidefinite
<spanclass="math">\(n \times n\)</span> matrices. In CVX, we represent this by the
function semidefinite(n), which returns an unnamed new variable,
that is constrained to be positive semidefinite. To require that the
matrix expression X be symmetric positive semidefinite, we use the
<p>The function call <ttclass="docutils literal"><spanclass="pre">lorentz(m)</span></tt> 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 <ttclass="docutils literal"><spanclass="pre">m</span></tt>. So the constraint in this specification
requires that the pair <ttclass="docutils literal"><spanclass="pre">{</span><spanclass="pre">A*x-b,</span><spanclass="pre">y</span><spanclass="pre">}</span></tt> lies in the appropriately-sized
Lorentz cone.</p>
</div>
<divclass="section"id="dual-variables">
<spanid="id4"></span><h2>Dual variables<aclass="headerlink"href="#dual-variables"title="Permalink to this headline">¶</a></h2>
<p>When a disciplined convex program is solved, the associated <em>dual
problem</em> is also solved. (In this context, the original problem is
called the <em>primal problem</em>.) 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 sensitivities with
respect to perturbing the constraints (<em>c.f.</em><aclass="reference external"href="http://www.stanford.edu/~boyd/cvxbook">Convex
Optimization</a>, chapter 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</p>
<divclass="math">
\[\begin{split}\begin{array}{llcll}
\mbox{minimize} & c^Tx \\
\mbox{subject to} & Ax \preceq b,
\end{array}\end{split}\]</div>
<p>with variable <spanclass="math">\(x\in\mathbf{R}^n\)</span>, and <spanclass="math">\(m\)</span> inequality
constraints. To associate
the dual variable <spanclass="math">\(y\)</span> with the inequality
constraint <spanclass="math">\(Ax\preceq b\)</span> in this LP, we use the following
<p>which prints out the products of the entries of <ttclass="docutils literal"><spanclass="pre">y</span></tt> and <ttclass="docutils literal"><spanclass="pre">b-A*x</span></tt>,
which should be nearly zero. This line must be executed <em>after</em> the
<ttclass="docutils literal"><spanclass="pre">cvx_end</span></tt> command (which assigns numerical values to <ttclass="docutils literal"><spanclass="pre">x</span></tt> and <ttclass="docutils literal"><spanclass="pre">y</span></tt>);
it will generate an error if it is executed inside the CVX
specification, where <ttclass="docutils literal"><spanclass="pre">y</span></tt> and <ttclass="docutils literal"><spanclass="pre">b-A*x</span></tt> are still just abstract
expressions.</p>
<p>If the optimization is <em>not</em> successful, because either the problem is
infeasible or unbounded, then <ttclass="docutils literal"><spanclass="pre">x</span></tt> and <ttclass="docutils literal"><spanclass="pre">y</span></tt> will have different
values. In the unbounded case, <ttclass="docutils literal"><spanclass="pre">x</span></tt> will contain an <em>unbounded
direction</em>; <em>i.e.</em>, a point <spanclass="math">\(x\)</span> satisfying</p>
<divclass="math">
\[c^T x = -1, \quad A x \preceq 0,\]</div>
<p>and <ttclass="docutils literal"><spanclass="pre">y</span></tt> will be filled with <ttclass="docutils literal"><spanclass="pre">NaN</span></tt> values, reflecting the fact that
the dual problem is infeasible. In the infeasible case, x is filled
with <ttclass="docutils literal"><spanclass="pre">NaN</span></tt> values, while y contains an <em>unbounded dual direction</em>;
<em>i.e.</em>, a point <spanclass="math">\(y\)</span> satisfying</p>
<divclass="math">
\[b^T y = -1, \quad A^T y = 0, \quad y \succeq 0\]</div>
<p>Of course, the precise interpretation of primal and dual points and/or
directions depends on the structure of the problem. See references such
as <aclass="reference external"href="http://www.stanford.edu/~boyd/cvxbook">Convex Optimization</a> for
more on the interpretation of dual information.</p>
<p>CVX also supports the declaration of <em>indexed</em> dual variables. These
prove useful when the <em>number</em> 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
<spanid="assignment"></span><h2>Assignment and expression holders<aclass="headerlink"href="#assignment-and-expression-holders"title="Permalink to this headline">¶</a></h2>
<p>Anyone with experience with C or Matlab understands the difference between the
single-equal <em>assignment</em> operator <ttclass="docutils literal"><spanclass="pre">=</span></tt> and the double-equal <em>equality</em> operator <ttclass="docutils literal"><spanclass="pre">==</span></tt>.
This distinction is vitally important in CVX as well, and CVX takes steps to ensure
that assignments are not used improperly. For instance, consider the following code snippet:</p>
<p>At first glance, the statement <ttclass="docutils literal"><spanclass="pre">X</span><spanclass="pre">=</span><spanclass="pre">semidefinite(n);</span></tt> may look like it
constrains <ttclass="docutils literal"><spanclass="pre">X</span></tt> to be positive semidefinite. But since the assignment operator is
used, <ttclass="docutils literal"><spanclass="pre">X</span></tt> is actually <em>overwritten</em> by the anonymous semidefinite variable instead.
Fortunately, CVX forbids declared variables from being overwritten in this way; when
<ttclass="docutils literal"><spanclass="pre">cvx_end</span></tt> is reached, this model would issue the following error:</p>
<divclass="highlight-none"><divclass="highlight"><pre>??? 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.
</pre></div>
</div>
<p>We hope that this check will prevent at least some typographical errors
from having frustrating consequences in your models.</p>
<p>Despite this warning, assignments can be genuinely useful, so we encourage their
use with appropriate care. For instance, consider the following excerpt:</p>
<divclass="highlight-none"><divclass="highlight"><pre>variables x y
z = 2 * x - y;
square( z ) <= 3;
quad_over_lin( x, z ) <= 1;
</pre></div>
</div>
<p>The construction <ttclass="docutils literal"><spanclass="pre">z</span><spanclass="pre">=</span><spanclass="pre">2</span><spanclass="pre">*</span><spanclass="pre">x</span><spanclass="pre">-</span><spanclass="pre">y</span></tt> is <em>not</em> an equality constraint; it
is an assignment. It is storing an intermediate calculation
<ttclass="docutils literal"><spanclass="pre">2</span><spanclass="pre">*</span><spanclass="pre">x</span><spanclass="pre">-</span><spanclass="pre">y</span></tt>, which is an affine expression, which is then used later
in two different constraints. We call <ttclass="docutils literal"><spanclass="pre">z</span></tt> an <em>expression holder</em> to
differentiate it from a formally declared CVX variable.</p>
<p>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
<p>CVX will accept this construction without error. You can then use
the concave expressions <ttclass="docutils literal"><spanclass="pre">x(1)</span></tt>, ..., <ttclass="docutils literal"><spanclass="pre">x(10)</span></tt> in any appropriate ways;
for example, you could maximize <ttclass="docutils literal"><spanclass="pre">x(10)</span></tt>.</p>
<p>The differences between a variable object and an expression
object are quite significant. A variable object holds an
optimization variable, and cannot be overwritten or assigned in the
CVX specification. (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 specification.</p>
<p>Of course, as our first example shows, it is not always <em>necessary</em> 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