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 OSQPDatan

number of variables n

c_int OSQPDatam

number of constraints m

csc *OSQPDataP

quadratic part of the cost P in csc format (size n x n). It can be either the full P or only the upper triangular part. The workspace stores only the upper triangular part

csc *OSQPDataA

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

c_float *OSQPDataq

dense array for linear part of cost function (size n)

c_float *OSQPDatal

dense array for lower bound (size m)

c_float *OSQPDatau

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 cscnzmax

maximum number of entries.

c_int cscm

number of rows

c_int cscn

number of columns

c_int *cscp

column pointers (size n+1) (col indices (size nzmax)

c_int *csci

row indices, size nzmax starting from 0

c_float *cscx

numerical values, size nzmax

c_int cscnz

of entries in triplet matrix, -1 for csc

Settings

struct OSQPSettings

Settings struct

Public Members

c_float OSQPSettingsrho

ADMM step rho.

c_float OSQPSettingssigma

ADMM step sigma.

c_int OSQPSettingsscaling

heuristic data scaling iterations. If 0,

c_int OSQPSettingsadaptive_rho

boolean, is rho step size adaptive?

c_int OSQPSettingsadaptive_rho_interval

Number of iterations between rho.

c_float OSQPSettingsadaptive_rho_tolerance

Tolerance X for adapting rho. The new rho.

c_float OSQPSettingsadaptive_rho_fraction

Interval for adapting rho (fraction of.

c_int OSQPSettingsmax_iter

maximum iterations

c_float OSQPSettingseps_abs

absolute convergence tolerance

c_float OSQPSettingseps_rel

relative convergence tolerance

c_float OSQPSettingseps_prim_inf

primal infeasibility tolerance

c_float OSQPSettingseps_dual_inf

dual infeasibility tolerance

c_float OSQPSettingsalpha

relaxation parameter

linsys_solver_type OSQPSettingslinsys_solver

linear system solver to use

c_float OSQPSettingsdelta

regularization parameter for

c_int OSQPSettingspolish

boolean, polish ADMM solution

c_int OSQPSettingspolish_refine_iter

iterative refinement steps in

c_int OSQPSettingsverbose

boolean, write out progres

c_int OSQPSettingsscaled_termination

boolean, use scaled termination

c_int OSQPSettingscheck_termination

integer, check termination

c_int OSQPSettingswarm_start

boolean, warm start

c_float OSQPSettingstime_limit

maximum seconds allowed to solve

Solution

struct OSQPSolution

Solution structure

Public Members

c_float *OSQPSolutionx

Primal solution.

c_float *OSQPSolutiony

Lagrange multiplier associated to \(l <= Ax <= u\).

Info

struct OSQPInfo

Solver return nformation

Public Members

c_int OSQPInfoiter

number of iterations taken

char OSQPInfostatus[32]

status string, e.g. ‘solved’

c_int OSQPInfostatus_val

status as c_int, defined in constants.h

c_int OSQPInfostatus_polish

polish status: successful (1), unperformed (0), (-1)

c_float OSQPInfoobj_val

primal objective

c_float OSQPInfopri_res

norm of primal residual

c_float OSQPInfodua_res

norm of dual residual

c_float OSQPInfosetup_time

time taken for setup phase (seconds)

c_float OSQPInfosolve_time

time taken for solve phase (seconds)

c_float OSQPInfopolish_time

time taken for polish phase (seconds)

c_float OSQPInforun_time

total time (seconds)

c_int OSQPInforho_updates

number of rho updates

c_float OSQPInforho_estimate

best rho estimate so far from residuals

Workspace

struct OSQPWorkspace

OSQP Workspace

Vector used to store a vectorized rho parameter

c_float *OSQPWorkspacerho_vec

vector of rho values

c_float *OSQPWorkspacerho_inv_vec

vector of inv rho values

Iterates

c_float *OSQPWorkspacex

Iterate x.

c_float *OSQPWorkspacey

Iterate y.

c_float *OSQPWorkspacez

Iterate z.

c_float *OSQPWorkspacexz_tilde

Iterate xz_tilde.

c_float *OSQPWorkspacex_prev

Previous x.

NB: Used also as workspace vector for dual residual

c_float *OSQPWorkspacez_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 *OSQPWorkspaceAx

Scaled A * x.

c_float *OSQPWorkspacePx

Scaled P * x.

c_float *OSQPWorkspaceAty

Scaled A * x.

Primal infeasibility variables

c_float *OSQPWorkspacedelta_y

Difference of consecutive dual iterates.

c_float *OSQPWorkspaceAtdelta_y

A’ * delta_y.

Dual infeasibility variables

c_float *OSQPWorkspacedelta_x

Difference of consecutive primal iterates.

c_float *OSQPWorkspacePdelta_x

P * delta_x.

c_float *OSQPWorkspaceAdelta_x

A * delta_x.

Temporary vectors used in scaling

c_float *OSQPWorkspaceD_temp

temporary primal variable scaling vectors

c_float *OSQPWorkspaceD_temp_A

temporary primal variable scaling vectors storing

c_float *OSQPWorkspaceE_temp

temporary constraints scaling vectors storing norms of

Public Members

OSQPData *OSQPWorkspacedata

Problem data to work on (possibly scaled)

LinSysSolver *OSQPWorkspacelinsys_solver

Linear System solver structure.

OSQPPolish *OSQPWorkspacepol

Polish structure.

c_int *OSQPWorkspaceconstr_type

Type of constraints: loose (-1), equality (1),.

OSQPSettings *OSQPWorkspacesettings

Problem settings.

OSQPScaling *OSQPWorkspacescaling

Scaling vectors.

OSQPSolution *OSQPWorkspacesolution

Problem solution.

OSQPInfo *OSQPWorkspaceinfo

Solver information.

OSQPTimer *OSQPWorkspacetimer

Timer object.

c_int OSQPWorkspacefirst_run

flag indicating whether the solve function has been run before

c_int OSQPWorkspacesummary_printed

Has last summary been printed? (true/false)

Scaling

struct OSQPScaling

Problem scaling matrices stored as vectors

Public Members

c_float OSQPScalingc

cost function scaling

c_float *OSQPScalingD

primal variable scaling

c_float *OSQPScalingE

dual variable scaling

c_float OSQPScalingcinv

cost function rescaling

c_float *OSQPScalingDinv

primal variable rescaling

c_float *OSQPScalingEinv

dual variable rescaling

Polish

struct OSQPPolish

Polish structure

Public Members

csc *OSQPPolishAred

Ared = vstack[Alow, Aupp].

Active rows of A.

c_int OSQPPolishn_low

number of lower-active rows

c_int OSQPPolishn_upp

number of upper-active rows

c_int *OSQPPolishA_to_Alow

Maps indices in A to indices in Alow.

c_int *OSQPPolishA_to_Aupp

Maps indices in A to indices in Aupp.

c_int *OSQPPolishAlow_to_A

Maps indices in Alow to indices in A.

c_int *OSQPPolishAupp_to_A

Maps indices in Aupp to indices in A.

c_float *OSQPPolishx

optimal x-solution obtained by polish

c_float *OSQPPolishz

optimal z-solution obtained by polish

c_float *OSQPPolishy

optimal y-solution obtained by polish

c_float OSQPPolishobj_val

objective value at polished solution

c_float OSQPPolishpri_res

primal residual at polished solution

c_float OSQPPolishdua_res

dual residual at polished solution