C¶

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

Parameters:

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

Returns:

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

Parameters:: solver – Solver
Returns:: 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

Parameters:: solver – Solver
Returns:: 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

Parameters:

solver – Solver
x – Primal variable, NULL if none
y – Dual variable, NULL if none

Returns:

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

Parameters:

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

Returns:

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.

Parameters:

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

Returns:

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.

Note

the settings parameter must already be allocated in memory.

Parameters:: 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.

Note

Every setting from new_settings is copied to solver.

Parameters:

solver – Solver
new_settings – New solver settings

Returns:

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.

Parameters:

solver – Solver
rho_new – New rho value

Returns:

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 allocate_solution¶: boolean; allocate solution in OSQPSolver during osqp_setup

OSQPInt verbose¶: boolean; write out progress

OSQPInt profiler_level¶: integer; level of detail for profiler annotations

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)¶

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

Note

An optimal solution must be obtained before calling this function.

Parameters:

solver – [in] Solver
dx – [in] Vector of dx values (observed - true) of length n
dy – [in] Vector of dy values (observed - true) of length m

Returns:

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.

Note

osqp_adjoint_derivative_compute must be called first.

Parameters:

solver – [in] Solver
dP – [out] Matrix of dP values (n x n)
dA – [out] Matrix of dA values (m x n)

Returns:

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.

Note

osqp_adjoint_derivative_compute must be called first.

Parameters:

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

Returns:

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.

Note

The defines structure must already be allocated in memory.

Parameters:: 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.

Note

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

Parameters:

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.

Returns:

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

OSQPInt m¶: number of rows

OSQPInt n¶: 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