added vbd schemas

[Milad-Rakhsha-NV]

Description

Adds NewtonVbdSceneAPI, a single-apply API schema that extends NewtonSceneAPI with configuration for Newton's VBD (Vertex Block Descent) solver, including its AVBD rigid-body path. Applying it implicitly applies NewtonSceneAPI, and it can only be applied to a PhysicsScene.

Parameters are grouped by prefix:

• newton:vbd: — common solver parameters
• newton:vbd:particle: — cloth/particle self-contact parameters
• newton:vbd:rigid: — rigid-body AVBD penalty/stabilization parameters

Addresses #30.

graph TD
  NewtonSceneAPI["NewtonSceneAPI"]
  VbdSceneAPI["NewtonVbdSceneAPI"]
  VbdSceneAPI -->|"apiSchemas (inherits)"| NewtonSceneAPI

Loading

Design

Attributes are included based on whether they describe the simulation or the run. Parameters that control how the engine executes rather than what is simulated — memory preallocation (contact buffer sizes), backend acceleration toggles (tile solve), and solver-wiring flags (external rigid integration) — are left to application-level configuration and excluded.

iterations is not duplicated; it maps to the existing newton:maxSolverIterations on NewtonSceneAPI.

Override attributes that fall back to another parameter use a -inf sentinel meaning "inherit the solver default": avbdJointAlpha/avbdContactAlpha inherit avbdAlpha, and avbdLinearBeta/avbdAngularBeta inherit avbdBeta. These use soft limits so the sentinel stays valid.

Defaults, ranges, and units were taken from the VBD/AVBD solver source:

• Ranges mirror the constructor validation (alpha/gamma in [0, 1]; betas, stiffness seeds, ceilings, and damping >= 0).
• The penalty ramp is k = min(k_max, k + beta * |C|), so avbdLinearBeta has units force / distance² and avbdAngularBeta has units torque / radian².
• Joint damping enters as K_eff = k * (1 + kd/dt), so jointLinearKd and jointAngularKd are stiffness-proportional Rayleigh coefficients with units of seconds.

Attributes

namespace	attributes
newton:vbd:	frictionEpsilon
newton:vbd:particle:	selfContactEnabled, selfContactRadius, selfContactMargin, conservativeBoundRelaxation, collisionDetectionInterval, edgeParallelEpsilon, topologicalContactFilterThreshold, restShapeContactExclusionRadius
newton:vbd:rigid:	avbdAlpha, avbdJointAlpha, avbdContactAlpha, avbdBeta, avbdLinearBeta, avbdAngularBeta, avbdGamma, contactHistory, contactStickMotionEps, contactStickFreezeTranslationEps, contactStickFreezeAngularEps, contactKStart, jointLinearKe, jointAngularKe, jointLinearKStart, jointAngularKStart, jointLinearKd, jointAngularKd

Excluded from the schema

• integrate_with_external_rigid_solver — solver wiring, not a scene property
• particle_enable_tile_solve — backend acceleration toggle
• particle_vertex_contact_buffer_size, particle_edge_contact_buffer_size, rigid_body_contact_buffer_size, rigid_body_particle_contact_buffer_size — memory preallocation
• particle_external_vertex_contact_filtering_map, particle_external_edge_contact_filtering_map — element-level collision filtering; belongs to a dedicated element collision filter schema
• rigid_enable_dahl_friction — deprecated; controlled by model attributes

Open questions

• collisionDetectionInterval is exposed as a tri-state integer; should the "once" / "twice" / "every n" behavior instead split into a token plus interval?

Checklist

• I am familiar with the Contributing Guidelines.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[andrewkaufman]

Thanks @Milad-Rakhsha-NV, I didn't comment on attribute names & values much, I'll leave that to the VDB experts.

[mmichelis]

Thanks for the great effort! All relevant parameters are there for the demos we run in IsaacLab (so far). For the rigid contact, there is another potentially useful boolean to expose: rigid_contact_hard. Do you think this one could make sense?

[Milad-Rakhsha-NV]

Thanks for the great effort! All relevant parameters are there for the demos we run in IsaacLab (so far). For the rigid contact, there is another potentially useful boolean to expose: rigid_contact_hard. Do you think this one could make sense?

Hi Mike we can add it but the authors of VBD was in favor of not exposing it since it will be removed in the future, @jumyungc for visibility

[mmacklin]

@AnkaChan is this global? Should we key it off the contact_friction_gain parameter we added to the contact schema?

[mmacklin]

I think a big question here is what to do when we move self contact and triangle based contact out of VBD and into the collision pipeline object.

[Milad-Rakhsha-NV]

Thanks Miles I think based on JC's input we will remove this for the initial design and will add it later on if needed

[andrewkaufman]

Fixes #30

[jumyungc]

FYI, I added a minimal, starting set of rigid/AVBD params to carry over (#30). It'll need to expand later.

[Milad-Rakhsha-NV]

FYI, I added a minimal, starting set of rigid/AVBD params to carry over (#30). It'll need to expand later.

Thanks JC, will update soon.

[jumyungc]

The rigid-body side looks good to me overall - thanks!.
I only added a few small comments to tighten up the doc.
Just in case, please don’t forget to update the changelog.

This needs further testing, but after thinking about it more, we may not need joint_Linear/Angular_Ke/Kd. contactHistory may also be unnecessary. To keep the schema conservative and minimal, I'd suggest not shipping any rigid-specific parameters for now.