neupan
1.NeuPAN（神经近端交替最小化网络）是一种端到端、实时、无需地图且易于部署的基于模型预测控制（MPC）的机器人运动规划器。通过融合基于学习与基于优化的技术，NeuPAN 能够直接将障碍物点云数据映射为实时控制指令，其核心是求解一个包含大量点级碰撞避免约束的端到端数学模型。这种方法省去了传统中间模块的设计，避免了误差累积，从而实现了高精度，使机器人能够在杂乱且未知的环境中高效、安全地导航。、
为什么选择 NeuPAN？
run examples in the example folder to see the navigation performance of diff (differential), acker (ackermann) and omni (Omnidirectional) robot powered by NeuPAN in IR-SIM.
diff (differential) — 差速驱动机器人 ，Ackermann Steering Robot（模仿汽车的转向机制），omni (Omnidirectional) — 全向移动机器人
DUNE Model Training
To train a DUNE model for your own robot with a specific convex geometry, you can refer to the example/dune_train folder. Specifically, the convex geometry is defined in the robot section by the vertices (or length and width for rectangle) when the robot is in the initial state (coordinate origin). The training parameters can be adjusted in the train section.
Note
The DUNE model only needs to be trained once for a new robot geometry. This trained model can be used in various environments without retraining.
DUNE 是一个神经网络，用于从障碍物点云中学习“安全表示”（比如生成障碍势场）。
它的输入是障碍物点，输出会考虑机器人自身的形状（因为碰撞检测依赖于机器人几何）。
如果你有一个非标准形状的机器人（比如矩形、六边形等凸多边形），你需要重新训练 DUNE，让它“理解”这个新形状。
训练脚本和示例放在 example/dune_train/ 目录下。
具体来说，该凸形几何在 robot 配置段中定义：当机器人位于初始状态（坐标原点）时，通过其顶点坐标（或矩形的长宽）来描述。
image.png
训练参数可在 train 配置段中调整。
对于一种新的机器人几何形状，DUNE 模型只需训练一次。该模型可在各种环境中直接使用，无需重新训练。
4.为什么dune_train只有diff和acker？
DUNE 关注“几何”，MPC 关注“运动学”。DUNE 模型与驱动类型（drive type）无关，只与机器人几何形状有关！
DUNE 的任务是：给定障碍物点云 + 机器人几何 → 输出安全表示（用于碰撞避免）
它不关心机器人怎么动（是差速、阿克曼还是全向），只关心“你的身体轮廓是什么样”。
为什么我选择环境比如convex_obs里面分别有三种drivetype的目录，且每个目录都有env和planner的yaml文件？
因为 env.yaml 和 planner.yaml 控制的是运动学、传感器、MPC 行为，这些与驱动类型强相关，必须分开配置。
其中planner.yaml文件中可以服用model目录中训练好的dune模型
我可以在dune_train下写自己的机器人配置，然后训练出来会有自己的机器人的dune模型的pth文件，用来跑障碍环境
Note
The pretrained DUNE model provided in these examples are trained under the size of the robot. If you adjust the size of the robot, you must retrain the DUNE model by referring to the DUNE Training example.
示例中提供的预训练 DUNE 模型，是针对特定机器人尺寸训练的。
如果你修改了机器人的尺寸（如长、宽、半径等），就必须重新训练 DUNE 模型，方法参考 “DUNE Training” 示例
修改 robot 尺寸后 → 进入 dune_train/ → 训练新模型 → 在 planner.yaml 中指向新 .pth 文件
Note
Since the optimization solver cvxpy is not supported on GPU, we recommend using the CPU device to run the NeuPAN algorithm. Thus, the hardware platform with more powerful CPU (e.g. Intel i7) is recommended to achieve higher frequency and better performance. However, you can still use the GPU device to train the DUNE model for acceleration.
由于优化求解器 cvxpy 不支持 GPU，我们建议使用 CPU 运行 NeuPAN 算法。
因此，推荐使用高性能 CPU（如 Intel i7） 以获得更高的控制频率和更好性能。
但是，你仍然可以使用 GPU 来加速 DUNE 模型的训练过程。
MPC（整体） ⊃ NRMP（核心优化模块） ⊃ cvxpy（求解器），其中MPC 不是一个具体代码模块，而是一种控制策略思想：“在每一步预测未来、优化轨迹、执行第一步”
而NeuPAN 是 MPC 的一种实现，属于 “Learning-augmented MPC”（学习增强型 MPC）。
因此，当我们说 “NeuPAN 使用 MPC”，意思是：它遵循 MPC 的滚动时域机制，但用 DUNE + NRMP 实现了其中的“优化”部分。
NRMP工作：接收 DUNE 输出的障碍表示；构建一个带点级碰撞避免约束的优化问题；调用 cvxpy 求解该问题 → 得到安全控制指令
NRMP = NeuPAN 中实现 MPC 优化步骤的具体算法
所以：MPC ≈ NeuPAN 的运行时行为（整体）
cvxpy 是一个 Python 凸优化建模库，它本身不求解，而是调用后端求解器（如 ECOS、OSQP）。
┌───────────────────────┐
│ MPC │ ← 控制范式（滚动时域、重规划）
└──────────┬────────────┘
▼
┌───────────────────────┐
│ NeuPAN │ ← 整体系统（DUNE + NRMP）
└──────────┬────────────┘
▼
┌───────────────────────┐
│ NRMP │ ← 优化模块（构建+求解安全轨迹）
└──────────┬────────────┘
▼
┌───────────────────────┐
│ cvxpy + ECOS/OSQP │ ← 优化求解器（CPU-only）
└───────────────────────┘
同时，DUNE（神经网络） 与 NRMP 通过 交替最小化（Alternating Minimization） 耦合：DUNE ⇄ NRMP ⇄ DUNE ⇄ NRMP ...
NeuPAN = DUNE（可 GPU） + NRMP（仅 CPU）
所以整体 pipeline 无法端到端 GPU 加速。
6.Advanced Usage
DUNE Model Training
To train a DUNE model for your own robot with a specific convex geometry, you can refer to the example/dune_train folder. Specifically, the convex geometry is defined in the robot section by the vertices (or length and width for rectangle) when the robot is in the initial state (coordinate origin). The training parameters can be adjusted in the train section.
Note
The DUNE model only needs to be trained once for a new robot geometry. This trained model can be used in various environments without retraining.
ROS Integration
We provide a ROS wrapper for NeuPAN. You can refer to the neupan_ros repo to see the details. The Gazebo demonstrations are shown below:
ROS 和 Gazebo 是机器人开发的两大核心工具
Gazebo则在电脑里创建逼真的物理世界（重力、摩擦、碰撞）；模拟各种传感器（激光雷达、摄像头、IMU）；让你在不烧毁真机的情况下测试算法
Gazebo 启动一个仿真机器人→ 自动发布 /scan（激光）、/odom（里程计）等 ROS 话题
你的规划器（如 NeuPAN）作为 ROS 节点运行→ 订阅 /scan，计算安全速度 → 发布 /cmd_vel
Gazebo 接收 /cmd_vel→ 驱动虚拟机器人运动
rviz 实时显示轨迹、障碍物、机器人状态
下面是关于部署的问题
这段 “Real World Deployment”（真实世界部署） 是 NeuPAN 文档中非常实用的进阶指南，专门告诉你：如何把在仿真中跑通的 NeuPAN 算法，安全、高效地部署到真实机器人上。
下面我用清晰的结构为你逐层解读它在讲什么，以及每句话背后的工程含义：
✅ 核心目标一句话总结：
NeuPAN 可以直接从仿真迁移到真机，但需注意硬件、参数和初始路径三件事。
🔍 逐段详解
📌 第一段：支持哪些机器人？能否扩展？
“You can easily deploy the NeuPAN algorithm on a real robot platform using neupan_ros. Currently, NeuPAN supports the kinematics of differential drive robots, Ackermann robots and omni-directional robots... For robots with other kinematics, you can modify the constraints in the NRMP layer to suit your needs.”
✅ 意思：
- 通过
neupan_ros包，可轻松将 NeuPAN 部署到真实机器人。 - 原生支持三种驱动模型：
- 差速驱动（如 TurtleBot）
- 阿克曼（如小车，只能前进/后退+转向）
- 全向驱动（如麦克纳姆轮底盘）
- 如果你的机器人是其他类型（比如四轮独立转向），只需修改 NRMP 层的运动学约束即可适配。
💡 关键点：NeuPAN 的优化层（NRMP）是可编程的，不是死板的。
📌 第二段：DUNE 模型能直接用吗？
“The DUNE model trained in simulation can be directly applied in the real world without retraining.”
✅ 意思：
- 不需要域自适应（domain adaptation）！
- 在仿真中训练好的 DUNE 模型（
.pth文件），可以直接加载到真机上使用。 - 原因：DUNE 学的是几何级避障表示（“我的身体轮廓 vs 障碍点”），与传感器噪声、光照、纹理等无关。
🌟 这是 NeuPAN 的巨大优势：省去了麻烦的真实数据收集和重训练！
📌 第三段：性能瓶颈在哪？怎么提速？
**“NeuPAN solves the mathematical optimization problem in real time. Thus, its performance is influenced by three main factors:
- CPU 算力；
adjust参数；- 初始路径质量。”**
✅ 意思：
NeuPAN 的实时性取决于三大因素：
| 因素 | 说明 | 如何优化 |
|---|---|---|
| 1. CPU 算力 | 优化求解（cvxpy）只能在 CPU 跑 | 用 Intel i7/i9 或高性能嵌入式 CPU（如 Jetson AGX Orin 的 CPU 核） |
2. adjust 参数 |
控制成本函数权重 | 调低某些项权重可加速收敛 |
| 3. 初始路径 | 优化器的起点 | 好的初值 = 更少迭代 = 更快求解 |
⚠️ 重点：NeuPAN 不是纯神经网络，而是“学习 + 实时优化”，所以CPU 是关键！
📌 第四段：具体怎么调参提速？
“We recommend using a hardware platform with a powerful CPU... adjust parameters such as
receding,nrmp_max_num,dune_max_num,iter_num, anditer_threshold...”
✅ 这些参数的作用：
| 参数 | 含义 | 调小 → 效果 |
|---|---|---|
receding |
MPC 预测步数 | 规划视野变短，计算量 ↓ |
nrmp_max_num |
NRMP 最大迭代次数 | 早停，速度 ↑，但可能不收敛 |
dune_max_num |
DUNE 点云采样数 | 输入点更少，推理更快 |
iter_num / iter_threshold |
交替优化停止条件 | 减少 DUNE ↔ NRMP 交互次数 |
✅ 经验建议：Intel i7 可跑 >15 Hz，满足大多数移动机器人需求（10~30 Hz 足够）。
📌 第五段：adjust 参数调什么行为？
“The adjust parameters are used to tune the weights of the state cost, speed cost, and collision avoidance cost... making it either more aggressive or more conservative.”
✅ 意思：
adjust段控制 MPC 目标函数中各项的重要性：adjust: weight_state: 1.0 # 跟踪参考路径的权重 weight_speed: 0.5 # 保持高速的权重 weight_collision: 10.0 # 避障权重（越大越保守）- 调高
weight_collision→ 机器人“胆小”，远离障碍物 - 调低
weight_state→ 机器人“激进”，允许偏离路径以绕障
💡 这些参数可在运行时动态调整（比如进窄道时自动变保守）。
📌 第六段：初始路径怎么来？
**“The naive initial path can be generated from... waypoints or global planner... We offer functionality to generate:
- direct lines (diff),
- Dubins' paths (Ackermann forward),
- Reeds-Shepp paths (Ackermann forward+backward).”**
✅ 意思：
- NeuPAN 不需要完美的全局路径，只需要一个“粗糙初值”。
- 系统会根据机器人类型自动生成合适初值：
- 差速机器人 → 直线连接航点
- 阿克曼（仅前进） → Dubins 路径（曲率连续，符合最小转弯半径）
- 阿克曼（可后退） → Reeds-Shepp 路径（支持前进+后退）
🌟 好处：即使 A* 给出穿墙路径，NeuPAN 也能在局部优化中修正！
✅ 总结：Real World Deployment 告诉你什么？
| 问题 | NeuPAN 的答案 |
|---|---|
| 能上真机吗？ | ✅ 能！用 neupan_ros |
| 要重训练吗？ | ❌ 不用！仿真模型直接用 |
| 需要什么硬件？ | 💻 强 CPU（i7 起步） |
| 跑不快怎么办？ | ⚙️ 调 receding、nrmp_max_num 等参数 |
| 机器人太激进/太保守？ | 🎚️ 调 adjust 权重 |
| 没有全局规划器？ | 🗺️ 系统可自动生成初值路径 |
🛠️ 给你的实操建议
- 先在 Gazebo + ROS 中测试（零风险）
- 记录当前控制频率（
rostopic hz /cmd_vel） - 如果 <10 Hz：
- 降低
receding（如从 10 → 6） - 减少
dune_max_num（如 128 → 64）
- 降低
- 在狭窄环境调高
weight_collision - 真机部署时，确保 CPU 散热良好（持续高负载会降频！）
如果你告诉我你的机器人类型（比如“TurtleBot3 差速底盘”或“自研阿克曼小车”），我可以给你一份具体的 planner.yaml 调参建议 😊
浙公网安备 33010602011771号