solver-qpoases

A qpOASES wrapper for Python that ships prebuilt binaries. It exposes qpOASES' online active-set solver through a thin, numpy-friendly, MATLAB-quadprog-like interface.

pip install marinholab-solvers-qpoases

Overview

Given a symmetric matrix H, a vector f, and (optionally) inequality and equality constraint matrices, the solver solves the quadratic program

min_x   0.5 * x' H x + f' x
s.t.    A x <= b
        Aeq x = beq

Once a problem has been solved once, subsequent solves on the same Solver instance are warm-started by default (Configuration.use_hotstart = True), which is the main performance benefit of qpOASES for repeated, related QPs.

Quickstart

import numpy as np
from marinholab.solvers import qpoases

solver = qpoases.Solver()

H = np.eye(2)                          # positive definite Hessian
f = np.array([-1.0, -1.0])             # linear term
A = np.array([[1.0, 0.0]])             # x[0] <= 0.2
b = np.array([0.2])

x = solver.solve_quadratic_program(H, f, A, b,
                                   Aeq=np.zeros((1, 2)),
                                   beq=np.zeros((1,)))
# x ≈ [0.2, 1.0]

Omitting constraints

Any of the four constraint arguments (A, b, Aeq, beq) can be None, meaning "no such constraint". The matrix and its right-hand side must be omitted (or provided) together:

# Unconstrained
x = solver.solve_quadratic_program(H, f, None, None, None, None)

# Equality constraints only
x = solver.solve_quadratic_program(H, f, None, None, Aeq, beq)

Active set

solver.get_active_set() reports, for each row of the combined constraint matrix (rows of A followed by rows of Aeq), whether it is:

  • -1 active at its lower bound,
  • 0 inactive,
  • +1 active at its upper bound (equality constraints are always +1, since their bounds coincide).
solver.solve_quadratic_program(H, f, A, b, Aeq, beq)
solver.get_active_set()  # e.g. [ 1.0, 0.0, 0.0]

Configuration

All of qpOASES' Options fields are exposed, plus a few wrapper-specific settings. Create a Configuration, tweak the fields you need, and pass it to the solver:

config = qpoases.Configuration()
config.hessian_type = qpoases.HessianType.HST_SEMIDEF   # H is rank-deficient
config.enableRegularisation = qpoases.BooleanType.BT_FALSE
config.termination_tolerance = 1.0e-9                    # tighter convergence
solver = qpoases.Solver(config)

The enum types are re-exported for convenience: qpoases.BooleanType, qpoases.HessianType, qpoases.PrintLevel, and qpoases.SubjectToStatus.

Wrapper-specific options

Option Default Type Description
maximum_working_set_recalculations 150 int Max working-set recalculations during the initial homotopy (nWSR passed to init/hotstart). Increase if solves hit the maximum.
use_hotstart True bool Warm-start subsequent solves with hotstart() instead of re-initialising with init().
hessian_type HST_POSDEF HessianType Definiteness assumed for H; given to the underlying SQProblem.

Hessian definiteness (HessianType)

Value Meaning
HST_ZERO Hessian is the zero matrix (LP formulation)
HST_IDENTITY Hessian is the identity matrix
HST_POSDEF Hessian is (strictly) positive definite
HST_POSDEF_NULLSPACE Positive definite on the null space of active bounds/constraints
HST_SEMIDEF Positive semi-definite
HST_INDEF Indefinite
HST_UNKNOWN Unknown

qpOASES options

