prox_mpc_core

The ProxMPC math core: a C++17, library-only nonlinear Model Predictive Control.

The controller solves the nonlinear optimal-control problem with a Sequential Quadratic Programming (SQP) scheme that repeatedly builds and solves a Quadratic Program with the ProxQP solver, using Eigen for linear algebra. The same engine handles linear models for free: with linear dynamics the SQP converges in a single QP solve.

This package contains no ROS node: it is the reusable library that prox_mpc_controller (a Nav2 plugin) and prox_mpc_demo (a self-contained simulation) build on.

Table of Contents

• Overview
• Public API
• Models
• Prerequisites
• Build
• Architecture
• Project Structure
• Testing
• Troubleshooting
• License

Overview

The core owns the SQP/QP assembly, the tracking cost, the state/control/rate constraints, the disc-based obstacle math, and the prox_mpc::Model vehicle interface. It never needs editing to gain a new vehicle model: a model is a pluginlib plugin loaded by name.

See doc/architecture.md for the design overview, doc/nmpc.md for the NMPC/SQP/QP math, and doc/obstacle-avoidance.md for the obstacle constraints.

Public API

Everything lives in the prox_mpc C++ namespace.

Models

A model derives from Model and implements three pure virtual hooks that supply the Euler linearization (updateA, updateB, updatec). Two optional hooks make it loadable and usable generically: configure(params) sets its constants by name after construction, and toTwist(u) maps a control vector to a geometry_msgs/msg/Twist.

Model is a pluginlib base type, and the bundled models are registered as prox_mpc_core/Bicycle and prox_mpc_core/Unicycle. A consumer can load a model by name with a pluginlib::ClassLoader<prox_mpc::Model> and pass it to MPC::init, so adding a model requires no change to this library.

Both models enable obstacle avoidance; they differ in their toTwist mapping, because the bicycle’s second control is a steering rate and derives the yaw rate from the current steering state as omega = v*sin(delta)/L, while the unicycle’s control is already a body twist and uses the base identity mapping. Both are exported to pluginlib via prox_mpc_core_plugins.xml.

Prerequisites

• ROS 2 Jazzy on Ubuntu 24.04 (the code uses only standard ROS 2 APIs).
• Eigen 3: sudo apt install libeigen3-dev.
• ProxQP / proxsuite: the canonical reproducible provisioning is the apt package ros-jazzy-proxsuite (version >= 0.6.5); the proxsuite install guide is the upstream alternative.
• pluginlib, geometry_msgs, nav_msgs, rclcpp, resolved by rosdep.

ROS dependencies mirror the <depend> entries in package.xml and are resolved automatically by rosdep install.

Build

Build in a dedicated overlay workspace, never inside the package source tree.

cd ~/ros2_ws
source /opt/ros/jazzy/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install --packages-select prox_mpc_core
source install/setup.bash

The core builds Release by default to keep the SQP/QP hot path optimized, and defines EIGEN_NO_DEBUG to drop Eigen’s internal assertions.

Architecture

Model, MPC, and ProxQP compose the plain-data structs by inheritance. Model describes one vehicle; MPC owns the SQP loop and a ProxQP; ProxQP assembles and solves a single QP sub-problem.

File truncated at 100 lines see the full file

Changelog for package prox_mpc_core

1.0.0 (2026-07-28)

• Initial release: NMPC core solved by a Sequential Quadratic Programming scheme over the ProxQP solver, with a pluginlib prox_mpc::Model base and bundled Bicycle / Unicycle models.
• Linearized signed-distance obstacle half-planes with a discrete-time CBF coupling and bounded per-node slot capacity.
• Optional wall-clock budget for the SQP loop (fail-safe on overrun).
• Contributors: Simone Contorno