This page is structured as follows:

- Using ECOS in C: Procedure on how to use ECOS in C.
- ECOS Exitcodes: A list of ECOS exitcodes.
- Solving Mixed-Integer SOCPs: Description on how one can solve mixed-integer second order cone programs using ECOS in C.

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}$$

ECOS essentially exports three main functions, cf. `ecos.h`. You need to call these in the following sequence from your C code:

- Setup: allocates memory for ECOS, computes the fill-in reducing ordering and provides other initialization necessary before solve can start.
- Solve: the core interior-point solver. No memory manager (e.g.
`malloc`) is required. - Cleanup: frees memory that has been allocated during Setup.

First, we need a struct that holds all data ECOS requires for solving the problem:

…

pwork* mywork;

The following function can be used to initialize ECOS:

pfloat* Gpr, idxint* Gjc, idxint* Gir,

pfloat* Apr, idxint* Ajc, idxint* Air,

pfloat* c, pfloat* h, pfloat* b);

where you have to pass the following arguments:

Argument | Description |
---|---|

n |
Number of primal variables |

m |
Number of constraints, i.e. dimension 1 of the matrix \(G\) and length of vector \(h \) |

p |
Number of equality constraints, i.e. dimension 1 of matrix \( A \) and length of vector \(b\) |

l |
Dimension of the positive orthant \(R_+^l\) |

ncones |
Number of second-order cones present in problem |

q |
Array of length ncones; q[i] defines the dimension of the cone i |

e |
Number of exponential cones present in problem |

Gpr, Gjc, Gir |
Arrays for matrix \( G \) in column compressed storage (CCS) |

Apr, Ajc, Air |
Arrays for matrix \( A \) in column compressed storage (CCS). Can be NULL if no equality constraints are present |

c |
Array of length n |

h |
Array of length m |

b |
Array of length p. Can be NULL if no equality constraints are present |

**
NOTE:** The problem data `c, G, h, A, b` may be modified by ECOS for scaling purposes. Please ensure it resides in writeable memory.

After the initialization is done, you can call the solve function, which contains the actual interior point method, by

The return value is an integer, see below.

Call

to free all allocated memory.

ECOS defines a number of exitcodes that indicate the quality of the returned solution. In general, positive values indicate that the solver has converged within the given tolerance. More specifically,

Exitcode | Description | C Symbol |
---|---|---|

0 | Optimal solution found | ECOS_OPTIMAL |

1 | Certificate of primal infeasibility found | ECOS_PINF |

2 | Certificate of dual infeasibility found | ECOS_DINF |

10 | Optimal solution found subject to reduced tolerances | ECOS_OPTIMAL + ECOS_INACC_OFFSET |

11 | Certificate of primal infeasibility found subject to reduced tolerances | ECOS_PINF + ECOS_INACC_OFFSET |

12 | Certificate of dual infeasibility found subject to reduced tolerances | ECOS_DINF + ECOS_INACC_OFFSET |

-1 | Maximum number of iterations reached | ECOS_MAXIT |

-2 | Numerical problems (unreliable search direction) | ECOS_NUMERICS |

-3 | Numerical problems (slacks or multipliers outside cone) | ECOS_OUTCONE |

-4 | Interrupted by signal or CTRL-C | ECOS_SIGINT |

-7 | Unknown problem in solver | ECOS_FATAL |

Negative numbers indicate that the problem could not be solved to the required accuracy (the returned iterate might still be satisfactory - please do check the duality gap etc.). It is in general good practice to check the exitcode, in particular when solving optimization problems in an unsupervised, automated fashion (in a batch job, for example).

In order to solve a mixed-integer convex second-order cone program of the form

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

& Gx \preceq_K h \\

& \text{some}\ x_i \in \{0,1\} \\

& \text{some}\ x_j \in \mathbb{Z} \end{align}$$

using the branch-and-bound wrapper `ECOS_BB`, you need to call similar 3 functions as for ECOS (Setup, Solve and Cleanup).

**NOTE:** The range of integers supported by ECOS_BB is between and including -/+8388608.

Use the following function to initialize ECOS_BB:

idxint l, idxint ncones, idxint* q, idxint e,

pfloat* Gpr, idxint* Gjc, idxint* Gir,

pfloat* Apr, idxint* Ajc, idxint* Air,

pfloat* c, pfloat* h, pfloat* b,

idxint num_bool_vars, idxint* bool_vars_idx,

idxint num_int_vars, idxint* int_vars_idx,

settings_bb* stgs);

where you have to pass similar arguments as above, and the following additional arrays:

Argument | Description |
---|---|

num_bool_vars |
Number of boolean variables in the problem |

bool_vars_idx |
Array with indices of boolean variables (0-based indexing, must be strictly monotonically increasing) |

num_int_vars |
Number of integer variables in the problem |

int_vars_idx |
Array with indices of integer variables (0-based indexing, must be strictly monotonically increasing) |

settings_bb |
Struct carrying custom settings for the branch-and-bound module. This argument can be NULL if default settings are desired. |

The setup function returns a struct of type `ecos_bb_pwork`, which you need to define first.

After the initialization is done, you can call the solve function, which contains the branch and bound wrapper around the core ECOS solver, by

The return value is an integer indicating the exit code, see the list above.

Call

to free all allocated memory.