# boredengineering/isaaclab-arena architecture

> Architecture diagram of the GitHub repository boredengineering/isaaclab-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boredengineering/isaaclab-arena
- Repository: https://github.com/boredengineering/isaaclab-arena

## Overview

Isaac Lab-Arena composes robot embodiments, scenes, and task objectives into Isaac Lab simulation environments, then runs policies and records evaluation results. Users can also define environments as graph specs, generate them through an LLM-assisted workflow, and review previews. The README documents composable assembly, sequential tasks, semantic placement, parallel heterogeneous evaluation, and Isaac Lab interoperability. Some relationships below are directly documented; links within unsampled subsystems are omitted or marked unverified.

Main entry points: [`isaaclab_arena/environments/isaaclab_arena_environment.py`](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_environment.py) (Environment model), [`isaaclab_arena/environments/isaaclab_arena_manager_based_env.py`](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_manager_based_env.py) (Arena environment), [`isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py) (Asset visualization), [`isaaclab_arena/evaluation/policy_runner.py`](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/evaluation/policy_runner.py) (Policy runners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Environment authoring"]
  node_graphspec["Environment graph"]
  node_envmodel["Environment model"]
  node_scene["Scene composition<br/>[scene.py]"]
  node_embodiment["Robot embodiments<br/>[embodiment_base.py]"]
  node_tasks["Task library<br/>[task_library.py]"]
  node_sequential["Sequential tasks"]
  node_placement["Relation placement<br/>[relation_solver.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_builder["Environment builder"]
  node_environment["Arena environment"]
  node_variations["Scene variations<br/>[variation_base.py]"]
end

subgraph group_evaluation["Policy evaluation"]
  node_metrics["Metrics manager<br/>[metrics_manager.py]"]
  node_recorders["Episode recording"]
  node_policy["Policy runners<br/>[policy_runner.py]"]
  node_experiments["Experiment runner"]
  node_analysis["Result analysis<br/>[report_data.py]"]
end

subgraph group_generation["Agentic generation"]
  node_specinfer["Spec inference<br/>[spec_inference.py]"]
  node_backend["LLM backend"]
  node_priminfer["Prim path inference"]
  node_validation["Spec validation<br/>[spec_validation.py]"]
  node_review["Generation review UI<br/>[editor_panel.py]"]
  node_simclient["Preview client<br/>[client.py]"]
  node_simserver["Preview server<br/>[server.py]"]
  node_simvisual["Asset visualization"]
end

subgraph group_foundation["Runtime foundations"]
  node_bbox["Bounding geometry<br/>[bounding_box.py]"]
  node_pose["Pose utilities<br/>[pose.py]"]
  node_usdhelpers["USD helpers<br/>[usd_helpers.py]"]
  node_primtree["USD prim tree<br/>[usd_prim_tree.py]"]
end

node_user(("Researcher"))
node_llm(("Inference service"))
node_sim["Isaac Sim"]
node_policyactor(("Policy provider"))

node_user -->|"defines"| node_graphspec
node_user -->|"composes"| node_envmodel
node_graphspec -->|"converts to"| node_envmodel
node_envmodel -->|"includes"| node_scene
node_envmodel -->|"includes"| node_embodiment
node_envmodel -->|"includes"| node_tasks
node_user -->|"builds"| node_builder
node_builder -->|"assembles"| node_environment
node_tasks -->|"chains skills"| node_sequential
node_placement -->|"positions assets"| node_scene
node_environment -.->|"samples"| node_variations
node_user -->|"evaluates"| node_policy
node_policyactor -.->|"supplies policy"| node_policy
node_policy -.->|"acts in"| node_environment
node_environment -->|"records episodes"| node_recorders
node_environment -.->|"computes metrics"| node_metrics
node_policy -.->|"runs in"| node_experiments
node_experiments -.->|"reports results"| node_analysis
node_user -.->|"requests generation"| node_specinfer
node_specinfer -->|"requests structured output"| node_backend
node_backend -->|"sends inference"| node_llm
node_specinfer -->|"validates spec"| node_validation
node_priminfer -->|"requests inference"| node_backend
node_priminfer -->|"loads tree"| node_primtree
node_user -.->|"reviews spec"| node_review
node_review -->|"requests thumbnails"| node_simvisual
node_simvisual -->|"requests preview"| node_simclient
node_simclient -->|"sends RPC"| node_simserver
node_simserver -.->|"renders preview"| node_sim
node_placement -.->|"uses geometry"| node_bbox
node_placement -.->|"uses transforms"| node_pose
node_simvisual -->|"resolves tree"| node_primtree
node_simvisual -->|"gets thumbnails"| node_simclient
node_primtree -.->|"reads USD"| node_usdhelpers

click node_graphspec "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environment_spec/arena_env_graph_spec.py"
click node_envmodel "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_environment.py"
click node_scene "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/scene/scene.py"
click node_embodiment "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/embodiments/embodiment_base.py"
click node_tasks "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/tasks/task_library.py"
click node_sequential "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/tasks/sequential_task_base.py"
click node_placement "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/relations/relation_solver.py"
click node_builder "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/arena_env_builder.py"
click node_environment "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_manager_based_env.py"
click node_variations "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/variations/variation_base.py"
click node_metrics "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/metrics/metrics_manager.py"
click node_recorders "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/recording/episode_recorder_manager.py"
click node_policy "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/evaluation/policy_runner.py"
click node_experiments "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/evaluation/experiment_runner.py"
click node_analysis "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/visualization/report_data.py"
click node_specinfer "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/spec_inference.py"
click node_backend "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/inference_backend.py"
click node_priminfer "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/prim_path_inference.py"
click node_validation "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/spec_validation.py"
click node_review "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/editor_panel.py"
click node_simclient "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/client.py"
click node_simserver "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/server.py"
click node_simvisual "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py"
click node_bbox "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/bounding_box.py"
click node_pose "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/pose.py"
click node_usdhelpers "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/usd_helpers.py"
click node_primtree "https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/usd_prim_tree.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_graphspec,node_envmodel,node_scene,node_embodiment,node_tasks,node_sequential,node_placement toneBlue
class node_builder,node_environment,node_variations toneAmber
class node_metrics,node_recorders,node_policy,node_experiments,node_analysis toneMint
class node_specinfer,node_backend,node_priminfer,node_validation,node_review,node_simclient,node_simserver,node_simvisual toneRose
class node_bbox,node_pose,node_usdhelpers,node_primtree,node_user,node_llm,node_sim,node_policyactor toneIndigo
```

## Components

### Environment authoring

- [Environment graph](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environment_spec/arena_env_graph_spec.py): `isaaclab_arena/environment_spec/arena_env_graph_spec.py`
- [Environment model](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_environment.py): `isaaclab_arena/environments/isaaclab_arena_environment.py`
- [Scene composition](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/scene/scene.py): `isaaclab_arena/scene/scene.py`
- [Robot embodiments](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/embodiments/embodiment_base.py): `isaaclab_arena/embodiments/embodiment_base.py`
- [Task library](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/tasks/task_library.py): `isaaclab_arena/tasks/task_library.py`
- [Sequential tasks](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/tasks/sequential_task_base.py): `isaaclab_arena/tasks/sequential_task_base.py`
- [Relation placement](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/relations/relation_solver.py): `isaaclab_arena/relations/relation_solver.py`

### Simulation runtime

- [Environment builder](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/arena_env_builder.py): `isaaclab_arena/environments/arena_env_builder.py`
- [Arena environment](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/environments/isaaclab_arena_manager_based_env.py): `isaaclab_arena/environments/isaaclab_arena_manager_based_env.py`
- [Scene variations](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/variations/variation_base.py): `isaaclab_arena/variations/variation_base.py`

### Policy evaluation

- [Metrics manager](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/metrics/metrics_manager.py): `isaaclab_arena/metrics/metrics_manager.py`
- [Episode recording](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/recording/episode_recorder_manager.py): `isaaclab_arena/recording/episode_recorder_manager.py`
- [Policy runners](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/evaluation/policy_runner.py): `isaaclab_arena/evaluation/policy_runner.py`
- [Experiment runner](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/evaluation/experiment_runner.py): `isaaclab_arena/evaluation/experiment_runner.py`
- [Result analysis](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/visualization/report_data.py): `isaaclab_arena/visualization/report_data.py`

### Agentic generation

- [Spec inference](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/spec_inference.py): `isaaclab_arena/agentic_environment_generation/spec_inference.py`
- [LLM backend](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/inference_backend.py): `isaaclab_arena/agentic_environment_generation/inference_backend.py`
- [Prim path inference](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/prim_path_inference.py): `isaaclab_arena/agentic_environment_generation/prim_path_inference.py`
- [Spec validation](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/agentic_environment_generation/spec_validation.py): `isaaclab_arena/agentic_environment_generation/spec_validation.py`
- [Generation review UI](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/editor_panel.py): `isaaclab_arena_examples/agentic_environment_generation/review_gui/editor_panel.py`
- [Preview client](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/client.py): `isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/client.py`
- [Preview server](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/server.py): `isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/server.py`
- [Asset visualization](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py): `isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`

### Runtime foundations

- [Bounding geometry](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/bounding_box.py): `isaaclab_arena/utils/bounding_box.py`
- [Pose utilities](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/pose.py): `isaaclab_arena/utils/pose.py`
- [USD helpers](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/usd_helpers.py): `isaaclab_arena/utils/usd_helpers.py`
- [USD prim tree](https://github.com/boredengineering/isaaclab-arena/blob/main/isaaclab_arena/utils/usd_prim_tree.py): `isaaclab_arena/utils/usd_prim_tree.py`

### Other components

- **Researcher**
- **Inference service**
- **Isaac Sim**
- **Policy provider**

## Connections

- Researcher → Environment graph: defines (evidence: `README.md`)
- Researcher → Environment model: composes (evidence: `README.md`)
- Environment graph → Environment model: converts to (evidence: `isaaclab_arena/environment_spec/arena_env_graph_spec.py`)
- Environment model → Scene composition: includes (evidence: `README.md`)
- Environment model → Robot embodiments: includes (evidence: `README.md`)
- Environment model → Task library: includes (evidence: `README.md`)
- Researcher → Environment builder: builds (evidence: `README.md`)
- Environment builder → Arena environment: assembles (evidence: `README.md`)
- Task library → Sequential tasks: chains skills (evidence: `README.md`)
- Relation placement → Scene composition: positions assets (evidence: `README.md`)
- Arena environment → Scene variations: samples
- Researcher → Policy runners: evaluates (evidence: `README.md`)
- Policy provider → Policy runners: supplies policy
- Policy runners → Arena environment: acts in
- Arena environment → Episode recording: records episodes (evidence: `isaaclab_arena/environments/isaaclab_arena_manager_based_env.py`)
- Arena environment → Metrics manager: computes metrics (evidence: `isaaclab_arena/environments/isaaclab_arena_manager_based_env.py`)
- Policy runners → Experiment runner: runs in
- Experiment runner → Result analysis: reports results
- Researcher → Spec inference: requests generation
- Spec inference → LLM backend: requests structured output (evidence: `isaaclab_arena/agentic_environment_generation/spec_inference.py`)
- LLM backend → Inference service: sends inference (evidence: `isaaclab_arena/agentic_environment_generation/inference_backend.py`)
- Spec inference → Spec validation: validates spec (evidence: `isaaclab_arena/agentic_environment_generation/spec_inference.py`)
- Prim path inference → LLM backend: requests inference (evidence: `isaaclab_arena/agentic_environment_generation/prim_path_inference.py`)
- Prim path inference → USD prim tree: loads tree (evidence: `isaaclab_arena/agentic_environment_generation/prim_path_inference.py`)
- Researcher → Generation review UI: reviews spec
- Generation review UI → Asset visualization: requests thumbnails (evidence: `isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`)
- Asset visualization → Preview client: requests preview (evidence: `isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`)
- Preview client → Preview server: sends RPC (evidence: `isaaclab_arena_examples/agentic_environment_generation/review_gui/simapp/client.py`)
- Preview server → Isaac Sim: renders preview
- Relation placement → Bounding geometry: uses geometry
- Relation placement → Pose utilities: uses transforms
- Asset visualization → USD prim tree: resolves tree (evidence: `isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`)
- Asset visualization → Preview client: gets thumbnails (evidence: `isaaclab_arena_examples/agentic_environment_generation/review_gui/visualization_service.py`)
- USD prim tree → USD helpers: reads USD (evidence: `isaaclab_arena/utils/usd_prim_tree.py`)
