python_simple_mppi

用 numpy 推导并实现 MPPI 控制，配四个完整示例

许可证

MIT

概述

模型预测路径积分（MPPI）控制会随机采样成千上万条输入序列，让每一条都在动力学模型中向前推演、打分，再按信息论权重把它们融合成一条指令。现代采样式控制有相当一部分就建立在这个方法上，而人们通常要么在一页公式里遇见它，要么在某个把算法深埋其中的生产级框架里遇见它。这个仓库补的正是中间那一段：四个完整示例——基于运动学自行车模型的路径跟踪、同一场景加上避障、单摆摆起，以及倒立摆小车——每个都是一份可直接运行的脚本，外加一份 Jupyter 笔记本，用 LaTeX 逐步推导算法，并对应其所引论文 Williams 等人的算法 1 与算法 2。全部依赖只有 numpy、matplotlib 和 notebook。

价值在于「成对」。每个示例都存在两份：一份是你运行起来看仿真的脚本，另一份是笔记本，在那里同一个控制器与支撑它的数学一同被搭建起来——采样输入序列、向前推演动力学、累加阶段代价与终端代价、由信息论导出权重，再把加权后的样本折回成一条指令。一边读一边跑，与单纯读论文是完全不同的体验，而这正是这个仓库存在的意义。作者在描述里说得很直白：这是用来理解基本思想的。

克制是刻意的，也正是它奏效的原因。没有 GPU，没有 JAX，没有 C++ 内核，没有配置系统——只有 numpy 和 matplotlib，只有当你想把动画写成 mp4 时才需要 ffmpeg。安装就是一句 uv sync，或者用 docker compose run，免得动你自己的 Python 环境。读者需要记在脑子里的只有算法本身，这正是目的所在，而整个实现小到可以一口气读完。

它同时也是通往一整片相关工作的入口，而不是一次性的产物。同一位作者是日本产业技术综合研究所（AIST）从事运动规划与控制的研究者，还发布了 mppi_swerve_drive_ros——一个面向全向轮机器人的 MPPI 控制器，发表于 IROS 2024；nullspace_mpc——在 ROS 中处理任务优先级的多目标 MPC 框架；以及 path_tracking_catalog——以同样方式实现的一批路径跟踪算法。读完这个仓库的人知道下一步去哪里，这一点在多数教学代码上并不成立。

为何重要

本目录收录了人们实际部署的规划器——MuJoCo MPC、OMPL、MoveIt、NeuPAN——却几乎没有能讲清采样式方法如何运作的东西。MPPI 尤其如此：它要么以一篇密集的 2018 年论文出现，要么以一份你能用却读不进去的优化实现出现。而这一份是你能读的版本：小到可以逐行跟下来，推导就在代码旁边，作者其后还在真实机器人上发表了经同行评审的 MPPI 工作。一个教学仓库拿到七百颗星，本身就说明这个空缺有多值得去填。

解决的问题

人们通常要么在一篇信息论论文里遇见 MPPI，要么在某个把算法藏进框架的快速实现里遇见它，而这两者都教不会你它是怎么运作的。这个仓库把算法以你读得下去的体量交给你，推导就在代码旁边，还有四个仿真让你看清每一部分究竟在做什么。

要点

• 四个完整示例：基于运动学自行车模型的路径跟踪、带避障的路径跟踪、单摆摆起，以及倒立摆小车
• 每个示例都提供两份——一份可直接运行的脚本，一份用 LaTeX 在同样的代码旁推导算法的笔记本
• 推导对应 Williams 等人《信息论模型预测控制》中的算法 1 与算法 2，因此笔记本与论文可以对照着读
• 依赖只有 numpy、matplotlib 和 notebook——跑通其中任何一部分都不需要别的东西
• 原生环境用 uv sync，容器环境用 docker compose run；只有想输出 mp4 时才需要 ffmpeg
• MIT 许可，作者是 AIST 的研究者，其后在 IROS 2024 发表了 MPPI 相关工作
• 避障示例把算法可视化了：采样轨迹的扇形，以及从中穿过的加权指令

适用人群

• 第一次接触 MPPI、想弄懂它而不只是调用它的人
• 寻找带完整数学推导的最优控制教学范例的学生与教师
• 打算原型化一个采样式控制器、希望在优化之前先有一个正确且可读起点的研究者
• 在评估 MPPI 是否适合自己问题、需要先看它在车辆模型上表现的工程师

局限

• 这在设计上就是教学代码——作者自己的说法是「用来理解基本思想」，并非为部署或实时性保证而构建
• 纯 numpy、跑在 CPU 上，因此采样数与预测时域都远低于实际部署的 MPPI 控制器
• 示例都是二维玩具动力学：没有接触、没有三维、没有传感器模型，也没有硬件接口
• 最后一次推送在 2026 年 5 月，还留着几个开启的 issue；它更像是「已完成」而非「在活跃开发」，这对参考实现是合适的，但别指望会有修复
• 两位贡献者，实际上只有一位——这个仓库的存续取决于作者的时间
• 是脚本与笔记本，而不是可导入的库，因此复用意味着把代码抄出来
• GitHub 把许可显示为无法识别，是因为文件名是 LICENSE.txt；文件内容本身是标准 MIT 文本，版权归 2023 年的 MizuhoAOKI