or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-solver.mddata-updates.mdindex.mdmixed-integer.md
tile.json

tessl/c-ecos

Embedded Conic Solver (ECOS) - A numerical software for solving convex second-order cone programs (SOCPs)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes

pkg:generic/ecos@1.1.x

To install, run

npx @tessl/cli install tessl/c-ecos@1.1.0

index.mddocs/

ECOS - Embedded Conic Solver

ECOS is a high-performance numerical library for solving convex second-order cone programs (SOCPs) designed specifically for embedded systems and real-time applications. The solver implements efficient algorithms for constrained optimization problems with conic constraints, supporting both continuous and mixed-integer formulations through its branch-and-bound extension (ECOS_BB).

Package Information

  • Package Name: ecos
  • Language: C
  • License: GPL-3.0
  • Installation: Build from source using provided Makefile (make all to build libraries, make demo to build demo)
  • Dependencies: SuiteSparse components (LDL and AMD packages are included in external/ directory)

Core Imports

#include "ecos.h"          // Core ECOS solver
#include "ecos_bb.h"       // Mixed-integer branch-and-bound extension

Basic Usage

Solving a Basic SOCP

#include "ecos.h"

// Problem data: minimize c'*x subject to A*x = b, G*x <=_K h
// where K is a product of positive orthant and second-order cones

int main() {
    // Problem dimensions
    idxint n = 3;    // number of variables
    idxint m = 3;    // number of inequality constraints  
    idxint p = 1;    // number of equality constraints
    idxint l = 1;    // number of positive orthant constraints
    idxint ncones = 1; // number of second-order cones
    idxint q[1] = {2}; // sizes of second-order cones

    // Problem data (example values)
    pfloat c[3] = {1.0, 1.0, 0.0};
    pfloat h[3] = {1.0, 0.0, 0.0};
    pfloat b[1] = {1.0};
    
    // Sparse matrices G and A (CSC format)
    pfloat Gpr[4] = {1.0, 0.0, 0.0, 1.0};
    idxint Gjc[4] = {0, 1, 2, 4};
    idxint Gir[4] = {0, 1, 1, 2};
    
    pfloat Apr[1] = {1.0};
    idxint Ajc[4] = {0, 1, 1, 1};
    idxint Air[1] = {0};

    // Set up solver workspace
    pwork* mywork = ECOS_setup(n, m, p, l, ncones, q,
                               Gpr, Gjc, Gir,
                               Apr, Ajc, Air,
                               c, h, b);
    
    if (mywork) {
        // Solve the problem
        idxint exitflag = ECOS_solve(mywork);
        
        // Check solution status
        if (exitflag == ECOS_OPTIMAL) {
            printf("Optimal solution found\\n");
            printf("Objective value: %f\\n", mywork->info->pcost);
            
            // Access solution
            for (int i = 0; i < n; i++) {
                printf("x[%d] = %f\\n", i, mywork->x[i]);
            }
        }
        
        // Clean up
        ECOS_cleanup(mywork, 0);
    }
    
    return 0;
}

Solving Mixed-Integer Problems

#include "ecos_bb.h"

int main() {
    // Set up problem data (same as above)
    // ...
    
    // Mixed-integer specific data
    idxint num_bool_vars = 1;    // number of boolean variables
    idxint bool_vars_idx[1] = {0}; // indices of boolean variables
    idxint num_int_vars = 0;     // number of integer variables
    idxint* int_vars_idx = NULL; // indices of integer variables
    
    // Set up mixed-integer solver
    ecos_bb_pwork* mywork = ECOS_BB_setup(n, m, p, l, ncones, q,
                                          Gpr, Gjc, Gir,
                                          Apr, Ajc, Air,
                                          c, h, b,
                                          num_bool_vars, bool_vars_idx,
                                          num_int_vars, int_vars_idx,
                                          NULL); // use default settings
    
    if (mywork) {
        // Solve mixed-integer problem
        idxint exitflag = ECOS_BB_solve(mywork);
        
        // Check results and clean up
        ECOS_BB_cleanup(mywork, 0);
    }
    
    return 0;
}

Architecture

ECOS is organized into several key modules:

  • Core Solver (ecos.h): Main optimization algorithm and workspace management
  • Branch-and-Bound (ecos_bb.h): Mixed-integer extension with tree search
  • Cone Operations (cone.h): Conic constraint handling and projections
  • KKT System (kkt.h): Linear system factorization and solving
  • Sparse Linear Algebra (spla.h): Matrix-vector operations
  • Problem Setup: Data preprocessing and equilibration

The solver uses interior-point methods with efficient sparse linear algebra, making it suitable for embedded applications with limited computational resources.

Capabilities

Core SOCP Solver

Complete interface for solving continuous second-order cone programs including problem setup, solving, and memory management.

pwork* ECOS_setup(idxint n, idxint m, idxint p, idxint l, idxint ncones, idxint* q,
                   pfloat* Gpr, idxint* Gjc, idxint* Gir,
                   pfloat* Apr, idxint* Ajc, idxint* Air,
                   pfloat* c, pfloat* h, pfloat* b);

idxint ECOS_solve(pwork* w);

void ECOS_cleanup(pwork* w, idxint keepvars);

const char* ECOS_ver(void);

Core SOCP Solver

Mixed-Integer Branch-and-Bound

Extension for solving mixed-integer and mixed-boolean second-order cone programs using branch-and-bound search.

ecos_bb_pwork* ECOS_BB_setup(idxint n, idxint m, idxint p, idxint l, idxint ncones, idxint* q,
                              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);

idxint ECOS_BB_solve(ecos_bb_pwork* prob);

void ECOS_BB_cleanup(ecos_bb_pwork* prob, idxint num_vars_keep);

