Free-body angular friction defaults

14 · Contact and friction

A ball spinning at 25 rad/s and a ball rolling at 1 m/s, as in the spin and rolling friction tutorial. Instead of setting steel:condim on every shape, SolverSteel(free_rigid_torsional_friction=..., free_rigid_rolling_friction=...) gives every free-body contact a spin and a rolling coefficient [m] with one argument each, replacing the shapes' condim gate and coefficients for that coefficient only.

drag to orbit · scroll to zoom

0.00 s

What to look at

Default (condim 3, no override): the spinner still turns at 20.5 rad/s after 4 s and the roller rolls at 0.67 m/s.
Per-shape condim 6 and the override 0.01 / 0.004 m stop both balls identically: spin by 0.67 s, roll by 2.0 s.
Tripling the override stops them in 0.23 s and 0.7 s.

Key parameter

free_rigid_torsional_friction / free_rigid_rolling_friction

Coefficients in metres for every free-body contact; None (default) keeps the shapes' condim and coefficients. Experimental, construction-only.

Try changing

Sweep the rolling coefficient from 0.001 to 0.02 m in a loop of solvers.
Set only the torsional override and leave rolling to the shapes.

Concept

Solver-wide angular friction

What it is

Spin and rolling rows are normally opt-in per shape through steel:condim, with coefficients from shape_material_mu_torsional and _rolling. The two constructor overrides turn the rows on for every free-body contact and use one coefficient each, without touching shape data.

In this scene

The overrides reproduce per-shape condim 6 exactly (both stop in 0.67 s and 2.0 s); three times the coefficients stop the balls about three times sooner.

Considerations

Cost: Up to six rows per contact instead of three, as with condim 6; size free_body_constraint_max for it.
Interactions: Free-body contacts only; articulated links use steel:min_torsional_patch_radius. Requires the interleaved row schedule, fixed_normal friction and no contact compliance.
Accuracy: One coefficient for all shapes: mixed materials need per-shape values.
Use it when: Sweeping or randomizing rolling resistance, or using assets you cannot edit.

The script

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

14_free_angular_defaults.py
replay.py

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

"""Model-wide spin and rolling friction for free bodies with one SolverSteel argument."""

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


def build(condim=3):
    builder = newton.ModelBuilder()
    SolverSteel.register_custom_attributes(builder)
    cfg = newton.ModelBuilder.ShapeConfig(
        density=800.0, mu=0.6, mu_torsional=0.01, mu_rolling=0.004
    )
    builder.add_ground_plane(cfg=cfg)
    spinner = builder.add_body(xform=wp.transform((0.0, 0.0, 0.08), wp.quat_identity()))
    builder.add_shape_sphere(spinner, radius=0.08, cfg=cfg)
    marker = newton.ModelBuilder.ShapeConfig(density=0.0, has_shape_collision=False)
    builder.add_shape_box(
        spinner,
        xform=wp.transform((0.0, 0.0, 0.08), wp.quat_identity()),
        hx=0.06,
        hy=0.008,
        hz=0.004,
        cfg=marker,
    )
    roller = builder.add_body(xform=wp.transform((-0.6, 0.35, 0.08), wp.quat_identity()))
    builder.add_shape_sphere(roller, radius=0.08, cfg=cfg)
    model = builder.finalize()
    model.steel.condim.fill_(condim)
    # spin one ball about the vertical, roll the other at 1 m/s
    model.joint_qd.assign(np.array([0, 0, 0, 0, 0, 25.0, 1.0, 0, 0, 0, 0, 0], dtype=np.float32))
    return model


def simulate(rec, label, condim=3, **options):
    model = build(condim)
    solver = SolverSteel(model, **options)
    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)

    run = rec.variant(label, model)
    for _ in range(rec.frames(4.0)):
        qd = state_0.body_qd.numpy()
        run.frame(state_0, spin=qd[0, 5], roll=np.linalg.norm(qd[1, :3]))
        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__":
    rec = Recorder()
    simulate(rec, "condim 3, no override (default)")
    simulate(rec, "per-shape steel:condim 6", condim=6)
    # one argument per coefficient, for every free-body contact, without touching shape data
    simulate(
        rec,
        "free_rigid_*_friction = 0.01 / 0.004",
        free_rigid_torsional_friction=0.01,
        free_rigid_rolling_friction=0.004,
    )
    simulate(
        rec,
        "override 0.03 / 0.012 (3x)",
        free_rigid_torsional_friction=0.03,
        free_rigid_rolling_friction=0.012,
    )
    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.