VBD 求解器

VBD 求解器#

顶点块下降（Vertex Block Descent，VBD）是用于布料和软体仿真的 Newton 求解器。在 Isaac Lab 中，选择 solver_cfg 为 VBDSolverCfg 的 NewtonCfg ，即可启用 VBD。

一个能在 PhysX 或 Newton 的 MuJoCo-Warp 求解器下运行的任务，仍可能需要调整可变形资产、材料、接触和耦合设置，才能在 VBD 下取得良好效果。

VBD 通常通过任务专用物理预设提供，而不是通用的 newton_vbd 预设。只有可变形物体的场景可以直接使用 VBDSolverCfg 。对于包含机器人或刚体的场景，可使用以下具名求解器条目耦合方案：

CouplerProxyCfg ：核心 Franka 任务采用的代理耦合。
CouplerAdmmCfg ：具名求解器条目之间的线性化 ADMM 耦合。

从已支持的可变形任务开始#

备注

Isaac-Lift-Soft-Franka 任务需要自动四面体化。以下 uv 命令在需要时选择 tetrahedralization 可选依赖组。

使用传统安装程序时：

./isaaclab.sh -i tetrahedralization

为新任务添加 VBD 前，先运行一个 Franka 可变形任务：

uv（推荐）

uv run --extra tetrahedralization python scripts/environments/zero_agent.py --task Isaac-Lift-Soft-Franka --num_envs 1 --visualizer kit

isaaclab.sh / isaaclab.bat

./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Lift-Soft-Franka --num_envs 1 --visualizer kit

对于表面可变形的布料变体，使用：

uv（推荐）

uv run python scripts/environments/zero_agent.py --task Isaac-Lift-Cloth-Franka --num_envs 1 --visualizer kit

isaaclab.sh / isaaclab.bat

./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Lift-Cloth-Franka --num_envs 1 --visualizer kit

两个任务都通过 CouplerProxyCfg ，为刚性 Franka 配置 MJWarp，为可变形物体配置 VBD。可将它们作为资产设置、求解器耦合和接触调优的起点。

添加 VBD 物理预设#

支持多种物理配置的任务，通常将 SimulationCfg.physics 存为 PresetCfg 。对于使用 Newton 的可变形任务，预设值是普通的 NewtonCfg 。独立 VBD 和软接触配置位于 isaaclab_newton.physics ，代理耦合与 ADMM 耦合位于 isaaclab_contrib.coupling 。

Franka 软体和布料任务定义了各自专用的代理预设。

关键配置如下：

添加一个值为 NewtonCfg 的 Newton 物理预设。
使用 CouplerProxyCfg 和具名的 CouplerEntryCfg 条目，将刚体和可变形粒子分别分配给 MJWarp 与 VBD。
为暴露给 VBD 的可碰撞刚体添加 CouplerProxyMappingCfg 条目。代理耦合的 VBD 条目应保持 integrate_with_external_rigid_solver=False 。
需要在任务层面调整刚体与粒子的接触或自接触参数时，将外层 soft_contact_cfg 设为 NewtonSoftContactCfg 。
预设应放在任务的 SimulationCfg 所使用的同一配置路径下，例如 env.sim.physics 。

可以全局选择可变形 Newton 预设：

uv（推荐）

uv run --extra tetrahedralization isaaclab train --rl_library rsl_rl --task=Isaac-Lift-Soft-Franka physics=newton_mjwarp_vbd_proxy

isaaclab.sh / isaaclab.bat

./isaaclab.sh train --rl_library rsl_rl --task=Isaac-Lift-Soft-Franka physics=newton_mjwarp_vbd_proxy

也可以直接选择物理字段：

uv（推荐）

uv run --extra tetrahedralization isaaclab train --rl_library rsl_rl --task=Isaac-Lift-Soft-Franka env.sim.physics=newton_mjwarp_vbd_proxy

isaaclab.sh / isaaclab.bat

./isaaclab.sh train --rl_library rsl_rl --task=Isaac-Lift-Soft-Franka env.sim.physics=newton_mjwarp_vbd_proxy

如果只有一个任务字段需要使用 VBD 预设，应直接覆盖该字段路径。如果希望任务配置中所有匹配的预设字段都解析为该预设，则使用 physics=newton_mjwarp_vbd_proxy 。Isaac Lab 训练命令接受放在常规命令行参数之后的 Hydra 覆盖项；上述示例不需要分隔符。

检查任务与资产兼容性#

VBD 使用由任务资产构建的 Newton 模型。为新任务添加 VBD 时，先验证以下事项，再调整求解器参数：

