Newton 执行器ActuatorAPI 深度指南基于 Warp 的 GPU 加速关节力矩计算模型【免费下载链接】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.actuators是 Newton 物理仿真引擎中负责从仿真状态与控制目标计算关节力矩的模块为机器人与仿真研究者提供一套模块化的执行器组件库驱动Drives、限幅Clamping与延迟Delay。本文基于 docs/api/newton_actuators.rst 展开结合模块源码newton/_src/actuators/与测试用例完整讲解执行器的组成方式、Actuator的构造与单步执行流程、五种驱动与三种限幅的计算模型、延迟缓冲机制、显式/隐式两种力矩求解模式以及 1.6 版本中从Controller系列到Drive系列的 API 迁移注意事项。读完本文你将能够直接使用Actuator组装自定义关节控制器并通过ModelBuilder.add_actuator将其接入仿真模型。模块定位与设计思想该模块在文档中被明确定位为GPU-accelerated actuator models for physics simulations即面向物理仿真的 GPU 加速执行器模型库。其核心设计是一个模块化组合管线——由驱动drive、限幅clamping与延迟delay三类组件共同计算关节力矩组件被组合进一个Actuator实例在模型构建阶段通过ModelBuilder.add_actuator注册见 newton/_src/sim/builder.py所有计算以 Warp kernel 形式在 GPU 上批量执行。newton.actuators的公共导出newton/actuators.py与模块文档中的 autosummary 列表完全一致共 14 个类、2 个函数ClassesActuator、ActuatorParsed、ClampingBase、ClampingDCMotor、ClampingMaxEffort、ClampingPositionBased、ComponentKind、Delay、DriveBase、DriveNeuralLSTM、DriveNeuralMLP、DrivePD、DrivePID、JointSpaceResponse、SchemaNamesFunctionsparse_actuator_prim、register_actuator_component⚠️ 该 API 在文档中标记为experimental实验性API 可能在没有事先通知的情况下变化欢迎通过 issue 或讨论区反馈。这是使用前需要知晓的重要前提。核心组件Actuator延迟 → 驱动 → 限幅 的组合管线Actuator是模块的枢纽类源码位于 newton/_src/actuators/actuator.py。它的工作流程文档总结为读取仿真状态/控制数组 → 可选延迟指令输入 → 驱动计算力矩 → 限幅力矩上限、饱和等→ 将结果累加scatter-add进输出数组。调用方在步进执行器前必须先清零输出数组。构造参数详解Actuator.__init__的完整签名与语义如下依据 actuator.py参数默认值说明indices必填指向速度形态数组速度、速度目标、前馈、力矩输出的 DOF 索引形状(N,)drive必填计算原始力矩的驱动DriveBase子类delayNone可选的输入延迟组件Delay实例clampingNone限幅对象列表后置力矩边界pos_indicesindices指向坐标形态数组state.joint_q的索引当位置与速度数组布局不同如浮动基座或球关节时与indices不同target_pos_indices依newton.use_coord_layout_targets而定指向control.joint_target_q的索引该标志在构造时读取一次构造后切换不再生效effort_indicesindices指向力矩输出数组的 DOF 索引用于耦合传动或肌腱驱动关节state_pos_attrjoint_qsim_state上的位置属性名state_vel_attrjoint_qdsim_state上的速度属性名control_target_pos_attrjoint_target_q控制结构上的目标位置属性control_target_vel_attrjoint_target_qd控制结构上的目标速度属性control_feedforward_attrjoint_act前馈力矩属性传None跳过control_output_attrjoint_f限幅后的输出力矩属性control_computed_output_attrNone限幅前原始力矩属性None表示不写requires_gradFalse为可微仿真分配带梯度支持的中间数组源码中的典型用法actuator Actuator( indicesindices, driveDrivePD(kpkp, kdkd), delayDelay(delay_stepswp.array([5, 5], dtypewp.int32), max_delay5), clamping[ClampingMaxEffort(max_effortmax_effort)], ) # 仿真循环 actuator.step(sim_state, sim_control, state_a, state_b, dt0.01)step()的五步执行流程Actuator.step的流程actuator.py可以精确拆解为延迟读取从current_state读取每个 DOF 的延迟目标缓冲为空时回退到当前目标力矩计算将原始力矩写入_computed_forces显式控制律或隐式的端步求解限幅将受限力矩写入_applied_forces。显式模式在驱动律之后限幅隐式模式在求解内部强制执行Scatter-add 累加将施加力矩可选地含计算力矩累加进输出数组——调用方必须在遍历执行器前清零输出如control.joint_f.zero_()状态更新先更新驱动状态再写入延迟缓冲将当前目标推入next_state。该流程通过_scatter_add_kernelactuator.py实现第 4 步的 GPU 并行累加。有状态组件与 CUDA Graph 支持is_stateful()若延迟或驱动维护内部状态则返回Truestate()返回新的组合状态Actuator.State含delay_state与drive_state若完全无状态则返回None。有状态执行器在step时必须同时提供current_act_state与next_act_stateis_graphable()所有组件是否可被 CUDA Graph 捕获State.reset(mask)按掩码长度 N 的布尔数组True项重置或整体重置组合状态State.assign(other)将另一状态的数值复制进来。assign对 Warp 数组使用dst.assign(src)对 Torch 张量在torch.inference_mode()下用copy_并严格校验类型、形状与声明字段见 actuator.py。assign的一个重要使用场景是 CUDA GraphGraph 记录的是缓冲地址而非 Python 变量名在奇数长度捕获区域的边界处用state_0.assign(state_1)替代最终的状态交换可为下一次回放保留推进后的状态for i in range(steps): control.joint_f.zero_() actuator.step(state, control, state_0, state_1, dt0.01) if steps % 2 1 and i steps - 1: state_0.assign(state_1) else: state_0, state_1 state_1, state_0驱动Drive力矩控制律DriveBasenewton/_src/actuators/drives/base.py是所有驱动的基类定义了组件的验证契约resolve_arguments负责在参数批量打包进 Warp 数组之前校验标量参数值如kp 0__init__只接收预构建数组并校验形状——回读数组内容做值校验会强制每次构造都发生同步的 device-to-host 拷贝。子类必须实现compute计算力矩写入forces[i]与resolve_arguments并可覆写finalize、is_stateful、is_graphable、state、update_state等钩子。DrivePD无状态 PD 驱动力矩律newton/_src/actuators/drives/drive_pd.pyeffort const_effort feedforward kp * (target_pos - current_pos) kd * (target_vel - current_vel)kp比例增益 [N/m 或 N·m/rad]形状(N,)resolve_arguments要求非负kd微分增益 [N·s/m 或 N·m·s/rad]const_effort常数偏置力矩 [N 或 N·m]可为None跳过。该驱动无状态is_stateful() False可被 CUDA Graph 捕获是默认的显式控制律主力。DrivePID带抗饱和积分的有状态 PID 驱动力矩律newton/_src/actuators/drives/drive_pid.pyeffort const_effort feedforward kp * (target_pos - current_pos) ki * integral(target_pos - current_pos) kd * (target_vel - current_vel)关键点ki积分增益 [N/(m·s) 或 N·m/(rad·s)]integral_max抗饱和anti-windup上限 [m·s 或 rad·s]resolve_arguments默认math.inf要求非负维护State.integral位置误差的积分累加State.reset支持按掩码在 GPU 上清零_masked_zero_1dkernel显式模式下_pid_effort_kernel在单 kernel 内完成积分累加、wp.clamp限幅与力矩计算隐式模式下prepare_implicit通过_pid_prepare_kernel将ki * integral折入参数包的常数列求解时积分项作为该步常数处理。DriveNeuralMLP / DriveNeuralLSTM神经网络驱动DriveNeuralMLP与DriveNeuralLSTM允许用训练好的神经网络多层感知机 / LSTM 循环网络替代解析控制律直接从状态与目标计算力矩适用于学习型控制器如模仿学习、强化学习策略部署场景。它们是有状态的LSTM 需维护隐状态且与ImplicitOptions配合时通过prepare_implicit做逐步线性化见下文隐式模式。限幅Clamping力矩边界与饱和特性ClampingBasenewton/_src/actuators/clamping/base.py限幅组件堆叠在驱动之上用于约束输出力矩对称限幅、速度相关饱和、位置相关曲线等。它们从源力矩缓冲读取、向目标缓冲写入有界值当src与dst是同一数组时即为原地更新——Actuator对第一个限幅使用不同数组保留原始驱动输出后续限幅使用同一数组。模块内置三种限幅ClampingMaxEffort对称最大力矩限幅最简单的对称硬限幅|effort| max_effort是最常用的保护性边界如 add_actuator 文档示例中的{max_effort: 50.0}。ClampingDCMotor直流电机四象限力-速饱和该限幅复现直流电机的力-速特性曲线newton/_src/actuators/clamping/clamping_dc_motor.pyeffort_max(vel) min(saturation_effort * (1 - vel / velocity_limit), max_motor_effort) effort_min(vel) max(saturation_effort * (-1 - vel / velocity_limit), -max_motor_effort)零速时电机可输出至多 ±saturation_effort被max_motor_effort封顶速度接近velocity_limit时运动方向上的可用力矩降至零参数校验约束saturation_effort 0、velocity_limit 0、max_motor_effort 0当velocity_limit有限时saturation_effort必须有限否则在v v_lim处会产生inf * 0 NaN。一个实现细节角速度corner velocity即包络达到max_motor_effort的速度不再缓存而是在 kernel 内从实时参数推导corner velocity_limit * (1 max_motor_effort / saturation_effort)以避免用户重调参数后缓存过期。因此ClampingDCMotor.corner_velocity属性已在 1.6 中标记为 deprecated仅用于兼容。ClampingPositionBased位置相关限幅依据关节位置改变力矩边界用于模拟关节运动范围相关的力矩限制如软限位、随姿态变化的驱动能力。延迟Delay逐 DOF 的指令输入延迟Delaynewton/_src/actuators/delay.py使用深度为max_delay的环形缓冲延迟指令输入控制目标与前馈项每个 DOF 拥有独立的滞后步数delay_steps形状(N,)单位为执行器时间步缓冲按所有 DOF 的最大滞后值统一分配深度因此不同延迟步数的 DOF 可以共享同一执行器组缓冲状态State包含三个(buf_depth, N)的二维数组位置/速度/前馈目标与逐 DOF 的num_pushes计数、设备侧的write_idxwrite_idx放在设备侧以支持 Graph 捕获reset(mask)支持按掩码清零指定 DOF 的缓冲列并重置计数。延迟始终产生输出缓冲为空如刚复位或某 DOFdelay_steps 0时直接使用当前指令缓冲未填满时滞后被钳制到可用历史深度返回最旧的可用条目见_delay_read_kernel中lag min(delays[i] - 1, n - 1)与read_idx (write_idx - lag buf_depth) % buf_depth。显式与隐式两种力矩求解模式显式模式默认控制律在当前状态上求值步进内采用零阶保持zero-order hold。这是Actuator的默认行为_EffortModeExplicit也是step()流程第 2 步的标准路径。隐式模式set_effort_mode_implicitActuator.set_effort_mode_implicit(response, options)actuator.py将力矩计算切换到隐式模式控制律针对预测的步末状态求解然后再进入物理求解器。其数学形式newton/_src/actuators/effort_mode_implicit.pyr(p) p - h * g(q(p), qd(p)) 0 qd(p) qd A * p q(p) q h * qd(p)其中h为时间步长g为带限幅的驱动力律A为JointSpaceResponse提供的耦合逆质量响应。注意预测中只计入该执行器自身的冲量——重力、其他外力、同关节组上的其他执行器以及未走执行器路径的关节驱动都不参与预测。参数说明responseJointSpaceResponse提供耦合有效逆质量 [1/kg 或 1/(kg·m²)]需每步在step前刷新一次optionsActuator.ImplicitOptions默认值如下effort_mode_implicit.py选项默认值含义max_iters4每个关节组的最大 Newton 迭代次数residual_tol1.0e-5残差向量范数低于该值即停止 [N·s 或 N·m·s]update_tol1.0e-5冲量更新向量范数低于该值即停止 [N·s 或 N·m·s]fd_epsilon1.0e-4速度空间上的相对前向有限差分步长无量纲derivative_floor1.0e-8消元与回代时使用的最小 Jacobian 主元无量纲warm_startWarmStart.EXPLICIT初猜从钳制后的显式力矩冲量EXPLICIT或零冲量ZERO出发重要限制隐式求解不可微。若执行器以requires_gradTrue构建调用set_effort_mode_implicit会抛出NotImplementedError——Newton 求解没有伴随adjoint且神经驱动会打开自己的wp.Tape无法嵌套在外层 tape 内。文档明确建议需要可微仿真时构建Actuator(..., requires_gradFalse)指需要隐式模式时。隐式模式的支持通过DriveBase.evaluate_force/ClampingBase.evaluate_clamp这两个wp.func入口实现驱动与限幅将自身参数打包进(N, P)的二维参数数组bind_params求解 kernel 以float64精度调用prepare_implicit允许驱动在每步求解前就地重写参数包如 PID 折入积分项、神经网络按当前状态线性化。限幅按列表顺序由内向外组合_compose_clamps只有可隐式化的限幅才进入链ClampingDCMotor在隐式求解内使用预测的步末速度qd使力-速包络自洽。USD 解析从场景描述构建执行器ActuatorParsed、ComponentKind、SchemaNames、parse_actuator_prim、register_actuator_component共同构成从 USD 场景描述自动解析执行器配置的子系统newton/_src/actuators/usd_parser.py。ComponentKind执行器组件模式的分类枚举——DRIVE驱动、CLAMPING限幅、DELAY延迟三个成员ActuatorParsed解析一个 USD 执行器 prim 的结果drive_classdrive_kwargs描述驱动component_specs存放其余组件延迟、限幅的(类, kwargs)列表target_path为被驱动关节的 USD prim 路径register_actuator_component注册自定义执行器组件使parse_actuator_prim能识别用户扩展的 schemaSchemaNames集中管理各组件 schema 的命名常量。这使得执行器定义可以声明式地写在 USD 资产中与代码构建方式ModelBuilder.add_actuator互补。通过ModelBuilder.add_actuator注册执行器在模型构建阶段逐 DOF 注册外部执行器的入口是ModelBuilder.add_actuatornewton/_src/sim/builder.pymodel_builder.add_actuator( drive_classDrivePD, indexdof_index, # 指向 joint_qd 形态数组的 DOF 索引 clamping[(ClampingMaxEffort, {max_effort: 50.0})], # 后置限幅 delay_steps3, # 可选输入延迟时间步数 pos_indexNone, # 可选joint_q 形态索引默认等于 index kp100.0, kd5.0, # 透传给 drive_class 的逐 DOF 参数 )源码层面的行为要点对相同的drive_class、clamping类型与一致的共享参数多次调用会在finalize阶段合并成一个Actuator实例同一组内支持不同的delay_steps值缓冲深度按max(delay_step_values)分配drive_class.resolve_arguments(kwargs)负责解析参数并填充默认值未识别的参数会被add_actuator发出警告并忽略共享参数SHARED_PARAMS与逐 DOF 数组参数被分开处理逐 DOF 参数打包为(N,)数组pos_index在浮动基座或球关节等joint_q与joint_qd布局不同的关节上必须显式指定。1.6 版本 API 迁移Controller→Drive模块文档用专门的 Deprecated 表格列出了 1.6 版废弃的旧名称与迁移指引废弃名称迁移指引ClampingDeprecated in 1.6; useClampingBaseinsteadControllerDeprecated in 1.6; useDriveBaseinsteadControllerNeuralLSTMDeprecated in 1.6; useDriveNeuralLSTMinsteadControllerNeuralMLPDeprecated in 1.6; useDriveNeuralMLPinsteadControllerPDDeprecated in 1.6; useDrivePDinsteadControllerPIDDeprecated in 1.6; useDrivePIDinstead代码层面的实现事实newton/actuators.py新名称全部进入__all__旧名称不再出现在__all__中旧名称通过__getattr__提供兼容别名访问时发出DeprecationWarning如newton.actuators.Controller→newton.actuators.DriveBase迁移涉及的不止模块级符号Actuator(controller...)关键字、Actuator.controller属性、Actuator.State.controller_state、ActuatorParsed.controller_class/controller_kwargs、ModelBuilder.add_actuator(controller_class...)、ComponentKind.CONTROLLER全部保留兼容但触发DeprecationWarning同时指定新旧参数如drive与controller一起传会抛出TypeError(Specify only one of ...)防止歧义。该迁移行为由 newton/tests/test_actuator_drive_api.py 全面覆盖测试断言旧名称访问必然伴随 DeprecationWarning、新旧别名指向同一对象、混用新旧参数抛TypeError以及JointSpaceResponse.__init__与refresh的公开方法类型标注保持不变{model: newton.Model}与{state: newton.State}。总结newton.actuators以驱动 → 限幅 → 延迟的模块化组合为核心把关节力矩计算从物理求解器中解耦出来形成一套完全在 GPU 上批量执行的执行器系统DrivePD/DrivePID覆盖经典解析控制律DriveNeuralMLP/DriveNeuralLSTM支持学习型策略三种Clamping提供从对称限幅到电机力-速饱和的边界控制Delay提供逐 DOF 指令延迟而显式/隐式双模式让用户可在控制带宽与端步一致性之间权衡。无论是通过 Python 逐 DOF 注册ModelBuilder.add_actuator还是通过 USD 场景描述parse_actuator_prim声明都能快速接入仿真管线迁移到 1.6 时只需将Controller*家族替换为Drive*家族即可。【免费下载链接】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），仅供参考