proofmass-check 0.1.0__py3-none-any.whl

proofmass_check/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""Physics checks for SimReady OpenUSD assets.
+
+Start with the command line: `proofmass-check run asset.usd --engine physx`.
+docs/spec.md describes every check, its rule and its numbers.
+"""
+
+__version__ = "0.1.0"

proofmass_check/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""Lets `python -m proofmass_check` work like the `proofmass-check` command."""
+
+import sys
+
+from proofmass_check.cli import main
+
+sys.exit(main())

proofmass_check/checks/__init__.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""The checks: what each one measures and how it decides PASS or FAIL.
+
+Each check asks the engine for a few measurements (engines/base.py) and judges them against the
+numbers in rules.py. No check knows which engine it runs on.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from proofmass_check import rules
+
+Verdict = Literal["PASS", "FAIL", "N/A"]
+
+# Every check, in the order a run reports them, with a one-line title.
+TITLES = {
+    "LOAD": "the engine builds the asset as the USD describes it",
+    "DROP": f"dropped from {rules.DROP_HEIGHT * 100:g} cm, comes to rest on the floor",
+    "HOLD": "drives hold the rest pose under gravity",
+    "TRACK": f"each drive reaches {rules.TRACK_AT[0]:.0%} and {rules.TRACK_AT[1]:.0%} of its range",
+    "LIMIT": "joint limits stop a drive commanded past them",
+    "STABLE": f"stable in {rules.RANDOM_POSES} random poses inside the limits",
+    "SPEED": f"at a {1 / rules.SPEED_DT:.0f} Hz physics step, each drive stays under its speed limit",
+    "PASSIVE": "each joint without a drive, when pushed, reaches both limits and stops there",
+    "GRIP": f"holds {rules.GRIP_LOAD:.0%} of gripper_maxPayload pulled two ways",
+    "SHAKE": f"holds {rules.GRIP_LOAD:.0%} of gripper_maxPayload shaken at up to 2 g",
+    "STAND": f"dropped from {rules.DROP_HEIGHT * 100:g} cm with its wheels braked, stands upright and still",
+    "DRIVE": "all driven wheels forward: drives straight along +X at the commanded speed",
+    "TURN": "wheels in opposite directions: turns in place at the expected rate",
+    "STEER": f"steered to {rules.STEER_FRACTION:.0%} of its range: drives a circle of the Ackermann radius",
+}
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    id: str
+    verdict: Verdict
+    detail: str
+
+    @property
+    def title(self) -> str:
+        return TITLES[self.id]
+
+
+def judge(check_id: str, ok: bool, detail: str) -> CheckResult:
+    return CheckResult(check_id, "PASS" if ok else "FAIL", detail)
+
+
+def not_applicable(check_id: str, reason: str) -> CheckResult:
+    return CheckResult(check_id, "N/A", reason)

