This page is structured as follow:

- How to call ECOS: Instructions on the ECOS function call.
- Return values: Results given by ECOS.
- Solve status: Information on the solve status.
- Example: Simple example on how to use ECOS in MATLAB®.
- Quadratic Programming: Description on how to solve quadratic programs with ECOS in MATLAB®.

To solve the convex second-order cone problem

$$ \begin{align} \text{minimize} \ \ & c^T x \\\text{subject to} \ \ & Ax = b \\

& Gx \preceq_K h

\end{align}$$

You can directly call ECOS from MATLAB® using its native interface:

It takes the problem data `c,G,h,A,b` and the necessary information on the dimension of the cones that is given in the struct `dims`. Note that `A` and `G` have to be given in sparse format. The equality constraints defined by `A` and `b` are optional and can be omitted. The `dims` structure has the following fields:

`dims.l`- scalar, dimension of positive orthant (LP-cone) \(R_+\)`dims.q`- vector with dimensions of second order cones \( Q^n = \{ (t,x) \in R_+ \times R^{n-1}~|~ t\geq \|x\|_2 \} \)`dims.e`- scalar, number of exponential cones \(K_e = closure \{ (x,y,z)\in R^3~|~exp(x/z) \leq y/z, z>0 \}\)

The length of `dims.q` determines the number of second order cones. Use the empty matrix `[ ]` to indicate that a cone is not present, for example `dims.q = [ ]` if there are no second-order cones in your problem instance. Auxiliary settings can be passed to the solver by means of the struct `opts`, which is explained in detail here.

After a solve, ECOS returns the following variables:

ID |
Description |
---|---|

x |
Primal variables |

y |
Dual variables for equality constraints |

s |
Slack variables for inequality \(Gx \preceq_K h \Leftrightarrow s = h - Gx\), \(s\in K\) |

z |
Dual variables associated to \(s \in K\) such that \(z \in K\) |

info |
Struct with detailed information on solve status |

The struct `info` contains the following fields:

Field | Description |
---|---|

exitflag |
Numerical value for status of the solve (details see below) |

infostring |
Information for humans on what the exitflag means |

pcost |
Primal objective value \(c^T x\) |

dcost |
Dual objective value \(-b^Ty -h^Tz \) (equals pcost when optimal) |

pres |
Normalized primal residual \( \text{max} \left( \|Ax-b\|_2 / \text{max}(1, \|b\|_2), \| Gx + s - h \|_2 / \text{max}(1, \|h\|_2) \right) \) |

dres |
Normalized dual residual \( \|A^Ty + G^T z + c \|_2 / \text{max}(1, \|c\|_2) \) |

pinfres |
Primal infeasibility measure \( \|A^Ty + G^Tz \|_2 / \text{max}(1,\|c\|_2) \) |

dinfres |
Dual infeasibility measure \( \text{max}\left( \|Ax\|_2/\text{max}(1,\|b\|_2), \|Gz+s\|_2/\text{max}(1,\|h\|_2)\right) \) |

pinf |
Indicates primal infeasibility if \( h^Tz + b^Ty < 0 \) and pinfres < FEASTOL |

dinf |
Indicates dual infeasibility if \( c^T x < 0 \) and dinfres < FEASTOL |

gap |
Complementarity gap \( s^T z \) |

relgap |
Normalized complementarity gap \( s^T z / (-pcost) \) if pcost < 0 or \( s^T z / dcost \) if pcost > 0 and dcost < 0 |

iter |
Number of iterations performed |

timing |
Struct with timing information |

Note these values refer to the last iterate before ECOS exited because of an exit criterion. See the exitcodes below for more details.

In the following, we show how to solve a L1 minimization problem, which arises for example in sparse signal reconstruction problems (compressed sensing):

$$ \begin{align} \text{minimize} \ \ & \| x \|_1 \\\text{subject to} \ \ & Ax = b

\end{align} $$

where \(x \in R^n\), \(A \in R^{m x n}\) with \(m \ll n\). We use the epigraph reformulation to express the L1-norm of \(x\),

$$ \begin{align} x &\leq u \\ -x & \leq u \end{align} $$where \(u \in R^n_+\) and we minimize \(\sum_{i=1}^{n} u_i\). Hence the optimization variables are stacked as follows:

With this reformulation, the sparse reconstruction problem can be written as the linear program (LP)

$$ \begin{align} \text{minimize} \ \ & c^T z \\ \text{subject to} \ \ & \tilde{A} z = b \\ & Gx \leq h \end{align} $$where the inequality is w.r.t. the positive orthant. The following MATLAB® code generates a random instance of this problem, and calls ECOS to compute a solution:

n = 1000; m = 10; density = 0.01;

% linear term

c = [zeros(n,1); ones(n,1)];

% equality constraints

A = sprandn(m,n,density);

Atilde = [A, zeros(m,n)];

b = randn(m,1);

% linear inequality constraints

I = speye(n);

G = [ I -I;

-I -I];

h = zeros(2*n,1);

% cone dimensions (LP cone only)

dims.l = 2*n; dims.q = [];

% call solver

z = ecos(c,G,h,dims,Atilde,b);

x = z(1:n);

nnzx = sum(abs(x) > 1e-8);

% print sparsity info

fprintf('Optimal x has %d/%d (%4.2f%%) non-zero entries.\n', nnzx , n, nnzx/n*100);

The MATLAB® package of ECOS comes with a quadratic programming interface that mimics the standard MATLAB® QP solver interface by
`quadprog`. It supports QPs of the form

where we assume that \(H\) is positive definite. This is the standard formulation that also MATLAB®'s built-in solver `quadprog` uses. To deal with the quadratic objective, we have to reformulate it into a second-order cone constraint to directly call ECOS. This conversion is done within a MATLAB® interface called `ecosqp`. Hence you can simply use

to solve the quadratic program. See `help ecosqp` for more details. The last output argument indicates the solution time required by the ECOS solver (without the conversion into an SOCP).