Setup and Training

Setup and Training#

This repository is a downstream Isaac Lab project. It provides task formulations, reusable MDP terms, and export utilities, while Isaac Lab provides the simulator integration, unified training entry points, and RSL-RL runner.

Prerequisites#

  • Linux workstation or cluster node with an NVIDIA GPU.

  • Python 3.12.

  • uv for Python environment management.

  • Git access to this repository and the pinned Isaac Lab dependency.

  • Isaac Sim for PhysX / Kit training. In the standalone uv workflow below, install it with the sim dependency group.

Install uv if it is not already available:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install the Standalone Repo#

Clone the repository and install the default dependencies:

git clone https://github.com/ashwinvkNV/IsaacLabTraining.git
cd IsaacLabTraining
uv sync

The isaaclab dependency is declared in pyproject.toml and pinned through uv.lock. The default uv sync path installs the repo in editable mode and resolves Isaac Lab from the pinned Isaac Lab wheel-builder source:

isaaclab = { git = "https://github.com/isaac-sim/IsaacLab.git", subdirectory = "tools/wheel_builder", ... }

This base install is enough for package imports, docs, tests, and task registration checks. PhysX / Kit training additionally requires Isaac Sim:

uv sync --group sim

The sim group installs Isaac Sim through NVIDIA’s Python package index. The resolver also carries the small compatibility overrides needed by the pinned Isaac Lab revision.

Use dependency groups for optional local workflows:

uv sync --group dev      # tests, ruff, pre-commit, codespell
uv sync --group docs     # Sphinx docs build
uv sync --group leapp    # LEAPP export tooling
uv sync --group sim      # Isaac Sim for PhysX / Kit training

Verify the Install#

Confirm the package imports and the downstream Isaac Lab tasks are registered:

uv run python -c "import isaaclab_training; print('isaaclab_training ok')"

uv run python -c 'import gymnasium as gym; import isaaclab_training.tasks; print([s.id for s in gym.registry.values() if s.id.startswith("IsaacTraining-")])'

The second command should list the registered IsaacTraining-* task IDs.

Train a DisplayPort Policy#

Install the simulation group before training:

uv sync --group sim

Task-space control is the recommended DisplayPort deployment path:

uv run isaaclab train --rl_library rsl_rl \
  --task IsaacTraining-DisplayPortInsertion-Rizon4s-TaskSpace-ROS-Inference \
  --num_envs 4 \
  --max_iterations 100 \
  --visualizer kit

Use this small visual run first to confirm that Isaac Sim launches, the task is registered, and the robot/plug/socket scene looks correct.

If this command reports Isaac Sim is not installed or not found on PYTHONPATH, run uv sync --group sim or use the Isaac Lab source-checkout workflow below.

For a longer headless training run:

uv run isaaclab train --rl_library rsl_rl \
  --task IsaacTraining-DisplayPortInsertion-Rizon4s-TaskSpace-ROS-Inference \
  --num_envs 256 \
  --viz none \
  --video --video_length 200 --video_interval 76800

Joint-space training is also packaged:

uv run isaaclab train --rl_library rsl_rl \
  --task IsaacTraining-DisplayPortInsertion-Rizon4s-Joint-NoJointVel-ROS-Inference \
  --num_envs 256 \
  --viz none

Training outputs are written under logs/rsl_rl/. Monitor a run with TensorBoard:

uv run python -m tensorboard.main --logdir logs/rsl_rl/displayport_insertion_rizon4s

Using an Isaac Lab Source Checkout#

If you already work inside an Isaac Lab source checkout, install this repository into Isaac Lab’s Python environment instead of creating a separate uv managed environment:

cd /path/to/IsaacLab
./isaaclab.sh -p -m pip install -e /path/to/IsaacLabTraining

./isaaclab.sh train --rl_library rsl_rl \
  --task IsaacTraining-DisplayPortInsertion-Rizon4s-TaskSpace-ROS-Inference \
  --num_envs 4 \
  --max_iterations 100 \
  --visualizer kit

Use the source-checkout path when you need to test against a local Isaac Lab branch. Use the standalone uv sync path for normal development in this repo.

Common Overrides#

  • --task: registered Isaac Lab task ID.

  • --rl_library rsl_rl: selects the RSL-RL backend used by these configs.

  • --num_envs: number of parallel simulation environments.

  • --max_iterations: short CLI override for the RSL-RL runner.

  • --viz none: disables visualization for throughput.

  • --visualizer kit: opens the Kit viewer for debugging.

  • --video --video_length ... --video_interval ...: records training videos.

The task-specific DisplayPort guide has the full train/play/export workflow.