Newton 耦合求解器框架（newton.solvers.experimental.coupled）深度解析：跨求解器的 Proxy 与 ADMM 多物理耦合

Newton 耦合求解器框架（newton.solvers.experimental.coupled）深度解析：跨求解器的 Proxy 与 ADMM 多物理耦合

【免费下载链接】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.solvers.experimental实验性命名空间为主体，系统讲解 Newton 耦合求解器框架的核心 API（ModelView、CouplingInterface、SolverCoupled、SolverCoupledProxy、SolverCoupledADMM），并结合仓库源码剖析共享 Model、入口视图所有权、Proxy 滞后迭代与 ADMM 对称约束两种耦合路径的调用机制，帮助读者掌握"刚体求解器 + VBD/XPBD/MPM 软体求解器"混合场景的构建与调参方法。

1. 为什么需要耦合求解器：一个 Model，多个后端

Newton 的定位是构建在 NVIDIA Warp 之上的 GPU 物理引擎，其稳定求解器（SolverMuJoCo、SolverKamino、SolverVBD、SolverXPBD、SolverImplicitMPM、SolverStyle3D、SolverFeatherstone、SolverSemiImplicit，见 newton/solvers.py 与 newton/_src/solvers/init.py 的惰性导入表_LAZY_IMPORTS）各自擅长不同材料模型。而真实场景经常把"不同求解器各自最擅长的部分"拼在一起：MuJoCo/Kamino 驱动的刚性机构、VBD 布料、XPBD 颗粒与 MPM 材料的交互，或者用 ADMM 约束连接的刚体-粒子系统。

耦合框架让"一个仿真步"可以拆给多个求解器后端执行，同时这些后端通过一个共享的newton.Model交换力、位姿与约束信息。这正是 newton/_src/solvers/coupled/ 目录下 9 个模块所实现的内容。

该框架刻意暴露为实验性命名空间而非newton.solvers上的扁平符号，导入方式必须显式写明：

from newton.solvers import SolverMuJoCo, SolverVBD from newton.solvers.experimental.coupled import ( SolverCoupledADMM, SolverCoupled, SolverCoupledProxy, )

从 newton/solvers.py 的源码可以看到，experimental与experimental.coupled是通过_LazyCoupledModule惰性加载的模块对象：只有在真正访问newton.solvers.experimental.coupled.SolverCoupledProxy时才导入newton._src.solvers.coupled，从而不拖累常规求解器的导入路径。这也说明该 API 属于实验性质，接口可能变化，适合受控实验与求解器集成工作。

框架的五个核心类型（newton/_src/solvers/coupled/init.py）：

完整的概念文档见 docs/concepts/coupling.rst，本文在其基础上补充源码级证据。

2. 共享 Model、入口视图与所有权：ModelView 的实现机制

耦合仿真从单个newton.Model出发，但每个子求解器拿到的不是裸 Model，而是一个ModelView。其设计目标是：子求解器看到相同的模型拓扑，但只"拥有"分配给本入口的刚体、粒子、关节或形状。

ModelView的实现（newton/_src/solvers/coupled/model_view.py）有三个要点：

1. 读穿透（read-through）委托：__getattr__中所有未被视图覆盖的属性都回落到父 Model（getattr(parent, name)），因此可以像普通Model一样把视图传给SolverFoo(model=view)构造子求解器。
2. 写时覆盖 + 类型校验：__setattr__只允许覆盖父 Model 存在的属性，并用_types_compatible()校验wp.array的 dtype/ndim/device、np.ndarray的 dtype/ndim，防止视图悄悄改变数组布局。
3. copy-on-write（写时复制）：视图提供一族修改器方法，第一次修改某数组时才克隆父数组（_cow_array()），父 Model 永不被改动。文档中的原话是："ModelViewapplies view-local changes with copy-on-write semantics so the coupler can hide, immobilize, or rescale endpoints without changing the parent model."

ModelView提供的关键修改器（每个方法都只写视图本地的克隆数组，底层是wp.kernel批量更新）：

