---

name: isaac-gym-simulation description: "Operate the Isaac Gym Preview 4 simulation, vectorized locomotion environments, robot assets, terrain, state tensors, effort control, and interactive MPC launcher for this project." disable-model-invocation: true metadata: disco-role: operating license: MIT

Isaac Gym simulation

Use this sub-skill when the task involves Isaac Gym setup, PhysX simulation, URDF loading, env/actor creation, terrain, state or force data, vectorized RL stepping, or the interactive RL_MPC_Locomotion launcher. It is a procedural, data-oriented guide: handles create the simulation, while NumPy or PyTorch arrays/tensors carry state and commands.

Required-backend gate

RL and simulation execution is currently blocked. The closed-source Isaac Gym Preview 4 package was unavailable in the construction environment. The partial handoff records PyTorch 1.10/CUDA 11.3, an A100 allocation, repository imports, rsl_rl, and mpc_osqp as passing checks; those results do not prove that Isaac Gym is installed or usable. From this sub-skill's directory, run the bundled diagnostic first:

python scripts/check_isaacgym.py

Do not claim that an RL rollout, viewer run, terrain run, or Isaac Gym import passed until this gate is cleared with the vendor package and a compatible GPU/runtime. The diagnostic never creates a viewer or simulation.

Route quickly

• Need the exact lifecycle, API calls, tensor shapes, or viewer loop: read references/simulation-api.md.
• Need robot selection, URDF/mesh caveats, ground, or terrain generation: read references/assets-and-terrains.md.
• Need a failure diagnosis or a safe stop condition: read references/troubleshooting.md.
• Need the PPO/Hydra task, checkpoint, observation, or training contract: route to rl-training.
• Need MPC state conversion, controller modes, gait, or solver behavior: route to mpc-control.

Setup contract

Use Python 3.8 with PyTorch 1.10.0 and CUDA 11.3, Isaac Gym Preview 4, NumPy, Hydra/OmegaConf, and the pinned rsl_rl integration. A compatible NVIDIA GPU/driver is required for the configured PhysX GPU pipeline; the upgrade notes call out driver 470 or newer. The project normally uses cuda:0 for both simulation and RL, physics_engine: physx, Z-up gravity [0, 0, -9.81], dt: 0.01, and two substeps. Keep the setup sequence and backend verdict explicit; CUDA-visible PyTorch alone is insufficient.

Canonical procedural order

1. Acquire a gym handle, create SimParams, and set the control timestep, substeps, up-axis, gravity, and PhysX options.
2. Create the PhysX simulation with compute and graphics device ids. Stop on a null simulation handle.
3. Add exactly the intended ground plane or triangle terrain before creating environments. Do not silently combine terrain conventions from the interactive and RL paths.
4. Select one supported URDF, configure AssetOptions, load it, inspect DOF and rigid-body names/counts, and configure effort properties.
5. Create the environment grid and one actor per environment. Cache env and actor handles and resolve the trunk, foot, thigh, and hip body handles.
6. Prepare the simulation before acquiring/wrapping GPU state tensors. Refresh every tensor immediately before reading it.
7. Create a viewer only when rendering is requested. In each loop apply controls, simulate, fetch results as required by the pipeline, read state, update graphics, and synchronize frame time.
8. On every exit path stop the gamepad thread, destroy the viewer if created, then destroy the simulation. Use try/finally in new integrations.

Control and data rules

• Effort mode is the project default. Set each DOF driveMode to DOF_MODE_EFFORT and stiffness/damping to zero, then apply a complete effort vector every physics frame. Missing a frame does not preserve a safe command.
• The direct launcher uses structured NumPy state (pos, vel; body pose, quaternion, linear and angular velocity) and applies per-actor efforts. The RL tasks use gymtorch wrappers and batched tensors; do not mix the two contracts without an explicit CPU/GPU conversion.
• With one actor per env, root state is (num_envs, 13) in the order position 3, quaternion 4 (x,y,z,w), linear velocity 3, angular velocity 3. DOF state is flattened as (num_envs * num_dof, 2) and reshaped to positions and velocities (num_envs, num_dof). Net contacts are (num_envs, num_bodies, 3).
• RL actions are (num_envs, 12) and clipped to [-1, 1]; observations are (num_envs, 48), commands are (num_envs, 3), rewards/resets are per-env. The vector task returns (obs, privileged_obs, rewards, resets, extras).
• The RL observation is base position, body-frame linear/angular velocity, scaled velocity command, offset DOF position, scaled DOF velocity, and the previous action. The standard simulator must refresh DOF, root, and contact tensors before computing it.

Interactive launcher contract

The supported robots are Aliengo, A1, and Go1. The launcher accepts --robot, --mode {Fsm,Min,Policy}, --num-envs, --render-fps, --disable-gamepad, and --checkpoint. Policy consumes a checkpoint; if it is omitted, the policy runner resolves the latest project run. Fsm is the normal hierarchical controller and Min is the minimal MPC runner.

Without --disable-gamepad, an Xbox-like device is required. The left stick commands forward/lateral velocity, the right stick commands yaw, LB cycles Trot/Walk/Bound, and RB cycles Locomotion/Recovery Stand. LB+RB requests an emergency stop; press the left stick to release it. For unattended or headless automation, disable the gamepad and do not create a viewer. The interactive launcher still renders and therefore remains backend-blocked here.

Completion criteria

A simulation task is complete only when the backend diagnostic passes, asset paths and names resolve, the simulation is stepped in the documented order, state refreshes and tensor shapes are checked, and cleanup is observed. If the backend is absent, provide the exact blocked prerequisite and stop; do not substitute a CPU-only import or a successful MPC build as Isaac Gym evidence.