Quadruped-PyMPC runs the same controller two ways: acados or JAX

One model, two solvers

Quadruped-PyMPC is a model predictive controller built on the single rigid body model and written in Python, and it comes in two flavours. The gradient-based path goes through acados, and the sampling-based path goes through JAX. The controller is tested on real robots and is compatible with MuJoCo. The single rigid body model is the piece that makes the project coherent, because it abstracts the legs away and reasons about the body as one rigid mass, which is what lets the same formulation be handed to a gradient-based solver and to a sampler without rewriting the model. The two backends are not interchangeable in their costs, and the README is honest about that difference in numbers, which is the most useful thing in the document. The last push was on 2026-10-16 and the project version in the packaging metadata is 1.0.0, with the licence BSD-3-Clause.

What the gradient-based path gives you

The acados route is the one with the latency claim, less than 5 milliseconds of computation on an Intel i7-13700H CPU. Its feature list is mostly about handling the gap between the model and reality. There are optional integrators for model mismatch, so the mismatch between the rigid body abstraction and a real legged robot has somewhere to go. There is optional smoothing for the ground reaction forces, which is where a rigid body model gets lumpy in practice. There is optional foothold optimization, so the controller can decide where to put a foot rather than only how to track a velocity. There is optional real-time iteration or the advanced-step variant of it, which lets the solver take a limited number of iterations per cycle instead of converging fully. And there are optional zero moment point and centre of mass constraints, plus optional Lyapunov-based criteria, which is the interesting one for a legged robot because it ties the optimisation to a stability argument rather than only to a tracking cost.

What the sampling-based path gives you

The JAX path moves the parallelism to the GPU, and the headline number is 10000 parallel rollouts in less than 2 milliseconds on an Nvidia 4050 mobile GPU. The strategies implemented are random sampling, MPPI, CEM-MPPI and OT-MPC, so the same sampling machinery can be run with a plain random search or with a cross-entropy method layered on top. The control parameterisations are zero-order, linear splines or cubic splines, following the mujoco-mpc lineage. The optional features are step frequency adaptation for robustness, control refinement through rollout gradient, and high-frequency feedback gains via Feedback-MPPI, which is the piece that closes the gap between a controller running at a low control frequency and a robot that needs fast reflexes. The practical split is that the sampling path wants a GPU and the gradient path does not, which is usually the deciding factor in a lab where the robot's onboard computer has no GPU.

Deployment path and the supported robot list

Real-world deployment rides on two companion projects. For state estimation there is muse, with a unitree_sdk branch referenced, and for unitree robot communication there is unitree-ros2-dls. The supported robots are GO2, A2, B2, GO1, Aliengo, Spot, Mini-Cheetah, HyqReal1 and HyqReal2, which is a wide list spanning Unitree's own hardware, Boston Dynamics' Spot, and the HyQ line from the IIT group that maintains the project. The animations at the top of the README show the Aliengo trotting, the HyqReal pacing and the GO2 bounding, which is a reasonable indication that the controller is not confined to one gait on one machine. Note the list is what the README names, and the maintainers are Giulio Turrisi and Daniel Ordonez.

The pixi environment matrix

The project uses pixi for its dependency management, and the pyproject shows how carefully the environments are separated. The workspace is named quadruped_pympc_env, the channels are conda-forge and nvidia, the platform is linux-64, and pixi itself is required at 0.63.0 or newer. The base dependencies include casadi, numpy, scipy, pinocchio, meshcat-python, matplotlib, gymnasium, cmake, ninja, compilers and colcon-common-extensions, and the pypi dependencies include the project itself as editable, adam-robotics with all extras, mujoco, readchar, liecasadi and gym-quadruped. JAX comes from PyPI in the no-cuda feature, with a comment explaining that the wheels bundle their own protobuf so they do not clash with the libprotobuf pinned by robostack, where conda-forge jaxlib lags behind. The cuda feature pins system requirement cuda 12 and installs jax with the cuda12 extra. ROS 2 is handled as features too, with a humble feature and a lyrical feature pulling from separate robostack channels, and the default environment is common, no-cuda and humble.

Where the setup work sits

The README is deliberately short on installation and delegates it to README_install.md, which is linked rather than reproduced. The repository layout shows how the pieces divide. The quadruped_pympc/ directory holds the package itself, simulation/ holds the simulation code, ros2/ holds the ROS 2 side, installation/ holds the installation files, and there is a gifs/ directory with the motion clips. There is also a pixi.lock, which means the environment is fully resolved and reproducible for a given platform, and a .gitmodules file, so some components arrive as submodules rather than being vendored. The two papers the README asks you to cite are the IROS 2024 work on the benefits of GPU sample-based stochastic predictive controllers for legged locomotion, and the 2025 Robotics and Automation Letters paper on adaptive non-linear centroidal MPC with stability guarantees.

Where Quadruped-PyMPC is the wrong choice

Three cases. The first is a team that wants a locomotion policy rather than a controller, because this is a model predictive controller you run in a loop against your own state estimator, not a trained behaviour you load, and the deployment path depends on two companion projects that you have to integrate and own. The second is a robot outside the supported list, where the abstraction still applies but the model parameters, the leg configuration and the communication layer all become your problem, and the sampling path's parameterisation choices and the gradient path's integrators are tuned around the listed platforms. The third is a project that needs one controller rather than two choices, because maintaining an acados path and a JAX path means two solver stacks, two performance profiles and two places where a bug can hide, and the README's structure, with the two feature lists kept separate, reflects that they have diverged. Against running an existing controller such as the one in the robot vendor's stack, the difference in approach is that the single rigid body model with a centroidal formulation is the design centre, so the leg dynamics are approximated and the contact handling is centralised in the contact forces rather than in the joint model.

Editorial conclusion

Quadruped-PyMPC is a good fit for a robotics lab that wants one controller codebase across simulation and hardware, or that wants to compare a gradient-based solver with a sampling-based one on the same model, since the shared single rigid body formulation is what makes the comparison meaningful. It is a poor fit for a team that needs a turnkey policy, since this is a controller you run, not a behaviour you load, and it is a poor fit if your robot is not on the supported list. Check three things before you start: that your machine is in the supported set, which covers GO2, A2, B2, GO1, Aliengo, Spot, Mini-Cheetah, HyqReal1 and HyqReal2, that you can choose the pixi environment that matches your ROS 2 distribution, since the default environment is common, no-cuda and humble and there are separate lyrical and cuda features, and that you read the installation document, because the README defers all setup to README_install.md and the repository ships separate installation/, simulation/ and ros2/ directories that suggest how much of the setup is yours to do.

Frequently asked questions

Official sources

1. iit-DLSLab/Quadruped-PyMPC on GitHub
2. Issues
3. License: BSD-3-Clause
4. README