• disable_body_dynamics(body_indices)：置零选定刚体的body_inv_mass/body_inv_inertia（逆动力学属性），把非拥有刚体变成不动端；
• scale_body_mass(body_indices, factor)：按factor缩放body_mass、body_inertia（同时反缩放逆质量与逆惯性张量）。源码注释明确说明用途：小于 1 让代理刚体更轻（耦合更软），大于 1 更重；
• mark_proxy_bodies/mark_proxy_particles：在视图本地body_flags/particle_flags上 OR 进BodyFlags.PROXY/ParticleFlags.PROXY位，父模型不变；
• disable_particles、zero_particle_mass、scale_particle_mass、set_particle_mass：粒子侧对应操作，其中scale_particle_mass的文档注明"Used by the ADMM coupler to inject the proximal term as a mass rescaling"；
• disable_joints：置位joint_enabled=False，并把ROD类型关节替换为D6；
• set_body_inertial_properties/add_body_lumped_inertia/add_particle_lumped_mass：设置完整惯性张量或叠加集中质量/各向同性惯性。

ModelView.state()会用视图本地的数量重跑Model.state()（通过_TemporaryStateArrayOverrides上下文临时裁剪particle_q、body_q等源数组），因此子求解器在视图上创建的State也只覆盖本视图拥有的实体。

入口（Entry）与所有权声明

一个SolverCoupled.Entry描述一个子求解器及其拥有对象。构造阶段的流程是：为每个入口创建 Model 视图 → 在视图上禁用/缩放非拥有端点 → 调用入口的solver(view)工厂构造子求解器 → 保留每个入口的输入/输出State。一个典型入口声明（来自官方概念文档）：

entry = SolverCoupled.Entry( name="soft", solver=lambda view: SolverVBD(model=view, iterations=20, rigid_compliant_alm=True), bodies=soft_body_ids, particles=cloth_particle_ids, shapes=cloth_shape_ids, substeps=2, )

substeps允许单个求解器以更小的时间间隔推进。顶层步执行后，只有各入口"拥有"的输出会被对齐回调用者的共享state_out，防止两个子求解器互相覆盖同一个刚体/粒子，除非显式耦合算法负责仲裁。

共享基类SolverCoupled还负责：按入口的 substep 调度、把State与Control中的公开力输入复制到入口本地状态、入口本地的碰撞可见性与形状所有权、给有私有历史缓冲的求解器发输入状态通知、以及从公开模型质量/惯性数组回退估计有效质量。

3. CouplingInterface：耦合钩子协议

一些求解器把关键状态放在公开State数组之外，或能比通用动量回退更精确地报告接口力。这些求解器通过继承CouplingInterface（newton/_src/solvers/coupled/interface.py）提供钩子。钩子都是"带默认实现的普通方法"，只需重写需要自定义的部分；无法支持某钩子的求解器应重写为抛NotImplementedError，而不是悄悄走无效路径。

钩子契约（源码模块 docstring 中给出的完整签名清单）：

def coupling_eval_effective_mass(endpoint_kind, endpoint_index, endpoint_local_pos, out) -> None: ... def coupling_eval_effective_mass_block( endpoint_kind, endpoint_index, endpoint_local_pos, out_mass, out_inertia=None ) -> None: ... def coupling_notify_input_state_update(state, flags, *, iteration_restart=False, dt=0.0) -> None: ... def coupling_supports_inertial_property_refresh() -> bool: ... def coupling_supports_full_surface_soft_contacts() -> bool: ... def coupling_rewind_proxy_body( body_local_to_proxy_global, state, coupling_forces, body_gravity_acceleration, dt ) -> None: ... def coupling_rewind_proxy_particle( particle_local_to_proxy_global, state, coupling_forces, particle_gravity_acceleration, dt ) -> None: ... def coupling_harvest_proxy_wrenches( body_local_to_proxy_global, out_body_f, *, body_qd_before, state, state_out, contacts, dt, ) -> None: ... def coupling_harvest_proxy_particle_forces( particle_local_to_proxy_global, out_particle_f, *, particle_qd_before, state, state_out, contacts, dt, ) -> None: ... def coupling_prepare_proxy_contacts(state, contacts, *, contacts_freshly_detected=False): ...

几个实现细节值得注意：

