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

Return

Exitflag for errors (0 if no errors)

Parameters
  • workp: Solver workspace pointer

  • data: Problem data

  • settings: Solver settings

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

Return

Exitflag for errors

Parameters
  • work: Workspace allocated

c_int osqp_cleanup(OSQPWorkspace *work)

Cleanup workspace by deallocating memory

This function is not used in code generation

Return

Exitflag for errors

Parameters
  • work: Workspace

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

Return

Exitflag

Parameters
  • work: Workspace structure

  • x: Primal variable

  • y: Dual variable

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

Warm start primal variable

Return

Exitflag

Parameters
  • work: Workspace structure

  • x: Primal variable

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

Warm start dual variable

Return

Exitflag

Parameters
  • work: Workspace structure

  • y: Dual variable

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

Return

Exitflag for errors and warnings

Parameters
  • work: Workspace

  • q_new: New linear cost

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

Update lower bound in the problem constraints

Return

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

Parameters
  • work: Workspace

  • l_new: New lower bound

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

Update upper bound in the problem constraints

Return

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

Parameters
  • work: Workspace

  • u_new: New upper 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

Return

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

Parameters
  • work: Workspace

  • l_new: New lower bound

  • u_new: 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.

Return

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

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

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.

Return

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

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

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.

Return

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

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

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