python_simple_mppi

MPPI control derived and implemented in numpy, with four worked examples

License

MIT

Overview

Model Predictive Path-Integral control samples thousands of random input sequences, rolls each one forward through a dynamics model, scores it, and blends them into one command by an information-theoretic weighting. It is the method behind a good deal of modern sampling-based control, and it is usually met either as a page of equations or as a production framework with the algorithm buried inside. This repository is the missing middle: four worked examples — path tracking with a kinematic bicycle model, the same with obstacle avoidance, a pendulum swing-up and a cartpole — each a runnable script paired with a Jupyter notebook that derives the algorithm step by step in LaTeX, following Algorithms 1 and 2 of the Williams et al. paper it cites. The only dependencies are numpy, matplotlib and notebook.

The value is in the pairing. Each example exists twice: once as a script you run to watch the simulation, and once as a notebook where the same controller is built up alongside the maths that justifies it — sampling the input sequences, rolling the dynamics forward, accumulating stage and terminal costs, deriving the weights from information theory, and folding the weighted samples back into a single command. Reading one while running the other is a different experience from reading a paper, and it is the thing the repository is actually for. The author says so plainly in the description: this is to understand the basic idea.

The restraint is deliberate and it is what makes it work. No GPU, no JAX, no C++ core, no configuration system — numpy and matplotlib, with ffmpeg needed only if you want to write the animation to mp4. Setup is uv sync, or a docker compose run if you would rather not touch your Python environment. Everything a reader has to hold in their head is the algorithm, which is the point, and the whole implementation is small enough to read in a sitting.

It is also the entry point to a body of related work rather than a one-off. The same author, a researcher at Japan's AIST working on motion planning and control, has published mppi_swerve_drive_ros, an IROS 2024 MPPI controller for a swerve-drive robot; nullspace_mpc, a multi-objective MPC framework handling task priorities in ROS; and path_tracking_catalog, a collection of path-tracking algorithms implemented the same way. Someone who works through this repository has somewhere to go next, which is not true of most teaching code.

Why it matters

The catalogue carries the planners people deploy — MuJoCo MPC, OMPL, MoveIt, NeuPAN — and almost nothing that explains how the sampling-based ones work. MPPI in particular tends to arrive either as a dense 2018 paper or as an optimised implementation you can use but not read. This is the version you can read: small enough to follow line by line, with the derivation next to the code, from someone who has since published peer-reviewed MPPI work on real robots. Seven hundred stars for a teaching repository is a fair measure of how much that gap was worth filling.

Problem it solves

MPPI is normally encountered either as an information-theoretic paper or as a fast implementation with the algorithm hidden inside a framework, and neither teaches you how it works. This gives you the algorithm at a size you can read, with the derivation beside the code and four simulations that show what each part of it does.

Key takeaways

• Four worked examples: path tracking with a kinematic bicycle model, path tracking with obstacle avoidance, pendulum swing-up and cartpole
• Every example ships twice — as a runnable script, and as a notebook deriving the algorithm in LaTeX alongside the same code
• The derivation follows Algorithms 1 and 2 of Williams et al., 'Information-Theoretic Model Predictive Control', so the notebook and the paper can be read together
• Dependencies are numpy, matplotlib and notebook — nothing else is needed to run any of it
• uv sync for a native setup, or docker compose run for a containerised one; ffmpeg only if you want mp4 output
• MIT licensed, from a researcher at AIST who has since published MPPI work at IROS 2024
• The obstacle-avoidance example makes the algorithm visible: the fan of sampled rollouts and the weighted command drawn through it

Who it is for

• Anyone meeting MPPI for the first time who wants to understand it rather than call it
• Students and teachers of optimal control looking for a worked example with the maths attached
• Researchers prototyping a sampling-based controller who want a correct, readable starting point before optimising
• Engineers evaluating whether MPPI suits their problem, who need to see its behaviour on a vehicle model before committing

Limitations

• This is teaching code by design — the author's own framing is 'to understand the basic idea', and it is not built for deployment or real-time guarantees
• Pure numpy on the CPU, so the sample counts and horizons are far below what a deployed MPPI controller would use
• The examples are 2D toy dynamics: no contact, no 3D, no sensor models and no hardware interface
• Last pushed in May 2026 and carrying a handful of open issues; it is finished rather than actively developed, which suits a reference implementation but means do not expect fixes
• Two contributors, and effectively one — the repository stands or falls on the author's time
• Scripts and notebooks rather than an importable library, so reusing it means copying code out
• GitHub reports the licence as unrecognised because the file is named LICENSE.txt; the file itself is the standard MIT text, copyright 2023 MizuhoAOKI