Add doc for supported randomizations by qianl-nv · Pull Request #1246 · isaac-sim/IsaacLab-Arena

qianl-nv · 2026-09-10T22:30:49Z

Summary

Add a doc for all supported randomizations in Arena

greptile-apps · 2026-09-10T22:36:14Z

Confidence Score: 4/5

The PR appears safe to merge after considering one non-blocking documentation correction to the object-set timing classification.

Findings

Incorrect object-set timing ▶

Summary

Catalogues the eight named Arena variations, including configuration paths, timing, defaults, and recording behavior.
Documents Arena-native placement and initial-state randomization alongside Isaac Lab event-based mechanisms.
Updates concept navigation and the existing variation reference for the current camera-intrinsics and object-mass classes.
One timing label should be corrected because object-set member assignment is fixed for the built environment rather than reset-time randomization.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  R[Supported randomization] --> V[Arena variations]
  R --> N[Arena-native placement and state]
  R --> E[Isaac Lab event terms]
  V --> VB[Build-time lighting and HDR]
  V --> VR[Reset-time camera and mass]
  V --> REC[Automatic variation recording]
  N --> NB[Build-fixed object-set assignment]
  N --> NR[Reset-time pose and layout sampling]
  E --> ER[Startup, reset, interval, or USD events]
  E --> CUSTOM[Custom recording required]

_{Reviews (1) · Last reviewed commit: "Refine randomization timing documentatio..."}

Signed-off-by: Qian Lin <qianl@nvidia.com>

arena-review-bot · 2026-09-10T22:40:25Z

