x = sdpvar(1,1);
double(x)
 ans = 
    NaN

By using assign, this value can be altered

assign(x,1)
double(x)
 ans = 
    1

By default, inconsistent assignments generate an error message.

t = sdpvar(1,1);x = [t t];
assign(x,[1 2])
??? Error using ==> sdpvar/assign
Inconsistent assignment

With a third argument, a least squares assignment is obtained

t = sdpvar(1,1);x = [t t];
assign(x,[1 2],1)
double(x)

ans =

    1.5000    1.5000

Setting up a binary linear program {min c^Tx subject to Ax≤b} can be done as

x = binvar(n,1);
solvesdp(set(A*x<b),c'*x)

or

x = sdpvar(n,1);
solvesdp(set(A*x<b)+set(binary(x)),c'*x)

Note, the binary constraint is imposed on the involved variables, not the actual sdpvar object. Hence, the following two constraints are equivalent

F = set(binary(x));
F = set(binary(pi+sqrt(2)*x));

A scalar binary variable is defined with

P = binvar(1,1)

For more examples, see sdpvar.

n = 5;
m = 3;
A = sdpvar(n,n);
B = randn(n,2);
E = sdpvar(m,m);
C = randn(2,2);
D = randn(2,m);

X = [A B zeros(n,m);B' C D;zeros(m,n) D' E];

By using a block variable, we can define blocks instead.

X = blkvar;
X(1,1) = A;
X(1,2) = B;
X(1,3) = 0;
X(2,2) = C;
X(2,3) = D;
X(3,3) = E;
X = sdpvar(X);

Dimension of 0 blocks do not have to be specified, they will be automatically be derived, if possible, from the dimension of other elements. Note that we only have to define one element of symmetric pairs, YALMIP will automatically fill in the symmetric counter-part. If no symmetric counter-part is found, the corresponding block is filled with zeroes. Hence, the following code is equivalent.

X = blkvar;
X(1,1) = A;
X(1,2) = B;
X(2,2) = C;
X(2,3) = D;
X(3,3) = E;
X = sdpvar(X);

Standard operators can typically be applied directly to the block variable (but it is currently recommended to convert the variable to an sdpvar object)

X = blkvar;
X(1,1) = A;
X(1,2) = B;
X(2,2) = C;
X(2,3) = D;
X(3,3) = E;
F = set(X > 0 ) + set(trace(X)==1);
% Recommended
X = sdpvar(X);
F = set(X > 0 ) + set(trace(X)==1);

A1 = randn(10,3);
b1 = rand(10,1)*10;
A2 = randn(10,3);
b2 = rand(10,1)*10;
x = sdpvar(3,1);bounds(x,[-25;-25;-25],[25;25;25]);
F = set((A1*x<=b1) | (A1*x <=b2));
solvesdp(F,sum(x))

Of course, standard MATLAB notation applies so if you have the same bound on all variables, you only need to supply one scalar bound.

A1 = randn(10,3);
b1 = rand(10,1)*10;
A2 = randn(10,3);
b2 = rand(10,1)*10;
x = sdpvar(3,1);bounds(x,-25,25);
F = set((A1*x<=b1) | (A1*x <=b2));
solvesdp(F,sum(x))

Note that the big-M computation only take advantage of bounds explicitly defined using the bounds command. Bounds defined using a set construction will not be detected or exploited. Hence, the following problem will give rise to a MILP with weaker relaxations (big-M will be set to e 10⁴).

x = sdpvar(3,1);
F = set(-25 <= x<= 25) + set((A1*x<=b1) | (A1*x <=b2));
solvesdp(F,sum(x))

After solving a problem, we can easily check how well the constraints are satisfied.

solvesdp(F,objective);
checkset(F)

The constraint residuals are defined as smallest eigenvalue, smallest element, negated largest absolute-value element and largest distance to an integer for semidefinite, element-wise, second order cone and integrality constraints respectively. Hence, a solution is feasible if all residuals related to inequalities are non-negative and residuals related to equalities are sufficiently close to zero.

Sometimes it might be convenient to have the numerical values of the constraint violations

[p,d] = checkset(F);

Removing nuisance variables

x1 = sdpvar(n,1);
x2 = sdpvar(n,1);
x = x1+1e-8*x2;
y = clean(x,1e-6);
sdisplay(y)
ans
    'x1'

sdpvar x y s t
p = x^2+x*y*(s+t)+s^2+t^2;

The coefficients are easily recovered

c = coefficients(p,[x y]);
sdisplay(c)

ans = 
    's^2+t^2'
    's+t'
    '1'

By adding a second output, the monomial basis is returned also.

[c,v] = coefficients(p,[x y]);
sdisplay([c v])

ans = 
    's^2+t^2'    '1'  
    's+t'        'xy' 
    '1'          'x^2'

p-c'*v

ans =
     0

Of-course, we might just as well consider this to be a polynomial in s and t with coefficients parameterized by x and y.

[c,v] = coefficients(p,[s t]); sdisplay([c v]) ans = 'x^2' '1' 'xy' 't' '1' 't^2' 'xy' 's' '1' 's^2'

Constraining the Euclidean norm of a vector to be less than 1 is done with

x = sdpvar(n,1);
F = set(cone(x,1));

Of-course, arbitrary complicated constructs are possible, such as constraining the norm of the diagonal to be less than the sum of the off-diagonal terms in a matrix!

x = sdpvar(n,n);
F = set(cone(diag(x),sum(sum(x-diag(diag(x))))))

An alternative is to use the nonlinear norm operator instead (see the examples on nonlinear operators for details)

x = sdpvar(n,n);
F = set(norm(diag(x)) < sum(sum(x-diag(diag(x)))))

The result from this command is nothing but a set object.

P = sdpvar(2,2); 
F = cut((P-eye(2))*(P-eye(2))>0);
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                                Type|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|   Matrix inequality (quadratic) 2x2|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The only difference is that this constraint will not be used in the upper bound problem in the branch & bound procudure. The constraint will thus only be used to improve the relaxations. See the examples in global solutions of bilinear programs.

Let us begin by defining a large but low bandwidth SDP constraint.

n = 500;
r = 3;
B = randn(n,r+1);
S = spdiags(B,0:r,n,n);S = S+S';
x = sdpvar(n,1);
X = diag(x)-S;
p = randperm(n);
X = X(p,p);
F = set(X > 0)
spy(F)
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                        Type|
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|   Matrix inequality 500x500|
+++++++++++++++++++++++++++++++++++++++++++++++++++++

Applying the dissect command simplifies the constraint to a set of two smaller SDP constraints, at the price of introducing 6 additional variables.

dissect(F)
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                        Type|
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|   Matrix inequality 252x252|
|   #2|   Numeric value|   Matrix inequality 251x251|
+++++++++++++++++++++++++++++++++++++++++++++++++++++
length(getvariables(dissect(F)))
ans =

   506

The procedure can be recursively applied.

dissect(dissect(F))
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                        Type|
+++++++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|   Matrix inequality 128x128|
|   #2|   Numeric value|   Matrix inequality 127x127|
|   #3|   Numeric value|   Matrix inequality 127x127|
|   #4|   Numeric value|   Matrix inequality 127x127|
+++++++++++++++++++++++++++++++++++++++++++++++++++++
length(getvariables(dissect((dissect(F)))))
ans =

   518

To see the impact of the dissection, let us solve an SDP problem for various levels of dissection

sol = solvesdp(F,trace(X));sol.solvertime
ans =

  123.2810

F = dissect(F);
sol = solvesdp(F,trace(X));sol.solvertime
ans =

   36.0940

F = dissect(F);
sol = solvesdp(F,trace(X));sol.solvertime
ans =

   11.9070

F = dissect(F);
sol = solvesdp(F,trace(X));sol.solvertime
ans =

    4.6410

F = dissect(F);
sol = solvesdp(F,trace(X));sol.solvertime
ans =

    3.8430

F = dissect(F);
sol = solvesdp(F,trace(X));sol.solvertime
ans =

    3.9370

Note that the dissection command can be applied to arbitrary SDP problems in YALMIP (nonlinear problems, mixed semidefinite and second order cone problems etc).

The algorithm in the command is based on finding a vertex separator of the matrix in the SDP constraint, applying a Dulmage-Mendelsohn permutation to detect corresponding blocks, followed by a series of Schur completions. Details will be available in an accompanying report soon...

After solving an optimization problem we might, e.g., extract the optimal objective value.

solvesdp(F,obj);
optobj = double(obj);

It can also be used to extract the residual of a constraint

solvesdp(F,obj);
res = double(F(1));

x1 = sdpvar(1,1);
x2 = sdpvar(1,1);
f = x1^4+5*x2^2;
sdisplay(hessian(f))

ans = 

    '12x1^2'    '0' 
    '0'         '10'

Giving a second argument controls what variables to differentiate with respect to

sdisplay(hessian(f,x1))
ans = 

    '12x1^2'

After solving an optimization problem we might, e.g., extract the dual variable of the 2nd constraint.

solvesdp(F,obj);
Z2 = dual(F(2));

If the constraints in the set object have been tagged, we can use the tag instead

solvesdp(F,obj);
Z2 = dual(F('Lyapunov constraint'));

X = sdpvar(3,3);
Y = sdpvar(3,3);
F = set(X>0) + set(Y>0);
F = F + set(X(1,3)==9) + set(Y(1,1)==X(2,2));
F = F + set(sum(sum(X))+sum(sum(Y)) == 20);
obj = trace(X)+trace(Y);

We can solve this in the given format. This will however be very inefficient in YALMIP, since the matrices X and Y will be explicitely parameterized, and the problem will be solved in a dual form with equality constraints. Instead, we note that the problem is an SDP in standard primal form. We therefor let YALMIP extract this primal model, and return the dual of this. If we solve this problem, the dual of this will be the original primal. Confused yet? (note that the dual objective should be maximized)

[Fd,objd,XX,y] = dualize(F,obj);
solvesdp(Fd,-objd);

To obtain our original variables, we extract the duals

assign(XX{1},dual(Fd(1));
assign(XX{2},dual(Fd(2));

Check out the tutorial for more examples

Consider a Lyapunov stability problem

A = randn(5,5);A = -A*A';
P = sdpvar(5,5);
F = set(A'*P+P*A < 0) + set(P>eye(5));
obj = trace(P);

Exporting this to a model in SeDuMi format is done by specifying the solver as 'sedumi' and calling export in the same way as solvesdp would have ben called.

[model,recoverymodel] = export(F,obj,sdpsettings('solver','sedumi'));

model = 

       A: [50x15 double]
       b: [15x1 double]
       C: [50x1 double]
       K: [1x1 struct]
    pars: [1x1 struct]

The data in recoverymodel can be used to relate a solution obtained from using the exported model, to the actual variables in YALMIP.

[x,y] = sedumi(model.A,model.b,model.C,model.K);
assign(recover(recoverymodel.used_variables),y);

Some solvers do not support equality constraints. One way to handle this in YALMIP is to use sdpsettings('remove',1). If this is done, YALMIP derives basis and solves the problem in the reduced variables. This basis is communicated through the structure recoverymodel.

ops = sdpsettings('solver','sedumi','remove',1);
[model,recoverymodel] = export(F+set(trace(P)==10),obj,ops);
[x,y] = sedumi(model.A,model.b,model.C,model.K);
z = recoverymodel.x_equ + recoverymodel.H*y;
assign(recover(recoverymodel.used_variables),z);

x1 = sdpvar(1,1);
x2 = sdpvar(1,1);
f = x1^4+5*x2^2;
sdisplay(hessian(f))

ans = 

    '12x1^2'    '0' 
    '0'         '10'

Giving a second argument controls what variables to differentiate with respect to

sdisplay(hessian(f,x1))
ans = 

    '12x1^2'

sdpvar x y
F1 = set(-1 < x < 1) + set(-1 < y < 1);
F2 = set(-1.5 < x-y < 1.5) + set(-1.5 < x+y < 1.5);

Plot the polytopes

plot(F2);hold on
plot(F1);

Notice, if you have MPT installed, this is quicker

plot(polytope(F2));hold on
plot(polytope(F1));

Create a convex model of the convex hull

H = hull(F1,F2)
+++++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                      Type|
+++++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|          Element-wise 2x1|
|   #2|   Numeric value|          Element-wise 2x1|
|   #3|   Numeric value|          Element-wise 2x1|
|   #4|   Numeric value|          Element-wise 2x1|
|   #5|   Numeric value|   Equality constraint 2x1|
|   #6|   Numeric value|   Equality constraint 1x1|
|   #7|   Numeric value|          Element-wise 2x1|
+++++++++++++++++++++++++++++++++++++++++++++++++++

Important to realize is that the representation will introduce new variables due to a lifting procedure. We can plot the convex hull, but since we have introduced new variables, we must declare that we are interested in the projection on the original variables x and y

clf;
plot(H,[x y]);hold on
plot(F2);
plot(F1);

The command applies to (almost) arbitrary convex constraints.

clf; sdpvar x y F1 = set([1 x y+3;[x;y+3] 1/5*eye(2)] > 0); F2 = set(-1.5 < x-y < 1.5) + set(-1.5 < x+y < 1.5); H = hull(F1,F2); plot(H,[x y]);hold on plot(F2); plot(F1);

At the moment, the command does not support constraints that involve nonlinear operators or quadratic terms, although this easily can be added if anyone needs it.

C = eye(2);
A1 = randn(2,2);A1 = A1*A1';
A2 = randn(2,2);A2 = A2*A2';
A3 = randn(2,2);A3 = A3*A3';
z = sdpvar(3,1);

obj = sum(z)
F = set(C+A1*z(1)+A2*z(2)+A3*z(3) > 0) + set(z(1)+z(2)== 1)

A model without the explicit equality constraint is easily obtained.

[Fi,obji,x,y] = imagemodel(F,obj);

We solve the reduced problem, and recover the original variables

solvesdp(F,obji);
assign(x,double(y));

Note that this reduction is automatically done when you call solvesdp and use a solver that cannot handle equality constraints. Hence, there is typically no reason to use this command, unless some further manipulations are going to be performed.

x = intvar(n,1);
solvesdp(set(A*x<b),c'*x)

or

x = sdpvar(n,1);
solvesdp(set(A*x<b)+set(integer(x),c'*x)

Note, the integrality constraint is imposed on the involved variables, not the actual sdpvar object. Hence, the following two constraints are equivalent

F = set(integer(x));
F = set(integer(pi+sqrt(2)*x));

P = intvar(1,1)

For more examples, see sdpvar.

x = sdpvar(1,1);
y = [x;x*x];
is(y,'linear')
ans =
     0

The command works almost in the same way on set objects, with the difference that the check is performed on every constraint in the set object separately, so the output can be a vector

x = sdpvar(1,1);
F = set(x>1) + set([1 x;x 1]>0) + set(x<3);
is(F,'elementwise')
ans =

     1
     0
     1

Hence, creating a set object containing only the element-wise constraints is done with

F_element = F(is(F,'elementwise'));

sdpvar x
F = set(ismember(x,[1 2 3 4]));

Of course, this can also be obtained with a standard integer variable.

intvar x
F = set(1 <= x <=4);

or an integrality constraint

sdpvar x
F = set(integer(x)) + set(1 <= x <= 4);

The functionality is more useful when the set is more complicated.

sdpvar x
F = set(ismember(x,[1 pi 12 -8]));

The function ismember can also be used together with the polytope object in MPT to constrain a variable to be inside at least one of several polytopes.

x = sdpvar(3,1);
P1 = polytope(randn(10,3),rand(10,1));
P2 = polytope(randn(10,3),rand(10,1));
F = set(ismember(x,[P1 P2]));

Note that ismember will introduce binary variables if the cardinality of the set Y is larger than 1

x1 = sdpvar(1,1);
x2 = sdpvar(1,1);
f = x1^2+5*x2^2;
sdisplay(jacobian(f))

ans = 

    '2x1'   '10x2'

Giving a second argument controls what variables to differentiate with respect to

sdisplay(jacobian(f,x2))
ans = 

    '10x2'

F = set(kyp(A,[],P) < 0)

Tthe following command is equivalent

F = set(A'*P+P*A < 0)

but the difference is that YALMIP does not know that the constraint is a Lyapunov equation, hence it will not be able to use the dedicated solver KYPD.

kyp can also be used to define more complex constraints. The following two commands generate the constraint  [A^TP+PA PB;B^TP 0] + M(x) < 0 (P and x are decision variables).

F = set([A'*P+P*A P*B;B'*P zeros(size(B,2))]+M < 0);
F = set(kyp(A,B,P,M) < 0);

The dedicated solver KYPD can only be used if the variable P is symmetric matrix, obtained directly from sdpvar, used only in 1 constraint.  This means that you cannot use KYPD if you want to impose explicit constraints (including positive definiteness) on P. However, positive definiteness of P is in some cases implied by the KYP constraint

x = sdpvar(1,1);
f = x^2;
assign(x,1);
sdisplay(linearize(f))
ans = 

    '-1+2x'

assign(x,3);
sdisplay(linearize(f))
ans = 

    '-9+6x'

The command of-course applies to matrices as well

p11 = sdpvar(1,1);p12 = sdpvar(1,1);p22 = sdpvar(1,1);
P = [p11 p12;p12 p22];
assign(P,[3 2;2 5])

sdisplay(linearize(P*P))
ans = 

    '-13+6p11+4p12'         '-16+2p11+8p12+2p22'
    '-16+2p11+8p12+2p22'    '-29+4p12+10p22'    

Define a semidefinite constraint with low-rank data matrices (both variables in x enter the constraint via rank-2 matrices)

x = sdpvar(2,1);
C = randn(10,10);C = C*C';
R = randn(10,2);
F = set(C-R*diag(x)*R' > 0);

If a low-rank data exploiting solver is available (currently only SDPLR), we can ask YALMIP to extract low-rank information and pass this to the solver.

solvesdp(F + lowrank(F),-sum(x),sdpsettings('solver','sdplr'));

In some cases, the low-rank structure is only with respect to some variables, as here where y enters via a full rank matrix. In this cases, it might be counter productive to try to exploit the (non-existing) low rank.

x = sdpvar(2,1);
y = sdpvar(1,1);
C = randn(10,10);C = C*C';
R = randn(10,2);
S = randn(10,10);S = S+S';
F = set(C-R*diag(x)*R'-y*S > 0);

In this case, it is possible to tell YALMIP which variables enter in a low-rank fashion, here x.

solvesdp(F+lowrank(F,x),-sum(x)-y,sdpsettings('solver','sdplr'));

An alternative way to work with low rank data matrices is to use the option sdpsettings('sdprl.maxrank'). By changing this setting from it default value of 0, YALMIP will automatically check all data matrices for low rank structure, and send low rank data to the solver if the rank is less than the value of sdpsettings('sdprl.maxrank'). Hence, YALMIP will exploit low rank w.r.t x but not y in the following solution.

solvesdp(F,-sum(x)-y,sdpsettings('solver','sdplr','sdplr.maxrank',2));

sdpvar x y
v = monolist([x y],2);
sdisplay(v')
 
ans = 

  '1'   'x'   'y'   'x^2'   'xy'   'y^2'

The command support different degrees on different variables
 

sdpvar x y
v = monolist([x y],[2 3]);
sdisplay(v')

ans = 

  '1'   'x'   'y'   'x^2'   'xy'   'y^2'   'x^2y'   'xy^2'   'y^3'

x = sdpvar(3,1);

F = set([1 x(2);x(2) x(1)])+set(3 > x);
F = F + set([1 x';x eye(3)]>0) + set(sum(x)>x'*x);

Plot the feasible set, projected on (x₁,x₃)

plot(F,[x(1);x(3)])

By default, the feasible set is projected to R³ (the three variables with lowest index in YALMIP)

plot(F)

Why not the feasible set on x₁=0.5

plot(replace(F,x(1),0.5))

A third argument can be used to control the color

plot(F,[],'b')

A fourth argument can be used to control the accuracy

plot(F,[],[],150)

The fifth argument can be used to pass an options structure for the solver

plot(F,[],[],[],sdpsettings('solver','sedumi','verbose',0));

To avoid strange looking plots, you should ensure that your feasible set is bounded. One way to that is to add bounds on on variables.

plot(F+set(-100 < recover(depends(F)) < 100));

Note that plotting the feasible set requires solving the associated optimization problem repeatedly. Hence, for feasible sets defined by a lot of constraints and variables, it may take a long time to generate the figure (controlled by the accuracy level in the fourth argument, 25 points is default for 2D and 100 for 3D figures, although much more is recommended for smooth figures). For small problems, a large portion of the solution time can easily be dominated by overhead costs. Hence, it is recommended to use a solver with low overhead (for SDP problems, PENSDP is recommended)

Also note that when you plot sets with constraints involving nonlinear operators and polynomials, it is recommended that you specify the variables of interest in the second argument (YALMIP may otherwise plot the set with respect to auxiliary variables introduced during the construction of the conic model.)

x = sdpvar(2,1);
clf;plot(norm(x,1))

Or a more complex PWA expression

x = sdpvar(2,1);
clf;plot(norm(randn(5,2)*x,1)+ max(x)-5*x(2))

Notice that the command by default plots the function over a grid from -100 to 100. This can currently not be changed. However, we can easily circumvent this by using the main function used in plot.

p = pwa(norm(randn(5,2)*x,1)+ max(x)-5*x(2),set(-1<x<1));
clf;plot(p)

sdpvar x y
F1 = set(x+y<0);
F2 = set(x+y>0);
f1 = (x+3)^2+(y+2)^2+7;
f2 = (x+3)^2+(y-2)^2+9;
t = pwf(f1,F1,f2,F2);

The variable returned from the function is a so called nonlinear operator. To minimize the piece-wise function, we use the variable t as usual and simply call solvesdp. YALMIP will automatically try to construct a model that can be solved. In this case, YALMIP will derive a mixed integer second order cone problem.

solvesdp([],t);

Support for piece-wise functions is still limited, but can easily be improved if wanted. At the moment, the function can be defined using arbitrary functions and sets, but when it comes down to computing things, only convex quadratic functions and regions defined by convex quadratic constraints are allowed.

F = F + set(rank(X)<=1)

For more information, please study the rank constrained example.

x = sdpvar(1,1);y = sdpvar(1,1);
f = [x;x^2+y+x*y];
sdisplay(f)

ans = 

    'x'
    'y+x^2+xy'

The command tries to find the symbolic names of variables, but if this fails, the variable name internal will be used. Additionally, variables defined using nonlinear operators can currently not be displayed.

ops = sdpsettings

ops = 

               solver: ''
              verbose: 1
              warning: 1
         cachesolvers: 0
        beeponproblem: [-5 -4 -3 -2 -1]
         showprogress: 0
            saveduals: 1
     removeequalities: 0
     savesolveroutput: 0
      savesolverinput: 0
    convertconvexquad: 1
               radius: Inf
                relax: 0
                usex0: 0
                shift: 0
            savedebug: 0
                  sos: [1x1 struct]
               moment: [1x1 struct]
                  bnb: [1x1 struct]
                bpmpd: [1x1 struct]
               bmibnb: [1x1 struct]
               cutsdp: [1x1 struct]
               global: [1x1 struct]
                  cdd: [1x1 struct]
                  clp: [1x1 struct]
                cplex: [1x1 struct]
                 csdp: [1x1 struct]
                 dsdp: [1x1 struct]
                 glpk: [1x1 struct]
                 kypd: [1x1 struct]
               lmilab: [1x1 struct]
              lmirank: [1x1 struct]
              lpsolve: [1x1 struct]
               maxdet: [1x1 struct]
                  nag: [1x1 struct]
               penbmi: [1x1 struct]
               pennlp: [1x1 struct]
               pensdp: [1x1 struct]
                 sdpa: [1x1 struct]
                sdplr: [1x1 struct]
                sdpt3: [1x1 struct]
               sedumi: [1x1 struct]
                qsopt: [1x1 struct]
               xpress: [1x1 struct]
             quadprog: [1x1 struct]
              linprog: [1x1 struct]
             bintprog: [1x1 struct]
              fmincon: [1x1 struct]
           fminsearch: [1x1 struct]

Changing a value from the default settings is done as

ops = sdpsettings('solver','dsdp','verbose',0)

solver

In the code above, we told YALMIP to use the solver DSDP, and to run in silent mode. The possible values to give to the field solver can be found in the introduction to the solvers. If the solver DSDP not is found, an error message will be reported. To let YALMIP select the solver, use the solver tag ''. If you give a comma-separated list of solvers such as 'dsdp,csdp,sdpa', YALMIP will select based on this preference. If you add a wildcard in the end 'dsdp,csdp,sdpa,*', YALMIP will select another solver if none of the solvers in the list were found.

verbose

By setting verbose to 0, the solvers will run with minimal display. By increasing the value, the display level is controlled (typically 1 gives modest display level while 2 gives an awful amount of information printed).

warning

The warning option can be used to get a warning displayed when a solver has run into some kind of problem (recommended to be used if the solver is run in silent mode). 

beeponproblem

The field beeponproblem contains a list of error codes (see yalmiperror). YALMIP will beep if any of these errors occurs (nice feature if you're taking a coffee break during heavy calculations).

showprogress

When the field showprogress is set to 1, the user can see what YALMIP currently is doing (might be a good idea for large-scale problems).

cachesolvers

Everytime solvesdp is called, YALMIP checks for available solvers. This can take a while on some systems (some networks), so it is possible to avoid doing this check every call. Set cachesolvers to 1, and YALMIP will remember the solvers (using a persistent variable) found in the first call to solvesdp. If solvers are added to the path after the first call, YALMIP will not detect this. Hence, after adding a solver to the path the work-space must be cleared or solvesdp must be called once with cachesolvers set to 0.

removeequalities

When the field removeequalities is set to 1, YALMIP removes equality constraints using a QR decomposition and reformulates the problem using a smaller set of variables. If removeequalities is set to 2, YALMIP removes equality constraints using a basis derived directly from independent columns of the equality constraints (higher possibility of maintaining sparsity than the QR approach, but may lead to a numerically poor basis). With removeequalities set to -1, equalities are removed by YALMIP by converting them to double-sided inequalities. When set to 0, YALMIP does nothing if the solver supports equalities. If the solver does not support equalities, YALMIP uses double-sided inequalities.

saveduals

If the field saveduals is set to 0, the dual variables will not be saved in YALMIP. This might be useful for large sparse problems with a dense dual variable. Setting the field to 0 will then save some memory.

savesolverinput, savesolveroutput

The fields savesolverinput and savesolveroutput can be used to see what is actually sent to and returned from the solver. This data will then be available in the output structure from solvesdp.

convertconvexquad

With convertconvexquad set to 1, YALMIP will try to convert quadratic constraints to second order cones.

A constraint ||x||≤radius on the vector of all involved decision variables can be added by changing the field radius to a finite positive value. This can improve numerical performance in some cases. In fact, the field radius may be an sdpvar object. If you work with semidefinite programs and standard convex programming, it is recommended to keep the feature on. However, if you work with more general nonlinear optimization problem, it is most often recommended to turn the conversion off.

shift

Strict inequalities can be modeled in YALMIP by using the > and < when defining constraints. The behaviour of this feature can be altered using the option shift. For constraints defined with strict constraints, a small perturbation is added (semidefinite constraints F(x)>0 are changed to F(x)≥shift*I, while element-wise constraints are changed from F(x)>0 to F(x)≥shift). Note that the use of this feature does not guarantee a strictly feasible solution. This depends on the solver.

relax

If relax is set to 1, all nonlinearities and integrality constraints will be disregarded. Integer variables are relaxed to continuous variables and nonlinear variables are treated as independent variables (i.e., x and x² will be treated as two separate variables).

usex0

The current solution (the value returned from the double command) can be used as an initial guess when solving an optimization problem. Setting the field usex0 to 1 tells YALMIP to supply the current values as an initial guess to the solver.

solver options

The options structure also contains a number of structures with parameters used in the specific solver. As an example, the following parameters can be tuned for SeDuMi (for details, the user is referred to the manual of the specific solver).

ops.sedumi
ans = 
                 alg: 2
               theta: 0.2500
                beta: 0.5000
                 eps: 1.0000e-009
              bigeps: 0.0010
              numtol: 1.0000e-005
                denq: 0.7500
                denf: 10
               vplot: 0
             maxiter: 100
             stepdif: 1
                   w: [1 1]
              stopat: -1
                  cg: [1x1 struct]
                chol: [1x1 struct]

Finally, a convenient way to alter a lot of options is to send an existing options structure as the first input argument.

ops = sdpsettings('solver','sdpa');
ops = sdpsettings(ops,'verbose',0);

P = sdpvar(1,1)

A square real-valued symmetric matrix is obtained with

P = sdpvar(n,n)

The commands above can be simplified by only giving one argument when defining a symmetric matrix or a scalar (this might not work on MATLAB 5.3 and earlier version).

P = sdpvar(n)

We can also define the same matrix using a more verbose notation.

P = sdpvar(n,n,'symmetric')

A fully parameterized square matrix requires a third argument.

P = sdpvar(n,n,'full')

A square complex-valued fully parameterized matrix is obtained with

P = sdpvar(n,n,'full','complex')

YALMIP tries to complete the third and fourth argument, so an equivalent command is

P = sdpvar(n,n,'sy','co')

Variables can alternatively be defined using command line syntax.

sdpvar x y z(1,1) u(2,2) v(2,3,'full','complex')

A lot of users seem to get stuck initially on simple things such as defining a diagonal matrix. The most important thing to remember when working with YALMIP is that almost all MATLAB operators can be applied also on sdpvar objects. Hence, we create diagonal matrices with

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

Or Hankel...

X = hankel(sdpvar(n,1));

A typical situation is that several identical variables are needed, and the most straightforward way to code this is to use a loop.

for i = 1:100; X{i} = sdpvar(5,5);end

However, a much more efficient way to implement this is to use vector valued dimensions (this currently only works if all matrices are symmetric or full)

X = sdpvar(5*ones(1,100),5*ones(1,100));

Another way to create multi-dimensional matrices is to use more than 2 dimension arguments

X = sdpvar(5,5,100);

The benefit with this approach is that this variable can be manipulated as standard 1D and 2D sdpvar objects.

x = sdpvar(2,2);
see(x)

Constant matrix
 
     0     0
     0     0

Base matrices
 
     1     0
     0     0

 
     0     1
     1     0

 
     0     0
     0     1

 
Used variables
 
     1     2     3

When an sdpvar object is altered, the base matrices change

x = sdpvar(1,1);
see(2*x-3)
Constant matrix
 
    -3

Base matrices
 
     2

 
Used variables
 
     4

F = set([]);

Secondly, do not confuse the set object with the standard command set in MATLAB. Yes, it is confusing, but set was the only relevant short word for defining the feasible set that I could come up with...

Constraining a scalar variable to be larger than 5 is done with

x = sdpvar(1,1)
F = set(x > 5)

The variable F serves as a container for all constraints here. Defining a matrix to be both positive definite and elementwise positive is done with

P = sdpvar(n,n);
F = set(P > 0) + set(P(:) > 0);

A string-notation can also be used

F = set('P > 0') + set('P(:) > 0')

A set object can be tagged with a description (which can be useful for referencing a particular constraint in, e.g., dual)

F = set(P > 0,'positive definite');
F = F + set(P(:)>0,'positive elements')

Second order cone constraints ||Ax+b||<c^Tx+d can be added with the function cone

F = set(cone(A*x+b,c'*x+d))

Equality constraints can also be defined. A constraint that the sum of the vector components is equal to 1 is obtained with

F = set(sum(x) == 1)

In general, it should be remembered that YALMIP uses MATLAB standard when it comes to comparison of matrices and scalars. Hence, the following code will constrain all diagonal elements to be larger than 1.

F = set(diag(P) > 1))

Double-sided constraints and extensions can easily be defined.

F = set(2 > diag(P) > 1 > sum(sum(P)))

It is possible to have complex and integer valued constraints. No special code is necessary. To create a complex-valued integer Hermitian matrix and constrain it to be positive definite, we write

P = intvar(3,3,'hermitian','complex');
F = set(P > 0)

Notice that set objects can be referenced

F = set(P > 0) + set(A'*P+P*A < 0) + set(P(1,1) > 0)+set(P(1,:) > 0);
F_lmi     = F(1:2)
F_element = F(find(is(F,'element-wise')))

Finally, note that YALMIP does essentially not distinguish between strict and non-strict inequalities. Hence, the following two constraints are in almost all cases the same.

F = set(P > 0) + set(trace(P) < 1);
G = set(P >= 0) + set(trace(P) <= 1);

Please read the FAQ for more information on the difference.

x1 = sdpvar(1,1);x2 = sdpvar(1,1);x3 = sdpvar(1,1);
h = -2*x1+x2-x3;
F = set(x1*(4*x1-4*x2+4*x3-20)+x2*(2*x2-2*x3+9)+x3*(2*x3-13)+24>0)
F = F + set(4-(x1+x2+x3)>0);
F = F + set(6-(3*x2+x3)>0);
F = F + set(2-x1>0);
F = F + set(3-x3>0);
F = F + set(x1>0);
F = F + set(x2>0);
F = F + set(x3>0);
solvemoment(F,h);
double(h)
ans =

   -6.0000

In the code above, we solved the problem with the lowest possible lifting (decided by YALMIP), and the lower bound turned out to be -6. A higher order relaxation gives better bounds.

solvemoment(F,h,[],2);
double(h)
ans =

   -5.69

solvemoment(F,h,[],3);
double(h)
ans =

   -4.0685

solvemoment(F,h,[],4);
double(h)
ans =

   -4.0000

For a more complete introduction, please study the extensive examples.

x = sdpvar(length(c),1);
F = set(A*x<b)
solvesdp(F,c'*x);

If we only look for a feasible solution, we can omit the objective function

solvesdp(F);

Solving the feasibility problem with the solver QUADPROG can be done with

solvesdp(F,[],sdpsettings('solver','quadprog'));

Minimizing an objective function is done by passiing a second argument

solvesdp(F,sum(x));

For more examples, run yalmipdemo and check out all the examples.

x = sdpvar(1,1);
p = x^4+x+5;
F = set(sos(p)); % Constrain p to be a SOS
solvesos(F);

The SOS-decompositions should give p(x)=v(x)^Tv(x)

v = sosd(F);
sdisplay(p-v'*v)
ans = 

    '-1.7764e-015+7.7716e-016x-1.1102e-015x^4'

Obviously, not entirely true. However the coefficients are small and most likely due to numerical inaccuracy. Remove all terms with coeffients smaller than 1e-6 using the command clean

sdisplay(clean(p-v'*v,1e-6))
ans = 
    '0'

Parameterized SOS problems  are also possible. As an example, a lower bound on the global minimum of p is obtained by finding a SOS decomposition of p-t, while maximizing t. The full syntax is

t = sdpvar(1,1);
F = set(sos(p-t));
solvesos(F,-t,[],t);
double(t)
ans =

    4.5275

Parametric variables (the last argument in the code above) are automatically detected if they are part of the objective function or part of non-SOS constraints. Hence, the problem above can be simplified.

t = sdpvar(1,1);
F = set(sos(p-t));
solvesos(F,-t);
double(t)
ans =

    4.5275

For more examples, run yalmipdemo and check out the examples in this manual.

A = sdpvar(2,2);
B = sdpvar(3,3);
C = diag(sdpvar(3,1));
X = blkdiag(A,B,C);

Now destroy the block diagonal structure

p = randperm(8);
X = X(p,p);
spy(X)

The blocks are easily recovered (note that scalar terms are returned one by one)

blocks = unblkdiag(X)
  [3x3 sdpvar]  [1x1 sdpvar]  [2x2 sdpvar]  [1x1 sdpvar]  [1x1 sdpvar]

The command is most efficiently used on set objects (the function will go through all constraints in the set object and try to detect blocked terms)

F = set(X);
F = unblkdiag(F)
+++++++++++++++++++++++++++++++++++++++++++++++++
|   ID|      Constraint|                    Type|
+++++++++++++++++++++++++++++++++++++++++++++++++
|   #1|   Numeric value|   Matrix inequality 3x3|
|   #2|   Numeric value|   Matrix inequality 2x2|
|   #3|   Numeric value|        Element-wise 3x1|
+++++++++++++++++++++++++++++++++++++++++++++++++

yalmip('clear')

Version number and release-date can be obtained

[vernum,reldate] = yalmip('version');

Additional information can be displayed using the 'info' tag

ver = yalmip('info')
**********************************
- - - - YALMIP 3 - - - - - - - - -
**********************************

Variable Size
No SDPVAR objects found

SET
No SET objects found

yalmiperror

  Error codes
 
  -5 License problems in solver
  -4 Solver not applicable
  -3 Solver not found 
  -2 No suitable solver
  -1 Unknown error
   0 No problems detected
   1 Infeasible problem
   2 Unbounded objective function
   3 Maximum iterations exceeded
   4 Numerical problems
   5 Lack of progress
   6 Initial solution infeasible
   7 YALMIP sent incorrect input to solver
   8 Feasibility cannot be determined
   9 Unknown problem in solver
  10 bigM failed (increase sp.Mfactor)  
  11 Other identified error
  12 Infeasible or unbounded
  13 YALMIP cannot determine status in solver

To see a particular error message,

yalmiperror(3)
 ans =

 Maximum iterations exceeded 

yalmiptest

To test a particular solver

yalmiptest(sdpsettings('solver','sdpt3'))