C¶

Main solver API¶

The main C API is imported from the header osqp.h and provides the following functions

c_int osqp_setup(OSQPWorkspace **workp, const OSQPData *data, const OSQPSettings *settings)¶

Initialize OSQP solver allocating memory.

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

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

NB: This is the only function that allocates dynamic memory and is not used during code generation

Parameters:

workp – Solver workspace pointer
data – Problem data
settings – Solver settings

Returns:

Exitflag for errors (0 if no errors)

c_int osqp_solve(OSQPWorkspace *work)¶

Solve quadratic program

The final solver information is stored in the work->info structure

The solution is stored in the work->solution structure

If the problem is primal infeasible, the certificate is stored in work->delta_y

If the problem is dual infeasible, the certificate is stored in work->delta_x

Parameters:: work – Workspace allocated
Returns:: Exitflag for errors

c_int osqp_cleanup(OSQPWorkspace *work)¶

Cleanup workspace by deallocating memory

This function is not used in code generation

Parameters:: work – Workspace
Returns:: Exitflag for errors

Sublevel API¶

Sublevel C API is also imported from the header osqp.h and provides the following functions

Warm start¶

OSQP automatically warm starts primal and dual variables from the previous QP solution. If you would like to warm start their values manually, you can use

c_int osqp_warm_start(OSQPWorkspace *work, const c_float *x, const c_float *y)¶

Warm start primal and dual variables

Parameters:

work – Workspace structure
x – Primal variable
y – Dual variable

Returns:

Exitflag

c_int osqp_warm_start_x(OSQPWorkspace *work, const c_float *x)¶

Warm start primal variable

Parameters:

work – Workspace structure
x – Primal variable

Returns:

Exitflag

c_int osqp_warm_start_y(OSQPWorkspace *work, const c_float *y)¶

Warm start dual variable

Parameters:

work – Workspace structure
y – Dual variable

Returns:

Exitflag

Update problem data¶

Problem data can be updated without executing the setup again using the following functions.

c_int osqp_update_lin_cost(OSQPWorkspace *work, const c_float *q_new)¶

Update linear cost in the problem

Parameters:

work – Workspace
q_new – New linear cost

Returns:

Exitflag for errors and warnings

c_int osqp_update_lower_bound(OSQPWorkspace *work, const c_float *l_new)¶

Update lower bound in the problem constraints

Parameters:

work – Workspace
l_new – New lower bound

Returns:

Exitflag: 1 if new lower bound is not <= than upper bound

c_int osqp_update_upper_bound(OSQPWorkspace *work, const c_float *u_new)¶

Update upper bound in the problem constraints

Parameters:

work – Workspace
u_new – New upper bound

Returns:

Exitflag: 1 if new upper bound is not >= than lower bound

c_int osqp_update_bounds(OSQPWorkspace *work, const c_float *l_new, const c_float *u_new)¶

Update lower and upper bounds in the problem constraints

Parameters:

work – Workspace
l_new – New lower bound
u_new – New upper bound

Returns:

Exitflag: 1 if new lower bound is not <= than new upper bound

c_int osqp_update_P(OSQPWorkspace *work, const c_float *Px_new, const c_int *Px_new_idx, c_int P_new_n)¶

Update elements of matrix P (upper triangular) without changing sparsity structure.

If Px_new_idx is OSQP_NULL, Px_new is assumed to be as long as P->x and the whole P->x is replaced.

Parameters:

work – Workspace structure
Px_new – Vector of new elements in P->x (upper triangular)
Px_new_idx – Index mapping new elements to positions in P->x
P_new_n – Number of new elements to be changed

Returns:

output flag: 0: OK 1: P_new_n > nnzP <0: error in the update

c_int osqp_update_A(OSQPWorkspace *work, const c_float *Ax_new, const c_int *Ax_new_idx, c_int A_new_n)¶

Update elements of matrix A without changing sparsity structure.

If Ax_new_idx is OSQP_NULL, Ax_new is assumed to be as long as A->x and the whole A->x is replaced.

Parameters:

work – Workspace structure
Ax_new – Vector of new elements in A->x
Ax_new_idx – Index mapping new elements to positions in A->x
A_new_n – Number of new elements to be changed

Returns:

output flag: 0: OK 1: A_new_n > nnzA <0: error in the update

