Pinocchio
新一、简介
Pinocchio 是由法国国家信息与自动化研究所 Inria 的 Willow 团队(与巴黎高等师范学校 ENS 联合)联合 LAAS-CNRS 的 Gepetto 团队共同开发的开放源代码刚体动力学算法库,以 BSD-2-Clause 许可发布,项目由 Nicolas Mansard 发起。它实现了面向多体系统的最先进刚体动力学算法,并在 Roy Featherstone 奠基性算法的基础上,补充了现代机器人与基于物理仿真所需的模块:正运动学、正逆动力学及其解析导数、质心动力学、回归量矩阵、闭链运动学以及摩擦接触相关量。该库是一个仅含头文件的 C++ 模板层,底层依赖 Eigen 做线性代数、依赖 coal 做碰撞几何,并提供一流的 Python 绑定,通过 Conda 与 pip 分发,因此成为快速原型开发的热门选择。对一个物理 AI 方案而言,它的意义在于把运动方程变成可微分函数:轨迹优化器、控制器与学习循环可以拿到解析梯度,而不必依赖有限差分。它已被 Crocoddyl、TSID、HPP、Aligator、Jiminy 以及众多机器人框架当作动力学计算底座使用,是连接经典刚体算法与现代学习式控制的桥梁。本条目所有事实于 2026 年 11 月 12 日对照仓库、软件论文与官方文档核实,第九节记录版本与许可口径。它之所以在物理 AI 讨论中被反复提及,是因为可微动力学正是把仿真器接入优化与学习闭环的那块基石,没有它,大大量基于梯度的控制器都将退回到昂贵且高方差的有限差分路径上。
二、原理与工作方式
解析导数层是这套库的核心。Pinocchio 实现了递归牛顿欧拉算法(RNEA)与铰接体算法(ABA)来计算正动力学与逆动力学,并额外提供这些量关于关节位形、速度、加速度以及外力的全部一阶偏导数。正运动学、任意坐标系的雅可比矩阵、质心位置与速度、质心动量矩阵以及回归量矩阵,都与其一阶导数一同可用。闭链机构通过约束铰接体算法得到支持,摩擦接触问题则由内置的接触求解器处理。由于整套算法建立在李群之上,在构型流形上积分微小增量、复合刚体变换等操作都能被一致地处理,避免了欧拉角之类的奇异性陷阱。库还兼容 CppAD 与 CasADi 等自动微分后端,以及 CppADCodeGen 等代码生成工具,因此同一个模型既能走数值微分,也能走符号微分或编译后的 C 代码。对于需要把动力学接入优化器的团队,这意味着可以拿到与模型完全一致的解析梯度,梯度质量直接决定了轨迹优化与系统辨识能否收敛,也避免了有限差分在高维构型空间里难以调参的老问题。
补充一点:由于刚体算法以闭式递推实现,其时间复杂度与关节数近似线性,因此无论模型有几十个还是上百个自由度,单次正逆动力学与导数都可以在极短时间内完成,这使它适合作为实时优化器的内层例程。对工程而言,解析导数还意味着可以把动力学直接嵌入到基于梯度的轨迹优化或模型预测控制里,而不必为每一个中间量手工推导灵敏度,从而把控制律的设计与求解更紧密地结合起来。
三、适用边界与前提
Pinocchio 面向由关节与刚体装配而成的多体系统,包括树状结构与闭链结构,并假设模型以标准的铰接体形式给出。它支持从 URDF、SDF、MJCF、SRDF 文件加载模型,也支持以编程方式构建,运行依赖 Eigen 与 coal 两个底层库。它跨平台且在 Windows、macOS、Linux、Unix 上都有测试,遵循 C++17、C++20、C++23 标准,采用仅含头文件的模板设计并支持自定义标量类型,因此能方便地嵌入到既有 C++ 工程。需要明确的是,它是一层算法与微分基础设施,并非独立仿真器:它计算控制器或优化器所需的各种量,而运动方程的积分、接触密集的仿真以及可视化,则交给 Jiminy 这类伴随工具或完整的物理引擎来完成。它不建模软体、流体或连续介质,且解析导数只在所提供模型正确的前提下才成立,因此在退化或奇异构型附近仍需小心处理,不能把它当成可以盲信的黑箱。
需要强调的是,它的正确性边界由所使用的模型界定:一个未标定或简化过度的 URDF,会在不发出任何警告的情况下把误差带进每一阶导数,因此把它接入真实系统前,模型校验与传感器对齐不可或缺。另外,尽管它支持自定义标量类型以便接入自动微分,真正启用自动微分时仍需注意标量类型与求解器的兼容,避免在高维配置下出现数值或性能退化。把它当作可信的计算底座,前提是先确认模型、单位与坐标系三者一致。
四、上手路径
推荐的安装方式是 Conda:conda install pinocchio -c conda-forge 会把 C++ 头文件与 Python 模块一起装好。Linux 平台另有 pip install pin 的 wheel,Docker 镜像以 ghcr.io/stack-of-tasks/pinocchio:devel 发布,ROS 用户则可通过 apt install ros-$ROS_DISTRO-pinocchio 安装系统包。在 Python 里最短有用的会话是先用 pin.buildModelFromUrdf 从 URDF 构建模型,再调用 pin.forwardKinematics、pin.computeJointJacobians、pin.computeForwardDynamics 或 pin.computeCentroidalMomentum,这些函数在调用对应接口时也会一并返回解析导数。项目随附速查表 PDF、Doxygen 文档以及覆盖模型加载、导数计算与接触求解的可运行示例。最快的验证路径是加载一个小型 URDF,打印某个坐标系的雅可比与逆动力学力矩向量,确认数值与手算一致,然后再进入控制器或优化器开发。团队在接入自有流程之前,建议先用官方示例跑通模型加载与导数校验,避免在依赖或环境上踩坑。
对希望快速评估的团队,建议先在不联网的本地环境里复现一个最小示例,确认 Conda 安装、Python 绑定与编译器工具链都正常,再接入自有模型,可以避免被环境差异分散注意力。需要指出的是,虽然上层框架会封装许多调用细节,但理解 RNEA 与 ABA 的输出含义、以及质心与雅可比的约定,仍是正确解读结果的前提;在把动力学接入控制器之前,先用几个教科书上的双臂或浮动基例子做交叉验证,能显著降低后续集成时的排错成本。对于以 C++ 为主的项目,头文件式的集成方式也意味着可以把 Pinocchio 直接编译进既有工程,而不必引入额外的运行期依赖。
五、横向对比
与 MuJoCo 这类完整物理引擎相比,二者的分工不同:MuJoCo 负责接触动力学的积分与仿真推进,而 Pinocchio 提供优化与控制层所需的刚体算法与精确导数,两者常以配合方式并存,并非彼此替代。与 NVIDIA Warp 相比,Pinocchio 是用 C++ 编写的领域专用刚体库,并非 GPU 内核编程底座。与 Frax、SuperMimic 这类更新、以自动微分为先的 Python 库相比,Pinocchio 的优势在于成熟度、解析导数以及作为机器人生态事实上的动力学底座,而这些新项目则在 JAX 原生可微与更紧密的学习闭环集成上作出权衡。相对于通用的自动微分框架,Pinocchio 直接编码了刚体方程,因此在计算动力学及其梯度这一具体任务上通常更快、数值更稳。对工程团队而言,真正要比较的不是功能清单的多寡,而是当项目需要把动力学接入梯度优化时,哪条路径能给出稳定且可验证的解析梯度,而这恰恰是 Pinocchio 长期被依赖的根本原因。
在工程选型时,更应看重的不是功能列表的长短,而是哪条路径能给出可验证、可复现的解析梯度,以及它是否与团队既有的语言栈和硬件匹配。对一个已经围绕 C++ 工程构建的团队,Pinocchio 的成熟度与稳定性往往是决定性因素;而对追求快速实验、又已采用 JAX 的团队,Frax 这类方案则更贴合。二者并非互斥,很多项目会同时保留原生库做生产、用脚本化库做研究原型,根据阶段灵活切换。
六、基准与数据
配套软件论文(Carpentier 等人,IEEE SII 2019,HAL hal-01866228)在标准刚体基准上报告了库的计算性能,并证明解析导数例程在诸多情形不输甚至快于其它实现,同时保持数值稳健。设计上强调缓存友好的内存访问、多线程友好以及对自定义标量类型的支持,使得同一份代码无需重写即可运行在单精度、双精度或自动微分标量类型上。在实践中,Pinocchio 是多个广泛使用项目的动力学内核:Crocoddyl 的差分动态规划、TSID 的任务空间逆动力学二次规划、HPP 的人形运动规划、Aligator 的约束轨迹优化器,以及 Jiminy 的仿真器。这些下游采用正是其正确性与性能最有说服力的证据,因为每一个都依赖精确梯度才能收敛。需要强调的是,本条目引用的性能与采用情况均来自项目自身发表的材料,应视作作者一方的验证,并非本站独立复测的结果;团队在选用时仍应结合自身模型规模与硬件,做一轮针对性的基准对照。
从更务实的角度,团队在引用这些数字时,应把它们视为一类能力的佐证,并非对未知负载的承诺;在自己的模型规模、自由度数量与目标硬件上重跑一组对照,才能得到可信的结论。需要强调的是,这里引用的性能与采用情况均来自项目自身发表的材料,本条目未做独立复测,凡超出一手来源的表述都不作采纳,以免把作者一方的验证外推成普遍结论。
七、物理 AI 场景中的用法
Pinocchio 处在任何需要精确运动方程式的物理 AI 工作流的根基位置。它的解析导数让基于梯度的轨迹优化、模型预测控制与系统辨识变得可行,因为它们用精确的一阶信息替代了有噪的有限差分。它既能补足 MuJoCo 这样的物理引擎,也能为 ProtoMotions 这类上层运动框架提供其假设成立的动力学,当工作负载转移到 GPU 时还可与 NVIDIA Warp 这样的内核底座搭配。对可微替代建模而言,它与 基于物理的深度学习 是自然的伙伴;在 物理 AI 学习路径 中,它被列为学习式控制器所依托的动力学原语。 物理仿真入门 解释了这些刚体建模背后的假设,而 经典求解器成本边界 指南则澄清了何时精确解析导数仍优于习得代理。像 Frax 这样以 JAX 为先的库展示了自动微分优先动力学的新方向,而 SuperMimic 则演示了当这些梯度闭合一个学习循环后可能达成的成果,二者共同勾勒出从经典可微动力学到学习式控制的演进脉络。
沿着这条脉络,Pinocchio 的价值不只是提供一个快速动力学例程,更在于它让基于梯度的控制与学习在机器人领域变得触手可及:当导数随手可得,许多原本需要手工线性化的控制与辨识问题,都能改写为直接的梯度下降或约束优化。它也因此成为连接经典刚体动力学与新兴学习式控制之间的稳定桥梁,使两类方法可以在同一套模型与坐标系下公平比较与组合。
八、不适用场景与失效模式
第一条限制是 Pinocchio 只建模刚体多体系统:软接触、可变形体、流体与连续介质不在其范围内,接触密集的仿真必须由专用引擎或在 Pinocchio 之上的 Jiminy 来处理。第二条是数值条件:在运动学奇异或近退化关节构型附近,雅可比与铰接体相关量会恶化,因此操作空间与控制、优化代码仍需正则化与截断保护。第三条是解析导数只对所提供模型成立,不准确的 URDF、未建模的执行器或错误的坐标系都会悄无声息地污染梯度。第四条是尽管 Python 绑定方便,繁重的数值计算仍在 C++ 中进行,模型很大时仍要考量内存与编译开销,仅含头文件的模板在实例化多种标量类型时也会拉长构建时间。它是一块基石,并非端到端的控制器,安全部署仍需配套的控制与校验栈,不能把库的可用性等同于整套控制方案的安全性,也应对其输出保持独立验证的习惯。
从工程落地看,这些限制意味着 Pinocchio 更适合作为控制与优化栈里的可信计算层,并非端到端的解决方案;把安全、约束与执行器特性补齐,仍旧是使用者自己的责任。最后需要提醒,作为一个被广泛依赖的底层库,版本升级时也应保留回归测试,确认导数与雅可比在边界构型上仍与参考一致,避免隐藏的数值漂移悄悄进入控制器。把库的可用性等同于整套方案的安全性,是采用它时最应避免的误解。
九、版本与口径核对
Pinocchio 始于约 2015 年,主要由 Inria 巴黎的 Willow 团队(通过 Willow 联合团队与 ENS 巴黎合作)与 LAAS-CNRS 的 Gepetto 团队共同开发,项目由 Nicolas Mansard 发起。它以 BSD-2-Clause 许可发布,官方网站为 stack-of-tasks.github.io/pinocchio,Doxygen 文档由 Gepetto 团队托管。参考软件论文为 Carpentier、Valenza、Mansard 所著《Pinocchio: An Efficient and Versatile Rigid Body Dynamics Library for Robot Analysis, Simulation and Control》,发表于 IEEE SII 2019(HAL hal-01866228)。仓库在 devel 分支上活跃维护,提交超过一万三千次,持续集成覆盖 ROS、Linux、macOS、Windows 与 Robotpkg。Crocoddyl、TSID、HPP、Aligator 与 Jiminy 是依赖它的知名项目,Disney Research 的 Kamino 亦将其列为 Newton 物理引擎的主要灵感来源。BSD-2-Clause 许可覆盖源代码;本条目中的性能与采用数据均取自项目自身发表的材料,本站未作独立复测。关于出处:版本、许可与机构信息来自仓库、软件论文与官方文档,本条目对人员规模或融资等商业信息不作任何推断,也避免对依赖它的第三方项目作超出一手来源的陈述。
补充一点口径:本条目所引用的机构与作者信息、许可类型(BSD-2-Clause)以及软件论文编号(HAL hal-01866228)均来自仓库、软件论文与官方文档的一手来源;对项目的实际采用规模、社区活跃度或后续商业化等信息,本条目不作超出这些来源的推断。Inria 与 LAAS-CNRS 均为法国在机器人与自动化领域的权威研究机构,但本条目仅就 Pinocchio 这一具体库作事实性记录,不对其所属机构的整体成果作超出一手材料的评价,也不对未发布的规划或第三方转述作任何确认。关于性能与采用数据,如前所述均以项目自身发表为准,本条目保持对推断类结论的审慎。
十、参考资料
- Pinocchio 仓库 README,GitHub(stack-of-tasks/pinocchio),框架总览、安装与示例。
- Carpentier、Valenza、Mansard,《Pinocchio: An Efficient and Versatile Rigid Body Dynamics Library for Robot Analysis, Simulation and Control》,IEEE SII 2019,HAL hal-01866228。
- Pinocchio 官方网站 stack-of-tasks.github.io/pinocchio,项目说明与发布页。
- Pinocchio Doxygen 文档,gepetto.github.io/doc/pinocchio/doxygen-html,API 参考。
- Pinocchio 速查表 PDF,仓库 doc 目录,算法与导数快速参考。
- Featherstone,《Rigid Body Dynamics Algorithms》,Springer,2008,Pinocchio 所重访的奠基性算法。
- Crocoddyl 仓库,构建于 Pinocchio 之上的差分动态规划与轨迹优化框架。
- TSID 仓库,构建于 Pinocchio 之上的任务空间逆动力学二次规划控制器。
- HPP(Humanoid Path Planner),使用 Pinocchio 做动力学的机器人运动规划 SDK。
- Jiminy 仓库,基于 Pinocchio 的机器人学习与控制的物理仿真器。