• 端点数组采用 SoA 布局：endpoint_kind存EndpointKind.BODY(0)/PARTICLE(1)，endpoint_index存求解器视图内的本地刚体/粒子 id，endpoint_local_pos存刚体坐标系下的端点位置（粒子为 0）。
• 默认有效质量估计：coupling_eval_effective_mass的默认实现会检查模型上body_inv_mass/particle_inv_mass是否存在，分四种分支启动不同的 Warp kernel；两者都没有时输出 0（_coupling_zero_mass_kernel）。coupling_eval_effective_mass_block的惯性回退有一个约束：对每个轴，刚体有效惯性不得小于模型惯性（kernel 中inertia * max(out_mass/mass, 1.0)）。
• 重力加速度钩子：coupling_eval_gravity_acceleration默认按gravity[body_world[i]]逐端点取值。代理与 ADMM 耦合器会把这些加速度数组显式传给 rewind/harvest 钩子，使做了重力缩放或补偿的求解器不会重复施加重力。
• 默认 harvest 的动量回退：coupling_harvest_proxy_wrenches默认实现要求state_out.body_qd存在且dt > 0，用harvest_proxy_momentum_forces_kernel从"求解前后的动量差"估计反馈力；粒子侧默认只处理ParticleFlags.ACTIVE的粒子。文档特别强调：这是回退方案，接触密集或求解器私有交互的场景应优先实现自定义 harvest 钩子。
• 默认代理接触过滤：coupling_prepare_proxy_contacts用filter_proxy_rigid_contacts_kernel剔除代理-静态、代理-代理刚体接触——因为通用动量 harvest 把代理反馈当作目标端动量变化，若再把两个虚拟对象之间的约束回喂源端就会造成双计。

另外两点边界：力注入本身不是钩子（耦合器直接写公开的state.body_f、state.particle_f、control.joint_f缓冲区，再走正常求解器步进）；虚拟/近端质量修改则是改ModelView并走正常notify_model_changed()路径刷新私有缓存。

4. Proxy 耦合：滞后代理与参数详解

Proxy 耦合把"由一个求解器拥有的端点"表示为"另一个求解器里的代理端点"：源求解器拥有真实对象，目标求解器收到带缩放虚拟惯性的代理刚体/代理粒子，针对代理求解自己的局部问题，然后在后续 pass 或迭代中把反馈送回源端。

这对"子步内天然单向、但可通过重复滞后迭代收敛"的耦合算法非常合适：例如刚体作为代理碰撞体进入软体求解、XPBD 粒子驱动 MPM 迁移粒子、VBD 把接触力回传给刚体源。

SolverCoupledProxy 配置

