NeuPAN 项目文件结构与使用方法文档

NeuPAN 项目文件结构与使用方法文档1. 项目目录结构概览1.1Neupan核心代码目录文件路径文件作用eupan/neupan.py主入口类封装 PAN 模块提供友好接口。负责从 YAML 配置初始化、管理 MPC 控制循环、处理激光雷达扫描数据转换为点云、协调路径规划与优化流程eupan/robot/robot.py机器人模型类。定义三种运动学模型Ackermann 差速转向、Diff 双轮差速、Omni 全向移动、机器人形状顶点生成、MPC 优化问题的约束速度/加速度边界、动力学约束和代价函数、线性化运动学模型eupan/blocks/pan.pyPAN (Proximal Alternating Minimization Network) 核心类。整合 NRMP 和 DUNE 两大组件迭代优化求解 MPC 视域内的最优控制管理点云数据在坐标系间的变换eupan/blocks/nrmp.pyNRMP (Neural Regularized Motion Planner)。使用 CVXPyLayer 定义可微分凸优化问题结合神经网络预测的潜在距离特征 (mu/lambda) 来生成避障最优控制序列eupan/blocks/dune.pyDUNE (Deep Unfolded Neural Encoder)。神经网络编码器将激光雷达点云映射到潜在距离空间 (latent distance space)输出 mu 和 lambda 矩阵供 NRMP 使用eupan/blocks/dune_train.pyDUNE 模型训练器。使用凸优化问题生成训练数据定义多任务损失函数mu loss、distance loss、fa loss、fb loss管理训练循环、验证和模型保存eupan/blocks/obs_point_net.py观察点神经网络。DUNE 中的 MLP 架构4 层隐藏层将 2D 点坐标映射为潜在距离特征向量eupan/blocks/initial_path.py初始路径生成器。从给定航点生成初始轨迹支持多种曲线类型line/dubins/reeds处理路径分段、档位切换、最近点查找eupan/configuration/__init__.py配置工具模块。管理计算设备CPU/GPU、张量数据类型、张量与 numpy 数组转换、时间测量开关eupan/util/__init__.py通用工具函数。时间测量装饰器、文件路径检查、角度 wrapping (WrapToPi)、距离计算、坐标变换矩阵生成、凸多边形不等式约束生成 (G, h)、均匀降采样eupan核心架构图neupan (主类) ├── robot (机器人模型 运动学 约束) ├── blocks/pan.py (核心优化网络) │ ├── blocks/nrmp.py (NRMP - 可微分凸优化层) │ └── blocks/dune.py (DUNE - 神经网络编码器) │ └── blocks/obs_point_net.py (MLP 网络) └── blocks/initial_path.py (初始轨迹生成)1.2example仿真场景目录1.2.1 场景类型说明场景目录测试目的corridor/走廊环境 — 带矩形障碍物的简单场景考验窄通道避障能力dyna_non_obs/动态非障碍场景 — 无障碍物的动态环境基准测试dyna_obs/动态障碍场景 — 有移动障碍物考验实时避障convex_obs/凸障碍场景 — 凸多边形障碍非矩形验证通用凸形状兼容性non_obs/无障碍场景 — 空旷环境基准测试pf//pf_obs/势场场景 — 与传统势场法做性能对比polygon_robot/多边形机器人场景 — 验证 DUNE 对非矩形机器人的适配reverse/倒车场景 — 验证档位切换前进/倒车功能LON/长走廊场景 — 长距离路径规划与执行dune_train/DUNE 模型训练场景 — 专用训练配置1.2.2 机器人运动学配置每个场景下包含三种运动学模型配置目录对应运动学模型acker/Ackermann 转向模型汽车式转向diff/双轮差速驱动模型omni/全向移动模型1.2.3 配置文件说明文件类型作用env.yaml环境配置。定义仿真世界参数尺寸、时间步长、机器人属性形状、运动学参数、传感器配置、障碍物属性数量、形状、位置planner.yaml规划器配置。MPC 参数视域大小、时间步长、机器人参数速度/加速度限制、初始路径配置航点、曲线类型、PAN 网络参数、DUNE 模型路径、调节参数1.2.4 关键文件文件路径作用example/run_exp.py实验运行脚本。基于 irsim 仿真环境的主程序解析命令行参数、初始化仿真器和规划器、执行 MPC 控制循环、可选保存动画example/model/预训练模型存储目录。包含针对不同机器人几何形状训练的 DUNE 模型权重 (.pth) 和训练参数 (train_dict.pkl)2.example目录与 irsim 仿真的关系是的example文件夹完全服务于 irsim 仿真环境。从run_exp.py中可以清楚看到importirsim envirsim.make(env_file,save_anisave_animation,fullfull,displayno_display)irsim 是本项目使用的基于 Python 的机器人仿真框架功能包括加载环境配置env.yaml获取机器人状态和传感器数据激光雷达扫描执行控制指令驱动机器人可视化轨迹、点云、目标点等生成动画GIF 文件因此example文件夹本质上是一套场景演示/测试用例每个子目录对应一个测试场景开发者可以快速验证 NeuPAN 在不同环境和运动学模型下的规划效果。生成的动画示例存放在example/animation/目录下。3. DUNE 模型训练方法3.1 训练触发方式方式一自动触发推荐运行实验脚本时若planner.yaml中指定的 DUNE 模型文件不存在会自动提示python example/run_exp.py-ecorridor-ddiff输出示例Do not find the DUNE model; Do you want to train the model now, input Y or N: Y方式二代码中直接调用fromneupanimportneupan plannerneupan.init_from_yaml(example/corridor/diff/planner.yaml)planner.train_dune()# 直接触发训练3.2 训练配置参数在planner.yaml中添加train部分train:model_name:diff_robot_default# 模型保存文件夹名data_size:100000# 训练样本数量data_range:[-25,-25,25,25]# 点云采样范围 (xmin, ymin, xmax, ymax)单位米batch_size:256epoch:5000save_freq:500# 每 500 轮保存一次valid_freq:250# 每 250 轮验证一次lr:5e-5lr_decay:0.5decay_freq:1500direct_train:True# True 跳过提示直接训练3.3 训练数据生成原理DUNE 的训练数据是在线生成的无需真实轨迹数据。对于每个随机采样点p通过求解以下凸优化问题得到最优mumax mu^T * (G * p - h) s.t. ||G^T * mu|| 1 mu 0其中G, h来自机器人凸多边形的顶点定义。这确保 DUNE 学习的是该特定机器人几何的潜在距离表示。4. 关于dune_train训练配置与场景定制4.1dune_train是否是最基本的训练方式是的。dune_train_diff.yaml只包含两类配置配置项内容robot机器人几何参数运动学类型、长、宽train训练超参数数据量、学习率、轮数等这是最简训练配置因为DUNE 的训练只依赖于机器人凸多边形形状与具体场景环境无关。无论机器人在走廊、仓库还是户外只要形状固定DUNE 学到的就是「空间中每个点距离机器人多远」。4.2 能否通过修改 yaml 使用其他场景配置来提高能力不推荐意义不大。不同场景存在的目的是测试和验证完整的 NeuPAN 规划器而非训练 DUNE。DUNE 训练是场景无关的。4.3 可调整的关键参数有两个参数可根据实际需求调整data_range— 训练点采样范围data_range:[-25,-25,25,25]如果实际运行环境空间更大如室外适当增大此范围如果运行环境很小如紧凑室内可缩小以提高该区域的拟合精度data_size— 训练样本数量data_size:100000样本越多模型越精确但训练时间线性增长100000 对大多数场景已足够4.4 需要重新训练 DUNE 的唯一情况只有当机器人几何形状与默认模型不同时才需要重新训练robot:kinematics:difflength:2.0# 新的机器人长度width:2.5# 新的机器人宽度或直接传入自定义顶点robot:kinematics:diffvertices:[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]# 自定义凸多边形顶点5. 不同场景存在的真正目的场景目的non_obs/无障碍基准测试— 验证在没有障碍物时规划器正常工作corridor/窄通道测试— 机器人在矩形障碍物形成的走廊中穿行考验避障能力dyna_obs/动态障碍测试— 有移动障碍物考验规划器在时变环境中的实时避障convex_obs/凸障碍测试— 凸多边形障碍验证对任意凸形状的兼容性pf//pf_obs/势场法对比— 与传统势场法做性能对比polygon_robot/多边形机器人测试— 验证 DUNE 对非矩形机器人的适配reverse/倒车测试— 验证档位切换前进/倒车功能LON/长走廊场景 — 长距离路径规划与执行、LON 参数调优总结DUNE 训练→ 只需几何形状场景无关完整规划器测试→ 需要各种场景验证算法在真实环境中的表现LON 调优→ 可选功能通过仿真数据对特定场景进行参数优化这些场景的env.yamlplanner.yaml组合再配合run_exp.py运行即可生成example/animation/目录下的 GIF 动画演示。6. LON 参数调优可选6.1 功能概述LON (Learning to Optimize NeuPAN)是可选的在线参数调优功能用于在具体仿真场景中自动优化 NRMP 的 adjust 参数以提升规划器在该场景下的性能。6.2 目的通过 ir-sim 仿真环境采集场景执行数据作为优化目标自动调优 NRMP 的 adjust 参数包括参数作用q_s状态代价权重p_u控制速度代价权重eta碰撞避免代价权重d_max最大安全距离d_min最小安全距离6.3 依赖ir-sim 仿真环境目标场景的env.yaml和planner.yaml配置已训练的 DUNE 模型6.4 输出优化后的配置文件YAML例如planner_0.1.yaml、planner_0.2.yaml等包含调优后的 adjust 参数。可将其复制或合并到生产配置中使用。6.5 训练脚本说明脚本作用LON_corridor_01.py第一轮 LON 调优LON_corridor_02.py第二轮 LON 调优训练过程中优化的参数由优化器定义opttorch.optim.Adam([p_u_tune,eta,d_max],lr5e-3)损失函数包含三个部分state_loss— 轨迹跟踪误差状态与参考状态的 MSEspeed_loss— 速度跟踪误差速度与参考速度的 MSEdistance_loss— 碰撞/停滞惩罚近距离或停滞时增加惩罚6.6 LON 训练步骤# 进入 LON 训练目录cdexample/LON# 运行第一轮 LON 训练python LON_corridor_01.py# 运行第二轮 LON 训练使用第一轮的输出配置python LON_corridor_02.py6.7 重要提醒LON 是可选的不是运行 NeuPAN 的前置需求。如果默认参数表现良好完全可以跳过 LON。只有当默认参数在特定场景下表现不佳如经常碰撞、速度跟踪误差大、容易停滞时才需要使用 LON 进行场景化调优。7. 快速入门7.1 使用预训练模型推荐python example/run_exp.py-ecorridor-ddiff7.2 训练自定义 DUNE 模型python example/dune_train/dune_train_diff.py7.3 LON 参数调优可选cdexample/LON python LON_corridor_01.py python LON_corridor_02.py7.4 命令行参数说明参数说明-e, --example场景名称corridor, dyna_obs, convex_obs 等-d, --kinematics运动学模型acker, diff, omni-a, --save_animation保存动画-f, --full全屏显示-n, --no_display关闭显示-v, --point_vel启用点速度-m, --max_steps最大步数