Joint limit activation gap

38 · Joints and drives

A twelve-link chain with ±20° hinges and no collisions, released with its root far outside its limit, so the lower joints slam into their bounds. With enable_joint_limits, joint_limit_activation_gap decides how close to a bound a joint gets a limit row. The default is speed-aware: a row appears within 0.05 + 2·h·|v| of a bound. inf makes rows for every finite limit every step; 0 makes them only once a joint is already past its bound.

drag to orbit · scroll to zoom

0.00 s

Cost

Time per step, CUDA graph replay, median of 7 interleaved rounds on one NVIDIA RTX PRO 6000 Blackwell Server Edition; ratios are against the first row. Solver allocation is the GPU memory the solver allocates at construction, before warm-up and graph capture. Scene: the twelve-link limited chain in each world.

Option	1 world	64 worlds	1024 worlds	solver allocation, 1024 worlds	result in this tutorial
gap=None (default)	0.21 ms	0.25 ms	0.35 ms	19 MB	worst overshoot 3.33°, 12 rows
gap=inf	0.25 ms 1.18×	0.29 ms 1.17×	0.41 ms 1.17×	19 MB	3.32°, 24 rows
gap=0	0.20 ms 0.95×	0.24 ms 0.97×	0.34 ms 0.98×	19 MB	5.21°, 11 rows

What to look at

Default and inf hold the lower joints to the same worst overshoot (3.33° vs 3.32°), but the default needs 12 limit rows at most and inf 24.
gap=0 creates rows too late: the worst overshoot grows to 5.2°.

Key parameter

joint_limit_activation_gap

Distance from a bound [m or rad] at which a limit row is created. None (default) is speed-aware; inf creates every finite limit's row each step.

Try changing

Add contacts that push the joints toward their bounds and compare None with inf.
Use drive_mode="rows": then None creates every limit row, like inf.

Concept

Speculative limit rows

What it is

A limit row is speculative while the joint is inside its bound: it applies no impulse unless the joint would cross the bound within the step. A row for a joint far from its bound therefore does nothing but cost a row. The speed-aware gap skips those rows and keeps the ones a joint can reach this step.

In this scene

The default needs half the rows of inf (12 vs 24) with the same overshoot; gap=0 overshoots 5.2° instead of 3.3°.

Considerations

Cost: Fewer rows: 0.35 vs 0.41 ms per step at 1024 worlds (15%), 0.21 vs 0.25 ms in one world.
Failure modes: Constraint impulses inside the solve, such as contacts, can push a gated joint past the margin in one step; the docstring names this case.
Interactions: Mimic and loop-closure joints, their subtrees, and drive_mode="rows" keep every limit row.
Use it when: Keep the default for robots with many limited joints; use inf when contacts drive joints into their stops hard.

The script

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

38_limit_activation_gap.py
replay.py

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

"""joint_limit_activation_gap: create joint-limit rows only near a bound."""

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
LINKS = 12
LIMIT = math.radians(20.0)


def tf(x, y, z):
    return wp.transform((x, y, z), wp.quat_identity())


def build():
    """A twelve-link chain with +-20 degree hinges whose joints slam into their limits."""
    builder = newton.ModelBuilder()
    parent, joints = -1, []
    for i in range(LINKS):
        link = builder.add_link(xform=tf(0.0, 0.0, 1.0 - 0.12 * i - 0.06))
        # no collisions: every row in this scene is a joint-limit row
        cfg = newton.ModelBuilder.ShapeConfig(has_shape_collision=False)
        builder.add_shape_capsule(link, radius=0.025, half_height=0.035, cfg=cfg)
        builder.add_shape_sphere(
            link,
            xform=tf(0.0, 0.0, -0.05),
            radius=0.03,
            cfg=newton.ModelBuilder.ShapeConfig(density=4000.0, has_shape_collision=False),
        )
        anchor = tf(0.0, 0.0, 1.0) if parent < 0 else tf(0.0, 0.0, -0.06)
        joints.append(
            builder.add_joint_revolute(
                parent,
                link,
                axis=newton.Axis.Y,
                parent_xform=anchor,
                child_xform=tf(0.0, 0.0, 0.06),
                limit_lower=-LIMIT,
                limit_upper=LIMIT,
                armature=0.001,
            )
        )
        builder.joint_q[-1] = 1.4 if i == 0 else 0.0  # the root starts far outside its limit
        parent = link
    builder.add_articulation(joints)
    return builder.finalize()


def simulate(rec, label, gap):
    model = build()
    solver = SolverSteel(
        model,
        enable_joint_limits=True,
        joint_limit_activation_gap=gap,
        row_watermark=True,
    )
    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)
    worst = 0.0
    for _ in range(rec.frames(3.0)):
        # limit violation of the lower joints, which start inside their limits
        q = np.abs(state_0.joint_q.numpy()[1:])
        worst = max(worst, math.degrees(max(0.0, q.max() - LIMIT)))
        rows = solver.constraint_row_watermarks()["articulation_raw_high_water"]
        run.frame(
            state_0,
            violation_deg=math.degrees(max(0.0, q.max() - LIMIT)),
            limit_rows_high_water=rows,
        )
        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)
    print(f"{label}: worst violation {worst:.2f} deg")


if __name__ == "__main__":
    rec = Recorder()
    simulate(rec, "gap=None (default, speed-aware)", None)
    simulate(rec, "gap=inf (every finite limit, every step)", float("inf"))
    simulate(rec, "gap=0 (rows only past the bound)", 0.0)
    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.