任务必须已兼容 Newton 后端。如果只包含刚体的 newton_mjwarp 预设在构建模型时失败，应先修复资产或任务配置。
场景必须包含兼容 Newton 的可变形资产与材料。体积可变形物体使用 NewtonDeformableBodyMaterialCfg ，布料或表面可变形物体使用 NewtonSurfaceDeformableBodyMaterialCfg 。
采用代理耦合的机器人任务，只应暴露可变形接触所需的可碰撞刚体。
接触密集的场景通常需要任务专用的 num_substeps 、 VBDSolverCfg 和 NewtonSoftContactCfg 参数值。先从与场景最接近的 Franka 软体或布料预设开始。
训练前运行小规模的可视化冒烟测试，确认可变形物体的生成、渲染、变形及其与刚体的接触符合预期。

VBD 求解器参数#

以下字段属于 VBDSolverCfg ，按其影响的求解器环节分组。

核心求解#

参数	描述
`iterations`	默认值： `10` 。每个子步的 VBD 迭代次数。增加此值可改善变形与接触的收敛，尤其适用于高刚度材料或刚性夹爪接触，但会增加运行耗时。
`rigid_compliant_alm`	默认值： `None` 。保留 Newton 的刚体求解器模式。在 Newton 1.6 中， `None` 会选择已弃用的传统 AVBD。设为 `True` 可为刚性关节和刚体间接触使用柔顺 ALM；设为 `False` 则显式保留传统 AVBD。
`rigid_body_contact_buffer_size`	默认值： `64` 。VBD 对刚体进行积分时，每个刚体的刚体间接触容量。如果 Newton 报告单个刚体的刚体间接触缓冲区溢出，应增加此值。
`rigid_body_particle_contact_buffer_size`	默认值： `256` 。每个刚体的粒子、边和面软接触容量。如果 Newton 报告单个刚体的接触缓冲区溢出，应增加此值。
`integrate_with_external_rigid_solver`	默认值： `False` 。仅在手动管理器对共享模型中的刚体进行积分时设为 `True` 。代理耦合条目使用分区模型视图，应保持 `False` 。

刚性缆绳#

新建刚性缆绳配置时，显式启用柔顺 ALM：

from isaaclab_newton.physics import VBDSolverCfg

cable_solver_cfg = VBDSolverCfg(
    rigid_compliant_alm=True,
    rigid_body_contact_buffer_size=256,
)

柔顺 ALM 为刚性关节和刚体间接触使用有限的材料刚度。从传统 AVBD 切换时，应在预期载荷和时间步长下验证缆绳的拉伸、弯曲及接触刚度。增加接触容量只会增加可用存储空间，不会改变刚度。

VBDSolverCfg 不设置 Newton 的 C0 稳定化参数 rigid_avbd_alpha 。Newton 1.6 中，对于刚性关节和刚体间接触，柔顺 ALM 的默认值均为 0.0 ，传统 AVBD 的默认值均为 0.95 。仅将 alpha 设为零并不会启用 ALM。

自接触#

参数	描述
`particle_enable_self_contact`	默认值： `False` 。启用可变形物体自接触，用于布料折叠或与自身碰撞的软体。它会增加接触计算量，通常需要额外调优。
`particle_self_contact_radius`	默认值： `0.005` [m]。有效自接触厚度。当当前几何基元间距小于此半径时，VBD 会施加顶点与三角形、边与边之间的自接触响应。
`particle_self_contact_margin`	默认值： `0.005` [m]。自接触候选的搜索距离。VBD 用这一包络范围构建自接触列表，再依据 `particle_self_contact_radius` 施加接触响应。此值应大于或等于接触半径，以免漏检。
`particle_collision_detection_interval`	默认值： `-1` 。控制自接触检测频率。负值表示只在初始化前检测； `0` 表示在初始化前及初始化后立即检测；正值 `k` 表示每 `k` 次 VBD 迭代前检测一次。
`particle_vertex_contact_buffer_size`	默认值： `32` 。每个顶点的顶点与三角形自接触缓冲区预分配容量。如果密集折叠或高分辨率布料超出默认容量，应增加此值。
`particle_edge_contact_buffer_size`	默认值： `64` 。每条边的边与边自接触缓冲区预分配容量。如果密集折叠或高分辨率布料超出默认容量，应增加此值。
`particle_topological_contact_filter_threshold`	默认值： `2` 。过滤网格中拓扑关系相近的几何基元之间的接触。增加此值可抑制同一表面的邻近元素相互接触。大于 `3` 时，计算耗时可能显著增加。
`particle_rest_shape_contact_exclusion_radius`	默认值： `0.0` [m]。过滤静止构型中距离小于此值的自接触候选。当静止状态下相邻元素的接触产生不必要的阻力时，可增加此值。