+
+          EventTermCfg(
+              func=mdp.randomize_rigid_body_scale,
+              mode="usd",


🔴 mode="usd" isn't a real event mode

EventManager only ever applies prestartup, startup, interval and reset, so a term with mode="usd" is registered and then silently never runs — a reader who copies this gets no scale randomization and no error. Isaac Lab's own test_scale_randomization.py and Arena's g1.py:94 use prestartup. Line 352 needs the same fix ("the pre-play usd event mode"), and it's worth adding that prestartup raises unless the scene sets replicate_physics=False.

Suggested change

mode="usd",

mode="prestartup",

arena-review-bot · 2026-09-10T22:40:25Z

+   * - **Rigid object-set member** (``RigidObjectSet``). Gives each parallel environment one rigid
+       object selected from a candidate set. ``random_choice=False`` cycles through the declared
+       order; ``True`` samples independently. The assignment remains fixed across resets.
+     - Runtime.


🟡 Object-set member looks like build time, not runtime

By this page's own definition ("Runtime means the value can change on reset without rebuilding"), Runtime doesn't fit here: assign_variants_for_envs runs during _solve_relations() inside compose_manager_cfg(), and RigidObjectSet.assign_variants no-ops once the env count matches, so the member never changes on reset. The intro paragraph and this row's own last sentence already say that. Could the cell say build time and note the per-env spread?

Suggested change

- Runtime.

- Build time; the member differs per parallel env but is fixed across resets.

arena-review-bot · 2026-09-10T22:40:25Z

+.. toctree::
+   :maxdepth: 1
+
+   variations/variations


🟡 This page's variations table duplicates the page it nests

variations/variations.rst already lists the same eight variations with build/run-time labels in its available-variations table, and already carries the same --list_variations command block and the same build-time vs run-time explanation. Two tables over the same eight rows will drift — the stale CameraIntrinsicsBuildTimeVariation row this PR is deleting is that already happening once. Could the "code snippet to enable it" column be added to the existing table instead, so this page keeps the three-path overview plus the non-variation randomization and links across with ``:ref:available-variations```? That would also make the index.rst` "Variation system" card land on the page that actually describes the variation system.

arena-review-bot · 2026-09-10T22:40:25Z

+
+          EventTermCfg(
+              func=mdp.randomize_rigid_body_material,
+              mode="reset",


🔵 Snippet uses the mode the timing column advises against

The timing cell says PhysX recommends startup (upstream: "recommended to use this function only during the initialization of the environment"), but the snippet a reader copies is mode="reset". Same in the collider-offsets row at line 238. Could both snippets show startup and leave the "Newton supports runtime writes" caveat in the prose cell?

Suggested change

mode="reset",

mode="startup",

arena-review-bot · 2026-09-10T22:40:25Z

-     - build-time
-     - Perturbs a pinhole camera's focal lengths and principal point when the environment is built.
-   * - ``CameraIntrinsicsRunTimeVariation``
+   * - ``CameraIntrinsicsVariation``


🔵 "principal point" is stale in the description below

CameraIntrinsicsVariation samples only (d_fx, d_fy) and rewrites the horizontal/vertical apertures; the principal point is never touched — the new page's table gets this right. Since this row is being rewritten anyway, worth trimming line 176 to "Perturbs a pinhole camera's focal lengths on every reset."

arena-review-bot · 2026-09-10T22:40:57Z

🤖 Isaac Lab-Arena Review Bot

Summary

Adds a single Supported Randomizations page covering the three randomization paths (Arena variations, Arena-native placement/pose/object-set, Isaac Lab event terms), retires variations/index.rst, and fixes the stale split CameraIntrinsics* rows. I spot-checked the factual claims against the code and the pinned Isaac Lab submodule (bb0c8e1) — defaults, class names, event-term names, the PoseRange/embodiment restriction, and the seed-vs-placement_seed recording note all hold up. Two things need fixing before merge: one snippet uses an event mode that does not exist, and the page overlaps heavily with the page it now nests.

Design, Boundaries & Scope

The new page re-lists all eight variations, repeats the --list_variations command block, and re-explains build-time vs run-time — all of which variations/variations.rst already does, and that page is now a child of this one. That is two sources of truth over the same eight rows, and the stale CameraIntrinsicsBuildTimeVariation row this PR deletes is evidence of how they drift. Suggestion inline: add the "code snippet to enable it" column to the existing available-variations table and have this page keep only the three-path overview plus the non-variation randomization.

Findings

🔴 concept_supported_randomizations.rst:352, :358 — the rigid-body-scale snippet uses mode="usd". EventManager only applies prestartup, startup, interval, reset, so such a term registers and then silently never runs. Should be prestartup (as in Isaac Lab's test_scale_randomization.py and Arena's g1.py:94), which also requires replicate_physics=False.

🟡 concept_supported_randomizations.rst:124 — RigidObjectSet is labelled Runtime, but assign_variants no-ops after the first call, so the member is fixed for the environment's lifetime. Contradicts the page's own intro and the row's last sentence.

🟡 concept_supported_randomizations.rst:105 — duplication with variations/variations.rst (see above).

🔵 concept_supported_randomizations.rst:204, :238 — timing cells recommend startup for PhysX, snippets show mode="reset".

🔵 variations/variations.rst:176 — CameraIntrinsicsVariation only scales apertures from (d_fx, d_fy); "principal point" is stale.

Test Coverage

Docs-only; no tests expected. The variations/index.rst deletion is clean — no dangling :doc: references remain, and the four other pages referencing ../variations/variations still resolve. The docs build job will confirm.

Verdict

Minor fixes needed

xyao-nv · 2026-09-10T23:02:36Z

+Supported Randomizations
+========================
+
+Arena has three randomization paths:


Can list as a table

xyao-nv · 2026-09-10T23:07:15Z

+* **Arena variations** are named, configurable randomizations attached to assets. They can be
+  discovered with ``--list_variations``, enabled with Hydra overrides, and their sampled values
+  are automatically written to the per-episode ``variations`` record. **Recording is supported.**
+* **Arena-native initial-state and scene randomization** uses Arena placement, pose, object-set,
+  task, and embodiment APIs. **Recording is not currently supported.**
+* **Isaac Lab event-based randomization** uses custom event terms merged from the scene,
+  embodiment, and task configurations. **Recording is not supported by default**; a custom
+  episode recorder term is required.


How about categorizing as

Environment structure

What the environment is: scene, assets, embodiment, task, and object sets. These are defined by the Arena environment spec and generally require rebuilding to change.

Environment variation
What can change while preserving the same environment definition:

Build-time variations change values between environment builds.

Run-time variations change values between episodes or resets.

Custom extensions
Properties not covered by an existing Arena variation require:

A custom variation or Isaac Lab event term to change behavior.

An episode-recorder term if the value must also be recorded.

Then the page could be introduced as Arena env defines what is built. Env variations define which dimensions arena can resample and record automatically. Others require either a new variation, an IsaacLabevent term or a full env rebuild.

xyao-nv · 2026-09-10T23:07:44Z

+In the tables, **build time** means the value is selected while
+``ArenaEnvBuilder.compose_manager_cfg()`` is compiling the environment and remains shared by all
+parallel environments and episodes in that build. **Runtime** means the value can change on reset
+without rebuilding the Arena environment. Object-set assignment happens before scene spawning and


remove object_set in this paragraph

xyao-nv · 2026-09-10T23:13:22Z

@@ -0,0 +1,382 @@
+Supported Randomizations


It still sounds confusing to me when mixing randomization with env spec level changes.
How about naming as ways an Arena env can change?

xyao-nv · 2026-09-10T23:16:28Z

+   * - **Rigid object-set member** (``RigidObjectSet``). Gives each parallel environment one rigid
+       object selected from a candidate set. ``random_choice=False`` cycles through the declared
+       order; ``True`` samples independently. The assignment remains fixed across resets.
+     - Runtime.


it selects one per env before spawning, and future reset does not shuffle objects

xyao-nv · 2026-09-10T23:17:55Z

+       pool of layouts satisfying ``On``, ``NextTo``, ``NotNextTo``, ``AtPosition``,
+       ``PositionLimitsBox``, and ``PositionLimitsCylindrical``; ``FaceTo`` controls heading.
+       ``IsAnchor`` fixes references, and ``random_yaw_init=True`` adds uniform yaw initialization.


Can it just refer to the relation doc for detailed types? It's annoying when a new relation type is added, all other explicit references need to be changed.

xyao-nv · 2026-09-10T23:19:02Z

+       ``PositionLimitsBox``, and ``PositionLimitsCylindrical``; ``FaceTo`` controls heading.
+       ``IsAnchor`` fixes references, and ``random_yaw_init=True`` adds uniform yaw initialization.
+       The same path supports co-placement of an embodiment when relations are attached to it.
+     - Runtime; the layout pool are prepared at build time.


also they are refilled at runtime if pool is running short

xyao-nv · 2026-09-10T23:26:37Z

+substitute for recording the actual object-set member, pose, relation layout, or joint-state draw.
+
+
+Isaac Lab event-based randomization examples


One value for Lab's even term rands is it controls how and when it changes. Arena existing ones are only builttime or runtime

xyao-nv · 2026-09-10T23:28:58Z

+parallel environments and episodes in that build. **Runtime** means the value can change on reset
+without rebuilding the Arena environment. Object-set assignment happens before scene spawning and
+is fixed for the lifetime of the built environment.
+


Maybe worth to link it domain rand in RL (where the term is used a lot), where it uses runtime event terms to resample properties. I can see why audiences are confused if they come from RL.

xyao-nv · 2026-09-10T23:31:07Z

+              {"mean": 0.0, "std": 0.05}
+          )
+          embodiment.set_joint_initial_pos({"panda_joint1": 0.1})
+   * - **Physics material: static/dynamic friction and restitution.**


For those that Arena core does not have code examples, can we point to Lab's doc/code?

In case of future Lab API changes, we may miss to catch and update them in our doc.

xyao-nv · 2026-09-10T23:39:01Z

+   * - Randomization type and description
+     - Randomization Timing
+     - Code snippet to enable it
+   * - **Rigid object-set member** (``RigidObjectSet``). Gives each parallel environment one rigid


Can we link to the concept page of rigid object set?

qianl-nv marked this pull request as ready for review September 10, 2026 22:33

qianl-nv requested review from alexmillane, cvolkcvolk, peterd-NV, viiik-inside, xyao-nv and zhx06 as code owners September 10, 2026 22:33

greptile-apps Bot reviewed Sep 10, 2026

View reviewed changes

Comment thread docs/pages/concepts/concept_supported_randomizations.rst

qianl-nv added 2 commits September 11, 2026 06:37

Document supported randomizations

09bd807

Signed-off-by: Qian Lin <qianl@nvidia.com>

Refine randomization timing documentation

a4f72f1

Signed-off-by: Qian Lin <qianl@nvidia.com>

qianl-nv force-pushed the qianl/docs/supported-randomizations branch from 66d8258 to a4f72f1 Compare September 10, 2026 22:38

arena-review-bot Bot reviewed Sep 10, 2026

View reviewed changes

xyao-nv reviewed Sep 10, 2026

View reviewed changes

	- Runtime.
	- Build time; the member differs per parallel env but is fixed across resets.

		substitute for recording the actual object-set member, pose, relation layout, or joint-state draw.


		Isaac Lab event-based randomization examples

Uh oh!

Conversation

qianl-nv commented Sep 10, 2026

Summary

Uh oh!

greptile-apps Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Diagram

Uh oh!

Uh oh!

arena-review-bot Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

arena-review-bot Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

arena-review-bot Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

arena-review-bot Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

arena-review-bot Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

arena-review-bot Bot commented Sep 10, 2026

🤖 Isaac Lab-Arena Review Bot

Summary

Design, Boundaries & Scope

Findings

Test Coverage

Verdict

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xyao-nv Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xyao-nv Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xyao-nv Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Sep 10, 2026 •

edited

Loading

xyao-nv Sep 10, 2026 •

edited

Loading

xyao-nv Sep 10, 2026 •

edited

Loading

xyao-nv Sep 10, 2026 •

edited

Loading