Lecture 09: Isaac Lab 3.0 Architecture¶
Overview¶
Lectures 01-08 drove one scene from your own loop. Isaac Lab inverts that: you describe one environment as configuration, and the framework clones it thousands of times on one GPU, steps it in lockstep, and hands batched tensors to an RL library. The point is throughput. A policy that needs 100 million environment steps will not train at one robot per process.
Isaac Lab 3.0 Early Access introduces a major architecture change. The September EA snapshot uses Python 3.12 and Sim 6.1 for full simulator workflows; kit-less workflows can omit Sim. The moving release branch has since changed dependencies, so use the exact compatibility record. Physics is multi-backend: PhysX through Isaac Sim, Newton with MuJoCo-Warp, or kit-less OvPhysX, chosen at launch with physics=.... Installation uses uv; training has a unified isaaclab train command; data properties return ProxyArray; quaternions change from wxyz to xyzw. This lecture teaches that 3.0 architecture and the migration from 2.x.
By the end you should be able to:
- name the 3.0 packages and say which one owns physics backends, tasks, RL wrappers, and visualizers
- install Isaac Lab 3.0 with
uv, run a task kit-less (Newton) and with Kit (Isaac Sim PhysX), and explain the difference - choose between the manager-based and direct workflows, and trace one
step()through either - read an
InteractiveSceneCfgand explain{ENV_REGEX_NS}, cloning, and per-env memory - select backends with
physics=,renderer=andpresets=, and author aPresetCfg - use the 3.0 data API (
.torch/.warp,_index/_maskwrites, xyzw) and the EventManager randomization modes - port a 2.x task or command line to 3.0
1. Why it matters: from one scene to thousands¶
Recall the rollout-regime argument from Deep RL Lecture 01: on-policy algorithms like PPO (Deep RL Lecture 06) are limited by env-steps/s, and the only way to get millions per second is to vectorize the simulator itself. Isaac Lab does that with three ideas:
| Idea | What it buys | Where it lives |
|---|---|---|
| Cloning | One environment authored once, replicated N times with physics parsing shared | InteractiveScene, isaaclab.cloner |
| Batched GPU state | Observations, actions, rewards and resets as (N, ...) tensors that never leave the GPU |
Asset .data (ProxyArray), managers, direct env methods |
| Configuration over code | Tasks are @configclass trees that you override from the CLI (Hydra) without editing Python |
ManagerBasedRLEnvCfg, DirectRLEnvCfg, PresetCfg |
3.0 adds a fourth: backend independence. The same task config runs on PhysX or Newton, because asset classes such as Articulation are factories that load the active backend's implementation.
2. Mental model¶
2.1 Packages¶
The release/3.0.0 source tree has these packages under source/:
| Package | Owns |
|---|---|
isaaclab |
Core: envs, managers, scene, assets, sensors, sim, actuators, cloner, physics, renderers, benchmark, cli, utils (incl. ProxyArray) |
isaaclab_physx |
PhysX backend implementations (assets, sensors, PhysxCfg, PhysX schema cfgs, SurfaceGripper) |
isaaclab_newton |
Newton backend (NewtonCfg, MJWarpSolverCfg, Kamino solver cfg; articulations, rigid objects, deformables) |
isaaclab_ov |
Omniverse kit-less integrations: OvPhysxCfg, OVRTX renderer |
isaaclab_tasks |
Registered gym tasks (core/ and contrib/) and PresetCfg utilities |
isaaclab_rl |
Wrappers and the unified train/play entrypoints for RSL-RL, RL-Games, skrl, SB3, RLinf, TorchRL |
isaaclab_assets |
Robot and object configs (CARTPOLE_CFG, ...) |
isaaclab_visualizers |
Kit, Newton (GL/RTX), Rerun and Viser viewers |
isaaclab_teleop / isaaclab_mimic |
Teleoperation (replaces isaaclab.devices.openxr) and Mimic data generation (Lecture 11) |
isaaclab_contrib, isaaclab_experimental, isaaclab_tasks_experimental |
Staged contributions and early-access features |
isaaclab_ppisp |
Renderer-agnostic HDR→LDR post-processing |
2.2 Install: uv first, Kit optional¶
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/isaac-sim/IsaacLab.git --branch v3.0.0-EA
cd IsaacLab
git checkout --detach ae37b028ea415c91ea2bc32609efcd759ed2b974
uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=newton_mjwarp # kit-less
uv run --extra ovphysx isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=ovphysx # kit-less PhysX
uv run --extra isaacsim isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct physics=isaacsim_physx
Upstream source-checked exercise; not executed here. Preserve this snapshot's lockfile and record the resolved environment. uv run synchronizes the project environment; --extra NAME goes before isaaclab. The following full-simulator dependency refers to the EA snapshot, not today's moving release branch. Check each task's --help and configuration at your chosen commit before launching a long run.
isaacsimaddsisaacsim[all,extscache]==6.1.0.0(Kit, RTX, Isaac Sim PhysX)ovphysx,ovrtxandovadd the kit-less Omniverse PhysX and RTX runtimesrl-games,skrl,sb3,rlinf,torchrl,rerun,viser,mimic,teleopandvideoadd those integrationsallcoversovplus the common RL and visualizer extras, but not Isaac Sim
rsl_rl is in the base environment and is the default library for most core tasks. ./isaaclab.sh -i still exists for manually managed environments; the docs call it legacy. The docs list 16 GB VRAM for full Isaac Sim workflows. Kit-less Newton runs do not load Isaac Sim at all, which is what makes them attractive on an 8 GB card.
Kit is in the process only when something needs it: physics=isaacsim_physx, renderer=isaacsim_rtx, --viz kit, or livestreaming. Newton (newton_mjwarp, newton_kamino) and OvPhysX run kit-less. Do not combine OvPhysX with a Kit runtime in one process.
2.3 Two workflows¶
Manager-based (ManagerBasedRLEnv + ManagerBasedRLEnvCfg) Direct (DirectRLEnv / DirectMARLEnv + *Cfg)
┌────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────┐
│ scene InteractiveSceneCfg │ │ scene InteractiveSceneCfg │
│ actions ActionManager (terms → targets) │ │ _pre_physics_step(actions) │
│ observations ObservationManager (groups of terms) │ │ _apply_action() × decimation │
│ rewards RewardManager (weighted terms) │ │ _get_dones() → terminated, time_out │
│ terminations TerminationManager │ │ _get_rewards() │
│ events EventManager (randomization) │ │ _reset_idx(env_ids) │
│ commands CommandManager (goals, optional) │ │ _get_observations() → {"policy": ...} │
│ curriculum CurriculumManager (optional) │ │ (you write the logic; cfg holds scalars) │
└────────────────────────────────────────────────────┘ └──────────────────────────────────────────┘
| Choose | When |
|---|---|
| Manager-based | Prototyping, swapping reward or observation terms, team projects, reusing the mdp library (reset_joints_by_offset, randomize_rigid_body_mass, ...) |
| Direct | Performance-critical or hard-to-decompose logic, ports from IsaacGymEnvs, multi-agent (DirectMARLEnv), fused reward kernels (TorchScript or Warp) |
Both Cartpoles in isaaclab_tasks/core/cartpole/ implement the same MDP (same reward scales, resets and termination), one per workflow. Reading them side by side is Lab 9b.
One ManagerBasedRLEnv.step(), in the order in manager_based_rl_env.py:
action_manager.process_action(action)decimationtimes:apply_action(),scene.write_data_to_sim(),sim.step(render=False), render only everysim.render_intervalsteps if rendering, thenscene.update(dt)termination_manager.compute(), thenreward_manager.compute(dt=step_dt)_reset_idx(...)for terminated envs, which triggersevent_manager.apply(mode="reset", ...)command_manager.compute(...), thenevent_manager.apply(mode="interval", ...)observation_manager.compute(), then return(obs, reward, terminated, time_out, extras)
So step_dt = decimation × sim.dt. The Cartpole has sim.dt = 1/120 and decimation = 2, so the policy acts at 60 Hz. Direct envs call _pre_physics_step once per policy step. In the ordinary path, _apply_action runs per decimation tick; a backend that handles decimation internally calls it once and advances the block itself. Do not rely on Python callback count to infer the number of integrated substeps; check _physics_handles_decimation in the pinned source.
2.4 The scene: one env, cloned¶
# from isaaclab_tasks/core/cartpole/cartpole_manager_env_cfg.py (release/3.0.0)
@configclass
class CartpoleSceneCfg(InteractiveSceneCfg):
ground = AssetBaseCfg(prim_path="/World/ground", spawn=sim_utils.GroundPlaneCfg(size=(100.0, 100.0)))
robot: ArticulationCfg = replace(CARTPOLE_CFG, prim_path="{ENV_REGEX_NS}/Robot")
distant_light = AssetBaseCfg(prim_path="/World/DistantLight", spawn=sim_utils.DistantLightCfg(intensity=3000.0))
scene: CartpoleSceneCfg = CartpoleSceneCfg(num_envs=4096, env_spacing=4.0, clone_in_fabric=True)
{ENV_REGEX_NS}expands to a regex over the per-env namespaces/World/envs/env_0,env_1, .... Anything under it is cloned per env. Anything at/World/...(ground, lights) exists once and is shared.replicate_physics=True(default) means every clone has identical USD and the physics parser handles them in one optimized pass. Setting it False allows per-env asset differences at a setup-time cost, and it is not supported on Newton.filter_collisions=Truestops envs from colliding with their neighbours.clone_in_fabricis a deprecated legacy flag in 3.0; the Cartpole configs still set it, but the replicator ignores it.- Asset configs are backend-neutral:
AssetBaseCfg(non-physics),RigidObjectCfg,RigidObjectCollectionCfg,ArticulationCfg(+actuators={...: ImplicitActuatorCfg(...)}), andDeformableObjectCfg. Backend-specific physics properties are now schema fragments passed as lists.CARTPOLE_CFGpassesrigid_props=[UsdPhysicsRigidBodyCfg(...), PhysxRigidBodyCfg(...)]andarticulation_props=[PhysxArticulationCfg(...), NewtonArticulationCfg(...)]. The 2.xRigidBodyPropertiesCfg-style classes are deprecated aliases scheduled for removal in 3.2. - Order matters. Entities are added in attribute order. The docstring recommends terrain, then articulations and rigid bodies, then sensors, then lights.
3.0 sources use isaaclab.utils.replace(cfg, prim_path=...). You will see the CARTPOLE_CFG.replace(prim_path=...) method form in 2.x code.
2.5 Backends and presets¶
A task exposes alternatives as a PresetCfg: typed fields are named variants, and default is used when you pass nothing. This is the Cartpole's (abridged from cartpole_common.py):
from isaaclab.physics import PhysxAutoCfg
from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
from isaaclab_ov.physics import OvPhysxCfg
from isaaclab_physx.physics import PhysxCfg
from isaaclab_tasks.utils import PresetCfg
@configclass
class CartpolePhysicsCfg(PresetCfg):
isaacsim_physx: PhysxCfg = PhysxCfg()
ovphysx: OvPhysxCfg = OvPhysxCfg()
physx: PhysxAutoCfg = PhysxAutoCfg(isaacsim_physx=isaacsim_physx, ovphysx=ovphysx)
newton_mjwarp: NewtonCfg = NewtonCfg(solver_cfg=MJWarpSolverCfg(njmax=5, nconmax=3),
num_substeps=1, use_cuda_graph=True)
default: NewtonCfg = newton_mjwarp # Cartpole runs on Newton unless told otherwise
# in the env cfg: self.sim.physics = CartpolePhysicsCfg()
| Selector (Hydra token, no dashes) | Examples | Changes |
|---|---|---|
physics= |
isaacsim_physx, physx (auto: Isaac Sim PhysX if Kit is needed, else OvPhysX), newton_mjwarp, newton_kamino (beta), ovphysx (experimental) |
The whole sim.physics section |
renderer= |
isaacsim_rtx, rtx (auto), newton_renderer, ovrtx |
Camera rendering backend |
presets= |
rgb, depth, ... (task-specific) |
Observation modes, camera layouts, bundles |
The order is: each preset's default first, then presets=, then path-targeted presets (env.sim.physics=newton_mjwarp), then scalar overrides (env.sim.dt=0.002). uv run isaaclab train --task <id> --help lists the names a task supports, and passing an unlisted name fails validation. Defaults are task-specific. Cartpole's is Newton, while tasks with an established PhysX default keep Isaac Sim PhysX, so always write physics= explicitly in anything you benchmark. Solver settings do not transfer numerically between families. Joint and body ordering can differ between backends, too; the docs have a PhysX↔Newton policy-transfer how-to and an articulation-ordering guide (Lecture 05).
2.6 The 3.0 data API¶
robot = env.unwrapped.scene["robot"]
q = robot.data.joint_pos.torch # torch.Tensor (N, num_joints): cached zero-copy view of the Warp buffer
qw = robot.data.joint_pos.warp # the original wp.array, for Warp kernels
rq = robot.data.root_quat_w.torch # (N, 4) in (x, y, z, w)
robot.write_root_pose_to_sim_index(root_pose=pose, env_ids=ids) # index-based write
robot.actuators.target_command.set_effort_index(value=effort, joint_ids=cart_ids) # 3.0 command API; the direct
# Cartpole still calls the deprecated robot.set_joint_effort_target_index(target=..., joint_ids=...)
ProxyArray. Every asset and sensor.dataproperty returns one..torchis a cached zero-copy tensor view (viawp.to_torch), and.warpis the underlying array. Arithmetic directly on theProxyArraystill works through a deprecation bridge that warns once. Don't cache.torchacross resets: Newton can reallocate buffers on a full reset, and the old tensor then points at stale memory. PhysX refreshes on first access each step; Newton refreshes every step automatically.- Writes name their selector.
write_*_index(...)takes env or joint indices andwrite_*_mask(...)takes boolean masks. The 2.x single method that took either is gone. - Quaternions are (x, y, z, w) everywhere in Lab 3.0, chosen to match Warp, PhysX and Newton without conversion. Isaac Sim's Core Experimental prims still return (w, x, y, z). If you mix Isaac Sim API calls into a Lab task, or read old 2.x configs, convert. The repo's
scripts/tools/find_quaternions.pyflags likely-wxyz literals in your own code. SettingWARN_ON_TORCH_QUATF_ACCESS=1warns on reads of quaternion buffers through.torch.
2.7 Events: where randomization lives¶
EventManager terms are EventTermCfg(func=..., mode=..., params=...):
| Mode | When it fires | Typical use |
|---|---|---|
"prestartup" |
Once, before the simulation starts | USD edits physics must parse at start, e.g. randomize_rigid_body_scale (which also needs replicate_physics=False) |
"startup" |
Once, after the simulation starts | Per-env friction, mass, CoM randomization |
"reset" |
On every env reset (the env calls it) | Initial joint and root states |
"interval" |
Every interval_range_s seconds (the manager handles it) |
Random pushes |
From the 3.0 velocity-tracking config (Isaac-Velocity-*-AnymalD): randomize_rigid_body_material (startup; static_friction_range, dynamic_friction_range, restitution_range, num_buckets), randomize_rigid_body_mass (startup; mass_distribution_params=(1/1.25, 1.25), operation="scale", distribution="log_uniform"), randomize_rigid_body_com, reset_root_state_uniform and reset_joints_by_scale (reset), and push_by_setting_velocity (interval, interval_range_s=(10.0, 15.0)). Domain randomization theory and evaluation are in Deep RL Lecture 13. The mechanism is just these terms.
3. 2.x → 3.0 migration¶
| Isaac Lab 2.x | Isaac Lab 3.0 | Source |
|---|---|---|
conda, Python 3.11, ./isaaclab.sh --install; Isaac Sim 4.5-5.1 |
uv run ..., Python 3.12, Isaac Sim 6.1 only (5.1 and older unsupported) |
Install docs, migration guide |
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py / play.py |
uv run isaaclab train\|play --rl_library rsl_rl (also rl_games, skrl, sb3, rlinf); library-specific scripts removed |
Migration guide |
--headless |
Omit --viz or pass --viz none; --headless now only controls Kit's rendering mode and no longer suppresses visualizers |
Migration guide |
--resume --load_run RUN, --use_pretrained_checkpoint |
--checkpoint <path>\|latest\|best\|pretrained |
Migration guide |
Isaac-Cartpole-v0, Isaac-Velocity-Rough-Anymal-C-v0, Isaac-Lift-Cube-Franka-v0 |
Isaac-Cartpole, Isaac-Velocity-Rough-AnymalD, Isaac-Lift-Franka; ANYmal-C only as IsaacContrib-Velocity-Rough-AnymalC-Direct. UNVERIFIED whether old -v0 IDs remain as aliases |
Task __init__.py files, EA notes |
Quaternions (w, x, y, z), identity (1, 0, 0, 0) |
(x, y, z, w), identity (0, 0, 0, 1) |
Migration guide |
robot.data.root_pos_w is a torch.Tensor |
robot.data.root_pos_w.torch (ProxyArray) |
Migration guide, ProxyArray how-to |
write_root_pose_to_sim(pose, env_ids) |
write_root_pose_to_sim_index(...) / ..._mask(...) |
Migration guide |
self.sim.physics = sim_utils.PhysxCfg(...) |
isaaclab_physx.physics.PhysxCfg inside a PresetCfg; select with physics= |
Migration guide |
RigidBodyPropertiesCfg, JointDrivePropertiesCfg(max_effort=, max_velocity=) |
Schema fragments (PhysxRigidBodyPropertiesCfg, JointDriveBaseCfg(max_force=, max_joint_velocity=)); old names warn, removed in 3.2 |
Migration guide |
TiledCamera / TiledCameraCfg |
Deprecated alias; Camera includes the tiled path |
sensors/camera/tiled_camera.py |
Imu (full state) |
Renamed Pva; new lightweight Imu (angular velocity + linear acceleration with gravity) |
Migration guide |
isaaclab.devices.openxr (OpenXRDevice) |
isaaclab_teleop (IsaacTeleopDevice, IsaacTeleopCfg) |
Migration guide, EA notes |
SurfaceGripper in isaaclab.assets |
isaaclab_physx.assets.SurfaceGripper |
Migration guide |
env_cfg.viewer.eye = ...; gym.wrappers.RecordVideo |
sim.default_visualizer_cfg = VisualizerCfg(eye=...); env_cfg.video_recorders = [VideoRecorderCfg(...)] |
Migration guide |
scripts/benchmarks/benchmark_*.py |
uv run isaaclab benchmark runtime\|training\|startup\|play |
Migration guide |
Port in this order: install, backend config, data access and quaternions, then training commands and visualization. Validate behavior after the quaternion step, because a wrong quaternion produces a task that runs and quietly learns nothing.
4. The hardware view: memory per environment, and who owns the GPU¶
Where VRAM goes in a training run. As a working model:
- \( M_{\text{fixed}} \) is the process baseline. With Kit, it includes the Kit app and RTX renderer you measured in Lecture 01. Kit-less, it is the CUDA context, Warp and PyTorch. The difference is the first thing Lab 9c measures.
- \( m_{\text{phys}} \) is per-env physics state: bodies, joints, contact pairs, solver buffers. PhysX GPU capacities are static (contact-rich or large scenes may need explicit buffer sizing). Newton with
use_cuda_graph=Truepays a one-time graph-capture cost. - \( m_{\text{buf}} \) is per-env observation, action, reward and reset buffers, plus manager scratch.
- Rollout storage for on-policy RL is arithmetic:
For the Cartpole RSL-RL config (\( T = \) num_steps_per_env \( = 16 \), \( d_{\text{obs}} = 4 \), \( d_{\text{act}} = 1 \), and \( k \approx 6 \) for rewards, dones, values, log-probs, returns and advantages), 4,096 envs need about 2.9 MB. For state-based tasks, rollout memory is a rounding error, and the fixed cost plus physics dominate. Cameras change the picture completely, because each env's render product adds \( W \cdot H \cdot \text{channels} \) per step (Lectures 07 and 10).
Instancing still matters. With replicate_physics=True and instanceable assets (the 6.x importers' default, Lecture 02), N robots share one set of meshes. Per-env cost is then state, not geometry.
Keep the loop on the GPU. The loop is physics buffers → ProxyArray zero-copy view → observation tensor → policy → action tensor → write_*_index → physics, with no host round trip. One stray .item(), .cpu(), print(tensor) or Python if on a GPU value forces a device sync every step. The 3.0 direct Cartpole carries comments on exactly this ("device indices avoid per-step host uploads", "no .item(): avoids a sync on every reset"). Rendering is skipped unless a visualizer, camera or video asks for it: with --viz none and no cameras, step() never renders.
Two processes cannot share 8 GB politely. Isaac Lab training and an Isaac Sim GUI (or a second training run) each hold their own fixed cost and caching allocators. Run one GPU job at a time on the 4060.
8 GB budget. State-only tasks are the sweet spot on a 4060. Kit-less Newton (
physics=newton_mjwarp,--viz none) avoids the Kit and RTX baseline entirely, so classic-control and many locomotion tasks should fit thousands of envs. Find the knee with Lab 9c rather than trusting any published number. With Kit (--extra isaacsim,physics=isaacsim_physx), subtract your Lecture 01 fixed cost first. Turn down--num_envsbefore anything else, then drop visualizers (--viz none), and avoid camera presets until Lecture 10's budget. Move to a cloud L40S / RTX PRO 6000 when you need Kit plus RTX cameras across many envs, or when Kit and an evaluation policy must share one card. The 4060 is below the official 16 GB minimum for full Isaac Sim workflows.
5. Build it¶
Lab 9a — Install and run Isaac-Cartpole, kit-less and with Kit¶
cd IsaacLab
uv run python scripts/environments/list_envs.py | grep -i cartpole # registered IDs (any -v0 left?)
uv run isaaclab train --task Isaac-Cartpole --help # look for the physics= choices
# kit-less Newton, no viewer
uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole --num_envs 4096 --viz none physics=newton_mjwarp
# the same task through Isaac Sim PhysX (Kit in the process)
uv run --extra isaacsim isaaclab train --rl_library rsl_rl --task Isaac-Cartpole --num_envs 4096 --viz none physics=isaacsim_physx
# watch the result
uv run isaaclab play --rl_library rsl_rl --task Isaac-Cartpole --checkpoint latest --num_envs 16 --viz newton_gl
Log nvidia-smi throughout. Note time-to-first-iteration, iteration time, and peak VRAM for both runs. Checkpoints land under logs/. Confirm in the startup log that the Kit run reports Isaac Sim starting and the Newton run does not. (--viz newton also works but is a deprecated alias for newton_gl.)
Lab 9b — Read a task end to end¶
Open source/isaaclab_tasks/isaaclab_tasks/core/cartpole/ and annotate, in ANNOTATED_CARTPOLE.md:
- Manager-based (
cartpole_manager_env_cfg.py). For each config class (CartpoleSceneCfg,ActionsCfg,ObservationsCfg.PolicyCfg,EventCfg,RewardsCfg,TerminationsCfg,CartpoleEnvCfg.__post_init__), write which manager consumes it, at which step of §2.3 it runs, and the tensor shape it produces for N envs. Note what is absent (commands,curriculum). Then do the same forEventsCfg,CommandsCfgandCurriculumCfgincore/velocity/velocity_env_cfg.py. - Direct (
cartpole_direct_env.py). Map each method to the manager it replaces. Find whereepisode_length_bufdrivestime_outand where the reward is fused into one TorchScript function. - Backends (
cartpole_common.py). List the physics presets and say which one runs when you pass nothing.
Then check your annotations against a live env. This probe follows the launcher pattern of 3.0's own zero_agent / random_agent entrypoint (isaaclab_rl/entrypoints/simple_agents.py):
# isaac_bench/lab_probe.py
# uv run python isaac_bench/lab_probe.py --task Isaac-Cartpole --num_envs 1024 --viz none physics=newton_mjwarp
import argparse, sys, time
import gymnasium as gym, torch
from isaaclab.app import add_launcher_args, launch_simulation
import isaaclab_tasks # noqa: F401 (registers the gym IDs)
from isaaclab_tasks.utils import resolve_task_config, setup_preset_cli
parser = argparse.ArgumentParser()
parser.add_argument("--task", default="Isaac-Cartpole")
parser.add_argument("--num_envs", type=int, default=1024)
parser.add_argument("--steps", type=int, default=500)
add_launcher_args(parser)
args, hydra_args = setup_preset_cli(parser, None)
sys.argv = [sys.argv[0]] + hydra_args # physics= / renderer= / presets= go to Hydra
env_cfg, _ = resolve_task_config(args.task, "")
env_cfg.scene.num_envs = args.num_envs
args.device = env_cfg.sim.device
with launch_simulation(env_cfg, args):
env = gym.make(args.task, cfg=env_cfg)
env.reset()
u = env.unwrapped
robot = u.scene["robot"] # "cartpole" in Isaac-Cartpole-Direct
jp = robot.data.joint_pos
print(f"{type(jp).__name__} torch={tuple(jp.torch.shape)} on {jp.torch.device}")
print("root quat (x, y, z, w):", [round(v, 3) for v in robot.data.root_quat_w.torch[0].tolist()])
print(f"physics_dt={u.physics_dt:.5f} step_dt={u.step_dt:.5f} action_space={u.action_space.shape}")
act = torch.zeros(u.action_space.shape, device=u.device)
with torch.inference_mode():
for _ in range(50): # warm-up (CUDA graphs, allocator)
env.step(act)
torch.cuda.synchronize(); t = time.perf_counter()
for _ in range(args.steps):
env.step(act)
torch.cuda.synchronize(); dt = time.perf_counter() - t
print(f"env-steps/s={u.num_envs * args.steps / dt:,.0f} ms/step={dt / args.steps * 1e3:.3f} "
f"torch peak={torch.cuda.max_memory_allocated() / 2**20:.0f} MiB")
env.close()
The startup log prints every manager's term table ([INFO] Event Manager: ..., Observation Manager, Reward Manager, ...). Diff it against your annotation. torch peak counts only PyTorch's allocator, so compare it with the nvidia-smi total to see how much belongs to physics and the runtime.
Lab 9c — Kit vs kit-less: VRAM and env-steps/s¶
isaaclab benchmark runtime steps a task with random actions, no policy, and writes a result bundle. Its flags (--num_envs, --num_steps, --warmup_steps, --benchmark_formatter, --output_path, --measure_sync_step) come from isaaclab/benchmark/entrypoints/runtime.py:
# isaac_bench/lab_sweep.sh
set -e; mkdir -p results
for physics in newton_mjwarp isaacsim_physx; do
extra=""; [ "$physics" = isaacsim_physx ] && extra="--extra isaacsim"
for n in 256 1024 4096 16384; do
tag=cartpole_${physics}_${n}
nvidia-smi --query-gpu=timestamp,memory.used --format=csv,noheader,nounits -lms 200 > results/$tag.vram.csv &
smi=$!
uv run $extra isaaclab benchmark runtime --task Isaac-Cartpole-Direct \
--num_envs $n --num_steps 1000 --warmup_steps 50 --visualizer none \
--benchmark_formatter json,summary --output_path results/$tag physics=$physics || echo "FAILED $tag"
kill $smi
done
done
Add physics=ovphysx (with --extra ovphysx) if it installs on your machine. For each run, record env-steps/s from the summary and peak VRAM minus idle desktop. Plot both against N on log axes. Then rerun the largest N that fits with --measure_sync_step to split simulation time from outside-simulation time.
What to expect qualitatively: at small N, both backends are dominated by fixed per-step overhead and throughput grows almost linearly with N. At large N, the GPU saturates and the curve flattens. The Kit run starts from a higher VRAM floor. Where the two cross in speed is task- and GPU-specific; that is why you measure.
6. Use it in the real stack¶
- Training (Lecture 10) is the same commands with longer runs, sweeps over
--num_envsandphysics=, and your own direct task. - Imitation and evaluation (Lecture 11) use
isaaclab_teleop,isaaclab_mimic, and Isaac Lab-Arena, which composes a scene, an embodiment and a task into aManagerBasedRLEnvCfg. The manager vocabulary from §2.3 is what Arena generates. - The Deep RL course uses Isaac Lab as its rung-2 simulator. The
ProxyArray→ policy →write_*_indexloop is where its PPO implementation (Deep RL Lecture 06) attaches. - Extension projects depend on the released
isaaclabwheel (uv pip install --index https://pypi.nvidia.com isaaclab==3.0.0rc1plus extras) instead of a checkout.
7. Measure it¶
| Metric | How | Why it matters |
|---|---|---|
| Env-steps/s vs N | Lab 9c summary; lab_probe.py |
The throughput curve that sets training wall-clock |
| Peak VRAM vs N | nvidia-smi log per run |
Slope = VRAM per env; intercept = fixed cost |
| Kit vs kit-less fixed cost | Intercept difference between backends | How many envs Kit costs you on 8 GB |
| Torch vs total VRAM | torch.cuda.max_memory_allocated() vs nvidia-smi |
Separates policy/rollout memory from physics and runtime |
| Sim vs outside-sim time | --measure_sync_step |
Whether physics or your Python/managers bound the step |
| Time to first step | isaaclab benchmark startup |
Iteration speed when you change configs often |
8. Ship it¶
Commit to isaac_bench/:
lab_probe.py,lab_sweep.sh, and theresults/directory (benchmark JSON, VRAM CSVs)lab_scaling.png— env-steps/s and peak VRAM vs N for each backendANNOTATED_CARTPOLE.md— the Lab 9b annotation, with the manager-to-method mapMIGRATION_NOTES.md— one 2.x snippet of your choice (from a tutorial or forum post) ported to 3.0, line by line, citing the table in §3- An update to
BASELINE.md— kit-less vs Kit fixed cost, VRAM per env for Cartpole, and the N where throughput stops scaling on your GPU
Exit criteria¶
You can move on when you can:
- install Isaac Lab 3.0 with
uvand run a task kit-less and with Kit, explaining what each loads - trace one
step()through the managers (or the direct methods) and computestep_dtfrom a config - explain
{ENV_REGEX_NS},replicate_physics, and what is shared vs per-env in a cloned scene - select and author physics presets, and say which preset runs when none is given
- use
.torch/.warp,_indexwrites and xyzw quaternions correctly, and port a 2.x command line - report VRAM per env and env-steps/s for Cartpole on both backends on your GPU
Self-check¶
- A 2.x tutorial runs
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Lift-Cube-Franka-v0 --headless --resume --load_run 2025-10-01. Write the 3.0 command, and name each change. - A ported task trains but the robot spawns lying on its side, and the reward never improves. The config has
rot=(1.0, 0.0, 0.0, 0.0)ininit_state. Explain the bug, and how you would find every other instance in your code. - Two teammates benchmark
Isaac-Cartpoleand get very different env-steps/s on identical GPUs. One passed nophysics=token and the other passedphysics=isaacsim_physx. Explain the difference, and what every benchmark command in your repo should include. - Your direct task's
_get_rewardscachesself.joint_pos = robot.data.joint_pos.torchin__init__, and on Newton the rewards become nonsense after the first full reset, while on PhysX they look fine. Why? - You want per-env friction randomization drawn once per training run, plus a random push every 10-15 s. Which EventManager modes and which
mdpfunctions do you use, and which component triggers each mode? - On an 8 GB card, Kit-mode Cartpole runs out of memory at an N where Newton is still comfortable. Using the \( M(N) \) model, explain which term differs, and how Lab 9c's two curves show it.
References¶
- Isaac Lab 3.0 installation (uv, extras, kit-less, legacy
isaaclab.sh) — docs - Quickstart (commands, RL libraries, backends, visualizers, benchmarks) — docs
- Migrating to 3.0 — docs
- Backends and presets — docs; physics backends — docs
- Task workflows (manager-based vs direct) — docs
- Working with
ProxyArray— docs - Isaac Lab v3.0.0-EA release notes — GitHub
- Source at
release/3.0.0— cartpole tasks,manager_based_rl_env.py,interactive_scene_cfg.py,event_manager.py, benchmarkruntime.py,pyproject.toml