自定义 MJWarp + VBD 参数#

可选的 CoupledMJWarpVBDSolverCfg 在同一共享模型上运行 MJWarp 和 VBD。显式导入 isaaclab_contrib.custom_coupling.tasks ，以注册选择 newton_mjwarp_vbd 预设的 IsaacContrib-Lift-Soft-Franka-Custom-Coupling 任务。

参数	描述
`rigid_solver_cfg`	刚体的 MJWarp 配置。
`soft_solver_cfg`	VBD 配置。设置 `integrate_with_external_rigid_solver=True` ，使 VBD 只推进粒子状态。
`coupling_mode="one_way"`	先推进刚体，再推进粒子，不施加来自刚体的反作用力。
`coupling_mode="two_way"`	在 MJWarp 求解前注入粒子反作用力，再使用同一组接触推进 VBD。

MJWarp 的 nconmax 和 njmax 必须覆盖场景中的刚体接触与约束。 ccd_iterations 可能影响可变形物体附近的高速刚体接触。刚体求解器参数见 MJWarp 调优。

需要直接控制共享模型的子步顺序时，使用自定义管理器；当可变形接触集中在选定刚体上时，使用代理耦合。

先使用 coupling_mode="two_way" 。双向耦合中，刚体与粒子接触的反作用力同时作用于机械臂和可变形物体，因此夹爪比单向耦合时更不容易穿过物体。如果仍有穿透，降低机械臂执行器刚度，使其能在反作用力下让步；同时令夹爪完全闭合，由执行器的最大驱动力限制夹持力。

MJWarp + VBD 耦合#

CouplerProxyCfg 是核心 Franka 任务采用的耦合方式。它在具名求解器条目之间划分模型，并将选定的源刚体作为代理暴露给目标求解器。接触反馈以滞后冲量的形式返回源求解器。这样，可变形接触计算就能集中在需要它的刚体上，例如夹爪的手掌和手指。当前锁定版本的代理求解器最多支持两个条目，且不接受跨条目边界的关节。

选择方案前，参阅耦合求解器中对代理耦合与 ADMM 耦合的总体比较。

核心 Franka 软体任务展示了代理配置：

newton_mjwarp_vbd_proxy: NewtonCfg = NewtonCfg(
    solver_cfg=CouplerProxyCfg(
        entries=[
            CouplerEntryCfg(
                name="rigid",
                solver_cfg=MJWarpSolverCfg(
                    cone="elliptic",
                    ls_iterations=50,
                    integrator="implicitfast",
                ),
                bodies=[r"/World/envs/env_[^/]+/Robot"],
            ),
            CouplerEntryCfg(
                name="soft",
                solver_cfg=VBDSolverCfg(iterations=10, rigid_body_particle_contact_buffer_size=256),
                all_particles=True,
                include_static_shapes=True,
            ),
        ],
        proxies=[
            CouplerProxyMappingCfg(
                source="rigid",
                destination="soft",
                bodies=[
                    r"/World/envs/env_[^/]+/Robot/Geometry/.*panda_hand",
                    r"/World/envs/env_[^/]+/Robot/Geometry/.*panda_(left|right)finger",
                ],
                collide_interval=1,
                collision_pipeline=NewtonCollisionPipelineCfg(
                    enable_rigid_soft_full_surface_contact=True,
                ),
            )
        ],
        iterations=1,
    ),
    soft_contact_cfg=NewtonSoftContactCfg(
        soft_contact_ke=8.0e3,
        soft_contact_kd=1.0e-2,
        soft_contact_mu=10.0,
    ),
    num_substeps=2,
)

各选择器的作用：

entries 为每个子求解器包含一个 CouplerEntryCfg 。每个条目都有稳定的 name 、独立的 solver_cfg 和显式的模型归属选择器。
条目的 bodies 选择器是匹配完整 Newton 刚体标签的正则表达式字符串。默认情况下，关节继承其子刚体的归属，形状继承其刚体的归属。使用 all_particles=True 可取得所有可变形粒子的归属，使用 include_static_shapes=True 可取得世界几何体的归属。刚体、粒子、关节和形状最多只能归属于一个条目；未分配元素不在嵌套求解器视图中。
proxies 包含有方向的 CouplerProxyMappingCfg 映射。每个映射指定 source 和 destination 条目，再用 bodies 选择目标求解器应与之碰撞的源刚体。只保留拥有至少一个带 newton.ShapeFlags.COLLIDE_SHAPES 标志的形状的刚体。
在上述代码中，整个 Franka 关节体交给 MJWarp，可变形粒子以及静态桌面和世界形状交给 VBD。只有 panda_hand 和两个手指作为代理暴露，因此不论机械臂有多少连杆，VBD 都只看到三个刚体代理。

