C / C++

Main solver API

The C API is imported from the header scs.h, available here. This file and scs_types.h are the only public header files required for downstream applications.

ScsWork *scs_init(const ScsData *d, const ScsCone *k, const ScsSettings *stgs)

Initialize SCS and allocate memory.

All the inputs must be already allocated in memory before calling. After this function returns then the memory associated with d, k, and stgs can be freed as SCS maintains deep copies of these internally.

It performs:

data and settings validation
problem data scaling
automatic parameters tuning (if enabled)
setup linear system solver:
- direct solver: KKT matrix factorization is performed here
- indirect solver: KKT matrix preconditioning is performed here.

Parameters:

d – Problem data.
k – Cone data.
stgs – SCS solve settings.

Returns:

Solver workspace.

scs_int scs_solve(ScsWork *w, ScsSolution *sol, ScsInfo *info, scs_int warm_start)

Solve quadratic cone program initialized by scs_init.

Parameters:

w – Workspace allocated by scs_init.
sol – Solution will be stored here. If members x, y, s are NULL then SCS will allocate memory for them which must be freed by the caller.
info – Information about the solve will be stored here.
warm_start – Whether to use the entries of sol as warm-start for the solve.

Returns:

Flag containing problem status (see glbopts.h).

scs_int scs_update(ScsWork *w, scs_float *b, scs_float *c)

Update the b vector, c vector, or both, before another solve call.

After a solve we can reuse the SCS workspace in another solve if the only problem data that has changed are the b and c vectors.

Parameters:

w – SCS workspace from scs_init (modified in-place).
b – New b vector (can be SCS_NULL if unchanged).
c – New c vector (can be SCS_NULL if unchanged).

Returns:

0 if update successful.

void scs_finish(ScsWork *w)

Clean up allocated SCS workspace.

Parameters:: w – Workspace allocated by init, will be deallocated.

Helper functions

This sets the ScsSettings struct to the default values as specified in the Settings page.

void scs_set_default_settings(ScsSettings *stgs)

Helper function to set all settings to default values (see glbopts.h).

Parameters:: stgs – Settings struct that will be populated.

If you only need to solve a single problem and not a series of related problems, then you can call the scs function documented here, which simply calls the scs_init, scs_solve, scs_finish sequence above.

scs_int scs(const ScsData *d, const ScsCone *k, const ScsSettings *stgs, ScsSolution *sol, ScsInfo *info)

Solve quadratic cone program defined by data in d and cone k.

All the inputs must already be allocated in memory before calling.

Parameters:

d – Problem data.
k – Cone data.
stgs – SCS solver settings.
sol – Solution will be stored here. If members x, y, s are NULL then SCS will allocate memory for them.
info – Information about the solve will be stored here.

Returns:

Flag containing problem status (see glbopts.h).

Primitive types

These are defined in header file scs_types.h.

scs_int: is long if the compiler flag DLONG is set, otherwise it is int
scs_float: is float if the compiler flag SFLOAT is set, otherwise it is double

Input Types

The relevant input structs required by API are as follows.

Data

struct ScsData

Struct containing problem data.

Public Members

scs_int m: A has m rows.

scs_int n: A has n cols, P has n cols and n rows.

ScsMatrix *A: A is supplied in CSC format (size m x n).

ScsMatrix *P: P is supplied in CSC format (size n x n), must be symmetric positive semidefinite. Only pass in the upper triangular entries. If P = 0 then set P = SCS_NULL.

scs_float *b: Dense array for b (size m).

scs_float *c: Dense array for c (size n).

Data Matrices

The matrices must be in Compressed Sparse Column (CSC) format using zero-based indexing. See Data matrices for more details on what SCS expects.

struct ScsMatrix

This defines the data matrices which should be supplied in compressed sparse column format with zero based indexing.

Public Members

scs_float *x: Matrix values, size: number of non-zeros.

scs_int *i: Matrix row indices, size: number of non-zeros.

scs_int *p: Matrix column pointers, size: n+1.

scs_int m: Number of rows.

scs_int n: Number of columns.

Cone

See Cones for more details.

struct ScsCone

Cone data. Rows of data matrix A must be specified in this exact order.

Public Members

