Skip to content

README.md

Latest commit

 

History

History
57 lines (46 loc) · 2.37 KB

README.md

File metadata and controls

57 lines (46 loc) · 2.37 KB

MPPI4Rob — Minimal MPPI controller demo

Lightweight, easy-to-read MPPI (Model Predictive Path Integral) controller implemented with PyTorch. This repository aims to be a compact starting point for experimenting with MPPI and small robotics examples.

Key features

  • Numerical stability improvements (log-space weight computation).
  • Exploration control: adaptive temperature (entropy-based) and noise annealing (cosine decay).
  • Optional residual-MPPI mode: MPPI can optimize a residual action on top of a user-provided baseline policy.
  • Minimal, well-separated interfaces for dynamics, cost, baseline policy and observation functions.

Dependencies

Install the runtime dependencies (CPU or GPU builds of PyTorch as needed):

pip install torch numpy matplotlib gymnasium

Examples

Two compact examples are included under examples/:

  • examples/pendulum_example.py

    • Basic MPPI controlling the OpenAI Gym Pendulum-v1 environment.
    • Usage: 
       python3 examples/pendulum_example.py

  • examples/pendulum_residual_example.py

    • Demonstrates residual MPPI: a simple PD baseline policy is wrapped as a BaselinePolicy and MPPI optimizes a residual action around it.
    • The script accepts a --mode argument to choose what action the controller returns:
      • --mode combined (or omit --mode): baseline + residual (full action) — default when residuals are enabled.
      • --mode residual: MPPI returns residual-only (you can add baseline yourself before sending to the env).
      • --mode baseline: run the baseline controller only (no MPPI sampling).
    • Usage examples: 
       # baseline + residual (default)
 python3 examples/pendulum_residual_example.py --mode combined

 # baseline-only
 python3 examples/pendulum_residual_example.py --mode baseline

 # residual-only
 python3 examples/pendulum_residual_example.py --mode residual

Usage notes

  • The canonical controller implementation is controllers/mppi_controller.py.
  • To run the examples you must have the dependencies installed (see above). If running on a headless server you can disable rendering with the --render flag omitted (or in pendulum_example.py pass --headless if added).

License & contribution

This project is intentionally small and permissive. Feel free to open issues or PRs to add small examples or improvements.