完整表面的刚体与软体接触包括边接触和三角形内部接触。解析代理形状可直接支持，网格代理和凸代理形状则需要体积 SDF。

重要

耦合器目前不接受 KaminoPADMMSolverCfg 或 KaminoDVISolverCfg 条目，也不接受配置为 project_outside_colliders=True 的 MPMSolverCfg 条目，以及配置为 use_mujoco_cpu=True 的 MJWarpSolverCfg 条目。这些配置需要管理器专用的构建、正向运动学、重置或逐步生命周期钩子，而嵌套求解器尚不具备这些钩子。可使用 project_outside_colliders=False 的 MPM 和 GPU MJWarp，或在添加嵌套生命周期支持之前，通过各自的独立管理器运行这些求解器。

代理专用的关键参数：

参数	描述
`CouplerProxyMappingCfg.mode`	默认值： `"lagged"` 。 `"lagged"` 同步源端起始位姿和结束速度，然后在目标求解前回退滞后反馈。 `"staggered"` 则直接同步源端结束位姿和结束速度。滞后模式是更稳妥的默认选择；交错模式可能耦合更紧密，但对时间步长更敏感。
`CouplerProxyCfg.iterations`	默认值： `1` 。每个耦合子步的松弛迭代次数。需要更精确的代理接触反馈时，可增加此值。
`CouplerProxyMappingCfg.collide_interval`	默认值： `None` （每次代理处理）。控制代理碰撞管线重建候选对的频率。增大间隔可降低开销，但代理接触信息会略有滞后。
`CouplerProxyMappingCfg.mass_scale`	默认值： `1.0` 。VBD 视图中代理刚体虚拟惯量的乘数。增加此值可使代理在 VBD 中更接近固定障碍物。

刚体选择器必须使用完整 Newton 刚体标签的正则表达式，例如 /World/envs/env_.*/Robot 。代理映射也接受原始 Newton 刚体 ID。

CouplerAdmmCfg 在同样的具名求解器条目之间提供线性化 ADMM 耦合。设置 contact_pairs 可显式选择条目对；保留 None 则检测所有不同条目组成的对。使用 iterations 和 rho 调整 ADMM 求解。

尝试演示：

uv（推荐）

# zero-agent visual smoke test
uv run --extra tetrahedralization python scripts/environments/zero_agent.py --task Isaac-Lift-Soft-Franka --num_envs 1 --visualizer kit

# scripted pick-and-lift via state machine
uv run --extra tetrahedralization python scripts/environments/state_machine/lift_franka_soft.py --num_envs 1

isaaclab.sh / isaaclab.bat

# zero-agent visual smoke test
./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Lift-Soft-Franka --num_envs 1 --visualizer kit

# scripted pick-and-lift via state machine
./isaaclab.sh -p scripts/environments/state_machine/lift_franka_soft.py --num_envs 1

接触与材料参数#

接触模型#

NewtonSoftContactCfg 通过 soft_contact_cfg ，将接触参数应用于最终构建完成的 Newton 模型：

参数	描述
`soft_contact_ke`	默认值： `1.0e3` [N/m]。刚体与粒子接触、粒子自接触的刚度。增加此值可减少粒子穿过刚体形状或其他可变形粒子的情况。如果过高，物体可能不再明显变形，或需要更多 VBD 迭代和子步。
`soft_contact_kd`	默认值： `1.0e1` [N*s/m]。接触阻尼。增加此值可减少抖动或回弹，但阻尼过大可能使接触响应黏滞或过阻尼。
`soft_contact_mu`	默认值： `0.5` 。刚体与粒子接触、粒子自接触的摩擦系数。当夹爪携带可变形物体时发生滑移，可增加此值。

对于未显式指定资产材料的形状，如需设置刚性碰撞形状的接触属性（ ke 、 kd 、 mu ），应改用 NewtonCfg.default_shape_cfg 上的 NewtonShapeCfg 。各资产的材料会覆盖这些默认值。

体积可变形材料#

体积可变形物体使用 NewtonDeformableBodyMaterialCfg ：

