Hydroelastic contact and compliance

20 · Compliance and adhesion

A dense sphere and box dropped onto a pad. Point contacts give a few rows per pair. Hydroelastic contact finds the equal-pressure surface inside the overlap, integrates pressure over it, and reports contacts with a stiffness each. Steel can solve those rows rigidly, or with contact_compliance as an implicit spring-damper, so objects sink to a depth set by the hydroelastic modulus kh.

drag to orbit · scroll to zoom

0.00 s

What to look at

The rigid variants rest at zero penetration.
With compliance, kh = 1e7 sinks the sphere about 6 mm and kh = 1e6 about 21 mm.
The box dropped from 10 cm decelerates at up to 26 g on rigid contacts, 11 g at kh = 1e7 and 4.8 g at 1e6: compliance spreads the impact.

Key parameter

contact_compliance

Experimental. Requires point friction, no warm start and no velocity iterations. The stiffness comes from ShapeConfig.kh with is_hydroelastic=True.

Try changing

Set kh = 3e6.
Drop the sphere from 20 cm.

Concept

Compliant contact

What it is

With contact_compliance, a contact that carries a stiffness k and damping c is an implicit unilateral spring-damper instead of a rigid row. Stiffness comes from the hydroelastic modulus kh, so objects sink until the pressure carries their weight.

f = max(0, −k φ − c u)

In this scene

The 4 g/cm³ box sinks 0.83 mm at kh = 1e7 and 8.6 mm at 1e6; rigid laws hold it at the surface. A box dropped from 10 cm peaks at 26 g of deceleration on rigid contacts, 11 g and 4.8 g with compliance.

Considerations

Cost: Hydroelastic patches bring many contacts: this scene raises row capacities to 512 and 4096.
Interactions: Requires point friction, no warm start, no velocity iterations, no regularization and zero restitution.
Accuracy: Penetration is the physical deformation; it is not removed. Impact loads are lower and closer to a real soft contact.
Use it when: Soft fingertips, pads and impacts where force peaks matter; keep rigid contacts elsewhere.

The script

cd tutorials && python 20_hydroelastic_compliance.py prints each variant's final metric; --record out.json also writes the replay. Every tutorial imports replay.py from the same folder.

20_hydroelastic_compliance.py
replay.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Hydroelastic contacts, solved rigidly or with contact_compliance."""

import newton
import warp as wp
from newton.geometry import HydroelasticSDF
from newton.solvers import SolverSteel

from replay import Recorder

DT = 1.0 / 240.0
SUBSTEPS = 8


def build(hydroelastic, kh):
    builder = newton.ModelBuilder()
    cfg = newton.ModelBuilder.ShapeConfig(
        mu=0.6,
        is_hydroelastic=hydroelastic,
        kh=kh,
        gap=0.005,
        sdf_max_resolution=48,
        sdf_narrow_band_range=(-0.02, 0.02),
        sdf_padding=0.01,
    )
    builder.add_shape_box(
        -1,
        xform=wp.transform((0.0, 0.0, -0.03), wp.quat_identity()),
        hx=0.25,
        hy=0.25,
        hz=0.03,
        cfg=cfg,
    )
    heavy = cfg.copy()
    heavy.density = 4000.0
    sphere = builder.add_body(xform=wp.transform((-0.1, 0.0, 0.065), wp.quat_identity()))
    builder.add_shape_sphere(sphere, radius=0.06, cfg=heavy)
    box = builder.add_body(xform=wp.transform((0.1, 0.0, 0.05), wp.quat_identity()))
    builder.add_shape_box(box, hx=0.05, hy=0.05, hz=0.05, cfg=heavy)
    # a third box dropped from 10 cm above the pad, to compare impact loads
    drop = builder.add_body(xform=wp.transform((0.0, 0.15, 0.15), wp.quat_identity()))
    builder.add_shape_box(drop, hx=0.05, hy=0.05, hz=0.05, cfg=heavy)
    model = builder.finalize()
    model.rigid_contact_max = 4096
    return model


def simulate(rec, label, hydroelastic, kh=1.0e7, **options):
    model = build(hydroelastic, kh)
    if hydroelastic:
        hydro = HydroelasticSDF.Config(
            reduce_contacts=True, moment_matching=True, anchor_contact=True, buffer_fraction=1.0
        )
        pipeline = newton.CollisionPipeline(
            model, rigid_contact_max=4096, sdf_hydroelastic_config=hydro
        )
        # a hydroelastic patch brings many contacts: raise the row capacities
        options.update(articulation_constraint_max=512, free_body_constraint_max=4096)
    else:
        pipeline = newton.CollisionPipeline(model)
    solver = SolverSteel(model, friction_anchor_beta=0.0, **options)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()

    run = rec.variant(label, model)
    for _ in range(rec.frames(2.0)):
        q = state_0.body_q.numpy()
        sphere_mm, box_mm = 1000.0 * (q[0, 2] - 0.06), 1000.0 * (q[1, 2] - 0.05)
        impact_g = 0.0  # largest deceleration of the dropped box during the frame
        for _ in range(SUBSTEPS):
            vz = state_0.body_qd.numpy()[2, 2]
            pipeline.collide(state_0, contacts)
            solver.step(state_0, state_1, control, contacts, DT)
            state_0, state_1 = state_1, state_0
            impact_g = max(impact_g, abs(state_0.body_qd.numpy()[2, 2] - vz) / DT / 9.81)
        run.frame(state_0, sphere_mm=sphere_mm, box_mm=box_mm, impact_g=impact_g)
    run.check(solver)


if __name__ == "__main__":
    rec = Recorder()
    simulate(rec, "point contacts, rigid", False)
    simulate(rec, "hydroelastic, rigid law", True)
    simulate(rec, "hydroelastic + contact_compliance, kh 1e7", True, 1.0e7, contact_compliance=True)
    simulate(rec, "hydroelastic + contact_compliance, kh 1e6", True, 1.0e6, contact_compliance=True)
    rec.save()

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Record Steel tutorial runs as replay JSON for the tutorials page, or print a summary.

Every tutorial imports this module. ``python NN_name.py`` runs the variants and prints
the final metric of each; ``--record out.json`` also writes body poses, shapes and metric
series that the page replays in 3D.
"""

