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.

Installation

Python (PyPI)

pip install marinholab-solvers-qpoases

C++ (Ubuntu .deb from the SmartArmStack PPA)

The C++ part (marinholab::solvers::qpoases, with qpOASES bundled) is distributed as the libmarinholab-solver-qpoases .deb from the SmartArmStack APT repository hosted at smartarmstack.github.io. On Ubuntu (Noble/24.04), add it and install:

sudo apt-get install -y --no-install-recommends curl ca-certificates gnupg
curl -s --compressed "https://smartarmstack.github.io/smart_arm_stack_ROS2/KEY.gpg" \
    | gpg --dearmor \
    | sudo tee /etc/apt/trusted.gpg.d/smartarmstack_lgpl.gpg >/dev/null
curl -s --compressed "https://smartarmstack.github.io/smart_arm_stack_ROS2/smartarmstack_lgpl.list" \
    | sudo tee /etc/apt/sources.list.d/smartarmstack_lgpl.list >/dev/null
sudo apt-get update
sudo apt-get install -y libmarinholab-solver-qpoases

curl, ca-certificates and gnupg are installed first because a bare Ubuntu (and every ubuntu: Docker image) ships without them: gpg is what dearmors the signing key -- apt cannot read the armored KEY.gpg directly -- and sudo is absent from containers, where the commands should instead be run as root without the sudo prefix.

This is the same repository the SmartArmStack ROS2 packages come from; see smartarmstack.github.io for the full list of available packages.

Building against it needs the toolchain and Eigen (the public header exposes Eigen types in its API):

sudo apt-get install -y --no-install-recommends build-essential cmake libeigen3-dev

Then, in your CMakeLists.txt:

find_package(marinholab_solver_qpoases REQUIRED)
target_link_libraries(your_target PRIVATE marinholab::solvers::qpoases)

The package links nothing but libc/libstdc++/libm at run time -- qpOASES is bundled statically -- so it does not need to be able to find_package(qpOASES).

docker/consumer/ is a small working project that does exactly this and checks the numbers it gets back. bash docker/test-ppa.sh builds it in a clean container against the published package, and bash docker/build-deb.sh --test does the same against a locally built .deb.

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]

C++ API

The same solver is available directly in C++ (the Python wrapper is a thin pybind11 layer over it). It is built with Eigen and qpOASES:

#include <marinholab/solvers/qpoases.h>

namespace qpoases = marinholab::solvers::qpoases;

qpoases::Configuration config;
config.set("terminationTolerance", 1.0e-9);  // the rest keeps its defaults

qpoases::Solver solver(config);

Eigen::MatrixXd H = Eigen::MatrixXd::Identity(2, 2);
Eigen::VectorXd f(2);
f << -1.0, -1.0;

Eigen::MatrixXd A(1, 2);
A << 1.0, 0.0;                            // x[0] <= 0.2
Eigen::VectorXd b(1);
b << 0.2;

Eigen::MatrixXd Aeq = Eigen::MatrixXd::Zero(1, 2);
Eigen::VectorXd beq = Eigen::VectorXd::Zero(1);

Eigen::VectorXd x = solver.solve_quadratic_program(H, f, A, b, Aeq, beq);
// x ≈ [0.2, 1.0]

Eigen::VectorXd active_set = solver.get_active_set();  // e.g. [1, 0]

The API mirrors the Python one: solve_quadratic_program(H, f, A, b, Aeq, beq) solves the QP above, and get_active_set() reports the active constraints with the same -1 / 0 / +1 convention. Configuration is keyed by option name (see below); a runnable version lives in example/example.cpp.

To build and run it (the example is off by default so pip install . is unaffected):

cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=ON
cmake --build build
./build/example_qpoases

Configuration

All of qpOASES' Options fields are exposed, plus a few wrapper-specific settings, by name. Values are typed: bool, int, float, or, for enum options, the enum value name (e.g. "HST_SEMIDEF", "PL_NONE"), so the public API (and the C++ header, where values are a std::variant<bool, long long, double, std::string>) stays free of qpOASES types. Unset options use qpOASES' own double-precision defaults except printLevel ("PL_NONE").

config = qpoases.Configuration()
config.set("hessian_type", qpoases.HessianType.HST_SEMIDEF)  # H is rank-deficient
config.set("terminationTolerance", 1.0e-9)                   # tighter convergence
solver = qpoases.Solver(config)

set() accepts a bool, an int, a float, an enum member (used by its name), or a string, converted to the option's kind: config.set("terminationTolerance", "1.0e-9") also works, and an int is accepted for a real option. The other accessors are:

Setting an unknown key, or a value that does not convert to the option's kind (e.g. 1.5 for an integer option or True for a real one), raises ValueError.

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

Wrapper-specific options

Hessian definiteness (HessianType)

qpOASES options

These map 1:1 onto qpOASES' Options fields. Defaults match qpOASES' own defaults for a double-precision build (see Options::setToDefault()), except printLevel, which defaults to the least verbose level (PL_NONE). See the qpOASES manual for a full description of each option.

Booleans (set as "true" / "false")

Integers (int_t)

Reals (real_t, double)

Status / print enums

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

• example/example.cpp — a standalone C++ usage of marinholab::solvers::qpoases::Solver. Build it with cmake -B build -GNinja -DBUILD_EXAMPLES=ON && cmake --build build, then run ./build/example_qpoases.
• 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.