Move typed Arena job configs into core

Keep the reusable environment and evaluation Cfg models out of the example package. Resolve concrete environment schemas through EnvironmentRegistry while retaining the Hydra runner as an example frontend.

Signed-off-by: Clemens Volk <cvolk@nvidia.com>

Author: cvolkcvolk

CONTEXT.md

@@ -0,0 +1,25 @@
+# Isaac Lab-Arena
+
+Isaac Lab-Arena defines composable robotics environments and evaluates policies against them.
+
+## Language
+
+**Environment Configuration**:
+Declarative values that specialize one environment provider for a job.
+_Avoid_: Hydra environment, environment wrapper
+
+**Environment Provider**:
+A named recipe that turns an environment configuration into an assembled Arena environment.
+_Avoid_: Runtime environment, Hydra environment
+
+**Arena Environment**:
+An assembled embodiment, scene, and task ready to be passed to an environment builder.
+_Avoid_: Environment configuration, environment provider
+
+**Gym Environment**:
+The instantiated simulation interface used for reset and step operations.
+_Avoid_: Arena environment configuration
+
+**Evaluation Job**:
+A portable specification of an environment, policy, and rollout that can be dispatched independently.
+_Avoid_: Suite, simulation application

isaaclab_arena/environments/arena_environment_cfg.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Base configuration for registered Arena environment providers."""
+
+from dataclasses import dataclass
+
+from omegaconf import MISSING
+
+
+@dataclass
+class ArenaEnvironmentCfg:
+    """Configure the environment provider selected for an Arena job."""
+
+    name: str = MISSING
+    """Name used to resolve the environment through ``EnvironmentRegistry``."""
+    enable_cameras: bool = False

isaaclab_arena/evaluation/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Arena policy-evaluation configuration and runners."""

isaaclab_arena/evaluation/arena_job_cfg.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Typed configuration for Arena evaluation jobs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from omegaconf import MISSING
+
+from isaaclab_arena.environments.arena_environment_cfg import ArenaEnvironmentCfg
+
+
+@dataclass
+class EnvironmentBuilderCfg:
+    """Configure how Arena builds the selected environment."""
+
+    num_envs: int = 1
+    env_spacing: float = 30.0
+    seed: int = 42
+    solve_relations: bool = True
+    placement_seed: int | None = None
+    resolve_on_reset: bool | None = None
+    random_yaw_init: bool = False
+    disable_fabric: bool = False
+    mimic: bool = False
+    presets: str | None = None
+
+    def __post_init__(self) -> None:
+        assert self.num_envs > 0, "num_envs must be greater than zero"
+
+
+@dataclass
+class RolloutCfg:
+    """Configure an evaluation rollout."""
+
+    num_steps: int = 2
+
+    def __post_init__(self) -> None:
+        assert self.num_steps > 0, "num_steps must be greater than zero"
+
+
+@dataclass
+class PolicyCfg:
+    """Select and configure an evaluation policy."""
+
+    type: str = "zero_action"
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        assert self.type, "policy type must not be empty"
+
+
+@dataclass
+class ArenaJobCfg:
+    """Configure one independently dispatchable Arena evaluation job."""
+
+    name: str = MISSING
+    environment: ArenaEnvironmentCfg = MISSING
+    """Concrete registered environment configuration selected during composition."""
+    environment_builder: EnvironmentBuilderCfg = field(default_factory=EnvironmentBuilderCfg)
+    policy: PolicyCfg = field(default_factory=PolicyCfg)
+    rollout: RolloutCfg = field(default_factory=RolloutCfg)
+    num_rebuilds: int = 1
+    variations: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        assert self.name, "job name must not be empty"
+        assert self.num_rebuilds > 0, "num_rebuilds must be greater than zero"

isaaclab_arena/tests/test_hydra_configuration_example.py

@@ -5,58 +5,207 @@
 
 """Tests for the minimal Hydra environment-configuration example."""
 
