Armature

37 · Joints and drives

Three identical pendulums with armature 0, 0.02 and 0.1 kg·m². Armature adds rotor inertia to a DOF in joint space, as in a geared motor. It slows the joint's response, which also slows the fastest motions of light links. A second scene swings a chain of six light capsules with armature 0, 0.001 and 0.01 kg·m² for 8 s.

drag to orbit · scroll to zoom

Pause0.00 s

0.1×¼×½×1×2×

Reset view

In review

Documents in the solver that fast, light chains gain energy from the explicit Coriolis and centrifugal forces of the step, and what reduces it. skild-ai/newton#19

What to look at

• Larger armature gives a longer swing period, so the three drift out of phase.
• Chain, energy as a share of its starting swing energy: without armature it rises by up to 197% and then swings erratically; 0.001 kg·m² still gains up to 46%; 0.01 kg·m² stays within 6%.
• The chain has no constraint rows, so iterations change nothing: the energy comes from the explicit velocity-product forces of the step, and shrinks with a smaller time step.

Key parameter

armature

Joint argument [kg·m² or kg]. Added to the joint-space mass matrix diagonal.

Try changing

• Use armature 1.0.
• Add a stiff drive to a very light link with and without armature.
• Set DT = 1/960 and SUBSTEPS = 32 and watch the chain's energy gain shrink.

Concept

Armature

What it is

Armature adds inertia directly to a DOF on the mass-matrix diagonal, the reflected inertia of a geared motor. It slows the joint's response and improves the conditioning of light links; it also changes the model.

H̃ = H + diag(armature)

In this scene

The pendulum period grows from 1.33 s to about 1.65 s at 0.1 kg·m². Over 8 s the light chain gains up to 197% of its swing energy without armature, 46% with 0.001 kg·m² and 6% with 0.01.

Considerations

Cost

None.

Stability

Fast, light chains gain energy because the step takes Coriolis and centrifugal forces at its start, as SolverFeatherstone and MuJoCo's euler integrator do. In separate runs a free-swinging 9-link chain of light capsules reached NaN within 3 s at 200 and 240 Hz; armature 0.001 kg·m² only delayed that to 6 to 8 s, while 0.01 kept it bounded over 30 s. A smaller step also helps: without armature, the 6-link chain at 960 Hz stayed bounded over 30 s.

Accuracy

Large armature changes the dynamics; use real motor values where known.

Use it when

Geared joints with known motor inertia. For light chains that gain energy, a smaller step comes first; armature that dominates the links' inertia also works, at the cost of changing the model.

The script

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

37_armature.py

tutorials/37_armature.py

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

"""Joint armature: rotor inertia added to a DOF slows its response, also on fast light links."""

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
ARMATURE = [0.0, 0.02, 0.1]  # kg m^2
CHAIN_ARMATURE = [0.0, 0.001, 0.01]  # kg m^2


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


def build():
    builder = newton.ModelBuilder()
    for i, armature in enumerate(ARMATURE):
        y = 0.45 * i - 0.45
        link = builder.add_link(xform=tf(0.0, y, 0.8))
        builder.add_shape_capsule(
            link,
            xform=tf(0.0, 0.0, -0.2),
            radius=0.02,
            half_height=0.18,
            cfg=newton.ModelBuilder.ShapeConfig(density=400.0),
        )
        builder.add_shape_sphere(
            link,
            xform=tf(0.0, 0.0, -0.4),
            radius=0.05,
            cfg=newton.ModelBuilder.ShapeConfig(density=2000.0),
        )
        j = builder.add_joint_revolute(
            -1, link, axis=newton.Axis.Y, parent_xform=tf(0.0, y, 0.8), armature=armature
        )
        builder.add_articulation([j])
    model = builder.finalize()
    model.joint_q.fill_(math.radians(60.0))
    return model


def build_chain(armature):
    """Six light capsule links hanging from a hinge, released at 1.2 rad."""
    builder = newton.ModelBuilder()
    parent, joints = -1, []
    for i in range(6):
        link = builder.add_link(xform=tf(0.0, 0.0, 1.0 - 0.1 * i - 0.05))
        builder.add_shape_capsule(link, radius=0.02, half_height=0.03)
        anchor = tf(0.0, 0.0, 1.0) if parent < 0 else tf(0.0, 0.0, -0.05)
        joints.append(
            builder.add_joint_revolute(
                parent,
                link,
                axis=newton.Axis.Y,
                parent_xform=anchor,
                child_xform=tf(0.0, 0.0, 0.05),
                armature=armature,
            )
        )
        builder.joint_q[-1] = 1.2 if i == 0 else 0.0
        parent = link
    builder.add_articulation(joints)
    return builder.finalize()


def swing_energy(model, state):
    """Energy above the chain hanging straight down at rest [J]."""
    rest = model.state()
    newton.eval_fk(model, wp.zeros_like(model.joint_q), model.joint_qd, rest)
    return energy(model, state) - energy(model, rest)


def energy(model, state):
    """Kinetic plus potential energy, including the joints' armature [J]."""
    mass, inertia = model.body_mass.numpy(), model.body_inertia.numpy()
    q, qd = state.body_q.numpy(), state.body_qd.numpy()
    total = 0.5 * (model.joint_armature.numpy() * state.joint_qd.numpy() ** 2).sum()
    for b in range(model.body_count):
        rot = np.array(wp.quat_to_matrix(wp.quat(*q[b, 3:]))).reshape(3, 3)
        omega = qd[b, 3:]
        total += (
            0.5 * mass[b] * qd[b, :3] @ qd[b, :3] + 0.5 * omega @ rot @ inertia[b] @ rot.T @ omega
        )
        total += mass[b] * 9.81 * q[b, 2]
    return total


def simulate_chain(rec, armature):
    model = build_chain(armature)
    solver = SolverSteel(model)
    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, swing = energy(model, state_0), swing_energy(model, state_0)

    run = rec.variant(f"light chain, armature {armature:g}", model, scene="chain")
    for _ in range(rec.frames(8.0)):
        run.frame(state_0, energy_change_pct=100.0 * (energy(model, state_0) - start) / swing)
        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, label):
    model = build()
    solver = SolverSteel(model)
    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, scene="pendulums")
    for _ in range(rec.frames(5.0)):
        q = np.degrees(state_0.joint_q.numpy())
        run.frame(state_0, **{f"armature_{a:g}": q[i] for i, a in enumerate(ARMATURE)})
        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, "armature 0 | 0.02 | 0.1 kg m^2")
    for armature in CHAIN_ARMATURE:
        simulate_chain(rec, armature)
    rec.save()

replay.py

tutorials/replay.py

# 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