Main solver API

Main solver functions

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

OSQPInt osqp_setup(OSQPSolver **solverp, const OSQPCscMatrix *P, const OSQPFloat *q, const OSQPCscMatrix *A, const OSQPFloat *l, const OSQPFloat *u, OSQPInt m, OSQPInt n, const OSQPSettings *settings)

Initialize OSQP solver allocating memory.

It performs:

  • data and settings validation

  • problem data scaling

  • setup linear system solver:

    • direct solver: KKT matrix factorization is performed here

    • indirect solver: reduced KKT matrix preconditioning is performed here

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

  • solverp – Solver pointer

  • P – Problem data (upper triangular part of quadratic cost term, csc format)

  • q – Problem data (linear cost term)

  • A – Problem data (constraint matrix, csc format)

  • l – Problem data (constraint lower bound)

  • u – Problem data (constraint upper bound)

  • m – Problem data (number of constraints)

  • n – Problem data (number of variables)

  • settings – Solver settings


Exitflag for errors (0 if no errors)

OSQPInt osqp_solve(OSQPSolver *solver)

Solve quadratic program

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

The solution is stored in the solver->solution structure

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

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


solver – Solver


Exitflag for errors (0 if no errors)

OSQPInt osqp_cleanup(OSQPSolver *solver)

Cleanup workspace by deallocating memory

This function is not used in code generation


solver – Solver


Exitflag for errors (0 if no errors)

Main solver data types

struct OSQPSolver

Main OSQP solver structure that holds all information.

Public Members

OSQPSettings *settings

Problem settings.

OSQPSolution *solution

Computed solution.

OSQPInfo *info

Solver information.

OSQPWorkspace *work

Internal solver workspace (contents not public)

struct OSQPSolution

Structure to hold the computed solution (if any), and any certificates of infeasibility (if any) found by the solver.

Public Members

OSQPFloat *x

Primal solution.

OSQPFloat *y

Lagrange multiplier associated with \(l \le Ax \le u\).

OSQPFloat *prim_inf_cert

Primal infeasibility certificate.

OSQPFloat *dual_inf_cert

Dual infeasibility certificate.

struct OSQPInfo

Information about the solution process.

Public Members

char status[32]

Status string, e.g. ‘solved’.

OSQPInt status_val

Status as OSQPInt, defined in osqp_api_constants.h.

OSQPInt status_polish

Polishing status: successful (1), unperformed (0), unsuccessful (-1)

OSQPFloat obj_val

Primal objective value.

OSQPFloat prim_res

Norm of primal residual.

OSQPFloat dual_res

Norm of dual residual.

OSQPInt iter

Number of iterations taken.

OSQPInt rho_updates

Number of rho updates performned.

OSQPFloat rho_estimate

Best rho estimate so far from residuals.

OSQPFloat setup_time

Setup phase time (seconds)

OSQPFloat solve_time

Solve phase time (seconds)

OSQPFloat update_time

Update phase time (seconds)

OSQPFloat polish_time

Polish phase time (seconds)

OSQPFloat run_time

Total solve time (seconds)

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

OSQPInt osqp_warm_start(OSQPSolver *solver, const OSQPFloat *x, const OSQPFloat *y)

Warm start primal and dual variables

  • solver – Solver

  • x – Primal variable, NULL if none

  • y – Dual variable, NULL if none


Exitflag for errors (0 if no errors)

Update problem data

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

OSQPInt osqp_update_data_vec(OSQPSolver *solver, const OSQPFloat *q_new, const OSQPFloat *l_new, const OSQPFloat *u_new)

Update problem data vectors

  • solver – Solver

  • q_new – New linear cost, NULL if none

  • l_new – New lower bound, NULL if none

  • u_new – New upper bound, NULL if none


Exitflag for errors (0 if no errors)

OSQPInt osqp_update_data_mat(OSQPSolver *solver, const OSQPFloat *Px_new, const OSQPInt *Px_new_idx, OSQPInt P_new_n, const OSQPFloat *Ax_new, const OSQPInt *Ax_new_idx, OSQPInt A_new_n)

Update elements of matrices P (upper triangular) and A by preserving their sparsity structures.

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

  • solver – Solver

  • Px_new – Vector of new elements in P->x (upper triangular), NULL if none

  • 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, NULL if none

  • Ax_new_idx – Index mapping new elements to positions in A->x

  • A_new_n – Number of new elements to be changed


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

Solver settings

Settings API

void osqp_set_default_settings(OSQPSettings *settings)

Get the default settings from the osqp_api_constants.h file.


the settings parameter must already be allocated in memory.


settings – Settings structure to populate

Many solver settings can be updated without running setup again.

OSQPInt osqp_update_settings(OSQPSolver *solver, const OSQPSettings *new_settings)

Update settings in solver with the new settings from new_settings.

The following settings can only be set at problem setup time through osqp_setup and are ignored in this function:

  • scaling

  • rho_is_vec

  • sigma

  • adaptive_rho

  • adaptive_rho_interval

  • adaptive_rho_fraction

  • adaptive_rho_tolerance

The rho setting must be updated using osqp_update_rho, and is ignored by this function.


Every setting from new_settings is copied to solver.

  • solver – Solver

  • new_settings – New solver settings


Exitflag for errors (0 if no errors)

OSQPInt osqp_update_rho(OSQPSolver *solver, OSQPFloat rho_new)

Update the ADMM parameter rho.

Limit it between OSQP_RHO_MIN and OSQP_RHO_MAX.

  • solver – Solver

  • rho_new – New rho value


Exitflag for errors (0 if no errors)

Settings structure

The setting structure has the following fields.

