<spanid="funcref"></span><h1>Reference guide<aclass="headerlink"href="#reference-guide"title="Permalink to this headline">¶</a></h1>
<p>In this section we describe each operator, function, set, and command that you are
likely to encounter in CVX. In some cases, limitations of the underlying solver
place certain restrictions or caveats on their use:</p>
<ulclass="simple">
<li>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 final precision. If you use one of these
functions, you will be warned that successive approximation will be
used. This technique is discussed further in
<aclass="reference internal"href="advanced.html#successive"><em>The successive approximation method</em></a>. As this section discusses, this is an experimental
approach that works well in many cases, but cannot be guaranteed.</li>
<li>Functions involving powers (<em>e.g.</em>, <ttclass="docutils literal"><spanclass="pre">x^p</span></tt>) and <spanclass="math">\(p\)</span>-norms
(<em>e.g.</em>, <ttclass="docutils literal"><spanclass="pre">norm(x,p)</span></tt>) are marked with a double dagger (‡). CVX
represents these functions exactly when <spanclass="math">\(p\)</span> is a rational
number. For irrational values of <ttclass="docutils literal"><spanclass="pre">p</span></tt>, a nearby rational is selected
instead. See <aclass="reference internal"href="advanced.html#powerfunc"><em>Power functions and p-norms</em></a> for details on
how both cases are handled.</li>
</ul>
<divclass="section"id="arithmetic-operators">
<h2>Arithmetic operators<aclass="headerlink"href="#arithmetic-operators"title="Permalink to this headline">¶</a></h2>
<p>Matlab’s standard arithmetic operations for addition <ttclass="docutils literal"><spanclass="pre">+</span></tt>, subtraction <ttclass="docutils literal"><spanclass="pre">-</span></tt>,
exponentiation <ttclass="docutils literal"><spanclass="pre">^</span></tt><ttclass="docutils literal"><spanclass="pre">.^</span></tt> have been overloaded to work in
CVX whenever appropriate—that is, whenever their use is consistent
with both standard mathematical and Matlab conventions <em>and</em> the DCP
ruleset. For example:</p>
<ulclass="simple">
<li>Two CVX expressions can be added together if they are of the same
dimension (or one is scalar) and have the same curvature (<em>i.e.</em>,
both are convex, concave, or affine).</li>
<li>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.</li>
<li>An affine 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.</li>
</ul>
<p>Numerous other combinations are possible, of course. The use of the exponentiation
operators <ttclass="docutils literal"><spanclass="pre">^</span></tt><ttclass="docutils literal"><spanclass="pre">.^</span></tt> are somewhat limited;
see the definitions of <ttclass="docutils literal"><spanclass="pre">power</span></tt> in <aclass="reference internal"href="#nonlinear"><em>Nonlinear</em></a> below.</p>
<p>Matlab’s basic matrix manipulation and arithmetic operations have been
extended to work with CVX expressions as well, including:</p>
<p>Most should behave identically with CVX expressions as they do with
numeric expressions. Those that perform some sort of summation, such as
<ttclass="docutils literal"><spanclass="pre">cumsum</span></tt>, <ttclass="docutils literal"><spanclass="pre">sum</span></tt>, or multiplication, such as <ttclass="docutils literal"><spanclass="pre">conv</span></tt>, <ttclass="docutils literal"><spanclass="pre">dot</span></tt> or
<ttclass="docutils literal"><spanclass="pre">kron</span></tt>, can only be used in accordance with the disciplined convex
programming rules. For example, <ttclass="docutils literal"><spanclass="pre">kron(X,Y)</span></tt> is valid only if either
<ttclass="docutils literal"><spanclass="pre">X</span></tt> or <ttclass="docutils literal"><spanclass="pre">Y</span></tt> is constant; and <ttclass="docutils literal"><spanclass="pre">trace(Z)</span></tt> is valid only if the
elements along the diagonal have the same curvature.</p>
</div>
<divclass="section"id="nonlinear">
<spanid="id1"></span><h3>Nonlinear<aclass="headerlink"href="#nonlinear"title="Permalink to this headline">¶</a></h3>
<dd><pclass="first">norms for real and complex vectors and matrices. Convex. Thus
function follows the Matlab conventions closely. Thus the
one-argument version <ttclass="docutils literal"><spanclass="pre">norm(x)</span></tt> computes the 2-norm for vectors,
and the 2-norm (maximum singular value) for matrices. The
two-argument version <ttclass="docutils literal"><spanclass="pre">norm(x,p)</span></tt> is supported as follows:</p>
<ulclass="last simple">
<li>‡ For vectors, all values <spanclass="math">\(p\geq 1\)</span> are accepted.</li>
<li>For matrices, <ttclass="docutils literal"><spanclass="pre">p</span></tt> must be <ttclass="docutils literal"><spanclass="pre">1</span></tt>, <ttclass="docutils literal"><spanclass="pre">2</span></tt>, <ttclass="docutils literal"><spanclass="pre">Inf</span></tt>, or <ttclass="docutils literal"><spanclass="pre">'Fro'</span></tt>.</li>
<dd><pclass="first">polynomial evaluation. <ttclass="docutils literal"><spanclass="pre">polyval(p,x)</span></tt>, where <ttclass="docutils literal"><spanclass="pre">p</span></tt> is a vector of
<p>This function can be used in CVX in two ways:</p>
<ulclass="last simple">
<li>If <ttclass="docutils literal"><spanclass="pre">p</span></tt> is a variable and <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a constant, then
<ttclass="docutils literal"><spanclass="pre">polyval(x,p)</span></tt> computes a linear combination of the elements of
<ttclass="docutils literal"><spanclass="pre">p</span></tt>. The combination must satisfy the DCP rules for addition
and scaling.</li>
<li>If <ttclass="docutils literal"><spanclass="pre">p</span></tt> is a constant and <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a variable, then
<ttclass="docutils literal"><spanclass="pre">polyval(x,p)</span></tt> constructs a polynomial function of the variable
<ttclass="docutils literal"><spanclass="pre">x</span></tt>. The polynomial must be affine, convex, or concave, and
<ttclass="docutils literal"><spanclass="pre">x</span></tt> must be real and affine.</li>
<dd><pclass="first"><ttclass="docutils literal"><spanclass="pre">x^p</span></tt> and <ttclass="docutils literal"><spanclass="pre">x.^p</span></tt>, where <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a real variable and and <ttclass="docutils literal"><spanclass="pre">p</span></tt>
is a real constant. For <ttclass="docutils literal"><spanclass="pre">x^p</span></tt>, both <ttclass="docutils literal"><spanclass="pre">x</span></tt> and <ttclass="docutils literal"><spanclass="pre">p</span></tt> must be
scalars. Only those values of <ttclass="docutils literal"><spanclass="pre">p</span></tt> which can reasonably and
unambiguously interpreted as convex or concave are accepted:</p>
<ulclass="simple">
<li><spanclass="math">\(p=0\)</span>. Constant. <ttclass="docutils literal"><spanclass="pre">x.^p</span></tt> is treated as identically 1.</li>
<li><spanclass="math">\(0 < p < 1\)</span>. Concave. The argument <spanclass="math">\(x\)</span> must be
concave (or affine), and is implicitly constrained to be
nonnegative.</li>
<li><spanclass="math">\(p = 1\)</span>. Affine. <ttclass="docutils literal"><spanclass="pre">x.^p</span></tt> is simply <ttclass="docutils literal"><spanclass="pre">x</span></tt>.</li>
<li><spanclass="math">\(p \in \{2,4,6,8,...\}\)</span>. Convex. Argument <spanclass="math">\(x\)</span> must be
<spanclass="math">\(x\)</span> must be affine, and is implicitly constrained to be
nonnegative.</li>
</ul>
<pclass="last">Negative and odd integral values of <spanclass="math">\(p\)</span> are not permitted, but
see the functions <ttclass="docutils literal"><spanclass="pre">pow_p</span></tt>, <ttclass="docutils literal"><spanclass="pre">pow_pos</span></tt>, and <ttclass="docutils literal"><spanclass="pre">pow_abs</span></tt> in the
<dd><pclass="first"><ttclass="docutils literal"><spanclass="pre">p.^x</span></tt> and <ttclass="docutils literal"><spanclass="pre">p^x</span></tt>, where <ttclass="docutils literal"><spanclass="pre">p</span></tt> is a real constant and <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a
real variable. For <ttclass="docutils literal"><spanclass="pre">p^x</span></tt>, both <ttclass="docutils literal"><spanclass="pre">p</span></tt> and <ttclass="docutils literal"><spanclass="pre">x</span></tt> must be scalars.
Valid values of <ttclass="docutils literal"><spanclass="pre">p</span></tt> include:</p>
<dt>The average absolute deviation about the median <spanclass="math">\(\mathop{\textrm{m}}(x)\)</span> of <spanclass="math">\(x\)</span>. Convex.</dt>
<dt>The reversed Huber function (hence, Berhu), defined as</dt>
<dd><divclass="first last math">
\[\begin{split}f_{\text{berhu}}(x,M) \triangleq \begin{cases} |x| & |x| \leq M \\ (|x|^2+M^2)/2M & |x| \geq M \end{cases}\end{split}\]</div>
</dd>
</dl>
<pclass="last">Convex. If <spanclass="math">\(M\)</span> is omitted, <spanclass="math">\(M=1\)</span> is assumed; but if supplied, it must be a positive constant.
Also callable with three arguments as <ttclass="docutils literal"><spanclass="pre">berhu(x,M,t)</span></tt>, which computes <ttclass="docutils literal"><spanclass="pre">t+t*berhu(x/t,M)</span></tt>,
useful for concomitant scale estimation (see <aclass="reference internal"href="credits.html#owen06"id="id2">[Owen06]</a>).</p>
<dd><spanclass="math">\(n\)</span>-th root of the determinant of a semidefinite matrix,
<spanclass="math">\((\det X)^{1/n}\)</span>. When used inside a CVX specification,
<ttclass="docutils literal"><spanclass="pre">det_rootn</span></tt> constrains the matrix to be symmetric (if real) or
Hermitian (if complex) and positive semidefinite. When used with
numerical arguments, <ttclass="docutils literal"><spanclass="pre">det_rootn</span></tt> returns <ttclass="docutils literal"><spanclass="pre">-Inf</span></tt> if these
<spanclass="math">\(\left( \prod_{k=1}^n x_k \right)^{1/n}\)</span>. When used inside a
CVX specification, <ttclass="docutils literal"><spanclass="pre">geo_mean</span></tt> constrains the elements of the
vector to be nonnegative. When used with numerical arguments,
<ttclass="docutils literal"><spanclass="pre">geo_mean</span></tt> returns <ttclass="docutils literal"><spanclass="pre">-Inf</span></tt> if any element is negative. Concave
\[\begin{split}f_{\text{huber}}(x,M) \triangleq \begin{cases} |x|^2 & |x| \leq M \\ 2M|x|-M^2 & |x| \geq M \end{cases}\end{split}\]</div>
</dd>
</dl>
<pclass="last">Convex. If $x$ is a vector or array, the function is applied on an elementwise basis. If $M$ is omitted, then $M=1$ is assumed; but if it supplied, it must be a positive constant. Also callable as <ttclass="docutils literal"><spanclass="pre">huber(x,M,t)</span></tt>, which computes <ttclass="docutils literal"><spanclass="pre">t+t*huber(x/t,M)</span></tt>, useful for concomitant scale estimation (see <aclass="reference internal"href="credits.html#owen06"id="id3">[Owen06]</a>).</p>
<dt>The circularly symmetric Huber function, defined as</dt>
<dd><divclass="first last math">
\[\begin{split}f_{\text{huber\_circ}}(x,M) \triangleq \begin{cases} \|x\|_2^2 & \|x\|_2 \leq M \\ 2M\|x\|_2-M^2 & \|x\|_2 \geq M \end{cases}\end{split}\]</div>
</dd>
</dl>
<pclass="last">Convex. Same (and implemented) as <ttclass="docutils literal"><spanclass="pre">huber_pos(norm(x),M)</span></tt>.</p>
\[\begin{split}f_{\text{kl}}(x,y) \triangleq \begin{cases} x\log(x/y)-x+y & x,y>0 \\ 0 & x=y=0 \\ +\infty & \text{otherwise} \end{cases}\end{split}\]</div>
<pclass="last">Convex. Outside CVX specification, returns <spanclass="math">\(+\infty\)</span> if arguments aren’t in the
<dd>log of determinant of a positive definite matrix,
<spanclass="math">\(\log \det(X)\)</span>. When used inside a CVX specification,
<ttclass="docutils literal"><spanclass="pre">log_det</span></tt> constrains its argument to be symmetric (if real) or
Hermitian (if complex) and positive definite. With numerical
argument, <ttclass="docutils literal"><spanclass="pre">log_det</span></tt> returns <ttclass="docutils literal"><spanclass="pre">-Inf</span></tt> if these constraints are not
<dd><pclass="first">Computes the value of the <em>convex or concave envelope</em> of the
polynomial described by <ttclass="docutils literal"><spanclass="pre">p</span></tt> (in the <ttclass="docutils literal"><spanclass="pre">polyval</span></tt> sense). <ttclass="docutils literal"><spanclass="pre">p</span></tt> must
be a real constant vector whose length <ttclass="docutils literal"><spanclass="pre">n</span></tt> is 0, 1, 2, 3, or some
other <em>odd</em> length; and <ttclass="docutils literal"><spanclass="pre">x</span></tt> must be real and affine. The sign of
the first nonzero element of <ttclass="docutils literal"><spanclass="pre">p</span></tt> determines whether a convex
(positive) or concave (negative) envelope is constructed. For
example, consider the function <spanclass="math">\(p(x)\triangleq (x^2-1)^2=x^4-2x^2+1\)</span>,
depicted along with its convex envelope in the figure below.</p>
<p>The two coincide when <spanclass="math">\(|x|\geq 1\)</span>, but deviate when
<spanclass="math">\(|x|<1\)</span>. Attempting to call <ttclass="docutils literal"><spanclass="pre">polyval([1,0,2,0,1],x)</span></tt> in a
CVX model would yield an error, but a call to <ttclass="docutils literal"><spanclass="pre">poly_env([1,0,2,0,1],x)</span></tt>
yields a valid representation of the envelope. For convex or concave
polynomials, this function produces the same result as <ttclass="docutils literal"><spanclass="pre">polyval</span></tt>.</p>
<dd><spanclass="math">\(\prod_i x_i^{-1}\)</span> when <spanclass="math">\(x\)</span> is positive; <spanclass="math">\(+\infty\)</span> otherwise. Convex
<dd><spanclass="math">\(x^TPx\)</span> for real <spanclass="math">\(x\)</span> and symmetric <spanclass="math">\(P\)</span>, and
<spanclass="math">\(x^HPx\)</span> for complex <spanclass="math">\(x\)</span> and Hermitian <spanclass="math">\(P\)</span>. Convex
in <spanclass="math">\(x\)</span> for <spanclass="math">\(P\)</span> constant and positive semidefinite;
concave in <spanclass="math">\(x\)</span> for <spanclass="math">\(P\)</span> constant and negative
semidefinite.</dd>
</dl>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Quadratic functions such as <ttclass="docutils literal"><spanclass="pre">quad_form</span></tt>, <ttclass="docutils literal"><spanclass="pre">sum_square</span></tt> can often be replaced
by the <ttclass="docutils literal"><spanclass="pre">norm</span></tt> function without sacrificing equivalence. For numerical reasons,
this alternate formulation is <em>preferred</em>. Please see <aclass="reference internal"href="advanced.html#quad-forms"><em>Eliminating quadratic forms</em></a> for
<dd><ttclass="docutils literal"><spanclass="pre">sum_square_pos(</span><spanclass="pre">x</span><spanclass="pre">)/y</span></tt> for <spanclass="math">\(x\in\mathbf{R}^n\)</span>, <spanclass="math">\(y>0\)</span>.
Convex, increasing in <spanclass="math">\(x\)</span>, and decreasing in <spanclass="math">\(y\)</span>.</dd>
<dd>sum of the smallest <spanclass="math">\(k\)</span> values, <em>i.e.</em>, equivalent to <ttclass="docutils literal"><spanclass="pre">-sum_largest(-x,k)</span></tt>. Concave and nondecreasing.</dd>
<dd>Equivalent to <ttclass="docutils literal"><spanclass="pre">sum(square(x))</span></tt>, but more efficient. Convex. Works only for real values.</dd>
<dd><pclass="first">The cone of all coefficients of nonnegative polynomials of degree <spanclass="math">\(n\)</span>; <spanclass="math">\(n\)</span> must be even:</p>
<dd><pclass="first">The cone of all coefficients of convex polynomials of degree <spanclass="math">\(n\)</span>; <spanclass="math">\(n\)</span> must be even:</p>
<dd>Begins a new CVX model. If a model is already in progress, it will issue a warning
and clear it. See <aclass="reference internal"href="basics.html#begin-end"><em>cvx_begin and cvx_end</em></a> for a full description, including the modifying
keywords that control solver output, SDP mode, GDP mode, etc.</dd>
<dd>Controls the issuance of warnings when models requiring the use of successive
approximation are employed; see <aclass="reference internal"href="advanced.html#successive"><em>The successive approximation method</em></a> more details.</dd>
<dd>Controls if and when CVX issues warnings during the construction of models involving
rational power functions (i.e., <ttclass="docutils literal"><spanclass="pre">x^p</span></tt>, where <ttclass="docutils literal"><spanclass="pre">x</span></tt> is a variable and <ttclass="docutils literal"><spanclass="pre">p</span></tt> is a constant);
see <aclass="reference internal"href="advanced.html#powerfunc"><em>Power functions and p-norms</em></a>.</dd>
<dd>Enables or disables screen output during the solution process; see <aclass="reference internal"href="solver.html#solver-output"><em>Controlling screen output</em></a>.
Also see <aclass="reference internal"href="basics.html#begin-end"><em>cvx_begin and cvx_end</em></a> for the newer, preferred syntax <ttclass="docutils literal"><spanclass="pre">cvx_begin</span><spanclass="pre">quiet</span></tt>.</dd>
<dd>Saves the current states for <ttclass="docutils literal"><spanclass="pre">cvx_expert</span></tt>, <ttclass="docutils literal"><spanclass="pre">cvx_power_warning</span></tt>, <ttclass="docutils literal"><spanclass="pre">cvx_precision</span></tt>,
and <ttclass="docutils literal"><spanclass="pre">cvx_solver</span></tt> to disk, so that their values are retained when quitting and
re-starting MATLAB. The file is saved in MATLAB’s preference directory, which can
be located by typing the <ttclass="docutils literal"><spanclass="pre">prefdir</span></tt> command.</dd>
<dd>Selects the solver to be employed when solving CVX models; see <aclass="reference internal"href="solver.html#solver-selection"><em>Selecting a solver</em></a>.</dd>
<dd>Creates one or more expression holders; see <aclass="reference internal"href="basics.html#assignment"><em>Assignment and expression holders</em></a>.</dd>
<dd>Creates one or more variables for use in the current CVX model; see <aclass="reference internal"href="basics.html#variables"><em>Variables</em></a>.</dd>