[PresetCLI] Refactor preset into reusable class

[hujc7]

Goal

Make preset selection a first-class, discoverable, and drift-resistant CLI surface — replacing the bare presets=... Hydra-style override with typed flags that work uniformly across every IsaacLab script.

Key design choices

1. Canonical names live next to the cfg class via a decorator. Each backend config class declares its preset name once, in the same file as the class. The CLI layer reads the registry; preset_cli has no hardcoded vocabulary list.

   # source/isaaclab_physx/isaaclab_physx/physics/physx_manager_cfg.py
   @preset_name("physx")
   @configclass
   class PhysxCfg(PhysicsCfg):
       ...

2. Closed vocabulary for --physics and --renderer; free-form for --presets. Physics and renderer names are project-wide concepts (small set, shared meaning across envs). Domain presets are intentionally env-specific. Drift on the canonical names is enforced by a CI lint; domain names are author-discretion.

3. Single validation surface. Both "name not in canonical vocabulary" and "name not defined for this task" errors come from one code path with consistent formatting. argparse stays open (no choices=) so the friendly error never collides with the terse argparse default.

4. Loose canonical-name rule, not strict. Inside a PresetCfg, every canonical type that appears must have at least one field named after its canonical name. Variants beyond that (e.g. physx_high_fidelity = PhysxCfg(...)) stay free-form. So envs can expose multiple PhysX tunings as long as the canonical physx entry is also present.