参数	描述
`density`	默认值： `1.0` [kg/m^3]。材料密度。较高密度会增加粒子质量和惯量，因此在相同接触力下，物体加速和变形的程度更小。
`particle_radius`	默认值： `0.008` [m]。Newton 使用的粒子接触半径。当接触漏检或检测过迟时，可增加此值。如果相对于网格分辨率过大，接触可能过早开始。
`k_mu`	默认值： `1.0e5` [Pa]。第一拉梅参数。较高值使可变形物体更硬，通常需要更多 VBD 迭代、更多子步或更小的时间步长。
`k_lambda`	默认值： `1.0e5` [Pa]。第二拉梅参数。较高值使可变形物体更硬，通常需要更多 VBD 迭代、更多子步或更小的时间步长。
`k_damp`	默认值： `0.0` [Pa*s]。四面体单元的阻尼。增加此值可减少变形后的振荡；如果物体应有回弹，则应避免过阻尼。

表面可变形材料#

布料或表面可变形物体使用 NewtonSurfaceDeformableBodyMaterialCfg ：

参数	描述
`density`	默认值： `1.0` [kg/m^3]。材料密度。较高密度会增加粒子质量和惯量。
`particle_radius`	默认值： `0.008` [m]。Newton 使用的粒子接触半径。
`tri_ke`	默认值： `1.0e4` [Pa]。三角形面积保持刚度。增加此值可减少布料拉伸。
`tri_ka`	默认值： `1.0e4` [Pa]。三角形面积刚度。增加此值可减少布料面积变化。
`tri_kd`	默认值： `1.5e-6` [Pa*s]。三角形面积阻尼。增加此值可减少拉伸后的布料振动。
`edge_ke`	默认值： `5.0` [N*m]。弯曲刚度。增加此值会使布料折叠更硬；减小则使垂坠更柔软。
`edge_kd`	默认值： `1.0e-2` [Nms]。弯曲阻尼。增加此值可抑制折叠振荡。

调优流程#

搭建新的 VBD 任务时，按以下顺序操作：

运行一个已支持的 Franka 可变形任务，确认安装、可视化器和可变形渲染路径正常。
从最接近的已支持任务复制配置，添加任务专用的 VBD 或代理耦合 VBD 预设。
训练前，使用 --num_envs 1 运行小规模的可视化冒烟测试。
调整可变形材料的刚度和阻尼，使物体在没有刚体接触时，变形程度处于预期范围。
如果物体不稳定，先增加 num_substeps 或减小 dt ，再进一步提高刚度。
当接触或高刚度材料在一个子步内无法收敛时，增加 iterations 。
先调整 soft_contact_ke 以减少刚体与可变形物体的相互穿透，再调整 soft_contact_mu 改善抓握，并调整 soft_contact_kd 抑制抖动。
刚体与粒子的接触稳定后再启用自接触。随后用 particle_self_contact_radius 调整有效自接触厚度，用 particle_self_contact_margin 处理漏检，用 particle_collision_detection_interval 调整检测频率。
单环境场景稳定后，再增加 num_envs 并进行性能分析。

常见现象与优先检查的参数#

现象	优先检查的参数
刚体明显穿过可变形物体。	增加 `soft_contact_ke` 、VBD 的 `iterations` 、 `num_substeps` 或可变形材料的 `particle_radius` 。
机器人无法举起可变形物体。	检查夹爪刚体是否包含在代理中，再增加 `soft_contact_mu` 和刚体侧形状摩擦（各资产材料的 `mu` 或 `NewtonShapeCfg.mu` ）。同时检查夹爪执行器的刚度和驱动力限制。
可变形物体几乎不变形。	降低材料刚度、 `soft_contact_ke` 或形状接触刚度。
接触发生抖动或回弹。	增加 `soft_contact_kd` 或材料阻尼，并考虑增加子步数。
布料穿过自身。	启用 `particle_enable_self_contact` ；有效自接触厚度过小时增加 `particle_self_contact_radius` ；接触漏检时增加 `particle_self_contact_margin` ；并为 `particle_collision_detection_interval` 使用正值。
自接触开销过高。	增大 `particle_collision_detection_interval` 、降低网格分辨率，或在场景其他部分调优完成前禁用自接触。

VBD 管理器和 Newton 耦合器的实现细节见扩展 Newton 求解器。

VBD 求解器

目录

VBD 求解器#

从已支持的可变形任务开始#

添加 VBD 物理预设#

检查任务与资产兼容性#

VBD 求解器参数#

核心求解#

刚性缆绳#

自接触#

自定义 MJWarp + VBD 参数#

MJWarp + VBD 耦合#

接触与材料参数#

接触模型#

体积可变形材料#

表面可变形材料#

调优流程#

常见现象与优先检查的参数#