c_int osqp_update_P_A(OSQPWorkspace *work, const c_float *Px_new, const c_int *Px_new_idx, c_int P_new_n, const c_float *Ax_new, const c_int *Ax_new_idx, c_int A_new_n)¶

Update elements of matrix P (upper triangular) and elements of matrix A without changing sparsity structure.

If Px_new_idx is OSQP_NULL, Px_new is assumed to be as long as P->x and the whole P->x is replaced.

If Ax_new_idx is OSQP_NULL, Ax_new is assumed to be as long as A->x and the whole A->x is replaced.

Parameters:

work – Workspace structure
Px_new – Vector of new elements in P->x (upper triangular)
Px_new_idx – Index mapping new elements to positions in P->x
P_new_n – Number of new elements to be changed
Ax_new – Vector of new elements in A->x
Ax_new_idx – Index mapping new elements to positions in A->x
A_new_n – Number of new elements to be changed

Returns:

output flag: 0: OK 1: P_new_n > nnzP 2: A_new_n > nnzA <0: error in the update

Data types¶

The most basic used datatypes are

c_int: can be long or int if the compiler flag DLONG is set or not
c_float: can be a float or a double if the compiler flag DFLOAT is set or not.

The relevant structures used in the API are

Data¶

struct OSQPData¶

Data structure

Public Members

c_int n¶: number of variables n

c_int m¶: number of constraints m

csc *P¶: the upper triangular part of the quadratic cost matrix P in csc format (size n x n).

csc *A¶: linear constraints matrix A in csc format (size m x n)

c_float *q¶: dense array for linear part of cost function (size n)

c_float *l¶: dense array for lower bound (size m)

c_float *u¶: dense array for upper bound (size m)

The matrices are defined in Compressed Sparse Column (CSC) format using zero-based indexing.

struct csc¶

Matrix in compressed-column form. The structure is used internally to store matrices in the triplet form as well, but the API requires that the matrices are in the CSC format.

Public Members

c_int nzmax¶: maximum number of entries

c_int m¶: number of rows

c_int n¶: number of columns

c_int *p¶: column pointers (size n+1); col indices (size nzmax) start from 0 when using triplet format (direct KKT matrix formation)

c_int *i¶: row indices, size nzmax starting from 0

c_float *x¶: numerical values, size nzmax

c_int nz¶: number of entries in triplet matrix, -1 for csc

Settings¶

struct OSQPSettings¶

Settings struct

Public Members

c_float rho¶: ADMM step rho.

c_float sigma¶: ADMM step sigma.

c_int scaling¶: heuristic data scaling iterations; if 0, then disabled.

c_int adaptive_rho¶: boolean, is rho step size adaptive?

c_int adaptive_rho_interval¶: number of iterations between rho adaptations; if 0, then it is automatic

c_float adaptive_rho_tolerance¶: tolerance X for adapting rho. The new rho has to be X times larger or 1/X times smaller than the current one to trigger a new factorization.

c_float adaptive_rho_fraction¶: interval for adapting rho (fraction of the setup time)

c_int max_iter¶: maximum number of iterations

c_float eps_abs¶: absolute convergence tolerance

c_float eps_rel¶: relative convergence tolerance

c_float eps_prim_inf¶: primal infeasibility tolerance

c_float eps_dual_inf¶: dual infeasibility tolerance

c_float alpha¶: relaxation parameter

enum linsys_solver_type linsys_solver¶: linear system solver to use

c_float delta¶: regularization parameter for polishing

c_int polish¶: boolean, polish ADMM solution

c_int polish_refine_iter¶: number of iterative refinement steps in polishing

c_int verbose¶: boolean, write out progress

c_int scaled_termination¶: boolean, use scaled termination criteria

c_int check_termination¶: integer, check termination interval; if 0, then termination checking is disabled

c_int warm_start¶: boolean, warm start

c_float time_limit¶: maximum number of seconds allowed to solve the problem; if 0, then disabled

Solution¶

struct OSQPSolution¶

Solution structure

Public Members

c_float *x¶: primal solution

c_float *y¶: Lagrange multiplier associated to \(l <= Ax <= u\).

Info¶

struct OSQPInfo¶

Solver return information

Public Members

