Performance options

60 · Solver and runtime

A fixed trunk with eight driven three-link branches, plus a separate two-link arm, so the model has two articulation sizes. Four construction options change how Steel schedules its work, not the physics: parallel_tree walks independent branches in parallel, use_parallel_streams runs each size group on its own CUDA stream, double_buffer clears scratch buffers on a side stream, and reuse_kinematics carries the step's kinematics into the next step instead of re-deriving them.

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 eight-branch tree and two-link arm in each world.

Option	1 world	64 worlds	1024 worlds	solver allocation, 1024 worlds	result in this tutorial
defaults	0.40 ms	0.47 ms	0.65 ms	160 MB	reference
parallel_tree	0.39 ms 0.97×	0.44 ms 0.93×	0.59 ms 0.91×	161 MB	identical trajectory
use_parallel_streams	0.39 ms 0.96×	0.46 ms 0.98×	0.64 ms 0.99×	161 MB	identical
double_buffer	0.40 ms 0.99×	0.47 ms 1.00×	0.65 ms 1.00×	190 MB	identical
reuse_kinematics	0.40 ms 0.99×	0.46 ms 0.99×	0.64 ms 0.99×	160 MB	within 0.03 µm

What to look at

All four runs match the default run: the largest body difference is 0 mm, and 0.03 µm with reuse_kinematics.
The Cost table shows which one pays off on this tree.

Key parameter

parallel_tree / use_parallel_streams / double_buffer / reuse_kinematics

Construction options; results are unchanged up to float summation order.

Try changing

Make the branches longer and count them again.
Add a FREE joint below the root and check solver.reuse_kinematics, which reports whether it runs.

Concept

Scheduling options

What it is

Steel walks each articulation tree for kinematics, dynamics and publication. parallel_tree gives a branched tree up to 32 threads instead of one; use_parallel_streams overlaps the factorization of different articulation sizes; double_buffer hides buffer clears; reuse_kinematics skips recomputing the kinematics the last step already formed.

In this scene

Trajectories are identical to the default. parallel_tree saved 9% per step at 1024 worlds (0.59 vs 0.65 ms); the others were within 1–3%.

Considerations

Cost: double_buffer kept 30 MB more at 1024 worlds for no gain here; the rest add no memory.
Interactions: reuse_kinematics stays off with the parallel tree, sleeping, joint velocity limits or a FREE joint that is not first; state edits outside step need notify_state_changed.
Failure modes: Narrow trees can get slower with parallel_tree; measure the full step.
Use it when: parallel_tree for broad branched robots such as hands and multi-legged bodies; test the others on your own model.

The script

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

60_performance_options.py
replay.py

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

"""Performance options: parallel_tree, use_parallel_streams, double_buffer and reuse_kinematics."""

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
OPTIONS = {
    "defaults": {},
    "parallel_tree": {"parallel_tree": True},
    "use_parallel_streams + double_buffer": {"use_parallel_streams": True, "double_buffer": True},
    "reuse_kinematics": {"reuse_kinematics": True},
}


def tf(x, y, z, q=None):
    return wp.transform((x, y, z), q if q is not None else wp.quat_identity())


def build():
    """A trunk with eight driven three-link branches, plus a two-link arm as a second size group."""
    builder = newton.ModelBuilder()
    builder.add_ground_plane()
    trunk = builder.add_link(xform=tf(0.0, 0.0, 0.8))
    builder.add_shape_cylinder(trunk, radius=0.06, half_height=0.05)
    joints = [builder.add_joint_fixed(-1, trunk, parent_xform=tf(0.0, 0.0, 0.8))]
    for k in range(8):
        yaw = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 2.0 * math.pi * k / 8)
        parent, anchor = trunk, wp.transform(wp.quat_rotate(yaw, wp.vec3(0.07, 0.0, 0.0)), yaw)
        for i in range(3):
            link = builder.add_link(xform=tf(0.0, 0.0, 0.8))
            builder.add_shape_capsule(
                link,
                xform=tf(
                    0.06, 0.0, 0.0, wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), math.pi / 2)
                ),
                radius=0.015,
                half_height=0.045,
                cfg=newton.ModelBuilder.ShapeConfig(has_shape_collision=False),
            )
            axis = newton.Axis.Y if i else newton.Axis.Z
            joints.append(
                builder.add_joint_revolute(
                    parent,
                    link,
                    axis=axis,
                    parent_xform=anchor,
                    target_ke=40.0,
                    target_kd=1.0,
                    armature=0.001,
                )
            )
            builder.joint_q[-1] = 0.3 * math.sin(k + i)
            parent, anchor = link, tf(0.12, 0.0, 0.0)
    builder.add_articulation(joints)
    base = builder.add_link(xform=tf(0.6, 0.0, 0.3))
    builder.add_shape_box(base, hx=0.02, hy=0.02, hz=0.1)
    j0 = builder.add_joint_revolute(
        -1, base, axis=newton.Axis.Y, parent_xform=tf(0.6, 0.0, 0.4), child_xform=tf(0.0, 0.0, 0.1)
    )
    tip = builder.add_link(xform=tf(0.6, 0.0, 0.1))
    builder.add_shape_box(tip, hx=0.02, hy=0.02, hz=0.1)
    j1 = builder.add_joint_revolute(
        base,
        tip,
        axis=newton.Axis.Y,
        parent_xform=tf(0.0, 0.0, -0.1),
        child_xform=tf(0.0, 0.0, 0.1),
    )
    builder.joint_q[-2:] = [0.8, 0.4]
    builder.add_articulation([j0, j1])
    return builder.finalize()


def simulate(rec, label, reference=None):
    model = build()
    solver = SolverSteel(model, **OPTIONS[label])
    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)
    # sway the branch targets so the tree keeps moving
    targets = control.joint_target_q.numpy()

    run = rec.variant(label, model)
    for frame in range(rec.frames(4.0)):
        t = frame / rec.fps
        control.joint_target_q.assign((targets + 0.4 * math.sin(2.0 * t)).astype(np.float32))
        q = state_0.body_q.numpy()
        diff = (
            0.0
            if reference is None
            else 1000.0 * np.abs(q[:, :3] - reference.poses[frame][:, :3]).max()
        )
        run.frame(state_0, difference_mm=diff)
        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}: reuse_kinematics runs = {solver.reuse_kinematics}")
    return run


if __name__ == "__main__":
    rec = Recorder()
    reference = simulate(rec, "defaults")
    for label in list(OPTIONS)[1:]:
        simulate(rec, label, reference)
    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.