newton 顶层 API 全解析面向 NVIDIA Warp 物理仿真引擎的核心接口、类型与常量【免费下载链接】newtonAn open-source, GPU-accelerated physics simulation engine built upon NVIDIA Warp, specifically targeting roboticists and simulation researchers.项目地址: https://gitcode.com/GitHub_Trending/newton9/newtonnewton是一个基于 NVIDIA Warp 构建的 GPU 加速物理仿真引擎面向机器人学与仿真研究人员开放。本文以仓库中 docs/api/newton.rst 记录的顶层 API 为准系统梳理import newton后可直接使用的全部公开符号——包括 11 个子模块、20 余个核心类、10 个求值函数以及 3 个常量并结合 newton/init.py 与newton/_src/下的源码实现说明每个符号的语义与使用方式。读完本文你将掌握 Newton 顶层命名空间的完整拼图从模型构建、状态与碰撞管线到运动学/动力学求值函数以及版本与布局相关的全局配置。一、顶层命名空间的设计定位Newton 的顶层包newton是一个聚合门面它不承载具体实现而是把散布在newton/_src/各子包中的核心 API 统一 re-export 到newton命名空间。这一点在 newton/init.py 中有明确体现——文件依次从._src.core、._src.geometry、._src.sim导入符号最后再导入 11 个子模块并写入__all__。因此顶层 API 按职责可划分为四组分组成员源码位置常量与配置MAXVAL、__version__、use_coord_layout_targetsnewton/_src/core/types.py、newton/_version.py核心类Model、ModelBuilder、State、Control、Contacts、CollisionPipeline、Rodnewton/_src/sim/枚举类型Axis、BodyFlags、EqType、JointTargetMode、JointType、ModelFlags、StateFlags、GeoType、ParticleFlags、ShapeFlagsnewton/_src/sim/enums.py、newton/_src/geometry/flags.py几何类型与函数Mesh、SDF、Heightfield、Gaussian、TetMesh、AxisType、intersect_ray及 9 个求值函数newton/_src/geometry/、newton/_src/sim/articulation.py 等__all__中出现的名称即是顶层包的官方可导入集合文档自动生成autosummary也以此为蓝本保证了文档、运行时与代码三者一致。二、11 个子模块一览顶层newton同时暴露了以下子模块对应 docs/api/ 下的独立 API 页面子模块文档页职责newton.actuatorsdocs/api/newton_actuators.rst驱动器drive与钳制clamping库实现位置/速度/力矩驱动newton.controllersdocs/api/newton_controllers.rst关节阻抗、差动 IK、操作空间等控制器newton.geometrydocs/api/newton_geometry.rst几何体类型、碰撞图元、惯性计算、粒子表面提取等newton.ikdocs/api/newton_ik.rst逆运动学目标定义与批量求解LM / L-BFGSnewton.mathdocs/api/newton_math.rst数学工具与空间代数newton.selectiondocs/api/newton_selection.rst实体选择与过滤辅助newton.sensorsdocs/api/newton_sensors.rstIMU、接触、平铺相机等传感器newton.solversdocs/api/newton_solvers.rst仿真求解器后端Featherstone、XPBD、VBD、Kamino、MuJoCo、隐式 MPM、Style3D 等newton.usddocs/api/newton_usd.rstUSD 相关工具与粒子处理newton.utilsdocs/api/newton_utils.rstURDF / MJCF / USD 导入、高度场、网格、下载资产等工具newton.viewerdocs/api/newton_viewer.rst交互式可视化与录制这些子模块在 newton/ 根目录下均有同名公开入口文件如 newton/solvers.py、newton/ik.py它们通常是薄封装以 newton/ik.py 为例它仅从._src.sim.ikre-exportIKObjective、IKObjectivePosition、IKObjectiveRotation、IKObjectiveJointLimit、IKOptimizer、IKOptimizerLM、IKOptimizerLBFGS、IKSampler、IKSolver、IKJacobianType等符号而 newton/solvers.py 更进一步实现了按需惰性加载__getattr___LazyCoupledModule把newton.solvers.experimental.coupled等重模块推迟到首次访问时才 import降低基础导入开销。三、常量与全局配置顶层文档明确列出三个常量其中前两个定义于源码第三个是一个模块级开关。3.1MAXVAL 10000000000.0MAXVAL即1e10在 newton/_src/core/types.py 中定义为大有限哨兵值用于表示无限制 / 无命中 / 无效标记其语义对齐 MuJoCo 的mjMAXVAL。文档明确建议用它代替inf以避免verify_fp对无穷值的误报与体素采样数据比较时使用 wp.static(MAXVAL * 0.99)以容忍插值引入的浮点误差。这一常量在关节限位、SDF 查询等场景中作为默认无界值被广泛使用例如JointDofConfig的limit_lower-MAXVAL、limit_upperMAXVAL见 newton/_src/sim/builder.py。3.2__version__ 1.7.0.dev0文档当前记录的版本为1.7.0.dev0。源码层面 newton/_version.py 通过importlib.metadata.version(newton)从已安装的包元数据读取版本读取失败时回退为字符串unknown——因此实际运行时的值取决于安装方式文档中固定写出的1.7.0.dev0是文档生成时的版本快照。3.3use_coord_layout_targets True这是顶层模块中的一个布尔开关控制关节位置目标的数组布局完整说明见 newton/init.pyTrue默认Model.joint_target_q与Control.joint_target_q的形状为(joint_coord_count,)与State.joint_q的坐标布局对齐False使用旧的(joint_dof_count,)DOF 布局——当关节链中存在位于位置受控 DOF 上游的 free、ball 或 distance 关节时该布局会与State.joint_q错位。无论哪种布局joint_target_qd始终为(joint_dof_count,)与State.joint_qd一致。求解器、执行器库、导入器与查看器都会遵循该开关因此它必须在构造ModelBuilder之前切换。该开关自 1.5 起标记弃用未来版本将只保留坐标布局并移除该开关finalize()在False下构建坐标数与 DOF 数不一致的模型时会发出警告。这是迁移旧代码时最需要注意的一个兼容性点。四、核心枚举类型顶层公开的枚举大多集中在 newton/_src/sim/enums.py它们是配置模型与驱动仿真状态的关键类型。4.1Axis与AxisTypeAxis是 3D 轴枚举X0、Y1、Z2定义于 newton/_src/core/types.py除基本枚举外还提供from_string(x/y/z)、from_any(...)、to_vector()返回单位向量、to_vec3()、quat_between_axes()等辅助方法且__eq__支持与字符串、整数直接比较。AxisType则是其联合类型Axis | Literal[X,Y,Z] | Literal[0,1,2] | int | str。也就是说任何需要轴参数的位置如add_joint_revolute(axis...)、ModelBuilder(up_axis...)都可以传入枚举、字符串或整数。4.2BodyFlags刚体动力学状态DYNAMIC 1 0参与仿真动力学计算的动态体KINEMATIC 1 1由用户指定位姿、不响应外力的运动学体PROXY 1 2耦合求解器视图局部的代理体标记实验性见experimental命名空间约定ALL DYNAMIC | KINEMATIC | PROXY过滤掩码用于eval_fk等 API 的body_flag_filter参数不是合法的存储状态。每个 finalize 后的模型刚体必须恰好存储DYNAMIC或KINEMATIC之一。4.3StateFlags状态刷新/复位掩码StateFlags是位掩码枚举用于描述State中哪些属性被更新或被复位也被耦合接口用来描述哪些公开状态输入被更新成员位含义JOINT_Q/JOINT_QD10 / 11关节位置坐标 / 速度坐标BODY_Q/BODY_QD12 / 13最大坐标刚体位姿 / 速度PARTICLE_Q/PARTICLE_QD14 / 15粒子位置 / 速度BODY_F/PARTICLE_F/JOINT_F16 / 17 / 18三类力输入数组另有组合掩码BODY BODY_Q | BODY_QD、PARTICLE ...、JOINT ...、FORCE BODY_F | PARTICLE_F | JOINT_F、ALL。SolverBase.reset接受该掩码以控制复位范围。4.4ModelFlags模型变更通知ModelFlags用于配合SolverBase.notify_model_changed声明哪些属性被修改了使求解器只需重建必要部分。其位定义覆盖关节属性JOINT_PROPERTIES、关节 DOF 属性目标增益、阻尼、力矩限制、armature、摩擦、限位等、刚体属性、刚体惯性属性、形状属性、模型全局参数重力、约束属性equality 约束与 mimic 关系、肌腱属性、执行器属性以及全量ALL。4.5JointType关节类型JointType枚举支持PRISMATIC1 DoF 平动、REVOLUTE1 DoF 转动、BALL3 DoF 角速度 / 4 坐标四元数、FIXED0 DoF、FREE6 DoF / 7 坐标、DISTANCE6 DoF / 7 坐标、D6通用 6-DoF、以及ROD四组 VBD 材料槽拉伸/剪切/弯曲/扭转。注意CABLE是ROD的弃用别名——访问JointType.CABLE会触发DeprecationWarning自 1.6 起代码中应改用JointType.ROD。JointType还提供两个实用的维度方法dof_count(num_axes) - (dof_count, coord_count)返回速度 DoF 数与位置坐标数。例如 BALL 为(3, 4)FREE/DISTANCE 为(6, 7)FIXED 为(0, 0)constraint_count(num_axes) - int返回该关节对应的速度级双边运动约束数。PRISMATIC/REVOLUTE 为56−1BALL 为3FREE/DISTANCE 为0FIXED 为6。4.6EqType等距约束类型已弃用EqTypeCONNECT/WELD/JOINT自 1.4 起弃用是newton.solvers.SolverMuJoCo.EqType的别名。访问或调用都会触发DeprecationWarning新代码请直接使用求解器命名空间下的类型。4.7JointTargetMode关节执行器模式该枚举管理关节 DOF 的驱动方式并用于 MuJoCo 求解器场景下决定是否为某个 DOF 安装显式执行器NONE不安装执行器关节被动POSITION仅位置执行器跟踪joint_target_qVELOCITY仅速度执行器跟踪joint_target_qdPOSITION_VELOCITY同时安装位置与速度执行器EFFORT施加驱动但不配置增益不创建 MuJoCo 执行器期望用户通过joint_f供力。静态方法from_gains(target_ke, target_kd, force_position_velocityFalse, has_driveFalse)可依据位置/速度增益自动推断模式有驱动且双增益非零 →POSITION_VELOCITY仅位置增益 →POSITION仅速度增益 →VELOCITY双零 →EFFORT无驱动 →NONE。MuJoCo 的通用执行器motor、general 等则通过mujoco:actuator自定义属性与control.mujoco.ctrl单独处理不走此枚举。五、几何类型与碰撞相关类顶层还暴露一组几何类型与碰撞管线类Mesh、TetMesh网格与四面体网格数据容器SDF符号距离场在 newton/_src/geometry/sdf_utils.py 中定义配合configure_sdf()生成用于 SDF 接触与 hydroelastic 接触Heightfield高度场地形Gaussian用于水动力/软接触的高斯密度表达GeoType几何类型枚举ShapeFlags、ParticleFlags形状与粒子标志见 newton/_src/geometry/flags.py。CollisionPipelinenewton/_src/sim/collide.py是碰撞检测的运行时管线构造函数支持大量调优参数reduce_contacts、rigid_contact_max、broad_phasenxn/sap/explicit三种模式分别对应全配对、扫描线与显式配对、narrow_phase、deterministic、contact_matchingdisabled/latest/sticky等。其核心入口是collide(state, contacts, ...)内部依次完成形状 AABB 计算、宽相配对、窄相检测与接触写出Contacts对象则承载每一帧检测出的接触数据法向、穿透距离、接触点等并支持request_contact_attributes扩展自定义接触属性。相关验证见 newton/tests/test_collision_pipeline.py 等测试。六、模型构建四件套ModelBuilder / Model / State / Control6.1ModelBuilder声明式建模入口文档建议始终通过ModelBuilder构造模型直接实例化并手工填充Model字段虽可行但不推荐。ModelBuildernewton/_src/sim/builder.py提供了丰富的声明式 API刚体add_body()/add_link()带mass、inertia、com、is_kinematic、lock_inertia等参数关节add_joint_fixed()、add_joint_revolute()、add_joint_prismatic()、add_joint_ball()、add_joint_free()、add_joint_distance()、add_joint_d6()、add_joint_rod()及弃用的add_joint_cable()每个关节都支持限位limit_lower/upper/ke/kd、目标target_pos/vel/ke/kd、阻尼、armature、力矩/速度限制、摩擦、actuator_mode等参数形状add_shape_plane()、add_shape_sphere()、add_shape_box()、add_shape_capsule()、add_shape_cylinder()、add_shape_cone()、add_shape_mesh()、add_shape_convex_hull()、add_shape_heightfield()、add_shape_gaussian()、add_ground_plane()可变形体add_particle(s)、add_cloth_grid()、add_cloth_mesh()、add_soft_grid()、add_soft_mesh()、add_rod()、add_rod_graph()导入add_urdf()、add_usd()、add_mjcf()以及多世界编排begin_world()/end_world()/add_world()、复制replicate()收尾finalize(deviceNone, requires_gradFalse, skip_all_validations..., ...)生成Model。JointDofConfig可在builder.add_joint_revolute(axisModelBuilder.JointDofConfig(...))中按 DOF 精细配置的默认参数在源码中有明确默认值limit_lower-MAXVAL、limit_upperMAXVAL、limit_ke1e4、limit_kd1e1、target_ke0.0、target_kd0.0、damping0.0、armature0.0、effort_limit1e6、velocity_limit1e6、friction0.0。6.2Model静态模型定义Modelnewton/_src/sim/model.py封装仿真所需的全部静态数据粒子、刚体、关节、形状、软/刚体单元等并支持按世界world分组——索引-1表示跨世界共享的全局实体0,1,2,...为各世界专属实体。分组带来三方面收益碰撞检测优化、可视化空间分离、以及独立世界的并行处理。Model还提供state()/control()/contacts()/collide()等便捷方法以及set_gravity()、request_state_attributes()、自定义属性add_attribute、AttributeFrequency、AttributeAssignment等扩展机制。测试见 newton/tests/test_model.py。6.3State与ControlState可变的仿真状态关节坐标joint_q/joint_qd、刚体位姿body_q/body_qd、粒子particle_q/particle_qd、力输入等支持clear_forces()、assign()、requires_grad()Control每帧输入控制量其joint_target_q/joint_target_qd的布局受use_coord_layout_targets开关影响见 3.3 节。七、顶层求值函数运动学与动力学顶层公开了 10 个函数其中 9 个是求值器统一接收model与state部分接收contacts实现见 newton/_src/sim/articulation.py、newton/_src/sim/inverse_dynamics.py、newton/_src/sim/contact_kinematics.py、newton/_src/sim/joint_mimic.py、newton/_src/geometry/raycast.py。7.1 正向/逆向运动学eval_fk、eval_ikeval_fk(model, joint_q, joint_qd, state, maskNone, indicesNone, body_flag_filterBodyFlags.ALL)根据关节坐标/速度计算刚体位姿与速度底层调用eval_articulation_fk支持按mask/indices选择关节链、按body_flag_filter过滤刚体类型eval_ik(model, state, joint_q, joint_qd, maskNone, indicesNone, body_flag_filterBodyFlags.ALL)逆向操作从刚体位姿反解关节坐标/速度eval_articulation_ik。7.2 雅可比与质量矩阵eval_jacobian、eval_mass_matrixeval_jacobian(model, state, JNone, joint_S_sNone, maskNone)计算刚体雅可比矩阵J输出形状[body_count, 6, joint_dof_count]内部调用eval_articulation_jacobianeval_mass_matrix(model, state, HNone, JNone, body_I_sNone, joint_S_sNone, maskNone)计算关节空间质量矩阵内部先算雅可比再聚合H J^T I_s J。7.3 逆动力学eval_inverse_dynamics_force、eval_inverse_dynamics_passiveeval_inverse_dynamics_force(model, state, *, mass_matrix, joint_qdd, coriolis_force, gravity_force, joint_f, maskNone)给定质量矩阵、期望加速度与各力项直接组装广义力taueval_inverse_dynamics_passive(model, state, *, mass_matrixNone, gravity_forceNone, coriolis_forceNone, maskNone)计算被动分量——即重力项与科里奥利项底层对应_compute_gravity_force/_compute_coriolis_force与_rnea_compensation_pass递归牛顿-欧拉补偿。相关基准见 asv/benchmarks/simulation/bench_inverse_dynamics.py。7.4 其余求值函数eval_mimic(model, state_in, state_outNone)把 mimic联动关节的目标joint_q/joint_qd按其系数joint_mimic_coeffs写入目标关节使一组关节按比例跟随参考关节eval_rigid_contact_kinematics(model, state, contacts, *, out_distance, out_point0_world, out_point1_world)在不改变接触集合的前提下对刚体接触输出逐接触的穿透距离与两个接触点世界系常用于微分接触与后处理分析intersect_ray(...)几何模块的射线求交函数源自 newton/_src/geometry/raycast.py。这些求值器全部面向 GPU 数组Warpwp.array批量运算天然支持mask局部求值与requires_grad自动微分可直接嵌入 RL 训练或可微仿真管线。八、典型用法从示例看顶层 API 的组装仓库中的 newton/examples/basic/example_basic_joints.py 演示了顶层 API 的典型组装流程import warp as wp import newton builder newton.ModelBuilder() static_cfg newton.ModelBuilder.ShapeConfig() static_cfg.density 0.0 builder.add_ground_plane() # 地面 # 1. 添加刚体 a_rev builder.add_link(xformwp.transform(pwp.vec3(0.0, y, drop_z upper_hz), qwp.quat_identity())) b_rev builder.add_link(xformwp.transform(...), labelb_rev) # 2. 添加形状 builder.add_shape_box(a_rev, hx0.1, hy0.1, hz0.25 * 0.75, cfgstatic_cfg) builder.add_shape_box(b_rev, hx0.1, hy0.1, hz0.75) # 3. 添加关节FIXED / REVOLUTE / PRISMATIC / BALL / DISTANCE ... builder.add_joint_fixed(parent-1, childa_rev) builder.add_joint_revolute(parenta_rev, childb_rev, axiswp.vec3(1.0, 0.0, 0.0), ...)示例同时展示了求解器驱动的仿真循环结构model builder.finalize(device...)→state model.state()→control model.control()→ 每帧model.collide(state, contacts)→ 求解器步进 →viewer.log_state(state)/viewer.log_contacts(contacts, state)。运行方式为python -m newton.examples basic_joints --solver xpbd # 可选 --solver vbd顶层 API 的稳定性由测试保障例如 newton/tests/test_api.py 与 newton/tests/test_model.py 会验证公开符号的导入与基本行为求解器选择的更完整指导可参考 docs/solvers/index.rst 与 docs/api/newton_solvers.rst。九、版本与迁移提示最后汇总docs/api/newton.rst与源码中标注的弃用/兼容信息帮助你在升级时快速定位改动点EqType自 1.4 弃用改用newton.solvers.SolverMuJoCo.EqTypeJointType.CABLE自 1.6 弃用改用JointType.RODuse_coord_layout_targetsFalse的旧 DOF 布局自 1.5 弃用未来版本将只保留坐标布局版本号文档快照为1.7.0.dev0运行时以安装元数据为准。理解这套顶层 API 是使用 Newton 的第一步——它把构建模型 → 求值运动学/动力学 → 碰撞检测 → 求解器步进的完整链路浓缩在一个import newton的命名空间中值得作为阅读 docs/api/ 其余子模块文档的起点。【免费下载链接】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），仅供参考