Relaxation and CFM

28 · Convergence

relaxation scales every Gauss-Seidel update: each row moves its impulse ω times the step that would satisfy it. ω above 1 over-relaxes and carries corrections further per sweep; below 1 under-relaxes. cfm adds a small constant to every row's effective-mass diagonal. The eight-box stack runs at 6 iterations with ω = 1, 1.4 and 1.8 and with cfm = 0.01; a second scene drops a ball with restitution 0.8 at ω = 1 and 1.8; a third rests a 1 kg sphere on the ground with and without contact_regularization, at cfm 1e-6 (default) and 1.

drag to orbit · scroll to zoom

0.00 s

What to look at

Stack: sag falls from 4.3 mm (ω = 1) to 2.5 mm (1.4) and 1.1 mm (1.8).
cfm 0.01 leaves the sag at about 4.4 mm. cfm only enters the denominator of each update, so it scales each step by A/(A + cfm), with A the row's unit response (1/m for a contact in line with a body's center of mass, more off it); for these 1 kg boxes 0.01 changes each step by about 1% or less.
Resting sphere: without regularization, cfm 1 still leaves it on the surface, since the sweep converges to the same impulse. With contact_regularization=0.5 it settles 0.43 mm deep, and cfm 1, equal to its A, doubles that to 0.85 mm.
Bounce: at ω = 1.8 the second bounce reaches 23 cm instead of 32 cm, and the ball stops sooner.

Key parameter

relaxation / cfm

relaxation defaults to 1.0 and is read every step. cfm defaults to 1e-6 and is fixed at construction; drive rows of drive_mode="rows" use their exact response instead.

Try changing

Try ω = 1.8 on the four-bar loop closure tutorial at 2 iterations.
Raise cfm to 0.1 on the stack: the converged sag barely changes; lower iterations to 2 to see the slower sweep.

Concept

Successive over-relaxation and constraint force mixing

What it is

Over-relaxation multiplies each row's Gauss-Seidel correction by ω. On slowly converging problems, such as load running down a stack, it speeds convergence. Coupled friction modes are not scaled. cfm adds a value to the diagonal of ordinary scalar rows: it shortens each step like ω below 1 and leaves the answer of an unregularized row unchanged, but a row regularized by contact_regularization settles at a residual that grows with A + cfm.

λ ← λ + ω · Δλ

In this scene

ω = 1.8 cut the stack's sag from 4.3 to 1.1 mm at 6 iterations, but took 28% off the second bounce of a restitution 0.8 ball (32 → 23 cm). In separate runs ω = 1.6 cut a four-bar's closure gap at 2 iterations from 163 to 52 mm; ω = 1.4 left a 40-object pile with five times the residual kinetic energy of ω = 1; cfm from 1e-6 to 0.01 changed neither scene. On the regularized sphere cfm 1 doubled the resting penetration (0.43 → 0.85 mm).

Considerations

Cost: None: the same sweeps with a different step.
Interactions: cfm also floors the regularization of enable_bilateral_preelimination. Drive rows of drive_mode="rows" and the coupled friction modes' contact blocks leave it out, and compliant normal rows of contact_compliance replace it with their compliance term.
Accuracy: ω > 1 overshoots single contacts, which damps bounces and can leave piles jittering.
Use it when: Raise ω to 1.4–1.8 for stacks and loops at low iteration counts after checking bounces and resting piles. Leave cfm at its default; to soften contacts use contact_regularization or contact_compliance.

The script

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

28_relaxation_cfm.py
replay.py

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

"""relaxation over-relaxes each Gauss-Seidel update; cfm shifts each row's diagonal."""

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

from replay import Recorder

DT = 1.0 / 240.0
SUBSTEPS = 8
N, H = 8, 0.05  # eight 10 cm boxes
R = 0.05  # m, a 1 kg sphere: its contact row's unit response is about 1 / (1 kg)


def build_stack():
    builder = newton.ModelBuilder()
    builder.add_ground_plane(cfg=newton.ModelBuilder.ShapeConfig(mu=0.6))
    for i in range(N):
        box = builder.add_body(
            xform=wp.transform((0.0, 0.0, H + 2 * H * i + 0.0002 * i), wp.quat_identity())
        )
        builder.add_shape_box(box, hx=H, hy=H, hz=H, cfg=newton.ModelBuilder.ShapeConfig(mu=0.6))
    return builder.finalize()


def build_ball():
    builder = newton.ModelBuilder()
    cfg = newton.ModelBuilder.ShapeConfig(restitution=0.8)
    builder.add_ground_plane(cfg=cfg)
    ball = builder.add_body(xform=wp.transform((0.0, 0.0, 0.56), wp.quat_identity()))
    builder.add_shape_sphere(ball, radius=0.06, cfg=cfg)
    return builder.finalize()


def build_sphere():
    builder = newton.ModelBuilder()
    builder.add_ground_plane()
    sphere = builder.add_body(xform=wp.transform((0.0, 0.0, R), wp.quat_identity()))
    density = 1.0 / (4.0 / 3.0 * 3.14159265 * R**3)
    builder.add_shape_sphere(sphere, radius=R, cfg=newton.ModelBuilder.ShapeConfig(density=density))
    return builder.finalize()


def simulate(rec, label, scene, **options):
    model = {"stack": build_stack, "ball": build_ball, "rest": build_sphere}[scene]()
    solver = SolverSteel(model, **options)
    pipeline = newton.CollisionPipeline(model)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()

    run = rec.variant(label, model, scene=scene)
    for _ in range(rec.frames(4.0 if scene == "stack" else 2.0)):
        z = state_0.body_q.numpy()[:, 2]
        if scene == "stack":
            run.frame(state_0, sag_mm=1000.0 * (H * (2 * N - 1) - z[N - 1]))
        elif scene == "rest":
            run.frame(state_0, penetration_mm=1000.0 * (R - z[0]))
        else:
            run.frame(state_0, height=z[0] - 0.06)
        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()
    for relaxation in [1.0, 1.4, 1.8]:
        default = " (default)" if relaxation == 1.0 else ""
        simulate(
            rec,
            f"stack, relaxation={relaxation}{default}",
            "stack",
            iterations=6,
            relaxation=relaxation,
        )
    simulate(rec, "stack, cfm=1e-2", "stack", iterations=6, cfm=1.0e-2)
    for relaxation in [1.0, 1.8]:
        simulate(rec, f"bounce, relaxation={relaxation}", "ball", relaxation=relaxation)
    # cfm moves the resting point only of a regularized row: the residual is -g (A + cfm) lambda
    simulate(rec, "rest, cfm=1", "rest", cfm=1.0)
    for cfm in [1.0e-6, 1.0]:
        simulate(
            rec, f"rest, regularized, cfm={cfm:g}", "rest", cfm=cfm, contact_regularization=0.5
        )
    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.