+from pathlib import Path
+
 import pytest
 from hydra.errors import ConfigCompositionException
 
-from isaaclab_arena_examples.hydra_configuration.config import ArenaRunConfiguration, compose_hydra_example_suite
-from isaaclab_arena_examples.hydra_configuration.pick_and_place_maple_table import (
-    PickAndPlaceMapleTableEnvironmentConfiguration,
+from isaaclab_arena.assets.registries import EnvironmentRegistry
+from isaaclab_arena.evaluation.arena_job_cfg import ArenaJobCfg
+from isaaclab_arena_environments.pick_and_place_maple_table_environment import (
+    PickAndPlaceMapleTableEnvironment,
+    PickAndPlaceMapleTableEnvironmentCfg,
+)
+from isaaclab_arena_examples.hydra_configuration.run import (
+    _evaluation_runner_arguments,
+    _job_from_configuration,
+    compose_from_command_line,
+    compose_hydra_example_jobs,
 )
-from isaaclab_arena_examples.hydra_configuration.run import _job_from_configuration, compose_from_command_line
 
+EXAMPLE_CONFIG_PATH = (
+    Path(__file__).parents[2] / "isaaclab_arena_examples" / "hydra_configuration" / "hydra_example_suite.yaml"
+)
 
-def test_hydra_example_suite_composes_to_concrete_environment_configuration():
-    configuration = compose_hydra_example_suite()
 
-    assert isinstance(configuration, ArenaRunConfiguration)
-    assert isinstance(configuration.environment, PickAndPlaceMapleTableEnvironmentConfiguration)
-    assert configuration.environment.embodiment_asset_name == "droid_abs_joint_pos"
-    assert configuration.environment.pick_up_object_asset_name == "rubiks_cube_hot3d_robolab"
-    assert configuration.policy.type == "zero_action"
-    assert configuration.rollout.num_steps > 0
+def test_hydra_example_jobs_port_variations_job_and_control():
+    jobs = compose_hydra_example_jobs(EXAMPLE_CONFIG_PATH)
+
+    assert [job.name for job in jobs] == ["variations_demo", "baseline_no_variations"]
+    assert all(isinstance(job, ArenaJobCfg) for job in jobs)
+    assert all(isinstance(job.environment, PickAndPlaceMapleTableEnvironmentCfg) for job in jobs)
+    assert all(job.environment.name == "pick_and_place_maple_table" for job in jobs)
+    assert all(job.environment.enable_cameras for job in jobs)
+    assert all(job.environment.embodiment_asset_name == "droid_rel_joint_pos" for job in jobs)
+    assert all(job.environment.high_dynamic_range_image_name == "home_office_robolab" for job in jobs)
+    assert all(job.environment.pick_up_object_asset_name == "rubiks_cube_hot3d_robolab" for job in jobs)
+    assert all(job.environment.destination_location_asset_name == "bowl_ycb_robolab" for job in jobs)
+    assert jobs[0].environment is not jobs[1].environment
+    assert all(job.policy.type == "zero_action" for job in jobs)
+    assert all(job.rollout.num_steps == 10 for job in jobs)
+    assert all(job.num_rebuilds == 1 for job in jobs)
+    assert jobs[0].variations == {
+        "light": {
+            "hdr_image": {"enabled": True},
+            "intensity": {"enabled": True},
+        },
+        "droid_rel_joint_pos": {
+            "camera_extrinsics_wrist_camera": {"enabled": True},
+        },
+    }
+    assert jobs[1].variations == {}
+
+
+def test_hydra_example_jobs_accept_typed_shared_environment_override():
+    jobs = compose_hydra_example_jobs(EXAMPLE_CONFIG_PATH, ["environment.light_intensity=825"])
+
+    assert [job.environment.light_intensity for job in jobs] == [825.0, 825.0]
+
+
+def test_hydra_example_jobs_preserve_add_operator_for_shared_override():
+    jobs = compose_hydra_example_jobs(EXAMPLE_CONFIG_PATH, ["+policy.parameters.checkpoint=/tmp/model"])
+
+    assert [job.policy.parameters["checkpoint"] for job in jobs] == ["/tmp/model", "/tmp/model"]
+
+
+def test_hydra_example_cli_keeps_dispatcher_flags_out_of_job_configuration():
+    jobs, launcher_arguments = compose_from_command_line([
+        str(EXAMPLE_CONFIG_PATH),
+        "--device",
+        "cuda:1",
+        "--viz",
+        "kit",
+        "rollout.num_steps=1",
+    ])
+    eval_arguments = _evaluation_runner_arguments(
+        jobs,
+        launcher_arguments.device,
+        launcher_arguments.visualizer,
+    )
+
+    assert launcher_arguments.device == "cuda:1"
+    assert launcher_arguments.visualizer == "kit"
+    assert [job.rollout.num_steps for job in jobs] == [1, 1]
+    assert eval_arguments.device == "cuda:1"
+    assert eval_arguments.visualizer == "kit"
+    assert eval_arguments.enable_cameras
 
 
-def test_hydra_example_suite_accepts_typed_environment_override():
-    configuration = compose_hydra_example_suite(["environment.light_intensity=750"])
+def test_hydra_example_cli_requires_a_yaml_path():
+    with pytest.raises(SystemExit):
+        compose_from_command_line([])
 
-    assert configuration.environment.light_intensity == 750.0
 
+def test_dispatcher_aggregates_camera_requirements_without_mutating_jobs():
+    no_cameras = ArenaJobCfg(
+        name="no_cameras",
+        environment=PickAndPlaceMapleTableEnvironmentCfg(),
+    )
+    with_cameras = ArenaJobCfg(
+        name="with_cameras",
+        environment=PickAndPlaceMapleTableEnvironmentCfg(enable_cameras=True),
+    )
 
-def test_hydra_example_cli_maps_visualizer_and_forwards_hydra_overrides():
-    configuration = compose_from_command_line(["--viz", "kit", "rollout.num_steps=1"])
+    eval_arguments = _evaluation_runner_arguments([no_cameras, with_cameras], "cuda:0", None)
 
-    assert configuration.simulation_app.visualizer == "kit"
-    assert configuration.rollout.num_steps == 1
+    assert eval_arguments.enable_cameras
+    assert not no_cameras.environment.enable_cameras
+    assert with_cameras.environment.enable_cameras
 
 
-def test_hydra_example_suite_rejects_unknown_environment_option():
+def test_hydra_example_jobs_reject_unknown_environment_option():
     with pytest.raises(ConfigCompositionException, match="unknown_option"):
-        compose_hydra_example_suite(["environment.unknown_option=true"])
+        compose_hydra_example_jobs(EXAMPLE_CONFIG_PATH, ["environment.unknown_option=true"])
 
 
-def test_hydra_run_maps_to_eval_job_without_environment_cli_round_trip():
-    configuration = compose_hydra_example_suite([
-        "name=mapped_run",
-        "environment_builder.num_envs=3",
-        "policy.type=zero_action",
-        "rollout.num_steps=7",
-    ])
+def test_hydra_example_jobs_apply_python_defaults_to_minimal_yaml(tmp_path):
+    config_path = tmp_path / "minimal_jobs.yaml"
+    config_path.write_text("""\
+jobs:
+  - name: maple_table_job
+    environment:
+      name: pick_and_place_maple_table
+""")
+
+    jobs = compose_hydra_example_jobs(config_path)
+
+    assert [job.name for job in jobs] == ["maple_table_job"]
+    assert isinstance(jobs[0].environment, PickAndPlaceMapleTableEnvironmentCfg)
+
 
-    job = _job_from_configuration(configuration)
+def test_hydra_example_jobs_resolve_environment_configuration_through_registry():
+    jobs = compose_hydra_example_jobs(EXAMPLE_CONFIG_PATH)
 
-    assert job.name == "mapped_run"
-    assert job.num_envs == 3
-    assert job.num_steps == 7
-    assert job.policy_type == "zero_action"
-    assert job.policy_config_dict == {}
-    assert job.arena_env_args == []
+    provider = EnvironmentRegistry().get_component_by_name(jobs[0].environment.name)
+
+    assert provider is PickAndPlaceMapleTableEnvironment
+    assert provider.cfg_type is PickAndPlaceMapleTableEnvironmentCfg
+
+
+def test_hydra_example_jobs_require_an_environment_name(tmp_path):
+    config_path = tmp_path / "missing_environment_name.yaml"
+    config_path.write_text("""\
+jobs:
+  - name: maple_table_job
+    environment: {}
+""")
+
+    with pytest.raises(AssertionError, match="environment.name must be a string"):
+        compose_hydra_example_jobs(config_path)
+
+
+def test_hydra_example_jobs_reject_unknown_yaml_environment_option(tmp_path):
+    config_path = tmp_path / "invalid_jobs.yaml"
+    config_path.write_text("""\
+jobs:
+  - name: maple_table_job
+    environment:
+      name: pick_and_place_maple_table
+      unknown_option: true
+""")
+
+    with pytest.raises(ConfigCompositionException, match="unknown_option"):
+        compose_hydra_example_jobs(config_path)
+
+
+def test_hydra_example_jobs_reject_duplicate_names(tmp_path):
+    config_path = tmp_path / "duplicate_jobs.yaml"
+    config_path.write_text("""\
+jobs:
+  - name: duplicate
+    environment:
+      name: pick_and_place_maple_table
+  - name: duplicate
+    environment:
+      name: pick_and_place_maple_table
+""")
+
+    with pytest.raises(AssertionError, match="job names must be unique"):
+        compose_hydra_example_jobs(config_path)
+
+
+def test_hydra_jobs_map_to_eval_jobs_without_environment_cli_round_trip():
+    configurations = compose_hydra_example_jobs(
+        EXAMPLE_CONFIG_PATH,
+        [
+            "environment_builder.num_envs=3",
+            "policy.type=zero_action",
+            "rollout.num_steps=7",
+        ],
+    )
+
+    jobs = [_job_from_configuration(configuration) for configuration in configurations]
+
+    assert [job.name for job in jobs] == ["variations_demo", "baseline_no_variations"]
+    assert all(job.num_envs == 3 for job in jobs)
+    assert all(job.num_steps == 7 for job in jobs)
+    assert all(job.num_rebuilds == 1 for job in jobs)
+    assert all(job.policy_type == "zero_action" for job in jobs)
+    assert all(job.policy_config_dict == {} for job in jobs)
+    assert all(job.arena_env_args == [] for job in jobs)
+    assert set(jobs[0].variations) == {
+        "light.hdr_image.enabled=true",
+        "light.intensity.enabled=true",
+        "droid_rel_joint_pos.camera_extrinsics_wrist_camera.enabled=true",
+    }
+    assert jobs[1].variations == []

isaaclab_arena/tests/test_hydra_configuration_example_subprocess.py

@@ -12,12 +12,13 @@
 
 
 @pytest.mark.with_subprocess
-def test_hydra_configuration_example_runs():
+def test_hydra_configuration_example_runs_two_jobs():
     result = run_subprocess(
         [
             TestConstants.python_path,
             "-m",
             "isaaclab_arena_examples.hydra_configuration.run",
+            "isaaclab_arena_examples/hydra_configuration/hydra_example_suite.yaml",
             "--viz",
             "none",
             "rollout.num_steps=1",
@@ -26,4 +27,7 @@ def test_hydra_configuration_example_runs():
     )
 
     assert result is not None
-    assert "[hydra-example] completed 'maple_table_zero_action'" in result.stdout
+    assert result.stdout.index("Running job variations_demo") < result.stdout.index(
+        "Running job baseline_no_variations"
+    )
+    assert "[hydra-example] completed jobs=['variations_demo', 'baseline_no_variations']" in result.stdout