Add asOverDog Kamino locomotion example

[han-xudong]

Description

Closes #4112.

Add an asOverDog locomotion example for Bennett, planar, and spherical overconstrained closed-chain leg mechanisms.

The example:

• selects the mechanism with --robot;
• simulates closed-loop joints with SolverKamino and DVI contact dynamics;
• evaluates the ONNX gait policy and shared learned actuator on the Warp device;
• captures one 50 Hz policy period containing eight 400 Hz physics steps in a CUDA Graph when available;
• accepts keyboard and command-line planar velocity and yaw-rate commands;
• caps viewer rendering at 50 FPS by default while retaining the common --render-fps override;
• checks simulation stability and loop-closure error for every mechanism.

Companion assets pull request: newton-physics/newton-assets#51

This PR is draft until the companion assets are merged. No public Newton APIs are added or changed.

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• For user-facing changes, a fragment has been added by following the changelog fragment instructions

Test plan

The tests below were run against a local checkout of assets PR #51 exposed through the Newton asset cache.

NEWTON_CACHE_PATH=/tmp/newton-asoverdog-assets-cache \
  uv run --extra dev --extra examples -m newton.tests \
  -k example_kamino_robot_asoverdog

uv run --extra dev --extra examples -m newton.tests \
  -k test_asoverdog_render_fps_default

uvx pre-commit run -a

uvx --from towncrier==25.8.0 towncrier build --draft \
  --version 0.0.0 --date 2026-09-01

New feature / API change

uv run --extra examples -m newton.examples kamino_robot_asoverdog --robot bennett

Summary by CodeRabbit

• New Features

  • Added a Kamino asOverDog quadruped simulation example supporting Bennett, planar, and spherical robot variants.
  • Added movement, reset, rendering, and validation options for the example.
  • Added the example to the README gallery with usage instructions.

• Tests

  • Added automated coverage for all supported robot variants and rendering settings.

• Documentation

  • Added a changelog entry describing the new example.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Team

Run ID: 691ce7d0-c8ab-442b-8431-163bc762baec

📥 Commits

Reviewing files that changed from the base of the PR and between 95d9402 and 412d52b.

⛔ Files ignored due to path filters (1)

• docs/images/examples/example_kamino_robot_asoverdog.jpg is excluded by !**/*.jpg

📒 Files selected for processing (4)

• README.md
• changelog/4112.added.md
• newton/examples/kamino/example_kamino_robot_asoverdog.py
• newton/tests/test_examples.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Added a Kamino asOverDog example for Bennett, planar, and spherical closed-chain quadruped variants. The example uses SolverKamino, ONNX locomotion policies, a learned actuator, CUDA graph capture, command inputs, runtime validation, and registered subprocess tests.

Changes

asOverDog Kamino locomotion

Layer / File(s)	Summary
Robot and control contracts newton/examples/kamino/example_kamino_robot_asoverdog.py	Defines robot configurations, joint mappings, control dimensions, label resolution, and learned actuator loading.
Device control kernels newton/examples/kamino/example_kamino_robot_asoverdog.py	Adds kernels for observation history, policy actions, actuator inputs, motor torque limits, and loop-closure error.
Simulation runtime newton/examples/kamino/example_kamino_robot_asoverdog.py	Initializes SolverKamino, loads policies, runs physics substeps, supports CUDA graph capture, handles commands and resets, renders frames, and parses command-line options.
Validation and publication newton/examples/kamino/example_kamino_robot_asoverdog.py, newton/tests/test_examples.py, README.md, changelog/4112.added.md	Validates state, height, and loop-closure error. Registers Bennett, planar, and spherical subprocess tests. Documents the example and its invocation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 412d5

This PR adds a localized locomotion example and documentation without changing public APIs or introducing a concrete production risk; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CommandInput
  participant Example
  participant ONNXPolicy
  participant WarpKernels
  participant SolverKamino
  CommandInput->>Example: movement command or reset
  Example->>WarpKernels: build observation
  WarpKernels->>ONNXPolicy: observation tensor
  ONNXPolicy->>WarpKernels: action tensor
  WarpKernels->>SolverKamino: actuator forces and contact step
  SolverKamino->>WarpKernels: updated state and loop anchors
  WarpKernels->>Example: loop-closure error

Loading

Suggested reviewers: adenzler-nvidia

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 2 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the asOverDog Kamino locomotion example.
Linked Issues check	✅ Passed	The changes implement the requested asOverDog example for Bennett, planar, and spherical variants. The example uses SolverKamino, robot-specific ONNX policies, learned actuation, multi-rate simulation…
Out of Scope Changes check	✅ Passed	The changes are limited to the requested example, its tests, README documentation, and changelog entry. No unrelated code changes or public Newton API changes are indicated.

Full details: Linked Issues check

Explanation

The changes implement the requested asOverDog example for Bennett, planar, and spherical variants. The example uses SolverKamino, robot-specific ONNX policies, learned actuation, multi-rate simulation, command input, CUDA Graph support, loop-closure validation, and stability checks. Tests, documentation, and a changelog entry are also included.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}