Add VBD solver schema

[andrewkaufman]

Is this a new feature, an improvement, or a change to existing functionality?

New Feature

Feature Description

Newton's VBD solver is important for cable & cloth simulation. We should expose relevant solver parameters on a dedicated NewtonVBDSceneAPI schema

Additional context or alternatives

No response

Code of Conduct

• I agree to follow newton-usd-schemas Code of Conduct
• I have searched the open issues and have found no duplicates

[Milad-Rakhsha-NV]

Draft Proposal

1. Solver scene API, consistent with existing solvers. NewtonVbdSceneAPI
   is a single-apply, codeless API that applies only to PhysicsScene and
   lists NewtonSceneAPI as a built-in API. This matches the existing
   NewtonXpbdSceneAPI and NewtonKaminoSceneAPI.

2. iterations is not redefined. The base NewtonSceneAPI already provides
   newton:maxSolverIterations. VBD's iterations maps onto it, the same way
   NewtonXpbdSceneAPI relies on the base attribute rather than adding its own.

3. Namespacing by parameter group. Attributes use newton:vbd: for common
   parameters and newton:vbd:particle: / newton:vbd:rigid: for the particle
   and rigid (AVBD) groups, mirroring Kamino's newton:kamino:padmm: /
   newton:kamino:constraints: sub-grouping. (Open question 1 below asks whether
   to keep the sub-namespaces or flatten to newton:vbd:.)

4. Attributes are included based on whether they describe the simulation or
   the run. An attribute belongs in the schema when it describes the physical
   scene or changes the solver's simulation behavior, so that it travels with the
   asset and is portable across applications. An attribute is left to
   application-level configuration when it controls how the engine executes
   rather than what is simulated — memory preallocation, backend acceleration,
   algorithm plumbing, and debug output. These do not change the simulated result
   in a portable way and are better set by the runtime.

5. -inf sentinel for "use solver fallback." Constructor arguments that
   default to None and fall back to another parameter (the alpha and beta
   overrides) are represented with a -inf default, meaning "inherit the solver
   default." The sentinel keeps the attribute optional: when it is left
   unauthored, the solver chooses the effective value.

Parameters included in the schema

All attributes are uniform.

Common (newton:vbd:)

attribute	type	default	range	units
newton:vbd:frictionEpsilon	float	0.01	[0, inf)	distance / seconds

Particle (newton:vbd:particle:)

attribute	type	default	range	units
selfContactEnabled	bool	false	—	—
selfContactRadius	float	0.2	[0, inf)	distance
selfContactMargin	float	0.2	[0, inf)	distance
conservativeBoundRelaxation	float	0.85	[0, 1]	dimensionless
collisionDetectionInterval	int	0	(-inf, inf)	dimensionless
edgeParallelEpsilon	float	1e-5	[0, inf)	dimensionless
topologicalContactFilterThreshold	int	2	[0, inf)	dimensionless
restShapeContactExclusionRadius	float	0.0	[0, inf)	distance

Notes:

• selfContactMargin is expected to be larger than selfContactRadius to avoid
  missing contacts; this is a usage guideline, not a hard limit.
• collisionDetectionInterval is tri-state: a value < 0 runs detection once
  before initialization, 0 runs it twice (before and after initialization),
  and n >= 1 runs it before every n iterations. (Open question 2 below.)
• topologicalContactFilterThreshold, restShapeContactExclusionRadius, and
  the self-contact parameters are only consulted when selfContactEnabled is
  true.

Rigid / AVBD (newton:vbd:rigid:)

attribute	type	default	range	units
avbdAlpha	float	0.95	[0, 1]	dimensionless
avbdJointAlpha	float	-inf †	[0, 1]	dimensionless
avbdContactAlpha	float	-inf †	[0, 1]	dimensionless
avbdBeta	float	0.0	[0, inf)	per-iteration ramp ‡
avbdLinearBeta	float	-inf †	[0, inf)	force / distance per iteration
avbdAngularBeta	float	-inf †	[0, inf)	torque / radian per iteration
avbdGamma	float	0.999	[0, 1]	dimensionless
contactHard	bool	true	—	—
contactHistory	bool	false	—	—
contactStickMotionEps	float	1e-4	[0, inf)	distance
contactStickFreezeTranslationEps	float	1e-4	[0, inf)	distance
contactStickFreezeAngularEps	float	1e-4	[0, inf)	radians
contactKStart	float	100.0	[0, inf)	force / distance
jointLinearKe	float	1e5	[0, inf)	force / distance
jointAngularKe	float	1e5	[0, inf)	torque / radian
jointLinearKStart	float	100.0	[0, inf)	force / distance
jointAngularKStart	float	10.0	[0, inf)	torque / radian
jointLinearKd	float	0.0	[0, inf)	force · seconds / distance
jointAngularKd	float	0.0	[0, inf)	torque · seconds / radian