c_int iter¶: number of iterations taken

char status[32]¶: status string, e.g. ‘solved’

c_int status_val¶: status as c_int, defined in constants.h

c_int status_polish¶: polish status: successful (1), unperformed (0), (-1) unsuccessful

c_float obj_val¶: primal objective

c_float pri_res¶: norm of primal residual

c_float dua_res¶: norm of dual residual

c_float setup_time¶: time taken for setup phase (seconds)

c_float solve_time¶: time taken for solve phase (seconds)

c_float update_time¶: time taken for update phase (seconds)

c_float polish_time¶: time taken for polish phase (seconds)

c_float run_time¶: total time (seconds)

c_int rho_updates¶: number of rho updates

c_float rho_estimate¶: best rho estimate so far from residuals

Workspace¶

struct OSQPWorkspace¶

OSQP Workspace

Vector used to store a vectorized rho parameter

c_float *rho_vec¶: vector of rho values

c_float *rho_inv_vec¶: vector of inv rho values

Iterates

c_float *x¶: Iterate x.

c_float *y¶: Iterate y.

c_float *z¶: Iterate z.

c_float *xz_tilde¶: Iterate xz_tilde.

c_float *x_prev¶

Previous x.

NB: Used also as workspace vector for dual residual

c_float *z_prev¶

Previous z.

NB: Used also as workspace vector for primal residual

Primal and dual residuals workspace variables

Needed for residuals computation, tolerances computation, approximate tolerances computation and adapting rho

c_float *Ax¶: scaled A * x

c_float *Px¶: scaled P * x

c_float *Aty¶: scaled A’ * y

Primal infeasibility variables

c_float *delta_y¶: difference between consecutive dual iterates

c_float *Atdelta_y¶: A’ * delta_y.

Dual infeasibility variables

c_float *delta_x¶: difference between consecutive primal iterates

c_float *Pdelta_x¶: P * delta_x.

c_float *Adelta_x¶: A * delta_x.

Temporary vectors used in scaling

c_float *D_temp¶: temporary primal variable scaling vectors

c_float *D_temp_A¶: temporary primal variable scaling vectors storing norms of A columns

c_float *E_temp¶: temporary constraints scaling vectors storing norms of A’ columns

Public Members

OSQPData *data¶: Problem data to work on (possibly scaled)

LinSysSolver *linsys_solver¶: Linear System solver structure.

OSQPPolish *pol¶: Polish structure.

c_int *constr_type¶: Type of constraints: loose (-1), equality (1), inequality (0)

OSQPSettings *settings¶: problem settings

OSQPScaling *scaling¶: scaling vectors

OSQPSolution *solution¶: problem solution

OSQPInfo *info¶: solver information

OSQPTimer *timer¶: timer object

c_int first_run¶: flag indicating whether the solve function has been run before

c_int clear_update_time¶: flag indicating whether the update_time should be cleared

c_int rho_update_from_solve¶: flag indicating that osqp_update_rho is called from osqp_solve function

c_int summary_printed¶: Has last summary been printed? (true/false)

Scaling¶

struct OSQPScaling¶

Problem scaling matrices stored as vectors

Public Members

c_float c¶: cost function scaling

c_float *D¶: primal variable scaling

c_float *E¶: dual variable scaling

c_float cinv¶: cost function rescaling

c_float *Dinv¶: primal variable rescaling

c_float *Einv¶: dual variable rescaling

Polish¶

struct OSQPPolish¶

Polish structure

Public Members

csc *Ared¶

Ared = vstack[Alow, Aupp].

active rows of A

c_int n_low¶: number of lower-active rows

c_int n_upp¶: number of upper-active rows

c_int *A_to_Alow¶: Maps indices in A to indices in Alow.

c_int *A_to_Aupp¶: Maps indices in A to indices in Aupp.

c_int *Alow_to_A¶: Maps indices in Alow to indices in A.

c_int *Aupp_to_A¶: Maps indices in Aupp to indices in A.

c_float *x¶: optimal x-solution obtained by polish

c_float *z¶: optimal z-solution obtained by polish

c_float *y¶: optimal y-solution obtained by polish

c_float obj_val¶: objective value at polished solution

c_float pri_res¶: primal residual at polished solution

c_float dua_res¶: dual residual at polished solution