Usage from C

To solve the convex second-order cone problem

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.

1. Setup

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

#include <ecos.h>  
…  
pwork* mywork;

The following function can be used to initialize ECOS:

pwork* ECOS_setup(idxint n, idxint m, idxint p, 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);

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
p	Number of equality constraints, i.e. dimension 1 of matrix and length of vector
l	Dimension of the positive orthant
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 in column compressed storage (CCS)
Apr, Ajc, Air	Arrays for matrix 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.

2. Solve

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

idxint ECOS_solve(pwork* w);

The return value is an integer, see below.

3. Cleanup

Call

void ECOS_cleanup(pwork* w, idxint keepvars);

to free all allocated memory.

ECOS Exitcodes

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).

Solving Mixed-Integer SOCPs

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

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.

1. Setup

Use the following function to initialize ECOS_BB:

ecos_bb_pwork* ecos_bb_setup(idxint n, idxint m, idxint p,  
                             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.

2. Solve

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

idxint ecos_bb_solve(ecos_bb_pwork* w);

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

3. Cleanup

Call

void ecos_bb_cleanup(ecos_bb_pwork\* w);

to free all allocated memory.