Import Newton curve damping from USD (#4056)

Signed-off-by: JC Chang <jumyungc@nvidia.com>

Author: jumyungc

changelog/3980.added.md

@@ -0,0 +1 @@
+Import per-mode curve damping from `NewtonCurvesDeformableMaterialAPI` and discretize each value using the rod joint's dual rest length.

docs/concepts/usd_parsing.rst

@@ -156,16 +156,31 @@ The first release deliberately supports a narrow, predictable set of inputs:
 
 * Valid, enabled, **dynamic** cable, cloth, and volume simulation prims that use the AOUSD
   deformable APIs. A bound simulation material supplies thickness, stiffness, and density.
-  For cables, each authored ``physics:curves*Stiffness`` is a structural stiffness; an
-  unauthored mode is derived instead from ``physics:youngsModulus``, ``physics:poissonsRatio``,
-  and ``physics:curvesThickness``, each of which falls back to the proposal's assumed 1 MPa,
-  0.3, and 1 mm when it is itself unauthored.
-  Newton divides each resolved structural stiffness by that joint's own dual rest length
-  ``0.5 * (L_parent + L_child)``, so unevenly sampled curves keep per-joint accuracy.
-  The earlier unprefixed cable material attributes remain accepted with their former modulus
-  interpretation during a deprecation window and emit a ``DeprecationWarning``.
+  For cables, ``PhysicsCurvesDeformableMaterialAPI`` provides structural stiffness for stretch,
+  shear, bend, and twist through ``physics:curves*Stiffness``. A material may additionally apply
+  ``NewtonCurvesDeformableMaterialAPI`` to provide matching structural damping through
+  ``newton:curves*Damping``. These are material-level quantities, not direct per-joint target
+  values. For each generated rod joint, Newton uses the joint-local dual rest length
+  ``L_joint = 0.5 * (L_parent + L_child)`` to compute
+  ``joint_target_ke = structural_stiffness / L_joint`` and
+  ``joint_target_kd = structural_damping / L_joint``.
+  For stretch and shear, stiffness and damping have units of force and force times time,
+  respectively; for bend and twist, they have units of force times distance squared and force
+  times distance squared times time. Division by ``L_joint`` produces the corresponding linear
+  or angular per-joint units.
+  An unauthored or ``-inf`` stiffness is derived from ``physics:youngsModulus``,
+  ``physics:poissonsRatio``, and ``physics:curvesThickness`` (with assumed values of 1 MPa, 0.3,
+  and 1 mm diameter when those are unauthored). An unauthored or ``-inf`` damping instead leaves
+  that mode at its rod-joint default; authored damping modes are not copied to unauthored modes.
+  Newton damping requires the base ``PhysicsCurvesDeformableMaterialAPI``; without it, the
+  damping is ignored.
+  The deprecated unprefixed ``physics:stretchStiffness``, ``physics:shearStiffness``,
+  ``physics:bendStiffness``, and ``physics:twistStiffness`` attributes remain accepted with their
+  former modulus interpretation and emit a ``DeprecationWarning``. The
+  ``newton:curves*Damping`` attributes always use structural units and remain independent per mode,
+  even on a material using those deprecated stiffness attributes.
 * The points and topology **as currently authored**. Newton builds the deformable at that pose;
-  a cable's ``restShapePoints`` may affect stiffness normalization but never establishes an
+  a cable's ``restShapePoints`` may affect material-gain discretization but never establishes an
   initial strain state.
 * Point attachments only where the authored constraint can be represented without moving any
   geometry: hard cable-to-xform attachments, and hard, coincident cable-to-cable junctions.
@@ -200,10 +215,10 @@ Known gaps of the experimental importer, tracked as follow-ups:
 * **Rest state** -- authored rest geometry is not imported as the deformable's simulated rest
   configuration. Cloth and volume rest attributes are ignored with a warning. For a cable,
   including one in a welded graph, valid ``restShapePoints`` supplies only the segment lengths
-  used to discretize material stiffness into joint stiffness; invalid values warn and fall back
-  to the current ``points`` lengths. The rod itself is still built relaxed at the current
-  ``points`` pose, and mass distribution also uses the current geometry. A body saved in a
-  deformed pose therefore resumes relaxed at that pose instead of springing back.
+  used to discretize structural stiffness and damping into per-joint stiffness and damping gains.
+  Invalid values warn and fall back to the current ``points`` lengths. The rod itself is still
+  built relaxed at the current ``points`` pose, and mass distribution also uses the current geometry.
+  A body saved in a deformed pose therefore resumes relaxed at that pose instead of springing back.
 * **Springy attachments** -- attachments with a finite stiffness are not simulated. They are
   preserved in ``path_attachment_attrs`` with their authored stiffness and damping (silently
   hardening them would change the authored physics); only hard attachments (unauthored or
@@ -306,22 +321,23 @@ close a loop, so they stay outside the articulation.
     model = builder.finalize()  # cables are already wrapped and finalize-ready
 
 The :meth:`~newton.ModelBuilder.add_usd` return dict carries ``path_cable_attrs``,
-``path_cloth_attrs`` and ``path_soft_attrs``, mapping each prim path to its attributes exactly
-as authored, independent of any solver. The cable and cloth entries expose the parsed
-authored ``material`` values and the ``resolved_density``. The volume entry exposes the
+``path_cloth_attrs`` and ``path_soft_attrs``, mapping each prim path to validated import metadata,
+independent of any solver.
+The cable and cloth entries expose validated authored ``material`` values and the
+``resolved_density``. The volume entry exposes the
 ``resolved_density`` (a volume material's ``youngsModulus`` / ``poissonsRatio`` are applied to
-the built soft body and not repeated there). A cable entry preserves authored
-``curvesThickness``, ``youngsModulus``, ``poissonsRatio``, and the per-mode structural
-stiffnesses, plus any earlier unprefixed attributes the material still authors during the
+the built soft body and not repeated there). A cable entry preserves validated authored
+``curvesThickness``, ``youngsModulus``, ``poissonsRatio``, and the per-mode structural stiffness
+and damping values, plus any earlier unprefixed attributes the material still authors during the
 deprecation window; a cloth entry keeps moduli its isotropic membrane cannot express. This
 lets another solver rebuild the deformable without re-parsing the stage. A cable entry carries a
 ``graph_component`` identifier only when the curve was welded into a rod graph; curves of one
 graph share it, and independent or fallback cables have no such key.
 
 .. note::
 
-   Solver tuning that is not part of the AOUSD schema (e.g. damping) is not imported; supply it
-   on the builder or model after import.
+   Solver tuning that is not part of the supported AOUSD schemas or a documented Newton schema
+   extension is not imported; supply it on the builder or model after import.
 
 Material Color Spaces
 ---------------------

newton/_src/sim/builder.py

@@ -3817,7 +3817,7 @@ def add_usd(
                 * - ``"path_soft_map"``
                   - Mapping from prim path (str) of a soft body (a volume deformable, or a legacy bare TetMesh) to its ``[start, end)`` index ranges, keyed ``"particle"`` / ``"tet"``. Present only with ``return_deformable_results=True``.
                 * - ``"path_cable_attrs"``
-                  - Mapping from prim path (str) of a curve deformable (cable) to its as-authored, solver-neutral attributes (``material`` moduli, ``resolved_density``, ``closed``); includes moduli the imported rod cannot express (e.g. shear / twist). ``graph_component`` is present only for curves successfully welded into the same rod graph; curves in one graph share the component identifier. Present only with ``return_deformable_results=True``.
+                  - Mapping from prim path (str) of a curve deformable (cable) to its validated, solver-neutral cable import metadata (``material``, ``resolved_density``, ``closed``). ``material`` contains supported per-mode structural values before per-joint discretization: stretch/shear stiffness [N] and damping [N·s]; bend/twist stiffness [N·m²] and damping [N·m²·s]. ``graph_component`` is present only for curves successfully welded into the same rod graph; curves in one graph share the identifier. Present only with ``return_deformable_results=True``.
                 * - ``"path_cloth_attrs"``
                   - Mapping from prim path (str) of a surface deformable (cloth) to its as-authored, solver-neutral attributes (``material`` moduli, ``resolved_density``). Present only with ``return_deformable_results=True``.
                 * - ``"path_soft_attrs"``
@@ -5648,32 +5648,58 @@ def add_joint_cable(
             **kwargs,
         )
 
-    def _set_joint_rod_stiffnesses(
+    def _set_joint_rod_material_gains(
         self,
         joint: int,
         *,
-        stretch_stiffness: float | None,
-        shear_stiffness: float | None,
-        bend_stiffness: float | None,
-        twist_stiffness: float | None,
+        stretch_stiffness: float | None = None,
+        stretch_damping: float | None = None,
+        shear_stiffness: float | None = None,
+        shear_damping: float | None = None,
+        bend_stiffness: float | None = None,
+        bend_damping: float | None = None,
+        twist_stiffness: float | None = None,
+        twist_damping: float | None = None,
     ) -> None:
-        """Overwrite each non-None stiffness and its inferred target mode, in :meth:`add_joint_rod` axis order."""
+        """Overwrite non-None material gains and target modes in :meth:`add_joint_rod` slot order.
+
+        Args:
+            joint: Rod joint index.
+            stretch_stiffness: Per-joint stretch stiffness [N/m], or ``None`` to preserve it.
+            stretch_damping: Per-joint stretch damping [N·s/m], or ``None`` to preserve it.
+            shear_stiffness: Per-joint shear stiffness [N/m], or ``None`` to preserve it.
+            shear_damping: Per-joint shear damping [N·s/m], or ``None`` to preserve it.
+            bend_stiffness: Per-joint bend stiffness [N·m/rad], or ``None`` to preserve it.
+            bend_damping: Per-joint bend damping [N·m·s/rad], or ``None`` to preserve it.
+            twist_stiffness: Per-joint twist stiffness [N·m/rad], or ``None`` to preserve it.
+            twist_damping: Per-joint twist damping [N·m·s/rad], or ``None`` to preserve it.
+        """
         joint_type = self.joint_type[joint]
         joint_dof_dim = self.joint_dof_dim[joint]
         if joint_type != JointType.ROD or joint_dof_dim != (2, 2):
             raise ValueError(
-                "_set_joint_rod_stiffnesses() expected the four-slot ROD layout "
+                "_set_joint_rod_material_gains() expected the four-slot ROD layout "
                 f"(2 linear, 2 angular); got joint type {JointType(joint_type).name} with dimensions "
                 f"{joint_dof_dim}. Update the ROD material-slot mapping when changing its slot layout."
             )
         dof_start = self.joint_qd_start[joint]
-        for offset, stiffness in enumerate((stretch_stiffness, shear_stiffness, bend_stiffness, twist_stiffness)):
-            if stiffness is not None:
+        stiffnesses = (stretch_stiffness, shear_stiffness, bend_stiffness, twist_stiffness)
+        dampings = (stretch_damping, shear_damping, bend_damping, twist_damping)
+        for offset, (stiffness, damping) in enumerate(zip(stiffnesses, dampings, strict=True)):
+            if stiffness is not None or damping is not None:
                 dof = dof_start + offset
-                damping = self.joint_target_kd[dof]
-                self.joint_target_ke[dof] = stiffness
+                if stiffness is not None:
+                    self.joint_target_ke[dof] = stiffness
+                if damping is not None:
+                    self.joint_target_kd[dof] = damping
+                resolved_stiffness = self.joint_target_ke[dof]
+                resolved_damping = self.joint_target_kd[dof]
                 self.joint_target_mode[dof] = int(
-                    JointTargetMode.from_gains(stiffness, damping, has_drive=stiffness != 0.0 or damping != 0.0)
+                    JointTargetMode.from_gains(
+                        resolved_stiffness,
+                        resolved_damping,
+                        has_drive=resolved_stiffness != 0.0 or resolved_damping != 0.0,
+                    )
                 )
 
     def add_constraint_mimic(

newton/_src/usd/utils.py

@@ -2128,7 +2128,13 @@ def _read_physics_attr(prim: Usd.Prim, name: str, compat_namespaces: Sequence[st
 
 
 def _read_deformable_material(
-    prim: Usd.Prim, read_attr: Callable[[Usd.Prim, str], Any], api_schema: str, attr_names: Sequence[str]
+    prim: Usd.Prim,
+    read_attr: Callable[[Usd.Prim, str], Any],
+    api_schema: str,
+    attr_names: Sequence[str],
+    *,
+    attr_namespace: str = "physics",
+    material_prim: Usd.Prim | None = None,
 ) -> dict[str, float] | None:
     """Read a per-family deformable material's authored, in-range parameters bound to a prim.
 
@@ -2140,13 +2146,25 @@ def _read_deformable_material(
 
     Returns a dict of the authored, in-range values among ``attr_names``, or ``None`` if the bound
     material does not declare ``api_schema``; an applied API with no valid authored values returns
-    an empty dict. Stiffness and Young's modulus accept zero; thickness must be positive; density
-    must be positive to be returned, while zero is its ignored sentinel; and Poisson's ratio must
-    lie in ``(-1, 0.5]``. The ``-inf`` simulator-default sentinel used by stiffness, Young's modulus,
-    and thickness is silently dropped. Other out-of-range or non-finite values are dropped with a
-    warning.
-    """
-    material_prim = _find_physics_material_prim(prim)
+    an empty dict. ``attr_namespace`` identifies the schema namespace in diagnostics; ``read_attr``
+    remains responsible for the actual namespace resolution. ``material_prim`` may supply an
+    already-resolved binding when one caller reads multiple APIs from the same material. Stiffness,
+    damping, and Young's modulus accept zero; thickness must be positive; density must be positive
+    to be returned, while zero is its ignored sentinel; and Poisson's ratio must lie in
+    ``(-1, 0.5]``. The ``-inf`` simulator-default sentinel used by stiffness, damping, Young's
+    modulus, and thickness is silently dropped. Other out-of-range or non-finite values are dropped
+    with a warning.
+
+    Args:
+        prim: Prim whose bound physics material is resolved.
+        read_attr: Callable that reads an attribute from the bound material.
+        api_schema: Applied material API required on the bound material.
+        attr_names: Attribute names to read and validate.
+        attr_namespace: Namespace used when reporting invalid attributes.
+        material_prim: Previously resolved bound material, if available.
+    """
+    if material_prim is None:
+        material_prim = _find_physics_material_prim(prim)
     if material_prim is None or not has_applied_api_schema(material_prim, api_schema):
         return None
     out: dict[str, float] = {}
@@ -2161,12 +2179,12 @@ def _read_deformable_material(
         if not math.isfinite(val):
             expected = "a finite value or the -inf sentinel" if has_negative_infinity_sentinel else "a finite value"
             warnings.warn(
-                f"{material_prim.GetPath()}: invalid physics:{name} {val:g} (expected {expected}); "
+                f"{material_prim.GetPath()}: invalid {attr_namespace}:{name} {val:g} (expected {expected}); "
                 f"treating it as unauthored.",
                 stacklevel=2,
             )
             continue
-        # Stiffness and Young's modulus accept [0, inf), so an authored zero is preserved.
+        # Stiffness, damping, and Young's modulus accept [0, inf), so an authored zero is preserved.
         # Thickness and density must be strictly positive.
         if name in ("thickness", "curvesThickness", "density"):
             if val > 0.0:
@@ -2179,7 +2197,7 @@ def _read_deformable_material(
                 # unauthored sentinel (-inf); say it is dropped so users can tell it apart
                 # from an unauthored value.
                 warnings.warn(
-                    f"{material_prim.GetPath()}: invalid physics:{name} {val:g} (expected > 0); "
+                    f"{material_prim.GetPath()}: invalid {attr_namespace}:{name} {val:g} (expected > 0); "
                     f"treating it as unauthored.",
                     stacklevel=2,
                 )
@@ -2188,32 +2206,50 @@ def _read_deformable_material(
                 out[name] = val
             else:
                 warnings.warn(
-                    f"{material_prim.GetPath()}: invalid physics:{name} {val:g} "
+                    f"{material_prim.GetPath()}: invalid {attr_namespace}:{name} {val:g} "
                     f"(expected -1 < value <= 0.5); treating it as unauthored.",
                     stacklevel=2,
                 )
         elif val >= 0.0:
             out[name] = val
         else:
             warnings.warn(
-                f"{material_prim.GetPath()}: invalid physics:{name} {val:g} "
+                f"{material_prim.GetPath()}: invalid {attr_namespace}:{name} {val:g} "
                 f"(expected >= 0); treating it as unauthored.",
                 stacklevel=2,
             )
     return out
 
 
+_NEWTON_CURVE_DAMPING_ATTRS = (
+    "curvesStretchDamping",
+    "curvesShearDamping",
+    "curvesBendDamping",
+    "curvesTwistDamping",
+)
+
+
 def _get_curve_deformable_material(
     prim: Usd.Prim, read_attr: Callable[[Usd.Prim, str], Any]
 ) -> dict[str, float] | None:
     """Read curve-deformable (cable) ``PhysicsCurvesDeformableMaterialAPI`` parameters bound to a prim.
 
     Returns a dict of authored, in-range values from the current AOUSD curve material proposal,
-    plus the earlier unprefixed material attributes during their deprecation window; or ``None``
-    if the bound material does not declare ``PhysicsCurvesDeformableMaterialAPI``. See
-    :func:`_read_deformable_material` for value-validation rules.
+    the earlier unprefixed material attributes during their deprecation window, and the four
+    per-mode ``newton:curves*Damping`` values when ``NewtonCurvesDeformableMaterialAPI`` is also
+    applied. Returns ``None`` if the bound material does not declare
+    ``PhysicsCurvesDeformableMaterialAPI``. See :func:`_read_deformable_material` for
+    value-validation rules.
+
+    Args:
+        prim: Curve prim whose bound physics material is read.
+        read_attr: Callable that reads an AOUSD attribute from the bound material.
     """
-    return _read_deformable_material(
+    material_prim = _find_physics_material_prim(prim)
+    if material_prim is None:
+        return None
+
+    material = _read_deformable_material(
         prim,
         read_attr,
         "PhysicsCurvesDeformableMaterialAPI",
@@ -2233,7 +2269,22 @@ def _get_curve_deformable_material(
             "bendStiffness",
             "twistStiffness",
         ),
+        material_prim=material_prim,
+    )
+    if material is None:
+        return None
+
+    newton_damping = _read_deformable_material(
+        prim,
+        lambda mat_prim, name: get_attribute(mat_prim, f"newton:{name}"),
+        "NewtonCurvesDeformableMaterialAPI",
+        _NEWTON_CURVE_DAMPING_ATTRS,
+        attr_namespace="newton",
+        material_prim=material_prim,
     )
+    if newton_damping is not None:
+        material.update(newton_damping)
+    return material
 
 
 def _get_surface_deformable_material(