proofmass_check/checks/drop.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""DROP: lifted and let go, the asset comes to rest on the floor."""
+
+import math
+
+import numpy as np
+
+from proofmass_check.checks import CheckResult, judge
+from proofmass_check.engines.base import Engine
+from proofmass_check.geometry import lowest_collider, tilt
+from proofmass_check.model import Asset
+from proofmass_check.rules import DROP_HEIGHT, DROP_SECONDS, FLOOR_TOL, REST_SPEED
+
+
+def resting(finite: bool, speed: float, gap: float) -> bool:
+    """At rest: slower than REST_SPEED, with the lowest collider within FLOOR_TOL of the floor."""
+    return finite and speed < REST_SPEED and abs(gap) < FLOOR_TOL
+
+
+def drop(engine: Engine, asset: Asset, floor: float) -> CheckResult:
+    """The asset may end in any pose: a prop can also come to rest on its side.
+
+    The tilt is reported, but it does not decide the result.
+    """
+    outcome = engine.drop(DROP_HEIGHT, DROP_SECONDS)
+    lowest = min(
+        (
+            lowest_collider(asset.bodies[path], rotation, position)
+            for path, (rotation, position) in outcome.poses.items()
+        ),
+        default=math.inf,
+    )
+    gap = lowest - floor
+    root = asset.root_body
+    turned = math.degrees(tilt(asset.bodies[root].pose[:3, :3], outcome.poses[root][0])) if outcome.finite else math.nan
+    finite = outcome.finite and bool(np.isfinite(gap))
+    gap_mm = round(gap * 1000, 2) + 0.0  # adding 0.0 turns -0.0 into 0.0, so the text never says "-0.00 mm"
+    return judge(
+        "DROP",
+        resting(finite, outcome.root_speed, gap),
+        f"final speed {outcome.root_speed:.4f} m/s, lowest collider {gap_mm:+.2f} mm from the floor, "
+        f"tilted {turned:.0f} deg",
+    )

proofmass_check/checks/grip.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""GRIP and SHAKE: the gripper holds its rated payload. This follows NVIDIA's FET028 test.
+
+The fingers close on a box at the grasp centre. The box has no weight, so only the pull tests the
+grip. A slip is the box moving along the pads. Motion along the closing axis is drift: two fingers
+that each push with their force limit carry the box with them, and that is not a slip.
+"""
+
+from collections.abc import Sequence
+
+import numpy as np
+
+from proofmass_check.checks import CheckResult, judge, not_applicable
+from proofmass_check.engines.base import Engine, GripBox, GripOutcome, GripSetup
+from proofmass_check.geometry import apply, turn
+from proofmass_check.model import Asset, GripperSite, Joint
+from proofmass_check.rules import (
+    GRIP_HOLD_S,
+    GRIP_LOAD,
+    GRIP_LOADS,
+    GRIP_MIN_TRAVEL,
+    GRIP_SLIP,
+    GRIP_WIDTH,
+    LIMIT_TOL,
+    SHAKE_HZ,
+    Settings,
+)
+
+
+def choose_site(asset: Asset) -> tuple[GripperSite | None, list[str]]:
+    """The site GRIP tests, and a note for each site it does not test.
+
+    GRIP tests the first site that has gripper_maxPayload, sits on a rigid body, and belongs to a
+    gripper fixed to the world (a free gripper would fall).
+    """
+    fixed = bool(asset.world_fixed)
+    found, notes = None, []
+    for site in asset.sites:
+        why = (
+            "no gripper_maxPayload" if not site.payload
+            else "not on a rigid body" if not site.body
+            else "the gripper is not fixed to the world" if not fixed
+            else f"GRIP tests one site, {found.name}" if found
+            else None
+        )  # fmt: skip
+        if why:
+            notes.append(f"gripper site {site.name}: {why}, so GRIP does not test it")
+        else:
+            found = site
+    return found, notes
+
+
+def closing_targets(asset: Asset, site: GripperSite) -> dict[str, float]:
+    """The finger joints of a site, each with the limit that closes it.
+
+    A finger joint is a limited, position-driven joint below the site's body. Its closing limit is
+    the one that brings the bodies it moves nearer the grasp centre along the closing axis. A joint
+    that moves them less than GRIP_MIN_TRAVEL along that axis does not close the gripper.
+    The file pose is taken as each joint at its rest position.
+    """
+    below = set(asset.carried(site.body))
+    targets = {}
+    for joint in asset.joints:
+        if joint.drive_kind != "position" or not joint.limited or joint.body0 not in below:
+            continue
+        moved = [asset.bodies[path] for path in asset.carried(joint.body1)]
+        centre = np.mean([apply(b.pose, b.com) for b in moved], axis=0)
+        gaps = {}
+        for limit in (joint.lower, joint.upper):
+            if joint.revolute:
+                at_limit = joint.pivot + turn(centre - joint.pivot, joint.direction, limit - joint.rest)
+            else:
+                at_limit = centre + (limit - joint.rest) * joint.direction
+            gaps[limit] = abs((at_limit - site.centre) @ site.closing)
+        if abs(gaps[joint.lower] - gaps[joint.upper]) >= GRIP_MIN_TRAVEL:
+            targets[joint.name] = min(gaps, key=gaps.get)
+    return targets
+
+
+def grip_box(site: GripperSite) -> GripBox:
+    """The box: GRIP_WIDTH of the maximum opening across the pads, and the pad size in the other two directions."""
+    rotation = np.column_stack([np.cross(site.line, site.forward), site.line, site.forward])
+    return GripBox(size=(GRIP_WIDTH * site.opening, site.pad, site.pad), centre=site.centre, rotation=rotation)
+
+
+def gripped(joints: Sequence[Joint], closed: dict[str, float], targets: dict[str, float], settings: Settings) -> bool:
+    """True when the fingers stopped on the box: at least one finger short of its closing limit.
+
+    One is enough. With two fingers on separate drives, one can carry the box until it meets its
+    limit, and the other then holds the box against it. All fingers at their limits means the
+    gripper closed past the box.
+    """
+    return any(abs(closed[j.name] - targets[j.name]) > LIMIT_TOL * settings.tolerance(j.revolute) for j in joints)
+
+
+def grip_and_shake(engine: Engine, asset: Asset, site: GripperSite, settings: Settings) -> list[CheckResult]:
+    targets = closing_targets(asset, site)
+    if not targets:
+        return [
+            judge("GRIP", False, f"site {site.name}: no position drive closes the fingers"),
+            not_applicable("SHAKE", "GRIP found no finger drive"),
+        ]
+    fingers = [asset.joint(name) for name in targets]
+    hold = {j.name: j.rest for j in asset.joints if j.drive_kind == "position" and j.name not in targets}
+    setup = GripSetup(
+        site=site,
+        box=grip_box(site),
+        close=targets,
+        hold=hold,
+        close_seconds=settings.settle_s,
+        pull_seconds=GRIP_HOLD_S,
+        shake_hz=SHAKE_HZ,
+    )
+    scene = engine.grip_scene(setup)
+
+    def held(outcome: GripOutcome) -> tuple[bool, str]:
+        motion = np.asarray(outcome.motion, float)
+        drift = float(abs(motion @ site.closing))
+        slip = float(np.linalg.norm(motion - (motion @ site.closing) * site.closing))
+        closed = gripped(fingers, outcome.closed, targets, settings)
+        ok = outcome.finite and closed and slip < GRIP_SLIP
+        words = f"slid {slip * 1000:.1f} mm" if slip < 0.1 else "the box is lost"
+        if GRIP_SLIP <= drift < 0.1:
+            words += f", drifted {drift * 1000:.1f} mm with the fingers"
+        return ok, words + ("" if ok else " SLIP" if closed else " NOT GRIPPED")
+
+    payload = site.payload
+    rows, best_both = [], []
+    for label, direction in (("out of the fingers", site.forward), ("along the grip line", site.line)):
+        best, tried = 0.0, []
+        for fraction in GRIP_LOADS:
+            ok, words = held(scene.trial(fraction * payload, direction, shake=False))
+            tried.append(f"{fraction * payload:g} kg {words}")
+            if not ok:
+                break
+            best = fraction
+        best_both.append(best)
+        rows.append(f"{label} holds {best * payload:g} kg ({', '.join(tried)})")
+    grip = judge("GRIP", min(best_both) >= GRIP_LOAD, f"site {site.name}, payload {payload:g} kg: " + "; ".join(rows))
+    ok, words = held(scene.trial(GRIP_LOAD * payload, site.forward, shake=True))
+    shake = judge("SHAKE", ok, f"{GRIP_LOAD * payload:g} kg at {SHAKE_HZ:g} Hz: {words}")
+    return [grip, shake]