import argparse
import base64
import json
import os
import subprocess
import sys
import time

import newton
import numpy as np
import warp as wp

from source_hash import source_sha256

_RENDERED_TYPES = {
    newton.GeoType.PLANE,
    newton.GeoType.SPHERE,
    newton.GeoType.CAPSULE,
    newton.GeoType.ELLIPSOID,
    newton.GeoType.CYLINDER,
    newton.GeoType.BOX,
    newton.GeoType.MESH,
    newton.GeoType.CONE,
    newton.GeoType.CONVEX_MESH,
}


class Recorder:
    """Collect the variants of one tutorial; ``fps`` is the replay frame rate."""

    def __init__(self, fps: int = 30):
        parser = argparse.ArgumentParser()
        parser.add_argument(
            "--record", metavar="OUT.json", help="write a replay file for the tutorials page"
        )
        parser.add_argument("--device", default=None, help="Warp device, for example cuda:0")
        self.args = parser.parse_args()
        if self.args.device:
            wp.set_device(self.args.device)
        self.fps = fps
        self.script = os.path.abspath(sys.argv[0])
        self.variants: list[Variant] = []

    def frames(self, seconds: float) -> int:
        """Number of replay frames in ``seconds``, including the first."""
        return int(round(seconds * self.fps)) + 1

    def variant(
        self,
        label: str,
        model: newton.Model,
        *,
        ghost: bool = False,
        slot: int | None = None,
        scene: str | None = None,
    ) -> "Variant":
        """Start one run; ``ghost`` overlays run ``slot``, ``scene`` groups runs for charts."""
        variant = Variant(label, model, self.fps, ghost, slot, scene)
        self.variants.append(variant)
        return variant

    def save(self) -> None:
        """Print a summary and, with ``--record``, write the replay file."""
        for variant in self.variants:
            last = variant.metrics[-1] if variant.metrics else {}
            flag = "  (rows dropped)" if variant.overflow else ""
            print(f"{variant.label:<48} {json.dumps(last)}  {variant.wall:.2f} s{flag}")
        if not self.args.record:
            return
        source_sha = source_sha256(self.script)
        doc = {
            "script": os.path.basename(self.script),
            "script_sha256": source_sha,
            "newton_commit": _newton_commit(),
            "newton_version": newton.__version__,
            "warp_version": wp.config.version,
            "gpu": wp.get_device().name,
            "fps": self.fps,
            "variants": [v.to_json() for v in self.variants],
        }
        with open(self.args.record, "w") as f:
            json.dump(doc, f, separators=(",", ":"))
        print(f"wrote {self.args.record}")


