C/C++

Main solver API

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

OSQPWorkspace *osqp_setup(const OSQPData *data, 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
Solver environment
Parameters
  • 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/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, c_float *x, 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, c_float *x)

Warm start primal variable

Return
Exitflag
Parameters
  • work: Workspace structure
  • x: Primal variable

c_int osqp_warm_start_y(OSQPWorkspace *work, 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, 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, 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, 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, c_float *l_new, 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, c_float *Px_new, c_int *Px_new_idx, c_int P_new_n)

Update elements of matrix P (upper-diagonal) 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.

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

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

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 update_matrices()
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, c_float *Ax_new, 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 P->x is replaced.

Update elements of matrix A without changing sparsity structure.

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

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

Return
output flag: 0: OK 1: A_new_n > nnzA <0: error in update_matrices()
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, c_float *Px_new, c_int *Px_new_idx, c_int P_new_n, c_float *Ax_new, c_int *Ax_new_idx, c_int A_new_n)

Update elements of matrix P (upper-diagonal) 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 P->x is replaced.

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

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

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 P->x is replaced.

Return
output flag: 0: OK 1: P_new_n > nnzP 2: A_new_n > nnzA <0: error in update_matrices()
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

P: in csc format (size n x n). The workspace version stores only the upper triangular part. P->nzmax is the number of nonzero elements of the full P.

csc *A

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.

struct csc

Matrix in compressed-column or triplet form

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

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, scaling disabled

c_int adaptive_rho

boolean, is rho step size adaptive?

c_int adaptive_rho_interval

Number of iterations between rho adaptations rho. If 0, 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 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

linsys_solver_type linsys_solver

linear system solver to use

c_float delta

regularization parameter for polish

c_int polish

boolean, polish ADMM solution

c_int polish_refine_iter

iterative refinement steps in polish

c_int verbose

boolean, write out progres

c_int scaled_termination

boolean, use scaled termination criteria

c_int check_termination

integer, check termination interval. If 0, termination checking is disabled

c_int warm_start

boolean, warm start

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 nformation

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 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 * x.

Primal infeasibility variables

c_float *delta_y

Difference of consecutive dual iterates.

c_float *Atdelta_y

A’ * delta_y.

Dual infeasibility variables

c_float *delta_x

Difference of 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 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

Active rows of A. Ared = vstack[Alow, Aupp]

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