proofmass_check/checks/joints.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""HOLD, TRACK, LIMIT and STABLE: what the position drives do.
+
+Every move starts from the rest pose. The joint under test gets a target, and every other
+position-driven joint holds its rest position.
+"""
+
+from collections.abc import Sequence
+
+import numpy as np
+
+from proofmass_check.checks import CheckResult, judge, text
+from proofmass_check.engines.base import Engine
+from proofmass_check.model import Joint
+from proofmass_check.rules import LIMIT_TOL, OVERSHOOT, SEED, TRACK_AT, UNSTABLE_SPEED, Settings
+
+
+def rest_pose(driven: Sequence[Joint]) -> dict[str, float]:
+    return {j.name: j.rest for j in driven}
+
+
+def move_time(settings: Settings, distance: float, max_speed: float) -> float:
+    """The time a drive gets for a move: settle_s, plus the time its speed limit needs for the distance.
+
+    A long joint with a speed limit, such as an arm that turns 180 deg at 120 deg/s, cannot get
+    there in settle_s alone. A speed limit of 0 or less is read as no limit.
+    """
+    return settings.settle_s + (abs(distance) / max_speed if max_speed > 0 else 0.0)
+
+
+def hold(engine: Engine, driven: Sequence[Joint], settings: Settings) -> CheckResult:
+    state = engine.settle(rest_pose(driven), settings.settle_s)
+    errors = {j.name: abs(state.positions[j.name] - j.rest) for j in driven}
+    ok = state.finite and all(errors[j.name] <= settings.tolerance(j.revolute) for j in driven)
+    return judge("HOLD", ok, "; ".join(f"{j.name} {text.error(j, errors[j.name])}" for j in driven))
+
+
+def track(engine: Engine, driven: Sequence[Joint], limited: Sequence[Joint], settings: Settings) -> CheckResult:
+    rows, ok_all = [], True
+    for joint in limited:
+        for fraction in TRACK_AT:
+            target = joint.lower + fraction * (joint.upper - joint.lower)
+            state = engine.settle(
+                {**rest_pose(driven), joint.name: target}, move_time(settings, target - joint.rest, joint.max_speed)
+            )
+            error = abs(state.positions[joint.name] - target)
+            ok = state.finite and error <= settings.tolerance(joint.revolute)
+            ok_all &= ok
+            rows.append(f"{joint.name}@{fraction:.0%} {text.error(joint, error)}{'' if ok else ' FAIL'}")
+    return judge("TRACK", ok_all, "; ".join(rows))
+
+
+def limit(engine: Engine, driven: Sequence[Joint], limited: Sequence[Joint], settings: Settings) -> CheckResult:
+    """Each drive is sent OVERSHOOT of its range past its upper limit. It may stop LIMIT_TOL tolerances past it."""
+    rows, ok_all = [], True
+    for joint in limited:
+        target = joint.upper + OVERSHOOT * (joint.upper - joint.lower)
+        state = engine.settle(
+            {**rest_pose(driven), joint.name: target}, move_time(settings, joint.upper - joint.rest, joint.max_speed)
+        )
+        past = state.positions[joint.name] - joint.upper
+        ok = state.finite and past <= LIMIT_TOL * settings.tolerance(joint.revolute)
+        ok_all &= ok
+        rows.append(f"{joint.name} {text.error(joint, max(past, 0.0))} past limit{'' if ok else ' FAIL'}")
+    return judge("LIMIT", ok_all, "; ".join(rows))
+
+
+def stable(engine: Engine, driven: Sequence[Joint], limited: Sequence[Joint], settings: Settings) -> CheckResult:
+    """Random poses inside the limits. A pose is unstable when a value is not finite or a joint is too fast."""
+    rng = np.random.default_rng(SEED)
+    unstable = 0
+    for _ in range(settings.random_poses):
+        draws = rng.random(len(limited))
+        pose = rest_pose(driven) | {
+            j.name: j.lower + d * (j.upper - j.lower) for j, d in zip(limited, draws, strict=True)
+        }
+        state = engine.settle(pose, settings.settle_s)
+        unstable += (not state.finite) or state.max_speed > UNSTABLE_SPEED
+    return judge("STABLE", unstable == 0, f"{unstable} unstable")

proofmass_check/checks/load.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""LOAD: the engine builds every joint, and the same total mass as the USD."""
+
+import dataclasses
+
+from proofmass_check.checks import CheckResult, judge
+from proofmass_check.engines.base import LoadOutcome
+from proofmass_check.model import Asset
+from proofmass_check.rules import MASS_TOL
+
+
+def built(outcome: LoadOutcome) -> bool:
+    """True when the engine and the USD have the same joints. Other checks need this."""
+    return not outcome.missing and not outcome.unknown
+
+
+def load(asset: Asset, outcome: LoadOutcome) -> CheckResult:
+    given = [b.mass for b in asset.bodies.values()]
+    usd_mass = sum(given) if all(given) else None  # only when the USD gives every mass
+    engine_mass = sum(outcome.masses.values())
+    moving = [j for j in asset.joints if j.moves]
+    position = sum(j.drive_kind == "position" for j in moving)
+    velocity = sum(j.drive_kind == "velocity" for j in moving)
+    detail = f"{len(moving)} joints ({position} position, {velocity} velocity drives), "
+    detail += f"mass in the engine {engine_mass:.2f} kg"
+    if usd_mass is None:
+        detail += f" (the USD gives it for {sum(map(bool, given))} of {len(given)} bodies)"
+    else:
+        detail += f", in the USD {usd_mass:.2f} kg"
+    if outcome.missing:
+        detail += f"; joints the engine did not build: {list(outcome.missing)}"
+    if outcome.unknown:
+        detail += f"; engine joints that are not in the USD: {list(outcome.unknown)}"
+    mass_ok = usd_mass is None or abs(engine_mass - usd_mass) <= MASS_TOL * usd_mass
+    return judge("LOAD", built(outcome) and mass_ok, detail)
+
+
+def with_engine_masses(asset: Asset, outcome: LoadOutcome) -> Asset:
+    """The asset with the engine's mass and centre of mass for each body whose mass the USD leaves out.
+
+    PASSIVE and GRIP need every mass, and only the engine knows the ones it computes itself.
+    """
+    bodies = {
+        path: body
+        if body.mass is not None or path not in outcome.masses
+        else dataclasses.replace(body, mass=outcome.masses[path], com=outcome.coms.get(path, body.com))
+        for path, body in asset.bodies.items()
+    }
+    return dataclasses.replace(asset, bodies=bodies)

