<span id="quickstart"></span><span id="index-0"></span><h1>A quick start<a class="headerlink" href="#a-quick-start" title="Permalink to this headline">¶</a></h1>
<p>Once you have installed CVX (see <a class="reference internal" href="install.html#install"><em>Installation</em></a>), you can start using it by
entering a CVX <em>specification</em> into a Matlab script or function, or
directly from the command prompt. To delineate CVX specifications
from surrounding Matlab code, they are preceded with the statement
<tt class="docutils literal"><span class="pre">cvx_begin</span></tt> and followed with the statement <tt class="docutils literal"><span class="pre">cvx_end</span></tt>. A
specification can include any ordinary Matlab statements, as well as
special CVX-specific commands for declaring primal and dual
optimization variables and specifying constraints and objective
functions.</p>
<p>Within a CVX specification, optimization variables have no numerical
value; instead, they are special Matlab objects. This enables Matlab to
distinguish between ordinary commands and CVX objective functions
and constraints. As CVX reads a problem specification, 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 <tt class="docutils literal"><span class="pre">cvx_end</span></tt> command, it
completes the conversion of the CVX specification to a canonical
form, and calls the underlying core solver to solve it.</p>
<p>If the optimization is successful, the optimization variables declared
in the CVX specification 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.</p>
<p>This processing flow will become clearer as we introduce a number of
simple examples. We invite the reader to actually follow along with
these examples in Matlab, by running the <tt class="docutils literal"><span class="pre">quickstart</span></tt> script found in
the <tt class="docutils literal"><span class="pre">examples</span></tt> subdirectory of the CVX distribution. For example,
if you are on Windows, and you have installed the CVX distribution
in the directory <tt class="docutils literal"><span class="pre">D:\Matlab\cvx</span></tt>, then you would type</p>
<p>(The indentation is used for purely stylistic reasons and is optional.)
Let us examine this specification line by line:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">cvx_begin</span></tt> creates a placeholder for the new CVX
specification, and prepares Matlab to accept variable declarations,
constraints, an objective function, and so forth.</li>
<li><tt class="docutils literal"><span class="pre">variable</span> <span class="pre">x(n)</span></tt> declares <tt class="docutils literal"><span class="pre">x</span></tt> to be an optimization variable of
dimension <span class="math">\(n\)</span>. CVX requires that all problem variables be
declared before they are used in the objective function or
constraints.</li>
<li><tt class="docutils literal"><span class="pre">minimize(</span> <span class="pre">norm(A*x-b)</span> <span class="pre">)</span></tt> specifies the objective function to be
minimized.</li>
<li><tt class="docutils literal"><span class="pre">cvx_end</span></tt> signals the end of the CVX specification, and causes
the problem to be solved.</li>
</ul>
<p>Clearly 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.</p>
<p>When Matlab reaches the <tt class="docutils literal"><span class="pre">cvx_end</span></tt> command, the least-squares problem
is solved, and the Matlab variable <tt class="docutils literal"><span class="pre">x</span></tt> is overwritten with the
solution of the least-squares problem, i.e., <span class="math">\((A^TA)^{-1}A^Tb\)</span>. Now
<tt class="docutils literal"><span class="pre">x</span></tt> is an ordinary length-<span class="math">\(n\)</span> numerical vector, identical to
what would be obtained in the traditional approach, at least to within
the accuracy of the solver. In addition, several additional Matlab
variables are created; for instance,</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">cvx_optval</span></tt> contains the value of the objective function;</li>
<li><tt class="docutils literal"><span class="pre">cvx_status</span></tt> contains a string describing the status of the
calculation (see <a class="reference internal" href="solver.html#interpreting"><em>Interpreting the results</em></a>).</li>
</ul>
<p>All of these quantities—<tt class="docutils literal"><span class="pre">x</span></tt>, <tt class="docutils literal"><span class="pre">cvx_optval</span></tt>, and <tt class="docutils literal"><span class="pre">cvx_status</span></tt>,
<em>etc.</em>—may now be freely used in other Matlab statements, just like
any other numeric or string values. <a class="footnote-reference" href="#id4" id="id1">[1]</a></p>
<p>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 the objective function with</p>
<span id="index-2"></span><h2>Bound-constrained least squares<a class="headerlink" href="#bound-constrained-least-squares" title="Permalink to this headline">¶</a></h2>
<p>Suppose we wish to add some simple upper and lower bounds to the
least-squares problem above: <em>i.e</em>.,</p>
<div class="math">
\[\begin{split}\begin{array}{ll}
\mbox{minimize} & \|Ax-b\|_2\\
\mbox{subject to} & l \preceq x \preceq u
\end{array}\end{split}\]</div>
<p>where <span class="math">\(l\)</span> and <span class="math">\(u\)</span> are given data vectors with the same
dimension as <span class="math">\(x\)</span>. The vector inequality
<span class="math">\(u \preceq v\)</span> means componentwise, i.e., <span class="math">\(u_i \leq v_i\)</span> for
all <span class="math">\(i\)</span>. 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 difficulty with a standard QP solver. <a class="footnote-reference" href="#id5" id="id2">[2]</a></p>
<p>Let us provide some numeric values for <tt class="docutils literal"><span class="pre">l</span></tt> and <tt class="docutils literal"><span class="pre">u</span></tt>:</p>
<p>The first line displays the optimal value as determined by CVX; the
second recomputes the same value from the optimal vector <tt class="docutils literal"><span class="pre">x</span></tt> as
determined by CVX.</p>
<p>The list of supported nonlinear functions in CVX goes well beyond
<tt class="docutils literal"><span class="pre">norm</span></tt> and <tt class="docutils literal"><span class="pre">norm_largest</span></tt>. For example, consider the Huber penalty
minimization problem</p>
<div class="math">
\[\begin{split}\begin{array}{ll}
\text{minimize} & \sum_{i=1}^m \phi( (Ax-b)_i )
\end{array},\end{split}\]</div>
<p>with variable <span class="math">\(x \in \mathbf{R}^n\)</span>, where <span class="math">\(\phi\)</span> is the
Huber penalty function</p>
<div class="math">
\[\begin{split}\phi(z) = \begin{cases} |z|^2 & |z|\leq 1 \\ 2|z|-1 & |z|\geq 1\end{cases}.\end{split}\]</div>
<p>The Huber penalty function is convex, and has been provided in the
CVX function library. So solving the Huber penalty minimization
<p>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.)</p>
</div>
<div class="section" id="other-constraints">
<h2>Other constraints<a class="headerlink" href="#other-constraints" title="Permalink to this headline">¶</a></h2>
<p>We hope that, by now, it is not surprising that adding the simple
bounds <span class="math">\(l\preceq x\preceq u\)</span> to the problems above
is as simple as inserting the line <tt class="docutils literal"><span class="pre">l</span> <span class="pre"><=</span> <span class="pre">x</span> <span class="pre"><=</span> <span class="pre">u</span></tt>
before the <tt class="docutils literal"><span class="pre">cvx_end</span></tt> statement in each CVX specification. In fact,
CVX supports more complex constraints as well. For example, let us
define new matrices <tt class="docutils literal"><span class="pre">C</span></tt> and <tt class="docutils literal"><span class="pre">d</span></tt> in Matlab as follows,</p>
quite differently when they involve CVX optimization variables, or
expressions constructed from CVX optimization variables, than when
they involve simple numeric values. For example, because <tt class="docutils literal"><span class="pre">x</span></tt> is a
declared variable, the expression <tt class="docutils literal"><span class="pre">C*x==d</span></tt> causes a constraint to be
included in the CVX specification, and returns no value at all. On
the other hand, outside of a CVX specification, if <tt class="docutils literal"><span class="pre">x</span></tt> has an
appropriate numeric value—for example immediately after the
<tt class="docutils literal"><span class="pre">cvx_end</span></tt> command—that same expression would return a vector of
<tt class="docutils literal"><span class="pre">1</span></tt>s and <tt class="docutils literal"><span class="pre">0</span></tt>s, corresponding to the truth or falsity of each
equality. <a class="footnote-reference" href="#id6" id="id3">[3]</a> Likewise, within a CVX specification, the statement
<tt class="docutils literal"><span class="pre">norm(x,Inf)<=1</span></tt> adds a nonlinear constraint to the specification;
outside of it, it returns a <tt class="docutils literal"><span class="pre">1</span></tt> or a <tt class="docutils literal"><span class="pre">0</span></tt> depending on the numeric
value of <tt class="docutils literal"><span class="pre">x</span></tt> (specifically, whether its <span class="math">\(\ell_\infty\)</span>-norm is
less than or equal to, or more than, <span class="math">\(1\)</span>).</p>
<p>Because CVX is designed to support convex optimization, it must be
able to verify that problems are convex. To that end, CVX adopts
certain 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 affine. So a
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>If you type <tt class="docutils literal"><span class="pre">who</span></tt> or <tt class="docutils literal"><span class="pre">whos</span></tt> at the command prompt, you may see
other, unfamiliar variables as well. Any variable that begins with
the prefix <tt class="docutils literal"><span class="pre">cvx_</span></tt> is reserved for internal use by <tt class="docutils literal"><span class="pre">CVX</span></tt> itself,
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>There are also a number of solvers specifically designed to solve bound-constrained
least-squares problems, such as <a class="reference external" href="http://www.cs.ubc.ca/~mpf/bcls/">BCLS by Michael Friedlander</a>.</td></tr>
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>In fact, immediately after the <tt class="docutils literal"><span class="pre">cvx_end</span></tt> command above, you would
likely find that most if not all of the values returned would be
<tt class="docutils literal"><span class="pre">0</span></tt>. 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 satisfied