5. One-line script wiring. setup_cli(parser) collapses argparse + launcher + parse + apply + sys.argv mutation into a single line. Scripts with mid-flow argv intercepts (e.g. rsl_rl/train.py's --external_callback) opt into commit=False and finish with preset_cli.commit(args, remaining) — never touching sys.argv directly.

6. Kind detection is structural, not name-based. Whether a preset is "physics", "renderer", or "domain" comes from class inheritance (PhysicsCfg / RendererCfg / else). A class can be canonical-named without being one of those kinds (e.g. solver-dispatch types like MJWarpSolverCfg), and the CLI handles the dispatch via value.solver_cfg.

Before / after

CLI surface

	Before this PR	After this PR
Selecting a backend	python train.py --task=... presets=newton_mjwarp,newton_renderer (Hydra-style, no --, undiscoverable in --help)	python train.py --task=... --physics newton_mjwarp --renderer newton_renderer (typed flags shown in --help). Legacy presets=... form still works.
Both syntactic forms	n/a (only bare form)	--flag value and --flag=value both work natively. --presets accepts CSV.
--help listing	preset names absent — user has to read the env source	typed flags appear in --help. With --task=<task> --help the output also lists per-task valid names, grouped by flag, one kind per line.

Error messages

Before — generic, mixed-kind:

ValueError: Unknown preset(s): newton_kamino

Available presets (grouped by affected paths):

  newton_mjwarp, physx
    -> env.sim.physics
  rgb, depth, albedo
    -> env.tiled_camera
  ...

After — kind-specific, single-place, with consistent formatting:

error: --physics 'newton_kamino' is not defined for task 'Isaac-Velocity-Flat-Anymal-C-v0'.

  This task currently defines:
    --physics:  newton_mjwarp, physx

  Recognized physics presets across IsaacLab (any task may add):
    newton_kamino, newton_mjwarp, ovphysx, physx

A wrong-kind name (e.g. --physics albedo) gets a flag suggestion: "'albedo' is defined as a domain preset on this task; did you mean '--presets albedo'?"

Env author experience

Before — every PresetCfg name was free-form Python; nothing prevented one env from naming the Newton MJWarp variant mjwarp while another called it newton_mjwarp. Drift on canonical names was undetectable.

After — same PresetCfg syntax, but a CI lint walks the gym registry and asserts every PresetCfg containing a canonical-typed alternative has the canonical name as one of its fields. A future PR adding super_solver_v2 = NewtonCfg(MJWarpSolverCfg(...)) to some env config fails CI with:

PhysicsCfg: alternative(s) (super_solver_v2) hold values of canonical type
'newton_mjwarp', but no field is named 'newton_mjwarp'. Rename one of these
fields to 'newton_mjwarp' so the canonical CLI form works for this task.

This PR also lands the small drift fix for G1/Go1/Spot velocity-flat envs that the lint surfaced — adds a physx = default alias so --physics physx works on those tasks too.

Backend author experience

Adding a new physics solver "FastNewton":

Step	Before this PR	After this PR
1. Define class	class FastNewtonSolverCfg(NewtonSolverCfg): ...	same
2. Bind canonical name	(no concept)	one line: @preset_name("newton_fastsolver") above the class
3. Wire in env config	class MyPhysicsCfg(PresetCfg): newton_fastsolver = NewtonCfg(...)	same
4. Update preset_cli vocab	(no concept)	not needed — registry picks up the decorator at import time
5. CI lint	passes silently regardless	passes — name matches the decorator
6. User CLI	works only if user already knows the name	name appears in --help automatically

Script wiring

Before (every script copies 5+ lines of boilerplate):

parser = argparse.ArgumentParser(...)
# ... script-specific args ...
add_launcher_args(parser)
args_cli, hydra_args = parser.parse_known_args()
sys.argv = [sys.argv[0]] + hydra_args

After (one line):

parser = argparse.ArgumentParser(...)
# ... script-specific args ...
args_cli = setup_cli(parser)

For scripts with mid-flow argv intercepts (e.g. rsl_rl/train.py):

args_cli, remaining_args, preset_cli = setup_cli(parser, commit=False)
# ... external-callback logic mutates remaining_args ...
preset_cli.commit(args_cli, remaining_args)

What's not changed

• Hydra config-override semantics (env.sim.dt=0.001, agent.seed=42, etc.) are untouched.
• The presets=newton_mjwarp,... global broadcast still works exactly as before — typed flags translate into it internally, so nothing the existing test suite or workflow assumes is broken.
• PresetCfg structure is free-form. The decorator is on the leaf cfg classes (PhysxCfg, MJWarpSolverCfg, ...) — env authors writing PresetCfg subclasses don't change anything.

Files

Area	Files
New decorator + registry	source/isaaclab/isaaclab/utils/preset_meta.py
Rewritten CLI helper	source/isaaclab_tasks/isaaclab_tasks/utils/preset_cli.py
Backend cfg decorators (one line each)	physx_manager_cfg.py, ovphysx_manager_cfg.py, mjwarp_manager_cfg.py, kamino_manager_cfg.py, isaac_rtx_renderer_cfg.py, newton_warp_renderer_cfg.py, ovrtx_renderer_cfg.py
Drift fix surfaced by the lint	g1/flat_env_cfg.py, go1/flat_env_cfg.py, spot/flat_env_cfg.py
Reference script wiring	scripts/reinforcement_learning/rsl_rl/train.py, scripts/environments/zero_agent.py
Non-Hydra path	parse_cfg.py (added presets= kwarg)
Tests	source/isaaclab_tasks/test/test_preset_cli.py (41 tests, including registry-walk drift lint)
Docs	docs/source/features/hydra.rst
Changelogs	source/isaaclab/changelog.d/, source/isaaclab_tasks/changelog.d/

Test plan

• ./isaaclab.sh -p -m pytest source/isaaclab_tasks/test/test_preset_cli.py — 41/41 passed locally
• Pre-commit (./isaaclab.sh -f) passes
• describe_task('Isaac-Cartpole-Camera-Presets-Direct-v0') smoke produces the expected per-task listing
• --physics newton_mjwarp against an env without a physics preset emits the targeted error
• python scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Cartpole-Camera-Presets-Direct-v0 --physics newton_mjwarp --renderer newton_renderer --headless runs to completion (full Kit launch)
• python scripts/environments/zero_agent.py --task=Isaac-Cartpole-Camera-Presets-Direct-v0 --physics=physx --headless works (the = form)

[isaaclab-review-bot]

Review Summary

Well-architected refactor that elevates preset selection from a Hydra implementation detail to a first-class CLI concept. The three-layer design (registry → cfg → CLI) provides good separation of concerns.

Strengths

• preset_name decorator keeps canonical names co-located with their cfg classes — prevents vocabulary drift
• Kind taxonomy via class inheritance rather than name-matching is robust and extensible
• Backwards compatibility preserved: legacy presets=... override and from isaaclab_tasks.utils.hydra import PresetCfg still work
• Comprehensive test coverage (616 lines) with edge cases for legacy aliases, unknown presets, and multi-kind validation
• Clean API surface: setup_cli(parser) one-liner for script authors

Concerns

See inline comments. High-level:

1. The _BACKEND_MODULES force-import list is a maintenance liability — adding a new backend requires editing this list
2. PresetCli._task_loader as a mutable class variable is a testing footgun (global state shared across test cases)
3. The _user_stacklevel() function is duplicated across modules

[isaaclab-review-bot]

🟡 Hardcoded backend module list: _BACKEND_MODULES requires manual updates when new backends are added. Consider using entry points or a plugin registry pattern so backends self-register:

# In each backend's __init__.py or cfg module:
from isaaclab.utils.preset_meta import PresetRegistry
PresetRegistry.register(PresetKind.PHYSICS, "physx")(PhysxCfg)

Then _ensure_backends_imported could discover registered entry points instead of maintaining a hardcoded list. This is a longer-term suggestion — the current approach is fine for now given the small number of backends.

[isaaclab-review-bot]

🟡 Mutable class variable for task loader: _task_loader: ClassVar[Any] = None is mutable global state that persists across test cases. If tests register different loaders or forget to reset, they can leak state.

Consider using a contextmanager or explicit reset for testing:

@classmethod
@contextlib.contextmanager
def override_task_loader(cls, loader):
    prev = cls._task_loader
    cls._task_loader = loader
    try:
        yield
    finally:
        cls._task_loader = prev

[isaaclab-review-bot]

💡 _user_stacklevel duplication: This helper appears in both preset_cfg.py and hydra.py. Consider extracting it to a shared utility (e.g., isaaclab.utils._warnings):

# isaaclab/utils/_warnings.py
def stacklevel_outside(module_file: str, max_walk: int = 16) -> int: ...

Minor, but reduces the chance of the two implementations drifting.

[isaaclab-review-bot]

💡 PresetKind enum with dual-value constructor: The __new__ override with (value, legacy_aliases) tuple is clever but non-obvious. A first-time reader seeing PHYSICS = ("physics", {"newton": "newton_mjwarp", ...}) might not immediately understand the structure.

Consider adding a brief code comment above the first member:

# Members: (label_for_CLI_flag, {deprecated_alias: canonical_replacement})
PHYSICS = ("physics", {"newton": "newton_mjwarp", "kamino": "newton_kamino"})

[isaaclab-review-bot]

💡 Good backwards compat: Re-exporting PresetCfg, preset, and collect_presets from their new home while keeping the old import path working is the right call. Consider adding a deprecation note in the module docstring or via __deprecated__ so IDEs can flag the old imports:

# Deprecated re-exports — use isaaclab.utils.preset_cfg directly in new code.