proofmass_check/checks/passive.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""PASSIVE: a joint without a drive, such as a door or a drawer, opens to its limits and stops there.
+
+The base push is what the joint needs against gravity, plus a little to get it moving. A joint held
+by friction (a door that stays where you leave it) needs more. So a push that does not reach the
+limit is tried again, PUSH_STEP times stronger each time, up to what a hand adds at the handle.
+"""
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+
+from proofmass_check.checks import CheckResult, judge, text
+from proofmass_check.engines.base import Engine
+from proofmass_check.geometry import apply
+from proofmass_check.model import Asset, Joint
+from proofmass_check.rules import (
+    GRAVITY,
+    HAND_FORCE,
+    LIMIT_TOL,
+    PUSH_ACCEL_ANGULAR,
+    PUSH_ACCEL_LINEAR,
+    PUSH_GRAVITY_FACTOR,
+    PUSH_MIN_LEVER,
+    PUSH_SETTLE,
+    PUSH_STEP,
+    Settings,
+)
+
+
+def passive_joints(asset: Asset) -> list[Joint]:
+    """The joints PASSIVE pushes: limited, not following another joint, and with no position drive.
+
+    A damping-only drive (a door closer) counts as no drive, except on a wheeled robot: there it
+    turns a wheel.
+    """
+    skip = {"position", "velocity"} if asset.wheeled else {"position"}
+    return [j for j in asset.joints if j.moves and j.limited and not j.mimic and j.drive_kind not in skip]
+
+
+def lever(asset: Asset, joint: Joint) -> tuple[float, float]:
+    """The mass a joint carries (kg), and for a revolute joint the distance of its centre of mass from the axis (m)."""
+    carried = [asset.bodies[path] for path in asset.carried(joint.body1)] if joint.body1 else []
+    unknown = [b.path for b in carried if b.mass is None]
+    if unknown:  # the engine reports these masses (checks/load.py: with_engine_masses)
+        raise ValueError(f"the mass of {unknown} is not known")
+    mass = sum(b.mass for b in carried)
+    if mass <= 0:
+        return 0.0, 0.0
+    com = sum(b.mass * apply(b.pose, b.com) for b in carried) / mass
+    return mass, float(np.linalg.norm(np.cross(com - joint.pivot, joint.direction)))
+
+
+def base_push(asset: Asset, joint: Joint, seconds: float) -> float:
+    """The force (N) or torque (N m) that moves a joint to a limit against gravity.
+
+    PUSH_GRAVITY_FACTOR times the largest gravity load on the joint, plus enough to accelerate what
+    it carries (PUSH_ACCEL_LINEAR or PUSH_ACCEL_ANGULAR), plus what a damper needs to cross the range
+    in half the push.
+    """
+    mass, distance = lever(asset, joint)
+    axis = joint.direction
+    if joint.revolute:
+        arm = max(distance, PUSH_MIN_LEVER)
+        tilt_of_axis = float(np.linalg.norm(np.cross(axis, [0.0, 0.0, 1.0])))  # 0 for a vertical axis
+        gravity = mass * (PUSH_GRAVITY_FACTOR * GRAVITY * tilt_of_axis * distance + PUSH_ACCEL_ANGULAR * arm**2)
+    else:
+        gravity = mass * (PUSH_GRAVITY_FACTOR * GRAVITY * abs(axis[2]) + PUSH_ACCEL_LINEAR)
+    damping = joint.drive.damping if joint.drive else 0.0
+    return gravity + damping * (joint.upper - joint.lower) / (seconds / 2)
+
+
+def hand_budget(asset: Asset, joint: Joint, seconds: float) -> float:
+    """The most PASSIVE pushes a joint with: base_push plus HAND_FORCE at the handle.
+
+    On a revolute joint the handle is twice as far from the axis as the centre of mass, and at
+    least PUSH_MIN_LEVER away.
+    """
+    arm = 1.0 if not joint.revolute else max(2 * lever(asset, joint)[1], PUSH_MIN_LEVER)
+    return base_push(asset, joint, seconds) + HAND_FORCE * arm
+
+
+def passive(engine: Engine, asset: Asset, joints: Sequence[Joint], settings: Settings) -> CheckResult:
+    seconds = PUSH_SETTLE * settings.settle_s
+    rows, ok_all = [], True
+    for joint in joints:
+        for row, ok in _push_both_ways(engine, asset, joint, seconds, settings):
+            ok_all &= ok
+            rows.append(row + ("" if ok else " FAIL"))
+    return judge("PASSIVE", ok_all, "; ".join(rows))
+
+
+def _push_both_ways(engine: Engine, asset: Asset, joint: Joint, seconds: float, settings: Settings):
+    effort, budget = base_push(asset, joint, seconds), hand_budget(asset, joint, seconds)
+    margin = LIMIT_TOL * settings.tolerance(joint.revolute)
+    unit = text.effort_unit(joint)
+    for sign, limit, side in ((1, joint.upper, "upper"), (-1, joint.lower, "lower")):
+        tried = effort
+        error = abs(engine.push(joint.name, sign * tried, seconds) - limit)
+        ok = math.isfinite(error) and error <= margin
+        if ok:
+            yield f"{joint.name}@{side} {text.error(joint, error)} from the limit", True
+            continue
+        while not ok and tried < budget:
+            tried = min(tried * PUSH_STEP, budget)
+            error = abs(engine.push(joint.name, sign * tried, seconds) - limit)
+            ok = math.isfinite(error) and error <= margin
+        if ok:
+            yield f"{joint.name}@{side} needs {tried:.3g} {unit} (base push {effort:.3g}, hand {budget:.3g})", True
+        else:
+            yield (
+                f"{joint.name}@{side} {text.error(joint, error)} from the limit at the hand push {budget:.3g} {unit}",
+                False,
+            )

proofmass_check/checks/speed.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""SPEED: at Isaac Sim's default physics step, each drive stays under its speed limit.
+
+An asset can be stable at a small step and break at the step most users run. This follows NVIDIA's
+velocity_limit benchmark.
+"""
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+
+from proofmass_check.checks import CheckResult, judge, text
+from proofmass_check.checks.joints import rest_pose
+from proofmass_check.engines.base import Engine
+from proofmass_check.model import Joint
+from proofmass_check.rules import (
+    LIMIT_TOL,
+    SPEED_DT,
+    SPEED_MARGIN,
+    SPEED_SECONDS,
+    SPEED_SKIP_STEPS,
+    SPEED_TOL,
+    Settings,
+)
+
+
+def far_target(joint: Joint) -> float:
+    """The end of the range farther from rest, SPEED_MARGIN of the range short of it."""
+    margin = SPEED_MARGIN * (joint.upper - joint.lower)
+    return joint.upper - margin if joint.rest <= (joint.lower + joint.upper) / 2 else joint.lower + margin
+
+
+def speed(engine: Engine, driven: Sequence[Joint], tested: Sequence[Joint], settings: Settings) -> CheckResult:
+    """tested: the driven joints with limits and a speed limit.
+
+    Each one moves to far_target for SPEED_SECONDS. After the first SPEED_SKIP_STEPS steps its speed
+    must stay within its limit plus SPEED_TOL. At the end, every driven joint must be inside its
+    limits: a coupling that blows up at a large step pushes joints out of them.
+    """
+    rows, ok_all = [], True
+    for joint in tested:
+        motion = engine.move({**rest_pose(driven), joint.name: far_target(joint)}, SPEED_SECONDS, SPEED_DT)
+        peak = float(np.max(np.abs(motion.speeds[joint.name][SPEED_SKIP_STEPS:]), initial=0.0))
+        inside = motion.finite and all(_inside(j, motion.positions[j.name], settings) for j in driven)
+        ok = inside and peak <= joint.max_speed * (1 + SPEED_TOL)
+        ok_all &= ok
+        rows.append(
+            f"{joint.name} {text.speed(joint, peak)} of {text.speed(joint, joint.max_speed, 'g')} "
+            f"{text.speed_unit(joint)}" + ("" if inside else ", a joint left its limits") + ("" if ok else " FAIL")
+        )
+    return judge("SPEED", ok_all, "; ".join(rows))
+
+
+def _inside(joint: Joint, position: float, settings: Settings) -> bool:
+    if not math.isfinite(position):
+        return False
+    if not joint.limited:
+        return True
+    margin = LIMIT_TOL * settings.tolerance(joint.revolute)
+    return joint.lower - margin <= position <= joint.upper + margin

proofmass_check/checks/text.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Paweł Kikta
+# SPDX-License-Identifier: Apache-2.0
+"""Joint values as people read them: degrees for an angle, millimetres for a short distance."""
+
+import math
+
+from proofmass_check.model import Joint
+
+
+def error(joint: Joint, value: float) -> str:
+    """A joint error or distance: "0.250 deg" or "1.20 mm"."""
+    return f"{math.degrees(value):.3f} deg" if joint.revolute else f"{value * 1000:.2f} mm"
+
+
+def speed(joint: Joint, value: float, digits: str = ".3g") -> str:
+    """A joint speed without its unit: deg/s for a revolute joint, m/s for a prismatic one."""
+    return format(math.degrees(value) if joint.revolute else value, digits)
+
+
+def speed_unit(joint: Joint) -> str:
+    return "deg/s" if joint.revolute else "m/s"
+
+
+def effort_unit(joint: Joint) -> str:
+    return "N m" if joint.revolute else "N"