python_simple_mppi: MPPI Sampling Control You Can Read End to End

A controller written to be understood, not to be fast

This repository exists to explain the basic idea of Model Predictive Path-Integral control, and the readme says so directly. MPPI is described as a promising sampling-based optimal control algorithm, citing G. Williams and colleagues from 2018, and the whole project is framed as an implementation for understanding rather than a component to drop into a stack. That intent shows in the shape of the deliverable: three example problems, each with a runnable script and a matching Jupyter notebook that carries the mathematical explanation. The topic tags name the same territory, covering stochastic optimal control, sampling-based planning, nonlinear model predictive control and path tracking. It is a small repository by design, with `scripts/`, `notebooks/`, `data/` and `media/` directories at the root and little else.

Three dependencies and a package manager that reads the project file

The dependency set is deliberately minimal. The project metadata lists exactly three packages, `numpy>=1.25.2`, `matplotlib>=3.7.2` and `notebook>=7.0.2`, and the readme says the same: only numpy, matplotlib and notebook are needed to run all scripts in the repository. The project requires Python 3.10 or newer and builds with hatchling. The package manager is uv, described as a simple and fast Python package manager with a one-command installation, and the repository carries both a `pyproject.toml` and a `.python-version` file, which is what uv reads to pin the interpreter. That combination means the environment is described declaratively in the repository rather than in a setup script, and one command reproduces it.

Two ways to set up: native or inside Docker

The native path is three commands.

git clone https://github.com/MizuhoAOKI/python_simple_mppi.git
cd python_simple_mppi
uv sync

The Docker path exists for people who would rather not configure a Python environment on the host. The compose file defines a single service named dev, built from `docker/Dockerfile` with the repository root mounted into the container, with stdin and a tty left open so you land in a shell.

docker compose run --rm dev

The compose file pins the image name to `dev_mppi:v1.1` and the container to `dev_mppi_container`, and the volume mapping means changes on the host are reflected inside the container and the other way round, which is what makes the Jupyter workflow usable in the container at all. Building the image can take a few minutes. The tool also needs ffmpeg, because the animations are written as mp4 movies, and the readme gives per-platform installation commands for it.

Path tracking, and the same problem with an obstacle

The path tracking example is the simplest of the three, and the repository ships a rendered demo of it. The simulation script is invoked through uv run from the project directory.

cd python_simple_mppi
uv run scripts/mppi_pathtracking.py

The obstacle avoidance variant is a separate script with its own animation, and it is the more interesting of the two because an obstacle is what forces a controller to replan rather than follow a smooth reference.

cd python_simple_mppi
uv run scripts/mppi_pathtracking_obav.py

For both, the readme suggests opening the matching notebook if you want to check the mathematical explanations of the algorithm, which is the intended workflow: run the script to see the behaviour, then read the notebook to see why it happened.

The notebooks carry the explanation the scripts do not

Every example has a notebook that can be launched with the notebook directory set to the repository root.

cd python_simple_mppi
uv run jupyter notebook --notebook-dir=. notebooks/mppi_pathtracking.ipynb

There is one per example, `notebooks/mppi_pathtracking.ipynb`, `notebooks/mppi_pathtracking_obav.ipynb`, `notebooks/mppi_pendulum.ipynb` and `notebooks/mppi_cartpole.ipynb`, each named after the script it accompanies. The notebook option matters in a subtle way: pointing `--notebook-dir` at the repository root rather than the notebooks folder means the notebook can find the scripts and data it imports by relative path. For a project whose stated purpose is understanding the algorithm, this pairing of runnable simulation and derivation is the actual product, and anyone copying the code should copy the notebook too.

Swinging up a pendulum and balancing a CartPole

The other two examples are the standard sanity checks for a nonlinear controller. The pendulum example swings a pendulum up, which is interesting because the upright configuration is not reachable from rest without energy input, so the controller has to plan through a swing rather than hold a pose.

cd python_simple_mppi
uv run scripts/mppi_pendulum.py

The CartPole example runs the classic balancing task.

cd python_simple_mppi
uv run scripts/mppi_cartpole.py

Both have their notebooks as well. Choosing CartPole and pendulum swing-up alongside a driving scenario is a deliberate spread of dynamics. Path tracking is a kinematic problem with a smooth reference, pendulum swing-up is underactuated and nonlinear, and CartPole is a stiff balancing problem that punishes a sampling controller with too few samples or too little smoothing. A controller that handles all three is a decent sign that the implementation is general rather than tuned to one task.

What a teaching implementation leaves out

The gap between this and a production controller is large, and it is worth naming rather than discovering later. There is no statement anywhere about real-time guarantees, iteration budgets or latency, and the algorithm as implemented samples trajectories, which is the part that scales badly with horizon length and dimension. There is no safety layer, no state estimator for noisy measurements, no actuator saturation handling, and no path to a hardware interface: the demos are simulations writing mp4 files. The repository is not archived and the last push was on 2026-05-04, so it is still being touched, but the single tagged release is v1.0.0 from 2023-11-26, described as the stable version of the three basic examples. The readme also notes the working directory layout includes a `data/` folder, which is where the scenarios and reference paths are held.

Licence, attribution and where the theory comes from

The licence needs a small note, because the repository metadata classifies it as a custom licence GitHub cannot categorise while the readme badge says MIT, and the licence text itself sits in a file named LICENSE.txt. Read that file rather than relying on the badge. The author is MizuhoAOKI, and the single reference given is the paper the whole project is built around: G. Williams and colleagues, Information-Theoretic Model Predictive Control: Theory and Applications to Autonomous Driving, with a link to the IEEE Xplore entry and to a PDF on arXiv. The `media/` directory holds the rendered demo gifs the readme embeds, and the docker directory holds the image definition the compose service builds from.

Editorial conclusion

python_simple_mppi fits someone learning sampling based optimal control, or an engineer who wants to see exactly how a sampling MPC computes its control weights before reaching for a production implementation. It is the wrong choice for a robot or vehicle that needs verified dynamics, safety handling or real-time guarantees, because this is a teaching codebase with no such machinery. Before you build on it, read the notebooks alongside the scripts, since the explanations of the algorithm live there rather than in the source.

Frequently asked questions

Official sources

1. Issues
2. MizuhoAOKI/python_simple_mppi on GitHub
3. README
4. Releases