0
# Configuration and Settings
1
2
ECOS provides comprehensive configuration options for both the core solver and mixed-integer branch-and-bound extension. Proper parameter tuning can significantly improve solver performance and reliability for specific problem classes.
3
4
## Capabilities
5
6
### Core Solver Settings
7
8
Configuration structure for the main ECOS interior-point algorithm.
9
10
```c { .api }
11
typedef struct settings {
12
pfloat gamma; // Step length scaling factor (0-1)
13
pfloat delta; // Dynamic regularization parameter
14
pfloat eps; // Regularization threshold
15
pfloat feastol; // Primal/dual feasibility tolerance
16
pfloat abstol; // Absolute tolerance on duality gap
17
pfloat reltol; // Relative tolerance on duality gap
18
pfloat feastol_inacc; // Inaccurate solution feasibility tolerance
19
pfloat abstol_inacc; // Inaccurate solution absolute tolerance
20
pfloat reltol_inacc; // Inaccurate solution relative tolerance
21
idxint nitref; // Number of iterative refinement steps
22
idxint maxit; // Maximum number of iterations
23
idxint verbose; // Verbosity level (0=silent, 1=progress)
24
} settings;
25
```
26
27
**Default Values:**
28
29
```c
30
settings default_settings = {
31
.gamma = 0.99, // Conservative step length
32
.delta = 2E-7, // Dynamic regularization
33
.eps = 1E-13, // Regularization threshold
34
.feastol = 1E-8, // Standard feasibility tolerance
35
.abstol = 1E-8, // Standard absolute tolerance
36
.reltol = 1E-8, // Standard relative tolerance
37
.feastol_inacc = 1E-4, // Relaxed feasibility tolerance
38
.abstol_inacc = 5E-5, // Relaxed absolute tolerance
39
.reltol_inacc = 5E-5, // Relaxed relative tolerance
40
.nitref = 9, // Iterative refinement steps
41
.maxit = 100, // Maximum iterations
42
.verbose = 1 // Show progress
43
};
44
```
45
46
**Usage Example:**
47
48
```c
49
// Create custom settings
50
settings* custom_settings = malloc(sizeof(settings));
51
*custom_settings = (settings){
52
.gamma = 0.95, // More aggressive step length
53
.feastol = 1E-10, // Tighter feasibility tolerance
54
.abstol = 1E-10, // Tighter absolute tolerance
55
.reltol = 1E-10, // Tighter relative tolerance
56
.maxit = 200, // More iterations allowed
57
.verbose = 0 // Silent operation
58
};
59
60
// Apply custom settings after setup
61
pwork* work = ECOS_setup(n, m, p, l, ncones, q,
62
Gpr, Gjc, Gir, Apr, Ajc, Air,
63
c, h, b);
64
65
if (work) {
66
// Replace default settings
67
free(work->stgs);
68
work->stgs = custom_settings;
69
70
// Solve with custom settings
71
idxint status = ECOS_solve(work);
72
}
73
```
74
75
### Branch-and-Bound Settings
76
77
Configuration structure for mixed-integer optimization.
78
79
```c { .api }
80
typedef struct settings_bb {
81
idxint maxit; // Maximum branch-and-bound iterations
82
idxint verbose; // Verbosity level (0=silent, 1=progress, 2=detailed)
83
pfloat abs_tol_gap; // Absolute gap termination criterion |U-L|
84
pfloat rel_tol_gap; // Relative gap termination criterion |U-L|/|L|
85
pfloat integer_tol; // Integer feasibility tolerance
86
} settings_bb;
87
```
88
89
**Default Settings Function:**
90
91
```c { .api }
92
settings_bb* get_default_ECOS_BB_settings();
93
```
94
95
**Default Values:**
96
97
```c
98
settings_bb default_bb_settings = {
99
.maxit = 1000, // Branch-and-bound iterations
100
.verbose = 1, // Show progress
101
.abs_tol_gap = 1E-6, // Absolute gap tolerance
102
.rel_tol_gap = 1E-3, // Relative gap tolerance (0.1%)
103
.integer_tol = 1E-4 // Integer feasibility tolerance
104
};
105
```
106
107
**Usage Example:**
108
109
```c
110
// Get default settings and customize
111
settings_bb* bb_settings = get_default_ECOS_BB_settings();
112
113
// Customize for high-precision integer solution
114
bb_settings->abs_tol_gap = 1E-8; // Tighter absolute gap
115
bb_settings->rel_tol_gap = 1E-5; // Tighter relative gap (0.001%)
116
bb_settings->integer_tol = 1E-6; // Stricter integer feasibility
117
bb_settings->maxit = 5000; // More iterations allowed
118
bb_settings->verbose = 2; // Detailed output
119
120
// Use in mixed-integer setup
121
ecos_bb_pwork* work = ECOS_BB_setup(n, m, p, l, ncones, q,
122
Gpr, Gjc, Gir, Apr, Ajc, Air,
123
c, h, b,
124
num_bool_vars, bool_vars_idx,
125
num_int_vars, int_vars_idx,
126
bb_settings);
127
```
128
129
## Parameter Tuning Guidelines
130
131
### Convergence Tolerances
132
133
**Standard Precision (Default):**
134
```c
135
settings std_settings = {
136
.feastol = 1E-8, // Good balance of accuracy and speed
137
.abstol = 1E-8,
138
.reltol = 1E-8
139
};
140
```
141
142
**High Precision:**
143
```c
144
settings precision_settings = {
145
.feastol = 1E-12, // Very tight feasibility
146
.abstol = 1E-12, // Very tight optimality
147
.reltol = 1E-12,
148
.maxit = 300 // More iterations may be needed
149
};
150
```
151
152
**Fast/Approximate:**
153
```c
154
settings fast_settings = {
155
.feastol = 1E-6, // Looser tolerances
156
.abstol = 1E-6,
157
.reltol = 1E-6,
158
.maxit = 50 // Fewer iterations
159
};
160
```
161
162
### Step Length Control
163
164
```c
165
// Conservative (stable but slower)
166
.gamma = 0.90
167
168
// Standard (default balance)
169
.gamma = 0.99
170
171
// Aggressive (faster but may be unstable)
172
.gamma = 0.999
173
```
174
175
### Regularization Parameters
176
177
```c
178
// For well-conditioned problems
179
.delta = 1E-8,
180
.eps = 1E-14
181
182
// For ill-conditioned problems (default)
183
.delta = 2E-7,
184
.eps = 1E-13
185
186
// For very ill-conditioned problems
187
.delta = 1E-6,
188
.eps = 1E-12
189
```
190
191
### Mixed-Integer Parameters
192
193
**Fast Branch-and-Bound:**
194
```c
195
settings_bb fast_bb = {
196
.abs_tol_gap = 1E-4, // Looser gap tolerance
197
.rel_tol_gap = 1E-2, // 1% relative gap
198
.integer_tol = 1E-3, // Looser integer feasibility
199
.maxit = 500
200
};
201
```
202
203
**High-Quality Integer Solutions:**
204
```c
205
settings_bb quality_bb = {
206
.abs_tol_gap = 1E-8, // Very tight gap
207
.rel_tol_gap = 1E-5, // 0.001% relative gap
208
.integer_tol = 1E-6, // Strict integer feasibility
209
.maxit = 10000
210
};
211
```
212
213
## Runtime Configuration
214
215
### Verbosity Levels
216
217
**Core Solver Verbosity:**
218
```c
219
work->stgs->verbose = 0; // Silent
220
work->stgs->verbose = 1; // Progress info (default)
221
```
222
223
**Mixed-Integer Verbosity:**
224
```c
225
bb_work->stgs->verbose = 0; // Silent
226
bb_work->stgs->verbose = 1; // Branch-and-bound progress
227
bb_work->stgs->verbose = 2; // Detailed node information
228
```
229
230
### Iteration Limits
231
232
```c
233
// Set conservative iteration limit
234
work->stgs->maxit = 50;
235
236
// Check if limit was reached
237
if (work->info->iter >= work->stgs->maxit) {
238
printf("Iteration limit reached\\n");
239
240
// Try with more iterations
241
work->stgs->maxit = 200;
242
ECOS_solve(work);
243
}
244
```
245
246
### Dynamic Parameter Adjustment
247
248
```c
249
// Adaptive tolerance adjustment
250
pfloat initial_tol = 1E-8;
251
pfloat current_tol = initial_tol;
252
253
for (int attempt = 0; attempt < 3; attempt++) {
254
work->stgs->feastol = current_tol;
255
work->stgs->abstol = current_tol;
256
work->stgs->reltol = current_tol;
257
258
idxint status = ECOS_solve(work);
259
260
if (status == ECOS_OPTIMAL) {
261
printf("Converged with tolerance: %e\\n", current_tol);
262
break;
263
} else if (status == ECOS_MAXIT) {
264
// Relax tolerances and try again
265
current_tol *= 10;
266
printf("Relaxing tolerances to: %e\\n", current_tol);
267
} else {
268
printf("Solver failed with status: %d\\n", status);
269
break;
270
}
271
}
272
```
273
274
## Problem-Specific Tuning
275
276
### Real-Time Applications
277
278
```c
279
settings realtime_settings = {
280
.maxit = 20, // Strict iteration limit
281
.feastol = 1E-6, // Adequate precision
282
.abstol = 1E-6,
283
.reltol = 1E-6,
284
.gamma = 0.95, // Aggressive steps
285
.verbose = 0 // No output overhead
286
};
287
```
288
289
### High-Accuracy Scientific Computing
290
291
```c
292
settings scientific_settings = {
293
.maxit = 500, // Allow many iterations
294
.feastol = 1E-14, // Machine precision
295
.abstol = 1E-14,
296
.reltol = 1E-14,
297
.nitref = 15, // More refinement steps
298
.verbose = 1
299
};
300
```
301
302
### Large-Scale Problems
303
304
```c
305
settings largescale_settings = {
306
.maxit = 1000, // More iterations expected
307
.delta = 1E-6, // Stronger regularization
308
.nitref = 5, // Fewer refinement steps
309
.verbose = 1
310
};
311
```
312
313
## Settings Validation
314
315
```c
316
int validate_settings(settings* stgs) {
317
if (stgs->gamma <= 0 || stgs->gamma >= 1) {
318
printf("Invalid gamma: %f (must be in (0,1))\\n", stgs->gamma);
319
return 0;
320
}
321
322
if (stgs->feastol <= 0) {
323
printf("Invalid feastol: %e (must be positive)\\n", stgs->feastol);
324
return 0;
325
}
326
327
if (stgs->maxit <= 0) {
328
printf("Invalid maxit: %d (must be positive)\\n", stgs->maxit);
329
return 0;
330
}
331
332
return 1; // Valid settings
333
}
334
335
// Use validation before solving
336
if (validate_settings(work->stgs)) {
337
idxint status = ECOS_solve(work);
338
} else {
339
printf("Invalid settings detected\\n");
340
}
341
```
342
343
## Default Constants
344
345
Global default values defined in the header files:
346
347
```c { .api }
348
// Core solver defaults (ecos.h)
349
#define MAXIT 100 // Maximum iterations
350
#define FEASTOL 1E-8 // Feasibility tolerance
351
#define ABSTOL 1E-8 // Absolute tolerance
352
#define RELTOL 1E-8 // Relative tolerance
353
#define GAMMA 0.99 // Step length scaling
354
#define VERBOSE 1 // Verbosity flag
355
#define NITREF 9 // Iterative refinement steps
356
357
// Mixed-integer defaults (ecos_bb.h)
358
#define MI_ABS_EPS 1E-6 // Absolute gap tolerance
359
#define MI_REL_EPS 1E-3 // Relative gap tolerance
360
#define MI_MAXITER 1000 // Maximum BB iterations
361
#define MI_INT_TOL 1E-4 // Integer tolerance
362
```
363
364
These constants can be used to reset settings to defaults:
365
366
```c
367
work->stgs->feastol = FEASTOL;
368
work->stgs->abstol = ABSTOL;
369
work->stgs->reltol = RELTOL;
370
work->stgs->maxit = MAXIT;
371
```