solver = SolverCoupledProxy( model, entries=[rigid_entry, soft_entry], coupling=SolverCoupledProxy.Config( proxies=[ SolverCoupledProxy.Proxy( source="rigid", # 源入口名 destination="soft", # 目标入口名 bodies=robot_body_ids, # 源端点 proxy_bodies=robot_proxy_body_ids, # 目标端代理端点 particles=(), proxy_particles=(), mass_scale=0.25, # 目标视图中代理质量/惯性缩放 mode="lagged", # 或 "staggered" proxy_relaxation=0.5, # 反馈松弛系数 ) ], iterations=4, ), )

参数语义（依据官方概念文档 +ModelView源码）：

• source/destination命名入口；bodies、particles是源端点，proxy_bodies、proxy_particles是目标端点；某代理列表为None时复用源索引；
• mass_scale在目标视图中缩放代理刚体的质量/惯性与代理粒子质量（底层走ModelView.scale_body_mass/scale_particle_mass）；
• proxy_relaxation在每次目标求解后把 harvest 的反馈与上一轮滞后反馈缓冲做混合：小于 1 为欠松弛（更稳）、等于 1 保持 harvest 反馈不变、大于 1 为过松弛（更快但更脆）；
• 代理局部碰撞检测是可选的：代理可以提供接收目标ModelView的collision_pipeline工厂，若返回 pipeline，耦合器持有持久接触缓冲并按collide_interval刷新，内层代理迭代复用该结果；返回None或未提供工厂时，目标求解使用外层step()传入的接触。

两种调度模式

• LAGGED：把源端"开始时位姿 + 结束时速度"同步到目标代理，回卷目标代理速度中已被施加过的反馈、公开力输入与重力，然后步进目标端。这是最常用的"松弛不动点"模式；
• STAGGERED：把源端"结束时位姿与速度"直接同步到目标端，并跳过通用滞后回卷，适用于调度本身已给目标端提供了当前源端状态的场景。

目标步进后，耦合器执行 harvest：若目标求解器实现了 body/particle harvest 钩子，钩子可报告接触原生力或迁移冲量；否则使用共享动量回退估计。

代理循环当前最多支持两个求解器入口；在此限制内，刚体与粒子映射按(source, destination)分组，一轮代理迭代内对每对求解器执行一次源端步进 + 一次目标端步进，因此单条代理声明可以同时携带刚体与粒子映射。

实际示例：刚体-VBD 耦合布料

仓库示例 newton/examples/multiphysics/example_mujoco_vbd_coupled_solver.py 演示了完整链路：自由刚体箱 + 铰接摆链（由SolverMuJoCo或SolverKamino驱动）与 VBD 布料和软体交互，形变端的接触力回传使刚体反弹并落定。示例要点：

from newton.solvers.experimental.coupled import SolverCoupledProxy from newton.solvers import SolverKamino, SolverMuJoCo, SolverVBD # --rigid-solver mujoco|kamino 选择刚体后端 # 直接通过 SolverCoupledProxy 构建 rigid/VBD proxy 耦合

运行方式：

python -m newton.examples mujoco_vbd_coupled_solver python -m newton.examples mujoco_vbd_coupled_solver --solver vbd # 单一 VBD 参考基线

同目录还有一组耦合示例：example_mujoco_mpm_coupled_solver.py、example_xpbd_vbd_coupled_solver.py、example_vbd_mpm_coupled_solver.py 覆盖 VBD↔MPM、XPBD↔VBD 等组合；ADMM 路径见 example_admm_contact_solver.py 与 example_mujoco_vbd_admm_solver.py。

5. ADMM 耦合：对称约束路径

ADMM 耦合是"对称"路径：不在其他求解器里放虚拟代理，而是在不同入口拥有的端点之间构造接口行。每次迭代：恢复入口状态 → 配置了 proximal 速度目标时施加 → 让子求解器推进 → 解局部接口行 → 更新对偶变量 → 把等值反号的耦合力 splat 回端点力缓冲区。

与 proxy 相比，ADMM 对子求解器侵入更小（入口不需要表示代理体、过滤代理接触或 harvest 代理反馈），代价是耦合器必须显式实现每种受支持的接口行，且瞬态接触与刚性附件通常需要每步多轮耦合迭代。

支持的行来源

• 跨求解器模型关节：仅当连接的两个刚体分属不同入口、且关节本身不被任一子求解器拥有时由耦合器接管（避免同一约束被解两次）。当前通用路径支持BALL、FIXED、REVOLUTE：球关节生成平移锚点重合行；固定关节附加角度行；旋转关节保持铰链轴并可根据模型关节摩擦附加干摩擦行。PRISMATIC、距离关节与 D6 行尚不在实验性 API 内。
• body-particle 附件：一个端点是粒子、无法用模型关节表示的接口。SolverCoupledADMM.add_body_particle_attachment()会在coupling:body_particle_attachment自定义属性下登记 body id、particle id、体局部点、刚度、阻尼与启用状态；导入器也可以直接写同名的自定义属性。端点未拥有或同入口拥有的行被忽略，只有跨求解器附件由 ADMM 耦合。
• 接触行：由Config.contact_pairs中的ContactPair显式开启，SolverCoupledADMM.auto_detect_contact_pairs(entries)可为所有入口两两组合生成完整列表。启用后耦合器持有私有检测数据，按求解器所有权建行：粒子条目与其他入口刚体上形状之间的粒子-形状行、跨入口形状对的刚体-刚体行、跨入口粒子集经私有 hash-grid 流产生的粒子-粒子行。摩擦系数在建行时从shape_material_mu、Model.particle_mu等模型材料属性读取（不是ContactPair字段）。接触行使用各向同性 Coulomb 最大耗散投影，不直接解锥互补。

SolverCoupledADMM.Config 参数

源码 newton/_src/solvers/coupled/solver_coupled_admm.py 中Config默认值（节选，含单位）：

ADMM 接触缓冲是定容设备数组；持久接触通过稳定的接触键跨步热启动局部变量与对偶变量；粒子-粒子流是接触式、hash-grid 基础的，但属于 ADMM 耦合器内部实现，不应作为公开接触流使用。

当gamma > 0时，耦合器会在每个入口的ModelView中缩放拥有的刚体/粒子质量（利用上文ModelView.scale_body_mass/scale_particle_mass），请子求解器刷新模型派生缓存，并把入口输入速度向上一轮 ADMM 迭代移动；端点有效质量有求解器钩子就用钩子，否则用模型回退。这样既兼容能给出机构质量估计的求解器（如 MuJoCo Warp 的 GPU 有效质量钩子），也让更简单的求解器可以参与。

6. 求解器特有的钩子行为

各后端只在公开模型/状态行为不足时依赖自定义钩子：

• VBD：使用代理接触准备、body-proxy harvest 与输入状态通知。通知钩子让 VBD 在代理位姿同步或 ADMM 迭代重启时保持私有的上一帧刚体状态对齐；harvest 路径把最终的刚体-刚体与刚体-粒子接触力直接缩放到代理刚体上，而不是依赖聚合动量差。VBD 还支持代理关节：SolverCoupledProxy会在目标视图中保持已配置的 fixed/prismatic/revolute 关节（或其proxy_joints别名）启用，使约束继续在代理刚体之间起作用；对单自由度驱动，耦合器会把源端 target 重映射到目标本地索引，并在每次目标求解前复制joint_target_q、joint_target_qd。
• Implicit MPM：支持代理刚体/代理粒子的 rewind/harvest 钩子。transfer-active 代理粒子可参与 P2G/G2P 动量迁移，同时被排除在材料体积、应力、应变与本构更新之外；通过 collider-particle id 注册的形变碰撞粒子走碰撞冲量收集而非材料迁移。
• XPBD：粒子接触 kernel 理解代理粒子与代理刚体；拥有粒子可与目标代理粒子碰撞，但代理-代理、代理-静态、代理粒子对代理刚体的接触会被过滤，避免目标求解在两个代理端点之间产生反馈。
• MuJoCo：提供来自 MuJoCo Warp 数据的 GPU 有效质量钩子，使代理虚拟惯性与 ADMM 端点权重使用机构质量估计而非裸刚体质量。

7. Proxy 还是 ADMM：选型与当前限制

选 Proxy 当：一个求解器可以把另一个求解器的端点合理地当作障碍、迁移参与者或虚拟体来对待一个子步。它对碰撞体式交互更好调参，可复用目标求解器的接触机制，并且是目前支持 MPM transfer-active 代理粒子与形变碰撞粒子的路径。

选 ADMM 当：接口应当表示为入口之间的对称约束或摩擦接触：跨求解器关节、body-particle 附件、需要等值反号力的接触行。它更结构化，但调参更多、受支持的行类型更窄。

两者共享同一套基础概念：Model 视图、所有权、入口本地状态、力缓冲注入、输入状态通知与有效质量钩子。同一场景往往两种建式都可以，数值行为却不同：Proxy 类似"针对求解器特定动力学的松弛不动点迭代"，ADMM 类似"跨入口求解器与接口行的定迭代约束优化分解"。

当前实验性限制（写作使用时务必留意）：

• Proxy 稳定性对调参敏感：虚拟惯性缩放、接触刚度、求解器迭代数、lagged/staggered 调度都会显著影响阻尼与收敛；
• 通用动量 harvest 只是回退，求解器私有的接触模式应尽可能暴露自定义 harvest 钩子；
• ADMM 接触检测是内部的，不把调用方的任意Contacts行作为公开接口流；
• ADMM 关节支持仅限 ball/fixed/revolute 行；粒子-粒子 ADMM 接触用私有流；
• 无自定义钩子时有效质量加权回退到简单的模型质量/惯性；
• USD 所有权声明、自动耦合求解器构建与高层调参指南尚不属于实验性公开 API；
• 全表面（边/面）刚-软接触目前仅SolverVBD消费：入口级接触过滤会为其丢弃其他子求解器的这类记录，且仅当该入口拥有记录引用的所有角点时才保留给 VBD；跨两个入口的记录会被双方丢弃；代理粒子完全不支持。

官方建议：把耦合求解器当作面向受控实验与求解器集成工作的进阶特性，在新示例中优先配合聚焦的回归测试与显式的场景调参使用。

8. 小结与延伸阅读

newton.solvers.experimental.coupled提供了一套完整的"一个共享 Model + N 个求解器视图"的多物理耦合基建：ModelView用 copy-on-write 实现所有权隔离，CouplingInterface用带默认实现的标准钩子吸收求解器差异，SolverCoupledProxy与SolverCoupledADMM分别覆盖松弛不动点与定迭代 ADMM 两条收敛路径。理解这三层之后，newton/examples/multiphysics/ 下 rigid-soft、ADMM、VBD↔MPM、XPBD↔VBD 各示例都可以按同一套模型阅读：入口声明 → 视图修改 → 代理/接触行声明 → 迭代调参。

延伸阅读：docs/concepts/coupling.rst（官方概念文档）、docs/solvers/index.rst（求解器选型指南）、newton/_src/solvers/coupled/ 源码（interface.py钩子契约、solver_coupled_admm.py中Config的完整 docstring）。

【免费下载链接】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