scs_int z: Number of linear equality constraints (primal zero, dual free).

scs_int l: Number of positive orthant cones.

scs_float *bu: Upper box values, len(bu) = len(bl) = max(bsize-1, 0).

scs_float *bl: Lower box values, len(bu) = len(bl) = max(bsize-1, 0).

scs_int bsize: Total length of box cone (includes scale t).

scs_int *q: Array of second-order cone constraints, len(q) = qsize.

scs_int qsize: Length of second-order cone array q.

scs_int *s: Array of semidefinite cone constraints, len(s) = ssize.

scs_int ssize: Length of semidefinite constraints array s.

scs_int ep: Number of primal exponential cone triples.

scs_int ed: Number of dual exponential cone triples.

scs_float *p: Array of power cone params, must be in [-1, 1], negative values are interpreted as specifying the dual cone, len(p) = psize

scs_int psize: Number of (primal and dual) power cone triples.

Settings

See Settings for details on each of these.

struct ScsSettings

Struct containing all settings.

Public Members

scs_int normalize: Whether to heuristically rescale the data before solve.

scs_float scale: Initial dual scaling factor (may be updated if adaptive_scale is on).

scs_int adaptive_scale: Whether to adaptively update scale.

scs_float rho_x: Primal constraint scaling factor.

scs_int max_iters: Maximum iterations to take.

scs_float eps_abs: Absolute convergence tolerance.

scs_float eps_rel: Relative convergence tolerance.

scs_float eps_infeas: Infeasible convergence tolerance.

scs_float alpha: Douglas-Rachford relaxation parameter.

scs_float time_limit_secs: Time limit in secs (can be fractional).

scs_int verbose: Whether to log progress to stdout.

scs_int warm_start: Whether to use warm start (put initial guess in ScsSolution struct).

scs_int acceleration_lookback: Memory for acceleration.

scs_int acceleration_interval: Interval to apply acceleration.

const char *write_data_filename: String, if set will dump raw prob data to this file.

const char *log_csv_filename: String, if set will log data to this csv file (makes SCS very slow).

Output Types

The relevant output structs returned by SCS are as follows.

Solution

This will contain the solution as found by SCS or the certificate of primal or dual infeasibility (see Termination criteria). If the user wants to warm-start the solver, then the Solution struct is also used as an input to specify the warm-start points (see Caching the workspace and warm-starts).

struct ScsSolution

Contains primal-dual solution arrays or a certificate of infeasibility. Check the exit flag to determine whether this contains a solution or a certificate. If when passed into SCS the members x, y, s are NULL then SCS will allocate memory for them which should be managed by the user to prevent memory leaks.

Public Members

scs_float *x: Primal variable.

scs_float *y: Dual variable.

scs_float *s: Slack variable.

Info

See Return information for details on each of these.

struct ScsInfo

Contains information about the solve run at termination.

Public Members

scs_int iter: Number of iterations taken.

char status[128]: Status string, e.g. ‘solved’.

char lin_sys_solver[128]: Linear system solver used.

scs_int status_val: Status as scs_int, defined in glbopts.h.

scs_int scale_updates: Number of updates to scale.

scs_float pobj: Primal objective.

scs_float dobj: Dual objective.

scs_float res_pri: Primal equality residual.

scs_float res_dual: Dual equality residual.

scs_float gap: Duality gap.

scs_float res_infeas: Infeasibility cert residual.

scs_float res_unbdd_a: Unbounded cert residual.

scs_float res_unbdd_p: Unbounded cert residual.

scs_float setup_time: Time taken for setup phase (milliseconds).

scs_float solve_time: Time taken for solve phase (milliseconds).

scs_float scale: Final scale parameter.

scs_float comp_slack: Complementary slackness.

scs_int rejected_accel_steps: Number of rejected AA steps.

scs_int accepted_accel_steps: Number of accepted AA steps.

scs_float lin_sys_time: Total time (milliseconds) spent in the linear system solver.

scs_float cone_time: Total time (milliseconds) spent in the cone projection.

scs_float accel_time: Total time (milliseconds) spent in the acceleration routine.

Workspace

The user should not need to interact with the ScsWork struct, which contains the internal workspace allocated and maintained by SCS.