Demos

NovaPhy demos are executable documentation. They live under python/demos/ and are also packaged as novaphy.demos unless a wheel is built with NOVAPHY_EXCLUDE_DEMOS=true.

Run the commands on this page from the repository root.

ViewerNull and supported headless modes work with the core install. Unified interactive/recording backends require pip install -e ".[viewer]". Historical Polyscope windows require pip install -e ".[viz]". The broader examples extra includes both viewer stacks.

Start with these

Workflow	Demo	Headless command	Backend
Native robot dynamics	mujoco/demo_robot_basic.py	python python/demos/mujoco/demo_robot_basic.py --backend cpu --world-count 16 --headless 120	CPU; optional CUDA
Multi-environment foundation	demo_multi_env_physics.py	python python/demos/demo_multi_env_physics.py --num-worlds 8 --steps 240	CPU
Unified viewer surface	demo_viewer_api_basic.py	python python/demos/demo_viewer_api_basic.py --headless 120 --test	ViewerNull
High-level IK	demo_ik_arm.py	python python/demos/demo_ik_arm.py --headless --target-pos 0.5 0.0 0.4	ViewerGL / CPU
Lunar gravity validation	demo_moon_surface_drop_time.py	python python/demos/demo_moon_surface_drop_time.py --headless	CPU
Space manipulator validation	demo_space_arm_dynamics.py	python python/demos/demo_space_arm_dynamics.py --headless 1700	CPU
SPH fluids	demo_sph_fluid.py	python python/demos/demo_sph_fluid.py --headless --steps 100	SPH CUDA build
Sparse-block LBM	demo_lbm_volume.py	python python/demos/demo_lbm_volume.py --viewer null --num-frames 2	ViewerNull; LBM CUDA for fluid steps

The headless commands exercise physics or lifecycle code without requiring a window. Interactive flags are not uniform across every historical demo; use python <demo> --help before composing options.

Viewer conventions

Newer demos use the common novaphy.viewer lifecycle:

• --viewer gl — interactive ModernGL window;
• --viewer null --num-frames N — deterministic no-window run;
• --viewer usd, rerun, or viser — when offered by the demo.

Some demos expose purpose-specific --headless or --visual flags instead of the generic --viewer selector. The tables below state the path and capability; they do not imply that every script accepts every viewer backend.

See Viewer and Recording for the backend API.

Rigid bodies and collision

Demo	What it shows
demo_pyramid_ball.py	Rigid pyramid struck by a sphere; selectable semi-implicit, Featherstone, or XPBD path
demo_friction_ramp.py	Coulomb friction on an inclined plane
demo_wall_break.py	Dynamic impact against a brick wall
demo_dominoes.py	Angular impulse and contact propagation
demo_unified_collision.py	Current collision-shape pair gallery
demo_heightfield.py	Heightfield collision
xpbd/demo_xpbd_pendulum.py	XPBD pendulum constraint
xpbd/demo_xpbd_stack.py	XPBD supported stack
xpbd/demo_xpbd_weld.py	XPBD welded bodies

python python/demos/demo_pyramid_ball.py --solver semi_implicit
python python/demos/demo_pyramid_ball.py --solver featherstone
python python/demos/demo_pyramid_ball.py --solver xpbd
python python/demos/xpbd/demo_xpbd_stack.py

Featherstone articulated dynamics

The former articulated-demo tree has been replaced by the current featherstone/ examples.

Demo	What it shows
featherstone/demo_fs_joint_gallery.py	Joint-type gallery
featherstone/demo_fs_pgs_rope.py	Rope with PGS contact and viewer
featherstone/demo_fs_pgs_cradle.py	Newton's cradle
featherstone/demo_fs_pgs_wrecking_ball.py	Articulated chain and rigid impact
featherstone/demo_fs_pgs_seesaw.py	Revolute seesaw and impact
featherstone/demo_fs_pgs_motor_arm.py	Driven articulated arm
featherstone/demo_fs_pgs_box_stack.py	Articulated solver contact stack
featherstone/demo_fs_pgs_free_joint_shape_zoo.py	Free-joint primitive shapes
featherstone/demo_fs_pgs_pyramids_numerous.py	Featherstone pyramid stress scene
featherstone/demo_fs_pgs_100_robots.py	Many-robot articulated scene
demo_100_robots.py	Shared Featherstone / XPBD robot-grid entry point

python python/demos/featherstone/demo_fs_pgs_rope.py --headless 120
python python/demos/featherstone/demo_fs_pgs_cradle.py --headless 240

Use --backend cuda only after novaphy.has_featherstone_cuda() reports True.

Native MuJoCo-style dynamics

These demos use NovaPhy's native SolverMuJoCo; they do not wrap a World or change the five-argument solver contract.

Demo	What it shows
mujoco/demo_mujoco_cartpole.py	Procedural double-pole cart-pole without contacts
mujoco/demo_mujoco_pyramids_numerous.py	Rigid pyramid grid and projectile
mujoco/demo_mujoco_weld.py	Fixed, revolute, prismatic, ball, D6, and free joints
mujoco/demo_robot_basic.py	Configurable robot grid, drives, timing, CPU/CUDA selection
mujoco/demo_robot_policy.py	Generic ANYmal / Go2 / G1 policy runner
mujoco/demo_robot_anymal_c_walk.py	ANYmal C standing or TorchScript walking policy
mujoco/demo_robot_anymal_d.py	ANYmal D USD standing rollout
mujoco/demo_robot_g1.py	Unitree G1 structured-USD standing rollout
mujoco/demo_robot_panda_hydro.py	Panda/FR3 IK manipulation with hydroelastic contact
mujoco/demo_robot_ur10.py	UR10 USD arm with position drives