struct OSQPSettings

User settings

Public Members

OSQPInt device

device identifier; currently used for CUDA devices

enum osqp_linsys_solver_type linsys_solver

linear system solver to use

OSQPInt verbose

boolean; write out progress

OSQPInt warm_starting

boolean; warm start

OSQPInt scaling

data scaling iterations; if 0, then disabled

OSQPInt polishing

boolean; polish ADMM solution

OSQPFloat rho

ADMM penalty parameter.

OSQPInt rho_is_vec

boolean; is rho scalar or vector?

OSQPFloat sigma

ADMM penalty parameter.

OSQPFloat alpha

ADMM relaxation parameter.

OSQPInt cg_max_iter

maximum number of CG iterations per solve

OSQPInt cg_tol_reduction

number of consecutive zero CG iterations before the tolerance gets halved

OSQPFloat cg_tol_fraction

CG tolerance (fraction of ADMM residuals)

osqp_precond_type cg_precond

Preconditioner to use in the CG method.

OSQPInt adaptive_rho

boolean, is rho step size adaptive?

OSQPInt adaptive_rho_interval

number of iterations between rho adaptations; if 0, then it is timing-based

OSQPFloat adaptive_rho_fraction

time interval for adapting rho (fraction of the setup time)

OSQPFloat adaptive_rho_tolerance

tolerance X for adapting rho; new rho must be X times larger or smaller than the current one to change it

OSQPInt max_iter

maximum number of iterations

OSQPFloat eps_abs

absolute solution tolerance

OSQPFloat eps_rel

relative solution tolerance

OSQPFloat eps_prim_inf

primal infeasibility tolerance

OSQPFloat eps_dual_inf

dual infeasibility tolerance

OSQPInt scaled_termination

boolean; use scaled termination criteria

OSQPInt check_termination

integer, check termination interval; if 0, checking is disabled

OSQPFloat time_limit

maximum time to solve the problem (seconds)

OSQPFloat delta

regularization parameter for polishing

OSQPInt polish_refine_iter

number of iterative refinement steps in polishing

Compute solution derivatives

Adjoint derivatives of the QP problem can be computed at the current solution.

OSQPInt osqp_adjoint_derivative_compute(OSQPSolver *solver, OSQPFloat *dx, OSQPFloat *dy_l, OSQPFloat *dy_u)

Compute internal data structures needed for calculation of the adjoint derivatives of P/q/A/l/u.


An optimal solution must be obtained before calling this function.

  • solver[in] Solver

  • dx[in] Vector of dx values (observed - true) of length n

  • dy_l[in] Vector of dy_l values (observed - true) of length m

  • dy_u[in] Vector of dy_u values (observed - true) of length m


Exitflag for errors (0 if no errors)

OSQPInt osqp_adjoint_derivative_get_mat(OSQPSolver *solver, OSQPCscMatrix *dP, OSQPCscMatrix *dA)

Calculate adjoint derivatives of P/A.


osqp_adjoint_derivative_compute must be called first.

  • solver[in] Solver

  • dP[out] Matrix of dP values (n x n)

  • dA[out] Matrix of dA values (m x n)


Exitflag for errors (0 if no errors; dP, dA are filled in)

OSQPInt osqp_adjoint_derivative_get_vec(OSQPSolver *solver, OSQPFloat *dq, OSQPFloat *dl, OSQPFloat *du)

Calculate adjoint derivatives of q/l/u.


osqp_adjoint_derivative_compute must be called first.

  • solver[in] Solver

  • dq[out] Vector of dq values of length n

  • dl[out] Matrix of dl values of length m

  • du[out] Matrix of du values of length m


Exitflag for errors (0 if no errors; dq, dl, du are filled in)

Code generation

The QP problem and all solver data can be written to a problem workspace for use by OSQP in embedded mode.

void osqp_set_default_codegen_defines(OSQPCodegenDefines *defines)

Set default codegen define values.


The defines structure must already be allocated in memory.


defines – Structure to set to default values.

OSQPInt osqp_codegen(OSQPSolver *solver, const char *output_dir, const char *prefix, OSQPCodegenDefines *defines)

Generate source files with a statically allocated OSQPSolver structure.


osqp_setup must be called before a problem can be code generated.

  • solver – Solver

  • output_dir – Path to directory to output the files to. This string must include the trailing directory separator, and an empty string means output to the current directory.

  • prefix – String prefix for the variables and generated files.

  • defines – The defines to use in the generated code.


Exitflag for errors (0 if no errors)

struct OSQPCodegenDefines

Structure to hold the settings for the generated code

Public Members

OSQPInt embedded_mode

Embedded mode (1 = vector update, 2 = vector + matrix update)

OSQPInt float_type

Use floats if 1, doubles if 0.

OSQPInt printing_enable

Enable printing if 1.

OSQPInt profiling_enable

Enable timing of code sections if 1.

OSQPInt interrupt_enable

Enable interrupt checking if 1.

OSQPInt derivatives_enable

Enable deriatives if 1.

Data types

The most basic used datatypes are

  • OSQPInt: can be long or int if the compiler flag OSQP_USE_LONG is set or not

  • OSQPFloat: can be a float or a double if the compiler flag OSQP_USE_FLOAT is set or not.

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

struct OSQPCscMatrix

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


number of rows


number of columns

OSQPInt *p

column pointers (size n+1); col indices (size nzmax) starting from 0 for triplet format

OSQPInt *i

row indices, size nzmax starting from 0

OSQPFloat *x

numerical values, size nzmax

OSQPInt nzmax

maximum number of entries

OSQPInt nz

number of entries in triplet matrix, -1 for csc