† -inf is the "use solver fallback" sentinel: avbdJointAlpha and
avbdContactAlpha inherit avbdAlpha; avbdLinearBeta and avbdAngularBeta
inherit avbdBeta. These attributes use soft limits.

‡ avbdBeta is applied to both linear and angular ramps, whose units differ
(force/distance vs. torque/radian per iteration). It is documented as such, with
the per-axis overrides recommended for production tuning, matching the solver
docstring.

Parameters excluded from the schema

constructor argument	classification	rationale
iterations	mapped to base	covered by newton:maxSolverIterations on NewtonSceneAPI
integrate_with_external_rigid_solver	application config	describes how the application wires multiple solvers (one-way coupling), not a property of the scene
particle_enable_tile_solve	application config	backend acceleration toggle; output-equivalent
particle_vertex_contact_buffer_size	application config	memory preallocation
particle_edge_contact_buffer_size	application config	memory preallocation
rigid_body_contact_buffer_size	application config	memory preallocation
rigid_body_particle_contact_buffer_size	application config	memory preallocation
particle_external_vertex_contact_filtering_map	separate schema	element-level collision filtering; belongs to a dedicated element collision filter schema, not the solver scene API
particle_external_edge_contact_filtering_map	separate schema	element-level collision filtering; belongs to a dedicated element collision filter schema, not the solver scene API
rigid_enable_dahl_friction	deprecated	ignored by the solver; Dahl friction is controlled by model attributes (model.vbd.dahl_eps_max / model.vbd.dahl_tau)

The four buffer-size arguments are memory preallocation and the tile-solve
toggle is a backend acceleration switch. Both control how the engine executes
rather than what is simulated, so they are left to application-level
configuration.

The two contact-filtering maps describe per-element collision exclusions, which
is the subject of element collision filtering in the in-progress UsdPhysics
deformables proposal (PhysicsElementCollisionFilter). This is per-element pair
data with a solver-agnostic USD home of its own, separate from the VBD solver
scene configuration, so it is out of scope for this schema. Note a granularity
difference: the proposed filter pairs whole elements (triangle-triangle for a
mesh, segment-segment for curves, point-point for points), whereas the solver
maps are vertex-triangle and edge-edge exclusions. A parser would expand
element-level filter pairs into the corresponding vertex-triangle and edge-edge
exclusions rather than map them one to one.

Open questions

1. Namespacing. Keep the newton:vbd:particle: / newton:vbd:rigid:
   sub-namespaces, or flatten everything to newton:vbd:?
2. collisionDetectionInterval. Is the tri-state integer the right
   representation, or should the "once" / "twice" / "every n" behavior be split
   into a token plus an interval?
3. Units to confirm. Confirm the units marked above, in particular
   frictionEpsilon (relative velocity), edgeParallelEpsilon (treated as
   dimensionless), and the avbdBeta ramp units.
4. Defaults. The defaults mirror the current SolverVBD.__init__ defaults.
   Confirm these are the intended authored defaults for content, or whether any
   should instead default to a sentinel that defers to the solver.
5. Coverage. Are any excluded parameters expected to be authored per-scene
   in content pipelines, which would argue for moving them into the schema?
6. Element collision filtering. The two contact-filtering maps overlap with
   element collision filtering in the deformables proposal. Should they be driven
   by a dedicated element collision filter schema, and is the vertex-triangle /
   edge-edge vs. element-element granularity difference acceptable for a parser
   to bridge?

[jumyungc]

Thank you for the great proposal @Milad-Rakhsha-NV!

Just FYI, we have a couple of upcoming changes that may affect schema:

