Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ build/
dist/
*.egg-info/
*.so
.deb-out/
obj-*/

# Python caches
__pycache__/
Expand Down
3 changes: 3 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@
path = pybind11
url = https://github.com/pybind/pybind11.git
branch = v3.0
[submodule "qdldl"]
path = qdldl
url = https://github.com/osqp/qdldl.git
112 changes: 96 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,28 @@ first-order ADMM solver for quadratic programs.
marinholab/solvers/osqp/
__init__.py Public API re-exports (Solver, Configuration, Info, enums)
solver.py numpy-friendly Solver wrapper (accepts None constraints, warm-starts)
_options.py Pure-Python IntEnum types (LinsysSolverType,
PreconditionerType, Status) that mirror the OSQP
enums accepted by Configuration.set()
example.py runnable example (console script: osqp_example)
example_kinematics.py OPTIONAL example (needs dqrobotics + dqrobotics-pyplot)
_core.pyi type stub for the compiled _core extension (ships in the wheel)
py.typed PEP 561 marker so stubs are picked up by type checkers
include/marinholab/solvers/osqp.h C++ header (Solver + Configuration + Info): `marinholab::solvers::osqp::Solver` + `Configuration` (doxygen-documented)
src/core.cpp pybind11 module (_core): binds `Solver` + `Configuration` + `Info` + enums
src/core_function.cpp C++ implementation (wraps OSQP's OSQPSolver); compiled into the `marinholab_osqp` static library
CMakeLists.txt CMake build: `marinholab_osqp` static lib, `_core` pybind11 module, optional C++ example (`-DBUILD_EXAMPLES=ON`)
include/marinholab/solvers/osqp.h C++ header (Solver + Configuration + Info) — OSQP-free (pimpl Solver; Configuration keyed by name with typed `OptionValue`s)
src/core.cpp pybind11 module (_core): binds `Solver` + `Configuration` (set/get/has/keys/defaults/reset) + `Info` with native Python values
src/core_function.cpp C++ implementation (wraps OSQP's OSQPSolver via pimpl); option name->kind map; compiled into the `marinholab_osqp` library (shared by default, `-DBUILD_SHARED_LIBS=OFF` for static)
CMakeLists.txt CMake build: `marinholab_osqp` lib (shared by default), `_core` pybind11 module (`-DBUILD_PYTHON=ON`), optional C++ example (`-DBUILD_EXAMPLES=ON`). The vendored OSQP is always built **static** (its linear-solver, qdldl, embedded via the `qdldl` submodule) and linked **PRIVATE** into `marinholab_osqp`; consumers only link `marinholab::solvers::osqp`.
example/example.cpp standalone C++ usage example (target: `example_osqp`)
tests/test_solver.py pytest tests for `Solver` + `Configuration` (see "Tests")
cmake/GetVersion.cmake rolling version (YY.MM.NN) computed at configure time
cmake/marinholab_solver_osqp-config.cmake.in CMake package config (find_package consumers)
debian/ Debian packaging for the C++ part (libmarinholab-solver-osqp)
tools/version.sh compute the rolling version (YY.MM.NN)
tools/bump-changelog.sh bring debian/changelog in line with the rolling version
docker/build-deb.sh build the .deb (optionally + test it) in an Ubuntu noble container
docker/deb.Dockerfile Dockerfile for the .deb build
osqp/ OSQP (git submodule)
qdldl/ qdldl linear-solver (git submodule, used by OSQP's built-in algebra)
pybind11/ pybind11 (git submodule)
setup.py PEP 517 build (CMake + pybind11)
pyrightconfig.json Pyright configuration (python 3.9, mode basic)
Expand Down Expand Up @@ -63,9 +75,27 @@ built only when `BUILD_EXAMPLES=ON`; it is *not* built by `pip install .`:
```console
cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=ON
cmake --build build --target example_osqp
./build/example/example_osqp # prints x ≈ [0.2, 1.0] and the residuals
./build/example_osqp # prints x ≈ [0.2, 1.0] and the residuals
```

## Tests

```console
pip install pytest
cd tests && python -m pytest
```

Run pytest from inside `tests/`, not from the repository root. From the root,
the source `marinholab/` directory (which has no compiled `_core`) shadows the
installed package. CI runs the tests in the Docker job (`docker/compose.yml`)
before `osqp_example`.

`tests/test_solver.py` checks that one `Solver` instance gives the same
answers as a fresh one when the number of variables or constraints changes
between calls (with `use_hotstart` on and off), that the name-keyed
`Configuration` converts values to each option's kind (and rejects the wrong
kind), and that `Configuration.defaults()` matches OSQP's own defaults.

## Type checking (Pyright)

```console
Expand All @@ -90,23 +120,38 @@ Configuration lives in `pyrightconfig.json` (`pythonVersion` 3.9,

- **Defaults match OSQP.** `Configuration` defaults mirror OSQP's own
`osqp_set_default_settings()` for a standard double-precision, direct-solver
build (see the defaults tables in `README.md`), with one documented
exception: `verbose` defaults to `0` (quiet) instead of OSQP's own
`OSQP_VERBOSE = 1`. Do not silently override them here; if a particular
problem needs a non-default option, set it on the `Configuration` in the
*caller* (e.g. `example.py` tightens `eps_abs`/`eps_rel` and raises
build (see `detail::default_values` in `src/core_function.cpp`), with one
documented exception: `verbose` defaults to `false` (quiet) instead of
OSQP's own `OSQP_VERBOSE = 1`. Do not silently override them here; if a
particular problem needs a non-default option, set it on the `Configuration`
in the *caller* (e.g. `example.py` tightens `eps_abs`/`eps_rel` and raises
`max_iter`). Re-validate the `example.py` and `example_kinematics.py` solves
after any change to a default.
- **Option values are typed, never round-tripped through text.**
`Configuration` stores `OptionValue = std::variant<bool, long long, double,
std::string>`, converted to the option's kind in `set()`
(`detail::normalize`). Defaults come straight from OSQP's `OSQPSettings`
(`detail::default_values`), and `settings_from()` starts from OSQP's
`osqp_set_default_settings()`, applies the quieter `verbose`, then only the
options that were set. Enum options hold the enum value name (e.g.
`OSQP_DIRECT_SOLVER`, `OSQP_DIAGONAL_PRECONDITIONER`).
- **`Configuration` keyed by name.** Options are set by name
(`set(key, value)`); the C++ public header exposes no OSQP types (OSQP is
reached only through the pimpl in `src/core_function.cpp`), so enumeration
values are held by name. The OSQP option keys keep the library's native
snake_case spelling (e.g. `eps_abs`, `max_iter`, `warm_starting`); the
wrapper-specific key that has no OSQP counterpart is also snake_case
(`use_hotstart`). Enum options take the enum value name or, in Python, an
enum member; `set()` also converts strings for the other kinds (`"1e-9"`,
`"false"`). The option name->kind map (`detail::option_kinds`) and the
pure-Python enums in `_options.py` must stay in sync with the
`Configuration` options.
- **`Solver` API.** `Solver.solve_quadratic_program()` accepts `None` for
`A`/`b`/`Aeq`/`beq` (in the Python wrapper, which substitutes a single
trivially-satisfied zero row; the C++ `Solver` always takes all six
matrices) and optional `x0`/`y0` warm-starts. `Solver.get_info()` returns
`obj_val`, `dual_obj_val`, `prim_res`, `dual_res`, and the `dual_solution`.
- **Style.** Match the existing style: docstrings on the public API.
`Configuration` fields that map to OSQP `OSQPSettings` fields keep the
library's native snake_case spelling (e.g. `eps_abs`, `max_iter`,
`warm_starting`); the wrapper-specific field that has no OSQP counterpart is
also snake_case (`use_hotstart`).
- **Doxygen.** C++ types and members are documented with Doxygen
(`/** ... @brief ... @param ... @return ... @see ... */` blocks). Keep that
when adding fields or methods.
Expand All @@ -121,10 +166,45 @@ Configuration lives in `pyrightconfig.json` (`pythonVersion` 3.9,
`ubuntu-24.04-arm` for Python 3.12 and 3.13 and publishes to PyPI. Local
builds here mirror that (aarch64, Python 3.13).

## Debian build (libmarinholab-solver-osqp)

The `.deb` is **not** built by this repo's CI — it is built by the
SmartArmStack `build_ros2.sh` (SmartArmStack/smart_arm_stack_ROS2), which
clones `main` with submodules, runs `bash tools/bump-changelog.sh` and
`dpkg-buildpackage -us -uc -b` on this `debian/` directory, then `dpkg -i`
installs it. `build_ros2.sh`'s matrix is `ubuntu-24.04` (amd64) +
`ubuntu-24.04-arm` (arm64); the `debian/` packaging is shared, so it must
build on **both** architectures.

```console
bash docker/build-deb.sh # build the .deb -> ./.deb-out/
bash docker/build-deb.sh --test # + install it and build/run a
# find_package consumer inside the container
```

Only the C++ part is packaged (the `marinholab::solvers::osqp` library). The
vendored OSQP (with its linear-solver, qdldl, embedded) is built **static**
and bundled into the same package, so the `.deb` depends only on the C++
runtime (`libc6`, `libgcc-s1`, `libstdc++6`). `debian/rules` appends `-fno-lto`
after the `dpkg-buildflags` defaults: Ubuntu noble enables `-flto=auto`, and
LTO is disabled for reproducibility.

The `.deb` carries `libmarinholab_solver_osqp.so`, the bundled
`libosqpstatic.a`, the OSQP-free public header, the CMake package config
(`find_package(marinholab_solver_osqp)`) and the vendored OSQP/qdldl headers
(which are only needed to build the archive; they are not a consumer-facing
API). The pybind11 Python extension is intentionally NOT part of this
package; it is produced by `pip install .` from the same source tree.

## Version

The version is dynamic (`dynamic = ["version"]` in `pyproject.toml`) via
`setuptools-git-versioning`, computed from the git tag/commit. `setup.py`
The Python wheel version is dynamic (`dynamic = ["version"]` in `pyproject.toml`)
via `setuptools-git-versioning`, computed from the git tag/commit. `setup.py`
computes a date+commit-derived fallback when the git tag isn't available, which
is why locally-built wheels may show a different distribution version — this
is pre-existing and unrelated to code changes.

The C++/Debian version is a rolling `YY.MM.NN` computed at configure time by
`cmake/GetVersion.cmake` (from `tools/version.sh`; it falls back to a
hardcoded version when `tools/` isn't present). `tools/bump-changelog.sh`
keeps `debian/changelog` in line with it before `dpkg-buildpackage`.
122 changes: 98 additions & 24 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5,59 +5,133 @@ if(WIN32)
set(CMAKE_TOOLCHAIN_FILE C:/vcpkg/scripts/buildsystems/vcpkg.cmake)
endif()

project(marinholab_solver_osqp LANGUAGES CXX)
include(cmake/GetVersion.cmake)
project(marinholab_solver_osqp VERSION ${SOLVER_OSQP_VERSION} LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

option(BUILD_EXAMPLES "Build the standalone C++ example (example/)." OFF)
# The pybind11 Python extension is built via `pip install .` / setup.py,
# which passes -DBUILD_PYTHON=ON; the C++-only build (Debian package,
# find_package consumers) leaves it OFF.
option(BUILD_PYTHON "Build the pybind11 Python extension module (_core)." OFF)
# Shared library by default; build a static library with -DBUILD_SHARED_LIBS=OFF.
# The option() establishes the default while still honouring a value that a
# parent project (or the command line) provides.
option(BUILD_SHARED_LIBS "Build the marinholab_osqp shared library" ON)

find_package(Eigen3 REQUIRED)

# https://stackoverflow.com/questions/38296756/what-is-the-idiomatic-way-in-cmake-to-add-the-fpic-compiler-option
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
# CMAKE was not passing BUILD_SHARED_LIBS nicely to the add_subdirectory.
# https://thatonegamedev.com/cpp/cmake/how-to-manage-dependencies-with-cmake/
set(BUILD_SHARED_LIBS FALSE CACHE BOOL "x" FORCE)

# We only need the static library, and none of OSQP's own demos/tests.
# OSQP is always built as a *static* library: its archive is bundled (installed)
# with our package rather than shipped as a separate shared object. The Python
# build additionally links it into the pybind11 module, so our own library must
# be static there as well; the C++-only build lets marinholab_osqp follow
# BUILD_SHARED_LIBS (shared by default).
if(BUILD_PYTHON)
set(BUILD_SHARED_LIBS FALSE CACHE BOOL "x" FORCE)
endif()
# We only need the static library, and none of OSQP's own demos/tests. The
# built-in algebra embeds its own linear-solver (qdldl), so the static archive
# is self-contained (only the C++ runtime and Eigen headers are needed at
# runtime), which is what lets the Debian package bundle it with no extra
# shared-library dependencies.
set(OSQP_BUILD_SHARED_LIB FALSE CACHE BOOL "x" FORCE)
set(OSQP_BUILD_STATIC_LIB TRUE CACHE BOOL "x" FORCE)
set(OSQP_BUILD_DEMO_EXE FALSE CACHE BOOL "x" FORCE)
set(OSQP_BUILD_UNITTESTS FALSE CACHE BOOL "x" FORCE)
# OSQP ships a code-generation tool; we only use its solver, so turn codegen
# off to keep the built and installed tree small.
set(OSQP_CODEGEN FALSE CACHE BOOL "x" FORCE)
# OSQP's built-in algebra pulls in its linear-solver (qdldl) via
# FetchContent. Point that at the vendored submodule so no network access is
# needed at configure time (reproducible, offline-friendly builds).
set(FETCHCONTENT_SOURCE_DIR_QDLDL "${CMAKE_CURRENT_SOURCE_DIR}/qdldl" CACHE STRING "x")
add_subdirectory(osqp)

# Static library with the Solver/Configuration implementation. Both the
# pybind11 module and any standalone C++ consumer link against it, so the C++
# code is compiled exactly once.
add_library(marinholab_osqp STATIC
# The Solver/Configuration implementation. Both the pybind11 module and the
# standalone example link against it, so the C++ code is compiled exactly once.
# Shared by default; static with -DBUILD_SHARED_LIBS=OFF.
add_library(marinholab_osqp
src/core_function.cpp
)
add_library(marinholab::solvers::osqp ALIAS marinholab_osqp)

set_target_properties(marinholab_osqp PROPERTIES
OUTPUT_NAME marinholab_solver_osqp
POSITION_INDEPENDENT_CODE ON
VERSION ${PROJECT_VERSION}
SOVERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}")

target_include_directories(marinholab_osqp
PUBLIC
${PROJECT_SOURCE_DIR}/include
osqp/include/public
)

target_link_libraries(marinholab_osqp PUBLIC Eigen3::Eigen osqpstatic)
# The vendored OSQP is a private implementation detail: its static archive is
# linked into this package, so consumers only ever link the
# marinholab::solvers::osqp target. The public header is OSQP-free, so its
# headers are not even exposed to consumers.
target_link_libraries(marinholab_osqp
PUBLIC Eigen3::Eigen
PRIVATE osqpstatic)

# Build the standalone C++ example (see example/example.cpp).
if (BUILD_EXAMPLES)
add_executable(example_osqp example/example.cpp)
target_link_libraries(example_osqp PRIVATE marinholab_osqp)
set_target_properties(example_osqp PROPERTIES
RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/example)
endif ()

# Python extension.
set(PYBIND11_FINDPYTHON ON)
add_subdirectory(pybind11)
pybind11_add_module(_core MODULE
src/core.cpp
)
# Python extension (built only for `pip install .` / setup.py).
if(BUILD_PYTHON)
set(PYBIND11_FINDPYTHON ON)
add_subdirectory(pybind11)
pybind11_add_module(_core MODULE
src/core.cpp
)
target_link_libraries(_core PRIVATE marinholab_osqp)
# Version is dynamically obtained. See pyproject.toml
# Activating this causes issues with Windows compilation.
# target_compile_definitions(_core PRIVATE VERSION_INFO=${PROJECT_VERSION})
endif()

# ---- Install / CMake package (C++ part only) ----
# Runs only under `cmake --install` (e.g. from the Debian package build); the
# `pip install .` path uses build_ext and never invokes the install rules.
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)

# Values passed to the package config as @PACKAGE_<VAR>@ (see PATH_VARS below).
# Using the actual install dirs keeps the config correct on multiarch Debian
# (libdir = lib/<arch>, includedir = include).
set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR})
set(LIB_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR})

install(TARGETS marinholab_osqp
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

if(BUILD_EXAMPLES)
install(TARGETS example_osqp RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
endif ()

configure_package_config_file(
${CMAKE_CURRENT_SOURCE_DIR}/cmake/marinholab_solver_osqp-config.cmake.in
${CMAKE_CURRENT_BINARY_DIR}/marinholab_solver_osqp-config.cmake
INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/marinholab_solver_osqp
PATH_VARS INCLUDE_INSTALL_DIR LIB_INSTALL_DIR)

write_basic_package_version_file(
${CMAKE_CURRENT_BINARY_DIR}/marinholab_solver_osqp-config-version.cmake
VERSION ${PROJECT_VERSION}
COMPATIBILITY SameMajorVersion)

target_link_libraries(_core PRIVATE marinholab_osqp)
# Version is dynamically obtained. See pyproject.toml
# Activating this causes issues with Windows compilation.
# target_compile_definitions(_core PRIVATE VERSION_INFO=${PROJECT_VERSION})
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/marinholab_solver_osqp-config.cmake
${CMAKE_CURRENT_BINARY_DIR}/marinholab_solver_osqp-config-version.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/marinholab_solver_osqp)
22 changes: 14 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ pybind11 layer over it). It is built with
namespace osqp = marinholab::solvers::osqp;

osqp::Configuration config;
config.eps_abs = 1.0e-9; // the rest keeps its defaults
config.polishing = 1;
config.set("eps_abs", 1.0e-9); // the rest keeps its defaults
config.set("polishing", true);

osqp::Solver solver(config);

Expand Down Expand Up @@ -151,18 +151,24 @@ the pybind11 surface in `src/core.cpp`.
## Configuration

All of OSQP's `OSQPSettings` fields are exposed, plus one wrapper-specific
setting. Create a `Configuration`, tweak the fields you need, and pass it to
the solver:
setting. Options are set by name. Create a `Configuration`, set the options
you need, and pass it to the solver:

```python
config = osqp.Configuration()
config.eps_abs = 1.0e-9 # tighter absolute tolerance
config.eps_rel = 1.0e-9 # tighter relative tolerance
config.max_iter = 20000 # more ADMM iterations
config.polishing = 1 # polish the ADMM solution
config.set("eps_abs", 1.0e-9) # tighter absolute tolerance
config.set("eps_rel", 1.0e-9) # tighter relative tolerance
config.set("max_iter", 20000) # more ADMM iterations
config.set("polishing", True) # polish the ADMM solution
solver = osqp.Solver(config)
```

Values may be given as bool, int, float, or str (enum options take the enum
value name, e.g. `"OSQP_DIRECT_SOLVER"`, or a `LinsysSolverType` member;
`set()` also converts strings such as `"1e-9"` or `"false"`). Unset options
keep OSQP's own defaults. `config.keys()` and `config.defaults()` list the
full option names and their defaults.

The enum types are re-exported for convenience: `osqp.LinsysSolverType`,
`osqp.PreconditionerType`, and `osqp.Status`.

Expand Down
Loading
Loading