SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsisaaclab-migrating-from-isaac-gym

isaaclab-migrating-from-isaac-gym

Office & productivity

View repository

Updated 10-15 22:38

About this skill

Migrating From Isaac Gym

When To Use

Use this skill when a user wants to port an Isaac Gym task, asset workflow, observation/reward implementation, or training setup into Isaac Lab.

Do not use this skill for Isaac Lab 2.x to 3.x migration. Use the isaaclab-migrating-2x-to-3x skill for that workflow. Port Isaac Gym code directly to the current Isaac Lab APIs; do not introduce an intermediate port to an older Isaac Lab release.

Workflow

  1. Identify the Isaac Gym task structure: assets, environment state tensors, observations, rewards, resets, and training runner.
  2. If the user needs a new full-feature Isaac Sim setup, point them to the automatic uv installation guide first. If the user expects PhysX or Kit execution, run a runtime preflight from the Isaac Lab checkout before a long port: verify uv run --extra isaacsim python uses the intended Python environment and checkout, imports isaacsim and omni, and provides the requested RL library.
  3. Read the IsaacGymEnvs migration guide and direct workflow docs before proposing edits. Treat the guide as a direct mapping to the current Isaac Lab APIs, including physics presets, ProxyArray access, XYZW quaternions, and explicit indexed or masked write methods.
  4. For a new scratch or external migration project, follow the template scaffolding workflow. Use uv run isaaclab --new, choose External, a parent path outside Isaac Lab, project/task-family/robot names, direct single-agent for ordinary Isaac Gym tasks, and the needed RL library. Preserve existing project layouts when migrating into an established package.
  5. Migrate to a direct workflow first by default. This preserves the single-class structure that most Isaac Gym tasks already use.
  6. Choose the initial backend target. Start with PhysX when matching Isaac Gym behavior; add Newton only after the direct PhysX migration is validated or if the user explicitly targets Newton.
  7. Map Isaac Gym PhysX parameters through the schema cfg docs: first to Isaac Lab PhysX cfgs, then to backend-portable base cfgs or Newton/MuJoCo cfgs where an equivalent exists.
  8. Map assets to Isaac Lab asset configs and scene entities.
  9. Move action application, observation assembly, reward computation, termination checks, and reset logic into a DirectRLEnv or DirectMARLEnv implementation.
  10. Port training configuration to the selected Isaac Lab reinforcement learning workflow.
  11. Run a small smoke test before scaling training. Omit --viz for headless execution.
  12. For locomotion migrations, run the policy-success validation loop in Reference. Validate a flat walking policy before rough-terrain curriculum training; rough terrain can start and still be unhealthy if episodes terminate immediately. If the legacy task's command range is broad, use a staged command curriculum or a simpler flat source config such as IsaacGymEnvs Anymal.yaml before claiming policy success.
  13. After the direct migration resets, steps, and trains, recommend a manager-based follow-up when the task has reusable observation, reward, command, curriculum, termination, or event logic.
  14. Use the isaaclab-converting-direct-to-manager skill for that follow-up instead of mixing manager conversion into the first parity pass.
  15. Iterate through the validation loop until the environment resets, steps, trains, and reaches a task-appropriate policy metric. Do not claim policy success from a completed training command, checkpoint file, or improving scalar alone; parse training metrics and run a bounded checkpoint rollout.

Validation

Use this feedback loop:

uv run --with pytest python -m pytest PATH_TO_MIGRATION_TEST

For manual smoke testing, run the smallest random-action entry point before training. For generated external projects, run uv sync from the project root and use the generated isaaclab.tasks entry point for CLI discovery; see External Template Projects. Standalone validation scripts must import the task registration module before Gym lookup. When matching Isaac Gym PhysX behavior, retain --extra isaacsim and the physics=isaacsim_physx preset on simulation commands.

For policy validation, follow the policy-success loop in Reference. The loop must import/register the migrated task, smoke-test reset and random steps, train to a useful budget, parse TensorBoard or equivalent scalars, evaluate the saved checkpoint in a bounded rollout, then adjust the migration and rerun the shortest affected gate until the policy succeeds or a concrete blocker is identified.

Runtime preflight for execution/training requests:

uv run --extra isaacsim python -c "import importlib.util, sys; print(sys.executable); print(sys.version); print(importlib.util.find_spec('isaacsim')); print(importlib.util.find_spec('omni'))"

For skill changes, run:

uv run --no-project python tools/skills/cli.py check

Maintenance

Keep this skill synchronized with the Isaac Gym section in docs/source/migration/migrating_to_isaaclab_3-0.rst, docs/source/setup/installation/index.rst, docs/source/concepts/task_workflows.rst, docs/source/concepts/backend_architecture.rst, docs/source/concepts/schema_cfgs.rst, the direct environment tutorial, and direct task examples such as source/isaaclab_tasks/isaaclab_tasks/core/locomotion/ant/, source/isaaclab_tasks/isaaclab_tasks/contrib/anymal_c_direct/, and source/isaaclab_tasks/isaaclab_tasks/core/velocity/config/anymal_d/. If the migration requires documentation-level details, update docs/source/ or the maintained examples first and keep this skill as a workflow router.

References