0
# Core SOCP Solver
1
2
The core ECOS solver provides a complete interface for solving continuous second-order cone programs (SOCPs). It implements an interior-point method specifically optimized for embedded systems and real-time applications.
3
4
## Capabilities
5
6
### Problem Setup
7
8
Initializes the solver workspace with problem data in compressed sparse column (CSC) format.
9
10
```c { .api }
11
pwork* ECOS_setup(idxint n, idxint m, idxint p, idxint l, idxint ncones, idxint* q,
12
pfloat* Gpr, idxint* Gjc, idxint* Gir,
13
pfloat* Apr, idxint* Ajc, idxint* Air,
14
pfloat* c, pfloat* h, pfloat* b);
15
```
16
17
**Parameters:**
18
- `n`: Number of primal variables x
19
- `m`: Number of conically constrained variables s
20
- `p`: Number of equality constraints
21
- `l`: Number of positive orthant constraints (dimension of R_+)
22
- `ncones`: Number of second-order cones
23
- `q`: Array of sizes of second-order cones (length ncones)
24
- `Gpr`, `Gjc`, `Gir`: Inequality constraint matrix G in CSC format
25
- `Apr`, `Ajc`, `Air`: Equality constraint matrix A in CSC format
26
- `c`: Objective vector (length n)
27
- `h`: Inequality constraint RHS vector (length m)
28
- `b`: Equality constraint RHS vector (length p)
29
30
**Returns:** Pointer to solver workspace, or NULL on failure
31
32
**Usage Example:**
33
34
```c
35
// Problem: minimize c'*x subject to A*x = b, G*x <=_K h
36
idxint n = 3, m = 3, p = 1, l = 1, ncones = 1;
37
idxint q[1] = {2}; // One second-order cone of size 2
38
39
// Objective vector
40
pfloat c[3] = {1.0, 1.0, 0.0};
41
42
// Inequality constraints: x1 >= 0, (x2, x3) in second-order cone
43
pfloat h[3] = {0.0, 0.0, 0.0};
44
pfloat Gpr[4] = {-1.0, 0.0, 0.0, 1.0}; // G = [-1 0 0; 0 -1 0; 0 0 1]
45
idxint Gjc[4] = {0, 1, 2, 4};
46
idxint Gir[4] = {0, 1, 2};
47
48
// Equality constraint: x1 + x2 = 1
49
pfloat b[1] = {1.0};
50
pfloat Apr[2] = {1.0, 1.0}; // A = [1 1 0]
51
idxint Ajc[4] = {0, 1, 2, 2};
52
idxint Air[2] = {0, 0};
53
54
pwork* work = ECOS_setup(n, m, p, l, ncones, q,
55
Gpr, Gjc, Gir,
56
Apr, Ajc, Air,
57
c, h, b);
58
```
59
60
### Problem Solving
61
62
Solves the optimization problem using the interior-point algorithm.
63
64
```c { .api }
65
idxint ECOS_solve(pwork* w);
66
```
67
68
**Parameters:**
69
- `w`: Solver workspace from ECOS_setup
70
71
**Returns:** Exit code indicating solution status:
72
- `ECOS_OPTIMAL` (0): Problem solved to optimality
73
- `ECOS_PINF` (1): Certificate of primal infeasibility found
74
- `ECOS_DINF` (2): Certificate of dual infeasibility found
75
- `ECOS_MAXIT` (-1): Maximum iterations reached
76
- `ECOS_NUMERICS` (-2): Numerical difficulties
77
- `ECOS_OUTCONE` (-3): Variables left feasible region
78
- `ECOS_SIGINT` (-4): Interrupted by signal
79
- `ECOS_FATAL` (-7): Unknown error
80
81
**Usage Example:**
82
83
```c
84
idxint exitflag = ECOS_solve(work);
85
86
switch (exitflag) {
87
case ECOS_OPTIMAL:
88
printf("Optimal solution found\\n");
89
printf("Objective value: %f\\n", work->info->pcost);
90
91
// Access primal solution
92
for (int i = 0; i < work->n; i++) {
93
printf("x[%d] = %f\\n", i, work->x[i]);
94
}
95
96
// Access dual solution
97
for (int i = 0; i < work->p; i++) {
98
printf("y[%d] = %f\\n", i, work->y[i]);
99
}
100
break;
101
102
case ECOS_PINF:
103
printf("Problem is primal infeasible\\n");
104
break;
105
106
case ECOS_DINF:
107
printf("Problem is dual infeasible\\n");
108
break;
109
110
case ECOS_MAXIT:
111
printf("Maximum iterations reached\\n");
112
break;
113
114
default:
115
printf("Solver failed with code: %d\\n", exitflag);
116
break;
117
}
118
```
119
120
### Memory Management
121
122
Frees solver workspace and optionally preserves solution vectors.
123
124
```c { .api }
125
void ECOS_cleanup(pwork* w, idxint keepvars);
126
```
127
128
**Parameters:**
129
- `w`: Solver workspace to clean up
130
- `keepvars`: Number of solution variables to preserve (0 = free all)
131
132
**Usage Example:**
133
134
```c
135
// Standard cleanup - free all memory
136
ECOS_cleanup(work, 0);
137
138
// Keep solution vectors for later use (advanced usage)
139
// This preserves x, y, s, z arrays from deallocation
140
ECOS_cleanup(work, 4);
141
```
142
143
### Version Information
144
145
Returns the current ECOS version string.
146
147
```c { .api }
148
const char* ECOS_ver(void);
149
```
150
151
**Returns:** Version string in format "X.Y.Z"
152
153
**Usage Example:**
154
155
```c
156
printf("ECOS version: %s\\n", ECOS_ver());
157
```
158
159
## Accessing Solution Data
160
161
After successful solve, solution data is available in the workspace:
162
163
### Primal Solution
164
165
```c
166
// Primal variables (length n)
167
pfloat* x = work->x;
168
169
// Slack variables (length m)
170
pfloat* s = work->s;
171
```
172
173
### Dual Solution
174
175
```c
176
// Equality constraint multipliers (length p)
177
pfloat* y = work->y;
178
179
// Conic inequality multipliers (length m)
180
pfloat* z = work->z;
181
```
182
183
### Solution Statistics
184
185
```c
186
stats* info = work->info;
187
188
printf("Primal cost: %f\\n", info->pcost);
189
printf("Dual cost: %f\\n", info->dcost);
190
printf("Duality gap: %f\\n", info->gap);
191
printf("Primal residual: %f\\n", info->pres);
192
printf("Dual residual: %f\\n", info->dres);
193
printf("Iterations: %d\\n", info->iter);
194
```
195
196
## Problem Format
197
198
ECOS solves problems of the form:
199
200
```
201
minimize c'*x
202
subject to A*x = b
203
G*x <=_K h
204
```
205
206
Where:
207
- `<=_K` denotes generalized inequality with respect to cone K
208
- K is a Cartesian product: K = R_+ × Q_n1 × ... × Q_nN
209
- R_+ is the positive orthant (linear inequalities)
210
- Q_n is a second-order cone: Q_n = {(t,x) | t >= ||x||_2}
211
212
### Matrix Format
213
214
All matrices must be in compressed sparse column (CSC) format with:
215
- `pr`: Array of non-zero values
216
- `jc`: Array of column pointers (length n+1)
217
- `ir`: Array of row indices (length nnz)
218
219
This is the same format used by MATLAB's sparse matrices and SuiteSparse libraries.