python_simple_mppi

以 numpy 推導並實作的 MPPI 控制，附四個完整範例

授權條款

MIT

概述

Model Predictive Path-Integral（MPPI）控制會取樣數千條隨機輸入序列，讓每一條透過動力學模型向前推演、加以評分，再以資訊理論的加權方式把它們融合成單一指令。它是許多現代取樣式控制背後的方法，而人們通常不是在一頁方程式中，就是在把演算法埋在內部的量產框架中遇到它。這個儲存庫補上了缺少的中間地帶：四個完整範例，包括使用運動學自行車模型的路徑追蹤、加入避障的同一任務、單擺擺起與倒單擺台車，每個範例都是一個可執行的腳本，搭配一本以 LaTeX 逐步推導演算法的 Jupyter notebook，推導依循其引用的 Williams 等人論文中的演算法 1 與 2。唯一的相依套件是 numpy、matplotlib 與 notebook。

它的價值在於配對。每個範例都有兩份：一份是你執行來觀看模擬的腳本，另一份是 notebook，在其中把同一個控制器與支撐它的數學一起逐步建構起來，包括取樣輸入序列、向前推演動力學、累加階段成本與終端成本、從資訊理論推導權重，以及把加權後的樣本合併回單一指令。一邊執行一個、一邊閱讀另一個，是與閱讀論文截然不同的體驗，而這正是這個儲存庫真正的用途。作者在描述中說得很直白：這是為了理解基本概念。

這種克制是刻意的，也正是它成功的原因。沒有 GPU、沒有 JAX、沒有 C++ 核心、沒有設定系統，只有 numpy 與 matplotlib，只有在你想把動畫輸出成 mp4 時才需要 ffmpeg。設定方式是 uv sync，若不想動到自己的 Python 環境，也可以用 docker compose run。讀者唯一需要記在腦中的就是演算法本身，這正是重點，而整個實作小到可以一口氣讀完。

它也是通往一系列相關工作的入口，而不是一次性的作品。同一位作者是日本 AIST 從事運動規劃與控制的研究人員，已發表了 mppi_swerve_drive_ros，這是一個用於轉向輪驅動機器人的 IROS 2024 MPPI 控制器；nullspace_mpc，一個在 ROS 中處理任務優先順序的多目標 MPC 框架；以及 path_tracking_catalog，一組以相同方式實作的路徑追蹤演算法。讀完這個儲存庫的人還有下一步可走，而多數教學程式碼並非如此。

為何重要

本目錄收錄了人們實際部署的規劃器，例如 MuJoCo MPC、OMPL、MoveIt、NeuPAN，卻幾乎沒有任何解釋取樣式規劃器如何運作的內容。尤其是 MPPI，往往不是以一篇艱深的 2018 年論文出現，就是以一個你能用卻讀不懂的最佳化實作出現。這是一個你讀得懂的版本：小到可以逐行跟上，推導就放在程式碼旁邊，作者之後也在真實機器人上發表了經同儕審查的 MPPI 研究。一個教學儲存庫拿到七百顆星，相當能說明填補這個缺口有多大的價值。

解決的問題

人們通常不是以資訊理論論文、就是以把演算法藏在框架內部的快速實作接觸到 MPPI，而兩者都無法教你它如何運作。這個儲存庫以讀得懂的規模提供演算法，推導就放在程式碼旁邊，並以四個模擬展示其中每個部分的作用。

重點

四個完整範例：使用運動學自行車模型的路徑追蹤、加入避障的路徑追蹤、單擺擺起與倒單擺台車
每個範例都有兩份：一份可執行的腳本，以及一本在同一份程式碼旁以 LaTeX 推導演算法的 notebook
推導依循 Williams 等人〈Information-Theoretic Model Predictive Control〉中的演算法 1 與 2，因此 notebook 與論文可以對照閱讀
相依套件只有 numpy、matplotlib 與 notebook，執行任何部分都不需要其他東西
原生環境使用 uv sync，容器化環境使用 docker compose run；只有在需要 mp4 輸出時才需要 ffmpeg
採用 MIT 授權，作者是 AIST 的研究人員，之後也在 IROS 2024 發表了 MPPI 研究
避障範例讓演算法變得可見：取樣推演軌跡呈扇形展開，加權後的指令從中穿過

適用對象

第一次接觸 MPPI、想理解它而不只是呼叫它的人
尋找附有數學推導之完整範例的最佳控制學生與教師
為取樣式控制器製作原型、希望在最佳化之前有一個正確且易讀之起點的研究人員
評估 MPPI 是否適合自己問題、需要在投入之前先看到它在車輛模型上表現的工程師

限制

這在設計上就是教學程式碼：作者自己的說法是「為了理解基本概念」，它並非為部署或即時性保證而打造
純 numpy 在 CPU 上執行，因此樣本數與預測時域遠低於實際部署的 MPPI 控制器所用的規模
範例都是 2D 的玩具動力學：沒有接觸、沒有 3D、沒有感測器模型，也沒有硬體介面
最後一次推送是在 2026 年 5 月，並有少數未解決的 issue；它是已完成而非積極開發中的專案，這適合參考實作，但也意味著別期待修正
兩位貢獻者，實際上只有一位：這個儲存庫的存續完全取決於作者的時間
它是腳本與 notebook 而非可匯入的函式庫，因此重複使用就得把程式碼複製出來
由於檔案名稱為 LICENSE.txt，GitHub 將其授權顯示為無法辨識；檔案本身是標準的 MIT 文字，版權為 2023 MizuhoAOKI