Newton 关节仿随Joint Mimic机制迁移指南从稀疏 constraint_mimic 到关节自有的 set_joint_mimic 元数据【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton本文围绕 Newton 1.6 的一项 API 变更展开ModelBuilder.add_constraint_mimic()与稀疏的constraint_mimic_*模型数组被正式标记为废弃Deprecated取而代之的是以关节为单位的set_joint_mimic()与joint_mimic_joint、joint_mimic_coeffs元数据。读者将了解新旧两套机制的差异、新 API 的调用方式与约束校验规则、eval_mimic()的逐分量更新原理、各求解器Featherstone / SemiImplicit / XPBD / MuJoCo / VBD的支持情况以及一个可直接运行的丝杠lead screw示例从而完成平滑迁移。一、变更背景为什么要废弃 constraint_mimic在 Newton 1.6 之前的版本中关节仿随关系mimic是以“约束”的形式存在的用户调用ModelBuilder.add_constraint_mimic(joint0, joint1, coef0, coef1, ...)来声明“关节joint0跟随关节joint1”随后这些关系被写入一组稀疏的constraint_mimic_*模型数组constraint_mimic_joint0、constraint_mimic_joint1、constraint_mimic_coef0、constraint_mimic_coef1、constraint_mimic_enabled、constraint_mimic_label、constraint_mimic_world并以constraint_mimic_count记录总数。这种设计有两个明显问题语义割裂mimic 本质上是“某个关节的属性”却以独立的约束实体存储导致模型构建、复制replicate、世界/关节重映射等流程都要额外维护一套稀疏结构与 URDF/原生关节语义不对齐URDF 中mimic是关节的直接属性稀疏约束式存储难以自然对应。因此Newton 在 1.6 中引入了关节自有的仿随元数据joint-owned mimic metadata将关系内联到每个关节上并废弃旧的约束式 API。这一变更的记录位于 changelog/joint-mimic-metadata-8e61c4a2.deprecated.md配套的新功能清单见 changelog/joint-mimic-metadata-8e61c4a2.added.md。二、新旧 API 对照维度旧机制已废弃新机制推荐构建接口ModelBuilder.add_constraint_mimic(joint0, joint1, coef0, coef1, enabled, label, custom_attributes)ModelBuilder.set_joint_mimic(joint, reference_joint, coeffs)关系定义joint0 coef0 coef1 * joint1URDF mimic 语义q[joint] coeffs[0] coeffs[1] * q[reference_joint]逐分量模型存储constraint_mimic_joint0/constraint_mimic_joint1/constraint_mimic_coef0/constraint_mimic_coef1/constraint_mimic_enabled/constraint_mimic_label/constraint_mimic_worldjoint_mimic_jointwp.int32数组按关节索引存储与joint_mimic_coeffswp.vec2数组偏移量 乘数维度要求支持标量prismatic、revolute与多 DOF 关节对多 DOF 关节所有自由度施加相同关系要求主从关节位置与速度维度完全匹配逐分量对齐清理关系通过enabledFalse停用传入reference_jointNone清除新的存储结构定义在 newton/_src/sim/model.py 中joint_mimic_joint与joint_mimic_coeffs属于AttributeFrequency.JOINT频率的属性每个关节一个而旧的constraint_mimic_joint0等数组在模型属性说明中也已标注为应改用新机制并附有弃用提示指向set_joint_mimic与joint_mimic_*属性。三、新 APIset_joint_mimic() 的调用与校验规则ModelBuilder.set_joint_mimic(joint, reference_joint, coeffs(0.0, 1.0))的实现位于 newton/_src/sim/builder.py其语义为joint从动关节follower索引reference_joint参考关节reference索引传None表示清除该关节的仿随关系恢复为独立关节joint_mimic_joint[joint] -1joint_mimic_coeffs[joint] (0.0, 1.0)coeffs(offset, multiplier)二元组逐分量作用于参考关节的坐标量纲分别为[m 或 rad]与无量纲。底层关系为q[joint] coeffs[0] coeffs[1] * q[reference_joint] qd[joint] coeffs[1] * qd[reference_joint]在写入元数据之前该方法会执行一系列严格校验不满足即抛出ValueError迁移时必须注意索引合法性joint与reference_joint均须落在[0, joint_count)内且joint不能等于reference_joint不能自仿随维度匹配主从关节的位置自由度q与速度自由度qd维度必须完全一致dof_count比较否则报错并给出两者的维度明细世界归属两个关节必须属于同一个 worldjoint_world相等机构归属若两个关节都属于某个 articulation则必须属于同一个 articulation系数有限性offset与multiplier必须是有限浮点数math.isfinite禁止仿随链参考关节本身不能已是某个仿随关系的从动关节joint_mimic_joint[reference_joint] ! -1某个关节也不能被多个仿随关系引用。也就是说新机制只支持“星形”结构多个关节跟随同一个独立参考关节但参考关节必须保持独立。这些校验在 newton/tests/test_solver_mimic.py 中有对应测试测试构建了一个 revolute 参考关节 prismatic 从动关节或两个 D6 关节的机构设置offset0.1、multiplier-1.5并通过eval_mimic/ 各求解器 step 后断言每个跟随坐标都满足仿随关系。四、旧 APIadd_constraint_mimic() 的废弃行为ModelBuilder.add_constraint_mimic()在 newton/_src/sim/builder.py 中仍然保留但调用时会立即发出DeprecationWarningModelBuilder.add_constraint_mimic() is deprecated in Newton 1.6; use set_joint_mimic() for joints with matching dimensions instead.其行为在废弃期间为将joint0 coef0 coef1 * joint1追加到稀疏的constraint_mimic_*列表返回约束索引并支持custom_attributes以AttributeFrequency.CONSTRAINT_MIMIC频率处理。废弃期间它仍要求两个关节属于当前 world但不要求维度匹配对多 DOF 关节将所有自由度按同一关系处理——这正是与新机制最大的行为差异。五、运行时求值eval_mimic() 与逐分量内核关节自有的仿随元数据在运行时由 newton/_src/sim/joint_mimic.py 中的eval_mimic(model, state_in, state_outNone)驱动底层是一个 Warp 内核eval_mimic_joints按关节数并行启动dimmodel.joint_count每个线程读取当前关节的joint_mimic_joint[reference]若reference 0则为独立关节直接返回否则遍历该关节的每个位置坐标与速度坐标按coeffs (offset, multiplier)逐分量写入joint_q[q_start coordinate] coeffs[0] coeffs[1] * joint_q[reference_q_start coordinate] joint_qd[qd_start dof] coeffs[1] * joint_qd[reference_qd_start dof]state_out省略时原地更新state_in传入新 state 时先复制全部joint_q/joint_qd再更新从动关节便于在不污染输入状态的前提下求值。此外该文件还提供了从“最大坐标”maximal coordinates求取关节坐标与梯度的eval_joint_mimic_coordinate/eval_joint_mimic_velocity支撑 SemiImplicit 的惩罚弹簧力计算以及has_supported_joint_mimics(model, solver_name)—— 它只对PRISMATIC、REVOLUTE、D6三种关节类型视为受支持遇到不支持的关节类型会发出警告并列出最多 10 个从动关节索引。六、各求解器的支持与 SemiImplicit 的惩罚弹簧新增的addedchangelog 明确了求解器覆盖范围Featherstone、SemiImplicit、XPBD、MuJoCo、VBD均支持关节自有的仿随元数据。从源码看Featherstone / XPBD / MuJoCo / VBD在各自的求解器与内核如newton/_src/solvers/featherstone/kernels.py、newton/_src/solvers/xpbd/kernels.py、newton/_src/solvers/mujoco/solver_mujoco.py、newton/_src/solvers/vbd/中直接消费joint_mimic_joint/joint_mimic_coeffs将仿随关系作为投影或约束参与迭代SemiImplicitSolverSemiImplicit特殊之处在于它把仿随关系实现为全局惩罚弹簧构造器暴露两个增益参数见 newton/_src/solvers/semi_implicit/solver_semi_implicit.pyjoint_mimic_ke位置误差增益默认1.0e2用于-ke * position_errorjoint_mimic_kd速度误差增益默认1.0用于-kd * velocity_error。弹簧力在内核eval_joint_mimic_forcesnewton/_src/solvers/semi_implicit/kernels_body.py中累加其稳定性和精度取决于这两个增益与仿真步长需要针对机构质量与时间步调参——这与 XPBD/MuJoCo/VBD 的迭代投影方式不同。另外SemiImplicit 的文档明确说明其不支持 equality 约束与废弃的稀疏 mimic 约束迁移到新机制对它尤其重要。七、实操示例丝杠机构的迁移与验证仓库自带一个基于新机制的可运行示例 newton/examples/basic/example_basic_mimic_joint.py它模拟了一根丝杠让棱柱副螺母关节仿随旋转副螺杆关节把旋转转化为直线行程q_nut pitch / (2 * pi) * q_screw运行方式python -m newton.examples basic_mimic_joint示例默认使用 XPBD 求解器可通过--solver切换featherstone、semi_implicit、xpbd、mujoco、vbd五种后端用--pitch指定导程默认1.2 m/rev。核心调用只有一行对应第 140 行builder.set_joint_mimic(self.nut_joint, self.screw_joint, coeffs(0.0, self.coupling_ratio))其余配置要点螺杆关节为add_joint_revoluteZ 轴target_ke80.0、target_kd10.0、effort_limit200.0螺母关节为add_joint_prismaticZ 轴limit_lower-0.6、limit_upper0.6、limit_ke1.0e4、limit_kd100.0、damping0.2两个关节通过add_articulation([...], labellead_screw)组成同一机构SemiImplicit 后端下为该机构调优的增益为joint_mimic_ke5.0e4、joint_mimic_kd5.0e2对应 240 Hz 步长VBD 在每次求解迭代内投影仿随关系因此示例将其sim_substeps设为 1。示例内置自检test_final()要求螺杆累计转动超过 0.5 rad且全程最大耦合误差不超过 10 mmmax_abs_coupling_error 0.01即失败直接验证了迁移后新机制的保真度。test_solver_mimic.py则进一步覆盖了不同求解器下仿随关系的一致性含 vectorized D6 关节、kinematic 参考关节等变体。八、迁移清单将现有代码从旧机制迁移到新机制只需四步替换调用把builder.add_constraint_mimic(joint0, joint1, coef00.0, coef11.0, ...)改写为builder.set_joint_mimic(joint0, joint1, coeffs(coef0, coef1))。注意参数顺序变化旧接口是“(从动, 主动, coef0, coef1)”新接口的coeffs元组仍是(offset, multiplier)但第二个位置参数是参考关节索引核对维度新机制要求主从关节的 q/qd 维度严格一致。若旧代码中两个关节维度不同多 DOF 关节被施加同一关系需先统一关节维度或调整机构设计否则会在finalize前的校验阶段报错检查链式依赖新机制禁止仿随链参考关节必须独立若旧代码存在 A 仿随 B、B 仿随 C 的链式结构需要显式改写为 C 作为唯一参考的星形结构替换属性访问读取关系时改用model.joint_mimic_joint与model.joint_mimic_coeffs均为按关节索引的定长数组不再遍历稀疏的constraint_mimic_*数组。需要说明的是旧的稀疏数组与add_constraint_mimic()在 1.6 中仍可用会触发DeprecationWarning但新代码应一律采用关节自有的set_joint_mimic()方案未来版本移除旧接口时上述迁移步骤即可保证平滑过渡。【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newton创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考