Skip to content
Projects

kohonda/mppi_playground

View on GitHub

kohonda/mppi_playground has 238 GitHub stars and 28 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-19 21:41 UTC. Last push 2026-05-15.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Model Predictive Path Integral Control (MPPI) with PyTorch

Machine Learning

README.md

Original

MPPI Playground

A PyTorch implementation of Model Predictive Path Integral Control (MPPI).

Key Features:

  • 🚀 GPU-accelerated parallel computation
  • 🧠 Differentiable implementation in PyTorch
  • ⚙️ Flexible definitions of dynamics and cost functions
  • 🔧 Additional useful features, including automatic temperature tuning and Savitzky–Golay trajectory smoothing
  • 🤖 Example applications

Tested Environment

  • Ubuntu 20.04 or higher
  • [Optional] GPU with NVIDIA Driver (510 or later, tested with 550)
  • uv

Run Examples

To run the example applications, install with additional dependencies:

# Clone repository
git clone https://github.com/kohonda/mppi_playground.git
cd mppi_playground
uv sync --extra example # Install with extra dependencies for examples
# uv run pre-commit install  # (optional) install pre-commit hooks for code formatting
# uv run pre-commit run --all-files  # (optional) format code

Navigation 2D

uv run python example/navigation2d.py

navigation2d

Racing

uv run python example/racing.py

racing

circuit course information (Japan Automotive AI Challenge 2024)

Pendulum

uv run python example/pendulum.py

pendulum

Cartpole

uv run python example/cartpole.py

cartpole

Mountain car

uv run python example/mountaincar.py

mountaincar

Usage in Your Project

Add dependency to your pyproject.toml and uv sync:

dependencies = [
    "pi-mpc"
]

[tool.uv.sources]
pi-mpc = {git = "https://github.com/kohonda/mppi_playground.git"}

Or install via pip:

pip install git+https://github.com/kohonda/mppi_playground
Minimal code example
import torch
from pi_mpc.mppi import MPPI

# Define dynamics function (batch processing: state [N, dim_state], action [N, dim_control])
def dynamics(state: torch.Tensor, action: torch.Tensor) -> torch.Tensor:
    # Example: simple integrator
    next_state = state + action
    return next_state

# Define cost function (batch processing)
def cost_func(state: torch.Tensor, action: torch.Tensor, info: dict) -> torch.Tensor:
    # Example: distance to goal
    goal = torch.tensor([1.0, 1.0], device=state.device)
    return torch.sum((state - goal) ** 2, dim=1)

# Create MPPI controller
controller = MPPI(
    horizon=50,
    num_samples=1000,
    dim_state=2,
    dim_control=2,
    dynamics=dynamics,
    cost_func=cost_func,
    u_min=torch.tensor([-1.0, -1.0]),
    u_max=torch.tensor([1.0, 1.0]),
    sigmas=torch.tensor([0.5, 0.5]),
    lambda_=1.0,
)

# Solve for optimal action sequence
current_state = torch.tensor([0.0, 0.0])
action_seq, state_seq = controller(current_state)
print(f"Optimal first action: {action_seq[0]}")
Configurations

MPPI Parameters

Parameter Type Default Description
horizon int required Prediction horizon length
num_samples int required Number of trajectory samples
dim_state int required State dimension
dim_control int required Control dimension
dynamics Callable required Dynamics model: (state, action) -> next_state
cost_func Callable required Cost function: (state, action, info) -> cost
u_min Tensor required Minimum control bounds, shape (dim_control,)
u_max Tensor required Maximum control bounds, shape (dim_control,)
sigmas Tensor required Noise std for each control dim, shape (dim_control,)
lambda_ float / str required Temperature or auto-tuning method ("MPO", "LBPS", "ESSPS")

Auto-Lambda Parameters

Parameter Type Default Description
lbps_delta float 0.01 Confidence parameter for LBPS (0 < δ < 1)
essps_target_ess float num_samples/10 Target effective sample size for ESSPS
lambda_min float 0.01 Minimum lambda bound for optimization
lambda_max float 10.0 Maximum lambda bound for optimization

Sampling & Filtering Parameters

Parameter Type Default Description
exploration float 0.0 Fraction of purely random samples (0 to 1)
use_sg_filter bool False Enable Savitzky-Golay smoothing
sg_window_size int 5 Window size for SG filter (must be odd)
sg_poly_order int 3 Polynomial order for SG filter

Automatic Temperature Tuning (Auto-Lambda)

The temperature parameter λ is a hyperparameter that controls the exploration-exploitation trade-off. Three auto-tuning methods are available:

# Example: Enable auto-lambda with LBPS
controller = MPPI(..., lambda_="LBPS", lbps_delta=0.01)

Trajectory Smoothing

# Example: Enable smoothing
controller = MPPI(..., use_sg_filter=True, sg_window_size=5, sg_poly_order=3)

Citation

If you use this repo in your work, please cite this paper (https://arxiv.org/abs/2511.08019) as:

@article{honda2026model,
  title={Model Predictive Control via Probabilistic Inference: A tutorial and survey},
  author={Honda, Kohei},
  journal={Annual Reviews in Control},
  volume={61},
  pages={101052},
  year={2026},
  publisher={Elsevier}
}