class Variant:
    """One recorded run: a pose per frame for every body, plus named metric values."""

    def __init__(self, label, model, fps, ghost, slot, scene):
        self.label, self.model, self.fps, self.ghost, self.slot = label, model, fps, ghost, slot
        self.scene = scene
        self.poses: list[np.ndarray] = []
        self.metrics: list[dict] = []
        self.awake: list[list[int]] = []
        self.particles: list[np.ndarray] = []
        self.overflow = False
        self.start = time.perf_counter()
        self.wall = 0.0

    def frame(self, state: newton.State, awake=None, particles=None, **metrics) -> None:
        """Record ``state.body_q``, optional awake flags, particle positions and metric values."""
        self.poses.append(state.body_q.numpy().astype(np.float32).copy())
        if particles is not None:
            self.particles.append(particles.numpy().astype(np.float32).copy())
        self.metrics.append({k: _round(v) for k, v in metrics.items()})
        if awake is not None:
            self.awake.append([int(x) for x in awake.numpy()])
        self.wall = time.perf_counter() - self.start

    def check(self, solver) -> None:
        """Note whether the solver dropped rows; call once after the run."""
        try:
            solver.check_constraint_capacity()
        except RuntimeError:
            self.overflow = True

    def to_json(self) -> dict:
        poses = (
            np.stack(self.poses)
            if self.poses
            else np.zeros((0, self.model.body_count, 7), np.float32)
        )
        return {
            "label": self.label,
            "fps": self.fps,
            "ghost": self.ghost,
            "slot": self.slot,
            "scene": self.scene,
            "bodies": int(self.model.body_count),
            "frames": int(poses.shape[0]),
            "poses": base64.b64encode(poses.astype(np.float32).tobytes()).decode(),
            "shapes": _shape_table(self.model),
            "metric": self.metrics,
            "awake": self.awake or None,
            "particles": self._particles_json(),
            "wall_s": round(self.wall, 3),
            "overflow": self.overflow,
        }

    def _particles_json(self):
        if not self.particles:
            return None
        frames = np.stack(self.particles)
        tris = self.model.tri_indices
        radius = self.model.particle_radius.numpy()
        return {
            "count": int(frames.shape[1]),
            "frames": base64.b64encode(frames.astype(np.float32).tobytes()).decode(),
            "radius": round(float(radius.mean()), 5) if radius.size else 0.0,
            "tris": [int(v) for v in tris.numpy().reshape(-1)]
            if tris is not None and tris.shape[0]
            else None,
        }


def _shape_table(model):
    types = model.shape_type.numpy()
    scales = model.shape_scale.numpy()
    xforms = model.shape_transform.numpy()
    bodies = model.shape_body.numpy()
    flags = model.shape_flags.numpy()
    shapes = []
    for i, t in enumerate(types):
        if int(t) not in _RENDERED_TYPES or not flags[i] & int(newton.ShapeFlags.VISIBLE):
            continue
        shape = {
            "b": int(bodies[i]),
            "t": int(t),
            "s": [round(float(v), 5) for v in scales[i]],
            "x": [round(float(v), 6) for v in xforms[i]],
        }
        if int(t) in (newton.GeoType.MESH, newton.GeoType.CONVEX_MESH):
            mesh = model.shape_source[i]
            shape["v"] = [round(float(v), 5) for v in np.asarray(mesh.vertices).reshape(-1)]
            shape["i"] = [int(v) for v in np.asarray(mesh.indices).reshape(-1)]
        shapes.append(shape)
    return shapes


def _round(value):
    value = float(value)
    return round(value, 5) if np.isfinite(value) else None


def _newton_commit():
    if os.environ.get("NEWTON_COMMIT"):
        return os.environ["NEWTON_COMMIT"]
    try:
        root = os.path.dirname(os.path.dirname(newton.__file__))
        return subprocess.check_output(["git", "-C", root, "rev-parse", "HEAD"], text=True).strip()
    except (OSError, subprocess.CalledProcessError):
        return None

Recorded with SolverSteel on Newton 1.9.0.dev0, Warp 1.19.0, NVIDIA RTX PRO 6000 Blackwell Server Edition. Replays read the state back every frame, so they are not a speed benchmark. Script · page text

Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.