• We are moving toward removing the hard/soft flag split (hard = ALM, soft = penalty) and using a unified mode instead.
• We will soon support stretch / shear / bend / twist for cables. Currently we only support stretch and bend. If shear is not specified, it will fall back to the stretch stiffness; if twist is not specified, it will fall back to the bend stiffness.

A few notes on the rigid / AVBD section:

• Beta units: the avbdLinearBeta / avbdAngularBeta rows and footnote are missing a power. Linear should be force / distance², and angular should be torque / radian².
• avbdBeta has no single consistent unit. One value feeds both the linear and angular ramps, so it cannot carry a single physical unit. It may be worth stating this explicitly.
• Namespacing: I would keep the proposed newton:vbd:particle: and newton:vbd:rigid: namespaces.
• *KStart FYI: these are inert unless the matching beta is greater than zero.

[Milad-Rakhsha-NV]

Thanks @jumyungc

• I will remove the selfContactEnabled parameter for now then
• Regarding the material properties, I think those will go into the material properties APIs but thanks for the pointer.

Regarding AVBD parameters, all sound good to me. I will include those in the schema design

[Milad-Rakhsha-NV]

rest-shape-distance-based collision filtering and topological-distance-based collision filtering. Those are more of a solver-specific thing. I don't think we should over-complicate the schema?

Hi @AnkaChan
I think it is fine to include these in the VBDSchema if the users are expected to be able to use these parameters. However, if these are more exotic parameters that we don't necessarily want to expose for authoring, I can remove them from here to simply things.

[jumyungc]

@Milad-Rakhsha-NV From your rigid/AVBD list, I think this is a safe, minimal set of attributes that should carry over cleanly. I kept it intentionally conservative, so it doesn't cover the full feature set yet. (Also it is not about naming.)

attribute	default	ship	remark
avbdAlpha	0.95	X	Solver stabilization control; potentially useful for advanced tuning, but omitted to keep the initial API minimal — can add later if a need appears.
avbdJointAlpha	-inf †	X	Global joint-category stabilization override; useful for advanced tuning, but omitted to keep the initial API minimal — can add later if a need appears.
avbdContactAlpha	-inf †	X	Global body-contact stabilization override; useful for advanced tuning, but omitted to keep the initial API minimal — can add later if a need appears.
avbdBeta	0.0	X	Penalty-ramp control (mixed units); likely to be deprecated — omitted from the minimal API.
avbdLinearBeta	-inf †	X	Linear penalty-ramp control; likely to be deprecated — omitted from the minimal API.
avbdAngularBeta	-inf †	X	Angular penalty-ramp control; likely to be deprecated — omitted from the minimal API.
avbdGamma	0.999	X	Multiplier/history-retention control; potentially useful for advanced tuning, but omitted to keep the initial API minimal — can add later if a need appears.
contactHard	true	X	Hard/soft contact mode; can help some scenes today, but likely to be deprecated — omitted from the minimal API.
contactHistory	false	O X	Cross-step contact-state warm-starting; requires runtime contact matching.
contactStickMotionEps	1e-4 (use 0.0)	X	Not needed for the minimal API; 0.0 disables this feature.
contactStickFreezeTranslationEps	1e-4 (use 0.0)	X	Not needed for the minimal API; 0.0 disables this feature.
contactStickFreezeAngularEps	1e-4 (use 0.0)	X	Not needed for the minimal API; 0.0 disables this feature.
contactKStart	100.0	X	Contact penalty-ramp seed; likely to be deprecated — omitted from the minimal API.
jointLinearKe	1e5	O X	Meaningful material property (joint linear stiffness); kept in the minimal API.
jointAngularKe	1e5	O X	Meaningful material property (joint angular stiffness); kept in the minimal API.
jointLinearKStart	100.0	X	Linear joint penalty-ramp seed; likely to be deprecated — omitted from the minimal API.
jointAngularKStart	10.0	X	Angular joint penalty-ramp seed; likely to be deprecated — omitted from the minimal API.
jointLinearKd	0.0	O X	Absolute material damping, not a coefficient measured in seconds.
jointAngularKd	0.0	O X	Absolute material damping, not a coefficient measured in seconds.

Correction: 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. I will keep you guys posted.