Mixed-Integer Solver

Problem Data Updates

Expert-level interface for updating problem data during solve iterations without complete re-setup.

void ecos_updateDataEntry_h(pwork* w, idxint idx, pfloat value);
void ecos_updateDataEntry_c(pwork* w, idxint idx, pfloat value);

void updateDataEntry_h(ecos_bb_pwork* w, idxint idx, pfloat value);
void updateDataEntry_c(ecos_bb_pwork* w, idxint idx, pfloat value);

Data Updates

Configuration and Settings

Solver parameter configuration and default settings management.

typedef struct settings {
    pfloat gamma;
    pfloat delta;
    pfloat eps;
    pfloat feastol;
    pfloat abstol;
    pfloat reltol;
    pfloat feastol_inacc;
    pfloat abstol_inacc;
    pfloat reltol_inacc;
    idxint nitref;
    idxint maxit;
    idxint verbose;
} settings;

settings_bb* get_default_ECOS_BB_settings();

Configuration

Types

Core Data Types

typedef double pfloat;               // Floating point precision type
typedef SuiteSparse_long idxint;     // Index integer type

// Sparse matrix in compressed sparse column format
typedef struct spmat {    
   idxint* jc;    // Column pointers
   idxint* ir;    // Row indices
   pfloat* pr;    // Numerical values
   idxint n;      // Number of columns
   idxint m;      // Number of rows
   idxint nnz;    // Number of non-zeros
} spmat;

// Complete solver workspace
typedef struct pwork {
    // Problem dimensions
    idxint n;      // Number of primal variables
    idxint m;      // Number of conically constrained variables
    idxint p;      // Number of equality constraints
    idxint D;      // Degree of the cone

    // Solution variables
    pfloat* x;     // Primal variables
    pfloat* y;     // Equality constraint multipliers
    pfloat* z;     // Conic inequality multipliers
    pfloat* s;     // Slack variables
    pfloat kap;    // Homogeneous embedding parameter
    pfloat tau;    // Homogeneous embedding parameter

    // Problem data
    spmat* A;      // Equality constraint matrix
    spmat* G;      // Inequality constraint matrix
    pfloat* c;     // Objective vector
    pfloat* b;     // Equality constraint RHS
    pfloat* h;     // Inequality constraint RHS

    // Internal solver data
    cone* C;       // Cone structure
    kkt* KKT;      // KKT system
    stats* info;   // Solution statistics
    settings* stgs; // Solver settings
} pwork;

// Solution statistics
typedef struct stats {
    pfloat pcost;     // Primal objective value
    pfloat dcost;     // Dual objective value
    pfloat pres;      // Primal residual
    pfloat dres;      // Dual residual
    pfloat pinf;      // Primal infeasibility measure
    pfloat dinf;      // Dual infeasibility measure
    pfloat gap;       // Duality gap
    pfloat relgap;    // Relative duality gap
    idxint iter;      // Number of iterations
} stats;

Mixed-Integer Types

// Branch-and-bound settings
typedef struct settings_bb {
    idxint maxit;          // Maximum iterations
    idxint verbose;        // Verbosity level
    pfloat abs_tol_gap;    // Absolute gap tolerance
    pfloat rel_tol_gap;    // Relative gap tolerance
    pfloat integer_tol;    // Integer rounding tolerance
} settings_bb;

// Branch-and-bound tree node
typedef struct node {
    char status;           // Node status
    pfloat L;             // Lower bound
    pfloat U;             // Upper bound
    idxint split_idx;     // Split variable index
    pfloat split_val;     // Split value
} node;

// Mixed-integer solver workspace
typedef struct ecos_bb_pwork {
    // Mixed-integer data
    idxint num_bool_vars;  // Number of boolean variables
    idxint num_int_vars;   // Number of integer variables
    idxint* bool_vars_idx; // Boolean variable indices
    idxint* int_vars_idx;  // Integer variable indices

    // Core ECOS solver
    pwork* ecos_prob;      // Underlying ECOS problem

    // Branch-and-bound data
    node* nodes;           // Tree nodes
    pfloat global_U;       // Global upper bound
    pfloat global_L;       // Global lower bound
    idxint iter;           // Current iteration

    // Settings
    settings* ecos_stgs;   // ECOS settings
    settings_bb* stgs;     // Branch-and-bound settings
} ecos_bb_pwork;

Constants and Exit Codes

// ECOS Exit Codes
#define ECOS_OPTIMAL   0    // Problem solved to optimality
#define ECOS_PINF      1    // Found certificate of primal infeasibility
#define ECOS_DINF      2    // Found certificate of dual infeasibility
#define ECOS_MAXIT    -1    // Maximum number of iterations reached
#define ECOS_NUMERICS -2    // Search direction unreliable
#define ECOS_OUTCONE  -3    // Variables got outside the cone
#define ECOS_SIGINT   -4    // Solver interrupted by signal
#define ECOS_FATAL    -7    // Unknown problem in solver

// Mixed-Integer Exit Codes
#define MI_OPTIMAL_SOLN           0    // Optimal solution found
#define MI_MAXITER_FEASIBLE_SOLN -1    // Max iterations with feasible solution
#define MI_MAXITER_NO_SOLN        1    // Max iterations without solution
#define MI_INFEASIBLE             2    // Problem infeasible

// Default Parameter Values
#define MAXIT      100      // Maximum iterations
#define FEASTOL    1E-8     // Feasibility tolerance
#define ABSTOL     1E-8     // Absolute tolerance
#define RELTOL     1E-8     // Relative tolerance
#define GAMMA      0.99     // Step length scaling
#define VERBOSE    1        // Verbosity flag