CVXMOD – Symbols

Symbols in CVXMOD perform the same function as symbols in mathematics — they are used to represent constants or symbols. The two main types of symbols in CVXMOD are created using param (for parameters) and optvar (for optimization symbols). This page introduces the features common to both; see also the specifics of optvars and params.

>>> m = param('m')  # simple 1x1 parameter.

>>> A = param('A', value=randn(3, 2))  # rows and cols are set automatically.

>>> b = param('b', m)  # mx1 parameter with no value assigned at first.

>>> x = optvar('x') # 1x1 optimization variable.

>>> X = optvar('X', 5, 5, symm=True) # symmetric 5x5 matrix.

Naming symbols

Giving symbols a name attribute makes displaying them more attractive, especially when they are combined in expressions (see the later section in this document).

It is not possible for CVXMOD to assign symbol names implicitly; Python's object-oriented structure means that when you write m = symbol(), for example, the symbol has no idea that the first reference pointing to it happened to be called m. If no name is specified, symbols will be given a default sequential name like noname14.

Symbols may be named with any string. No checking is done to prevent duplicates or other confusing naming schemes. Symbol names are ignored for all purposes except display.

Symbolic sizes

It is possible to give symbols and parameters symbolic sizes. If m is a parameter, for example, a variable can be declared as having m rows. Symbolic checking will be carried out later to ensure that sizes match. This is currently only partially implemented.

>>> m = param('m')
>>> n = param('n')

>>> A = param('A', m, n)
>>> A
<mxn param symbol A>

>>> x = optvar('x', n)
>>> x
<nx1 optvar symbol x>

>>> A*x
<mx1 expression A*x; optvars: x>

Indexing (slicing) symbols

There are lots of different ways to slice symbols in CVXMOD. Indices start at 0. Symbolic indices are permitted.

Examples

• A[0,1] is the entry of A in the first row and second column ().

• A[:,2] is the third column of A.

• A[1,:] is the second row of A.

• A[2] is the third entry of the (column-major) vectorized form of A.

• A[(1,2),:] is the (vertically stacked) second and third rows of A.

• A[:,(3,4)] is the (horizontally stacked) fourth and fifth columns of A.

• A[((1,2),(3,4),(5,6)] is a column vector of the (2,3), (4,5) and (6,7) entries of A.

>>> x = optvar('x', 5)
>>> x[3]
<1x1 sliced optvar symbol x[3]>

Special symbols

These functions create ‘special’ symbols, which can be used like ordinary symbols, but have additional properties.

• eye(n, True) returns the size (n, n) symbolic identity matrix named I.

• unitvec(i, rows) returns the ith symbolic unit vector named, for example, e2. (Consistent with indexing from zero, the i unitvec has entry i-1 = 1.

• ones(m, n, symb=True) returns the symbolic all ones vector (or matrix).

• zeros(m, n, symb=True) returns the symbolic all zeros vector (or matrix).

Note: optvars and params are both symbols

In fact, param and optvar are treated in a very similar way by CVXMOD. Both are actually symbols, with the role attribute of the symbol used to specify how the symbol will be interpreted by CVXMOD.

In particular, for a symbol s,

• s.role = 'param' means that s is a parameter.

• s.role = 'optvar' means that s is an optimization variable.

The role can be changed at any time. This is useful for tasks like alternating optimization, where the role of a symbol is changed at each iteration.

# Setup for minimization over x of norm(Ax - b).
>>> A = param('A', 5, 3)
>>> b = param('b', 5)
>>> x = optvar('x', 5)

>>> type(A)
<class 'cvxmod.base.symbol'>
>>> type(x)
<class 'cvxmod.base.symbol'>
>>> A.role
'param'
>>> x.role
'optvar'