Friction update modes

08 · Contact and friction

Two checks with known answers. A box slides at 2 m/s with μ = 0.5, so it should stop after v²/(2μg) = 408 mm. A ball spinning at 60 rad/s without moving slides until it rolls, and then rolls at 2/7·ωr = 0.857 m/s. friction_mode selects how Steel updates each contact's Coulomb cone; the experimental modes solve normal and friction impulses together and use point friction.

drag to orbit · scroll to zoom

0.00 s

What to look at

fixed_normal (default) and coulomb_newton stop the box at 404 mm.
bisection stops it at 431 mm: its friction is too weak while the box slides.
All three modes give the ball the same 0.84 m/s rolling speed.
Second scene, a box at 97% of its friction limit with the default 12 iterations: fixed_normal slips 0.11 mm in 5 s and coulomb_newton 0.07 mm, while bisection slides 1.2 m.
Both bisection results come from one cause: each probe scales the stick impulse radially onto the friction disk, which is the wrong projection for a contact off the center of mass. More iterations do not help.

Key parameter

friction_mode

"fixed_normal" (default), "bisection", "bisection_desaxce" or "coulomb_newton". Experimental; may change.

Try changing

Raise iterations to 32: bisection still slides on the slope.
Add "bisection_desaxce" to the loop.

Concept

Coulomb update

What it is

Each contact's friction must stay inside a cone of radius μ·λn. The default fixed_normal mode solves the two tangent impulses together on the disk of the current normal impulse. bisection and coulomb_newton solve normal and tangent impulses of a contact together.

In this scene

fixed_normal and coulomb_newton stop the sliding box at 404 mm against 408 mm analytic; bisection stops it at 431 mm. All three give the spinning ball 0.84 m/s against 0.857 analytic. At 97% of the limit fixed_normal and coulomb_newton hold the box to 0.1 mm, and bisection lets it slide 1.2 m in 5 s.

Considerations

Cost: The coupled modes do more work per contact and use point friction.
Accuracy: coulomb_newton matches fixed_normal on these checks. At 90% of the limit with only 4 iterations, one run had bisection slipping least (0.02 mm against 1.17 mm for fixed_normal and 0.38 mm for coulomb_newton); that was a transient that happened to fall its way, not an advantage.
Failure modes: bisection and bisection_desaxce converge to a slipping answer near the friction limit, and their normal-impulse bracket can miss the root. In a separate run at 97% of the limit, bisection_desaxce slid 0.44 m in 5 s at 12 iterations and 0.28 m at 32.
Interactions: Patches, torsion, compliance and contact_regularization need fixed_normal.
Use it when: fixed_normal with patches; coulomb_newton for free-body contacts near the friction limit. Avoid the bisection modes until the fix below lands.

The script

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

08_friction_mode.py
replay.py

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

"""friction_mode: the per-contact Coulomb update, checked against analytic results."""

import math

import newton
import numpy as np
import warp as wp
from newton.solvers import SolverSteel

from replay import Recorder

DT = 1.0 / 240.0
SUBSTEPS = 8
MU, SPEED, G = 0.5, 2.0, 9.81


def build():
    builder = newton.ModelBuilder()
    cfg = newton.ModelBuilder.ShapeConfig(mu=MU)
    builder.add_ground_plane(cfg=cfg)
    # a box sliding along x and a ball spinning without rolling (it slides until it rolls)
    box = builder.add_body(xform=wp.transform((-0.6, -0.15, 0.05), wp.quat_identity()))
    builder.add_shape_box(box, hx=0.05, hy=0.05, hz=0.05, cfg=cfg)
    ball = builder.add_body(xform=wp.transform((-0.6, 0.15, 0.05), wp.quat_identity()))
    builder.add_shape_sphere(ball, radius=0.05, cfg=cfg)
    model = builder.finalize()
    model.joint_qd.assign(np.array([SPEED, 0, 0, 0, 0, 0, 0, 0, 0, 0, 60.0, 0], dtype=np.float32))
    return model


def build_slope(ratio=0.97):
    """A box near the top of a 3 m slope, at ``ratio`` of its friction limit, above a floor."""
    builder = newton.ModelBuilder()
    angle = math.atan(ratio * MU)
    tilt = wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), -angle)
    cfg = newton.ModelBuilder.ShapeConfig(mu=MU)
    builder.add_ground_plane(cfg=cfg)
    center = np.array([0.0, 0.0, 1.5 * math.sin(angle)])
    builder.add_shape_box(-1, xform=wp.transform(center, tilt), hx=1.5, hy=0.2, hz=0.05, cfg=cfg)
    normal = np.array(wp.quat_rotate(tilt, wp.vec3(0.0, 0.0, 1.0)))
    uphill = np.array(wp.quat_rotate(tilt, wp.vec3(1.0, 0.0, 0.0)))
    start = center + 1.2 * uphill + 0.11 * normal
    box = builder.add_body(xform=wp.transform(start, tilt))
    builder.add_shape_box(box, hx=0.12, hy=0.08, hz=0.06, cfg=cfg)
    return builder.finalize()


def simulate_slope(rec, mode):
    model = build_slope()
    solver = SolverSteel(model, friction_mode=mode, friction_anchor_beta=0.0)
    pipeline = newton.CollisionPipeline(model)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()
    start = state_0.body_q.numpy()[0, :3].copy()

    run = rec.variant(f'slope at 97% of the limit, "{mode}"', model, scene="slope")
    for _ in range(rec.frames(5.0)):
        run.frame(
            state_0, slope_slip_mm=1000.0 * np.linalg.norm(state_0.body_q.numpy()[0, :3] - start)
        )
        for _ in range(SUBSTEPS):
            pipeline.collide(state_0, contacts)
            solver.step(state_0, state_1, control, contacts, DT)
            state_0, state_1 = state_1, state_0
    run.check(solver)


def simulate(rec, mode):
    model = build()
    solver = SolverSteel(model, friction_mode=mode, friction_anchor_beta=0.0)
    pipeline = newton.CollisionPipeline(model)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()
    newton.eval_fk(model, model.joint_q, model.joint_qd, state_0)
    start = state_0.body_q.numpy()[0, 0]

    run = rec.variant(f'friction_mode="{mode}"', model, scene="slide")
    for _ in range(rec.frames(1.5)):
        q, qd = state_0.body_q.numpy(), state_0.body_qd.numpy()
        run.frame(state_0, slide_mm=1000.0 * (q[0, 0] - start), ball_v=qd[1, 0])
        for _ in range(SUBSTEPS):
            pipeline.collide(state_0, contacts)
            solver.step(state_0, state_1, control, contacts, DT)
            state_0, state_1 = state_1, state_0
    run.check(solver)


if __name__ == "__main__":
    print(f"analytic stopping distance v^2 / (2 mu g) = {1000 * SPEED**2 / (2 * MU * G):.1f} mm")
    rec = Recorder()
    for mode in ["fixed_normal", "bisection", "coulomb_newton"]:
        simulate(rec, mode)
    for mode in ["fixed_normal", "bisection", "coulomb_newton"]:
        simulate_slope(rec, mode)
    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.