# CPU is available in a standard build.
python python/demos/mujoco/demo_robot_basic.py \
  --backend cpu --world-count 16 --headless 120

# Requires NOVAPHY_WITH_MUJOCO_CUDA=ON and has_mujoco_cuda() == True.
python python/demos/mujoco/demo_robot_basic.py \
  --backend cuda --world-count 1024 --headless 120

See MuJoCo-style Solver for configuration and backend gating.

Reinforcement learning and policies

Install the policy/demo dependencies in an editable checkout:

pip install -e ".[policy]"

Demo	What it shows
mujoco/demo_robot_policy.py	Generic TorchScript policy rollout for ANYmal, Go2, or G1 assets
mujoco/demo_robot_anymal_c_walk.py	ANYmal C standing rollout or a supplied walking policy

The robot policy runners consume robot assets and compatible TorchScript checkpoints; inspect each demo's --help output for its asset and policy arguments.

Robotics, IK, and scene I/O

Demo	What it shows
demo_basic_urdf.py	URDF import smoke path
demo_robot_sim_pipeline.py	URDF import, torque-level simulation, and USD export
demo_ik_arm.py	ViewerGL target gizmo, headless solve, and IK solver-comparison benchmark
demo_sensors.py	IMU/contact/frame sensor reads
demo_multi_env_physics.py	Replicated world slices and MultiEnvRunner
demo_space_arm_dynamics.py	6-DOF manipulator under Moon/Earth gravity with analytical gates
demo_moon_surface_drop_time.py	Lunar free-fall time against an analytical solution

python python/demos/demo_robot_sim_pipeline.py --headless
python python/demos/demo_ik_arm.py \
  --headless --target-pos 0.5 0.0 0.4
python python/demos/demo_multi_env_physics.py \
  --num-worlds 8 --steps 240

Fluids

Demo	What it shows
demo_dam_break.py	PBF block collapse
demo_fluid_coupling.py	Two-way PBF/rigid coupling
demo_sph_fluid.py	CUDA SPH particles and optional boundary sampling
demo_lbm_volume.py	ViewerGL sparse-block speed volume and finite ViewerNull lifecycle
demo_lbm_robot.py	ViewerGL immersed-boundary FR3 arm
demo_lbm_robot_gripper.py	ViewerGL FR3 underwater payload transfer

python python/demos/demo_dam_break.py
python python/demos/demo_fluid_coupling.py

# Requires NOVAPHY_WITH_SPH_CUDA=ON.
python python/demos/demo_sph_fluid.py --headless --steps 200 --boundary

# ViewerNull runs a scene-lifecycle smoke without CUDA; fluid steps require
# NOVAPHY_WITH_LBM_CUDA=ON.
python python/demos/demo_lbm_volume.py --viewer null --num-frames 2

# Interactive ViewerGL; both require NOVAPHY_WITH_LBM_CUDA=ON.
python python/demos/demo_lbm_robot.py
python python/demos/demo_lbm_robot_gripper.py

# Finite offscreen ViewerGL verification (writes PNG frames by default).
python python/demos/demo_lbm_robot.py --headless 2
python python/demos/demo_lbm_robot_gripper.py --headless 2

SolverLBM is an optional CUDA runtime, not a scaffold. The volume demo's no-CUDA ViewerNull path validates scene construction and viewer lifecycle only; it deliberately skips fluid stepping. SolverMPM remains a scaffold and has no runnable demo.

VBD / AVBD and deformables

Demo	What it shows	Requirement
vbd/demo_vbd_rigid.py	Rigid VBD scene browser	CPU; optional CUDA
vbd/demo_vbd_joints.py	Supported VBD joint gallery	CPU; optional CUDA
vbd/demo_vbd_cable.py	Capsule-segment cable scenes	CUDA-oriented
vbd/demo_vbd_soft.py	Cloth / soft-particle browser	CUDA
demo_cloth_franka.py	Featherstone robot with VBD cloth	VBD CUDA
demo_softbody_franka.py	Featherstone robot with a tetrahedral soft body	VBD CUDA

python python/demos/vbd/demo_vbd_rigid.py \
  --scene stack --viewer null --num-frames 120
python python/demos/vbd/demo_vbd_joints.py \
  --viewer null --num-frames 120

# CUDA build
python python/demos/vbd/demo_vbd_soft.py \
  --scene cloth_hanging --backend cuda \
  --viewer null --num-frames 120

IPC contact

All IPC demos require an IPC-enabled build and novaphy.has_ipc() == True.

Demo	What it shows
demo_ipc_stack.py	Box stacking with IPC contact
demo_ipc_funnel_packing.py	Packing through a funnel
demo_ipc_mesh_bowl.py	Contact against a mesh bowl
demo_ipc_tower_impact.py	Tower impact

python python/demos/demo_ipc_stack.py
python python/demos/demo_ipc_funnel_packing.py
python python/demos/demo_ipc_mesh_bowl.py
python python/demos/demo_ipc_tower_impact.py

Viewer and profiling

Demo	What it shows
demo_viewer_api_basic.py	Immediate-mode shapes, meshes, lines, splats, and ViewerNull
demo_performance_monitor.py	Scoped phase timing and trace export

python python/demos/demo_viewer_api_basic.py --headless 120 --test
python python/demos/demo_performance_monitor.py \
  --scene rigid --measured-steps 120

Installed-package form

An editable checkout can always run source paths. A wheel includes the demos by default, so an installed package can use module form:

python -m novaphy.demos.demo_multi_env_physics --num-worlds 4 --steps 60
python -m novaphy.demos.demo_viewer_api_basic --headless 30 --test

Wheel producers can set NOVAPHY_EXCLUDE_DEMOS=true to omit the demo package. See Installation.