These map 1:1 onto qpOASES' Options fields. Defaults match qpOASES' own defaults for a double-precision build (see Options::setToDefault()), with two deliberate exceptions noted inline: enableNZCTests and enableFlippingBounds default to BT_FALSE here (qpOASES' default is BT_TRUE) because those are the recommended "fast"/MPC settings for repeated, online solves. See the qpOASES manual for a full description of each option.

Booleans (BooleanType: BT_FALSE / BT_TRUE)

Option Default Description
enable_ramping BT_TRUE Enables the ramping strategy.
enable_far_bounds BT_TRUE Enables the far bounds strategy.
enableFlippingBounds BT_FALSE Allows flipping active bounds between lower and upper values. (differs from qpOASES default)
enableRegularisation BT_FALSE Regularises H when (semi-)definiteness is detected.
enable_full_li_tests BT_FALSE Uses the condition-hardened linear-independence (LI) test.
enableNZCTests BT_FALSE Enables the nonzero-curvature test. (differs from qpOASES default)
enable_equalities BT_FALSE Treats equality constraints as always active.
enable_inertia_correction BT_TRUE Repairs the working set when negative curvature is found during a hotstart.
enable_drop_infeasibles BT_FALSE Whether infeasible constraints may be dropped.

Integers (int_t)

Option Default Description
enable_drift_correction 1 Frequency of drift corrections (0 = off).
enable_cholesky_refactorisation 0 Frequency of full Cholesky refactorisation of the projected Hessian (0 = rank updates only).
num_regularisation_steps 0 Max successive regularisation steps.
num_refinement_steps 1 Max iterative-refinement steps.
drop_bound_priority 1 Priority used when dropping bounds.
drop_eq_con_priority 1 Priority used when dropping equality constraints.
drop_ineq_con_priority 1 Priority used when dropping inequality constraints.

Reals (real_t, double)

Option Default Description
termination_tolerance 5.0e6 * EPS (~1.1e-9) Relative tolerance that stops the homotopy. Smaller = more accurate, more work.
bound_tolerance 1.0e6 * EPS Bound tolerance; a constraint whose bounds differ by less is treated as an equality.
bound_relaxation 1.0e4 Offset for relaxing bounds at the start of the initial homotopy (also the initial far-bound value).
eps_num -1.0e3 * EPS Numerator tolerance for the ratio test.
eps_den 1.0e3 * EPS Denominator tolerance for the ratio test.
max_primal_jump 1.0e8 Max allowed primal jump in nonzero-curvature tests.
max_dual_jump 1.0e8 Max allowed dual jump in LI tests.
initial_ramping 0.5 Start value of the ramping strategy.
final_ramping 1.0 Final value of the ramping strategy.
initial_far_bounds 1.0e6 Initial size of the far bounds.
grow_far_bounds 1.0e3 Growth factor applied to the far bounds.
eps_flipping 1.0e3 * EPS Tolerance of the squared Cholesky diagonal factor that triggers flipping a bound.
eps_regularisation 1.0e3 * EPS Scaling factor of the identity matrix used for Hessian regularisation.
eps_iter_ref 1.0e2 * EPS Early-termination tolerance for iterative refinement.
eps_li_tests 1.0e5 * EPS Tolerance for the linear-independence tests.
eps_nzc_tests 3.0e3 * EPS Tolerance for the nonzero-curvature tests.
rcond_s_min 1.0e-14 Min reciprocal condition number of the Schur complement before a refactorisation is triggered.

Status / print enums

Option Default Type Description
print_level PL_LOW PrintLevel Verbosity of qpOASES output (PL_NONE, PL_LOW, PL_MEDIUM, PL_HIGH, PL_TABULAR, PL_DEBUG_ITER). Defaults to PL_LOW so the solver stays quiet (qpOASES' own default is PL_MEDIUM).
initial_status_bounds ST_LOWER SubjectToStatus Status assumed for all bounds at the first iteration.

Print levels (PrintLevel)

PL_DEBUG_ITER, PL_TABULAR, PL_NONE, PL_LOW, PL_MEDIUM, PL_HIGH.

Bound/constraint statuses (SubjectToStatus)

ST_LOWER, ST_INACTIVE, ST_UPPER, ST_INFEASIBLE_LOWER, ST_INFEASIBLE_UPPER, ST_UNDEFINED.

Examples

  • marinholab/solvers/qpoases/example.py — positive-definite and semi-definite solves, the None-constraint path, and the active set. Run it with qpoases_example (installed as a console script).
  • marinholab/solvers/qpoases/example_kinematics.py — an optional example showing the solver used in a hierarchical (task-priority) controller for a kinematically redundant robot, built on dqrobotics. It requires the optional dependencies dqrobotics and dqrobotics-pyplot (pip install --pre dqrobotics dqrobotics-pyplot).

Building from source

The package builds a C++ extension (via CMake + pybind11) and vendors qpOASES and pybind11 as git submodules.

git clone --recurse-submodules <repo>
pip install .

Prerequisites: a C++23 compiler, CMake, an Eigen3 installation, and Python. On Ubuntu: sudo apt-get install cmake libeigen3-dev.

Type checking

The package ships a type stub (marinholab/solvers/qpoases/_core.pyi) and a py.typed marker, so downstream projects can be checked with Pyright (or Pylance) without extra configuration. Run the project's own check with:

pyright

License

The qpOASES library is LGPLv2.1; the wrapper is under the terms of the included LICENSE file.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (26.4.0.39)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author/Maintainer: Murilo M. Marinho

Requires

Python >=3.9

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-win_amd64.whl (249.4 kB view details)

Uploaded CPython 3.13Windows x86-64

marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-manylinux2014_aarch64.whl (294.1 kB view details)

Uploaded CPython 3.13

marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-macosx_26_0_universal2.whl (264.4 kB view details)

Uploaded CPython 3.13macOS 26.0+ universal2 (ARM64, x86-64)

marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-win_amd64.whl (249.3 kB view details)

Uploaded CPython 3.12Windows x86-64

marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-manylinux2014_aarch64.whl (293.8 kB view details)

Uploaded CPython 3.12

marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-macosx_26_0_universal2.whl (264.3 kB view details)

Uploaded CPython 3.12macOS 26.0+ universal2 (ARM64, x86-64)

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c040ea7353111080cefb4f2f49f1426a4eb579cd5ff9f05fbd5eb27dc2c755f2
MD5 bb36d4a328e88abb8dd0bc874777b3c7
BLAKE2b-256 640951e6db5d0b4a0766fc90e4cfc8986d1bacc55debba443b4fb6aa85646d87

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-win_amd64.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 84b5e9662261ec7e2642ca627b07c25da56d30ca2c378a9c7b1fae2838a1c0d5
MD5 1e498930105b4ec92fd45d1b66407925
BLAKE2b-256 88196f3c498e8aa0ecbe5eb71db3b7a51c4167c6195b4b2919975df22c2abf19

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-manylinux2014_aarch64.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-macosx_26_0_universal2.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-macosx_26_0_universal2.whl
Algorithm Hash digest
SHA256 41b7243542ee6f8b85fa629a6abdc817dafc07cde36fc3d86219b1e61431507c
MD5 b08c95dc8a323dbbf968f6f383931c69
BLAKE2b-256 10857c5c857b3a900090738800eb09e027cc3481d90309a09a25454032c36db3

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp313-cp313-macosx_26_0_universal2.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 c987242827f0285d1302931c54cddd5b2dab6b449ae0d29f551988323080007c
MD5 cf1b54566b3b99f4167374bbb2c1076f
BLAKE2b-256 89894c92e02edb36a4802798b19e4b4f1b323bb2ad39f9d58ed0bb10bd56e5ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-win_amd64.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2f45f1c49b76b6d4124e586c36d789f17faab24c2b722e85995faa8ce72d8fd8
MD5 629c0419dfe6e076b672869d3c5d67b1
BLAKE2b-256 d90ab5fa1142d6dff93e10ef6f47af02c751706d4f2597c9469c9ecd245f9f83

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-manylinux2014_aarch64.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-macosx_26_0_universal2.whl.

File metadata

File hashes

Hashes for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-macosx_26_0_universal2.whl
Algorithm Hash digest
SHA256 894567e318a95f56ec08ba5e633a584ffe6c045f00864f4ccf2478517ac08610
MD5 6cb54f5a53c5b336247a61915935a9be
BLAKE2b-256 7555a6d168f3a186030d4e3b50199ecf2a7fa8d2308adb1e5783a0660324a296

See more details on using hashes here.

Provenance

The following attestation bundles were made for marinholab_solvers_qpoases-26.4.0.37-cp312-cp312-macosx_26_0_universal2.whl:

Publisher: python-publish.yml on MarinhoLab/solver-qpoases

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

26.4.0.39

15 files

26.4.0.38

12 files

This release

26.4.0.37 This release

6 files

26.4.0.36

6 files

26.4.0.35

6 files

26.4.0.34

6 files

26.4.0.31

4 files

26.4.0.30

4 files

26.4.0.29

4 files

26.4.0.28

4 files

26.4.0.27

4 files

26.4.0.26

4 files

26.4.0.25

4 files

26.4.0.24

4 files

26.4.0.23

4 files

26.4.0.22

4 files

26.4.0.21

4 files

26.4.0.19

4 files

26.4.0.18

4 files

26.4.0.16

4 files

26.4.0.15

4 files

26.4.0.14

4 files

26.4.0.13

2 files

26.4.0.12

1 file

26.4.0.11

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page