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, and every part of the assembly that has to know where a quantity sits in the state vector - the obstacle constraints included - reads it from the model’s declared planar mapping rather than from a fixed layout.

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. doc/migration.md records what changed on the released surface since 1.0.0.

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/BicycleFrontAxle, prox_mpc_core/BicycleRearAxle and prox_mpc_core/Unicycle, with prox_mpc_core/Bicycle kept as a deprecated alias for the front-axle model. 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 that does not enable obstacle avoidance requires no change to this library; see Overview for the state-layout precondition on a model that does.

Every model enables obstacle avoidance; they differ in their toTwist mapping, because a bicycle’s second control is a steering rate and the yaw rate follows from the current steering state, while the unicycle’s control is already a body twist and uses the base identity mapping. Each model also declares its state and control layout, its reference point and its wheelbase through getPlanarMapping(), so a consumer reads them rather than assuming a layout. 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

File truncated at 100 lines see the full file

Changelog for package prox_mpc_core

2.0.0 (2026-09-13)

• Breaking: warm_start defaults to true. The ProxQP workspace is built once and updated in place, so the factorization and the previous primal/dual iterate carry over between cycles instead of being rebuilt every solve. Set it false to restore the previous behavior.
• Breaking: max_iter_sqp defaults to 1, making the real-time iteration scheme unconditional and per-cycle latency bounded by a single QP. The previous default of 100 could spend 99 further linearizations around a corrupted iterate after a failed solve.
• The horizon shift no longer overwrites the warm start's first control with the control already executed, which had left it violating its own control-rate chain on every cycle.
• Models declare their planar mapping and, where they have one, their steering-rate control; the keep-out rows are indexed by that mapping rather than by assumed state columns. The bicycle is split by reference point.
• Transactional solve entry point: a candidate is retained only once the caller's acceptance gates pass.
• Coupled obstacle linearisation completed and the CBF constraint assembly hardened; the inert first-node obstacle gradient is no longer built.
• Configuration-time validation across MPC and Model: horizon setters, dt/T, setMaxObs, setCbfGamma, inequality bound indices, and the rear-axle steering bound are all checked, and structural setters are rejected after init().
• Contributors: Simone Contorno

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