CyberFusion Lab

Overview

CF Lab is an Isaac Lab extension for RL-based locomotion control of the AYG quadruped robot.

Cloning

This repo uses git submodules (notably IsaacLab/, pinned to v2.3.2). After cloning, run:

git submodule update --init --recursive

docker-compose bind-mounts the host's IsaacLab/ over /workspace/isaaclab at runtime, overriding the base image's bundled copy so host and container see the same Isaac Lab source. (Running the image without this mount falls back to the base image's v2.3.2 copy.)

Installation

Isaac Lab

Follow the instruction here, i.e.,

uv venv --python 3.11 --seed .venv
source .venv/bin/activate
uv pip install isaaclab[isaacsim,all]==2.3.2.post1 --extra-index-url https://pypi.nvidia.com
uv pip install -U torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
uv pip install git+https://github.com/isaac-sim/rl_games.git@python3.11

Verify the installation by running the simulator with

isaaclab

Local Project

Install cf_lab with

uv pip install -e source/cf_lab

• Install Isaac Lab by following the installation guide. We recommend using the conda or uv installation as it simplifies calling Python scripts from the terminal.

• Clone or copy this project/repository separately from the Isaac Lab installation (i.e. outside the IsaacLab directory):

• Using a python interpreter that has Isaac Lab installed, install the library in editable mode using:

  # use 'PATH_TO_isaaclab.sh|bat -p' instead of 'python' if Isaac Lab is not installed in Python venv or conda
  python -m pip install -e source/cf_lab
  

• Verify that the extension is correctly installed by:

  • Listing the available tasks:

    Note: It the task name changes, it may be necessary to update the search pattern "Template-" (in the scripts/list_envs.py file) so that it can be listed.

    # use 'FULL_PATH_TO_isaaclab.sh|bat -p' instead of 'python' if Isaac Lab is not installed in Python venv or conda
    python scripts/list_envs.py

  • Running a task:

    # use 'FULL_PATH_TO_isaaclab.sh|bat -p' instead of 'python' if Isaac Lab is not installed in Python venv or conda
    python scripts/<RL_LIBRARY>/train.py --task=<TASK_NAME>

  • Running a task with dummy agents:

    These include dummy agents that output zero or random agents. They are useful to ensure that the environments are configured correctly.

    • Zero-action agent

      # use 'FULL_PATH_TO_isaaclab.sh|bat -p' instead of 'python' if Isaac Lab is not installed in Python venv or conda
      python scripts/zero_agent.py --task=<TASK_NAME>

    • Random-action agent

      # use 'FULL_PATH_TO_isaaclab.sh|bat -p' instead of 'python' if Isaac Lab is not installed in Python venv or conda
      python scripts/random_agent.py --task=<TASK_NAME>

Set up IDE (Optional)

To setup the IDE, please follow these instructions:

• Run VSCode Tasks, by pressing Ctrl+Shift+P, selecting Tasks: Run Task and running the setup_python_env in the drop down menu. When running this task, you will be prompted to add the absolute path to your Isaac Sim installation.

If everything executes correctly, it should create a file .python.env in the .vscode directory. The file contains the python paths to all the extensions provided by Isaac Sim and Omniverse. This helps in indexing all the python modules for intelligent suggestions while writing code.

Setup as Omniverse Extension (Optional)

We provide an example UI extension that will load upon enabling your extension defined in source/cf_lab/cf_lab/ui_extension_example.py.

To enable your extension, follow these steps:

1. Add the search path of this project/repository to the extension manager:

   • Navigate to the extension manager using Window -> Extensions.
   • Click on the Hamburger Icon, then go to Settings.
   • In the Extension Search Paths, enter the absolute path to the source directory of this project/repository.
   • If not already present, in the Extension Search Paths, enter the path that leads to Isaac Lab's extension directory directory (IsaacLab/source)
   • Click on the Hamburger Icon, then click Refresh.

2. Search and enable your extension:

   • Find your extension under the Third Party category.
   • Toggle it to enable your extension.

Running Multiple Trainings on One GPU

When two (or more) training jobs share a GPU, by default the NVIDIA driver time-slices CUDA contexts and each job gets roughly half the wall-clock throughput. NVIDIA's Multi-Process Service (MPS) lets the jobs share SMs concurrently instead, which is worth enabling whenever a single training doesn't saturate the GPU (typical for Isaac Lab at a few thousand envs).

Start the MPS daemon on the host before launching the container (it must run as root to create its pipes in /tmp/nvidia-mps):

sudo nvidia-cuda-mps-control -d

The compose file bind-mounts /tmp/nvidia-mps and /tmp/nvidia-log into the container, so any training launched inside the container will auto-attach as an MPS client — no extra environment variables or flags needed.

Verify, from inside the container:

echo get_server_list | nvidia-cuda-mps-control   # prints the server PID once a client connects
nvidia-smi --query-compute-apps=pid,used_memory --format=csv
# you should see an extra ~30 MiB process: nvidia-cuda-mps-server

To stop the daemon (on the host):

echo quit | sudo nvidia-cuda-mps-control

Caveats: if the MPS server dies, all its clients die with it, so it is not recommended for unattended multi-day runs unless you accept that risk.

Code formatting

We have a pre-commit template to automatically format your code. To install pre-commit:

pip install pre-commit

Then you can run pre-commit with:

pre-commit run --all-files

Troubleshooting

BLAS/OpenMP Threading Crash

Training may crash with "Illegal instruction" or a segfault caused by OpenBLAS/MKL thread conflicts. Fix by setting these environment variables before running any training script:

export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1

Troubleshooting (IDE)

Pylance Missing Indexing of Extensions

In some VsCode versions, the indexing of part of the extensions is missing. In this case, add the path to your extension in .vscode/settings.json under the key "python.analysis.extraPaths".

{
    "python.analysis.extraPaths": [
        "<path-to-ext-repo>/source/cf_lab"
    ]
}

Pylance Crash

If you encounter a crash in pylance, it is probable that too many files are indexed and you run out of memory. A possible solution is to exclude some of omniverse packages that are not used in your project. To do so, modify .vscode/settings.json and comment out packages under the key "python.analysis.extraPaths" Some examples of packages that can likely be excluded are:

"<path-to-isaac-sim>/extscache/omni.anim.*"         // Animation packages
"<path-to-isaac-sim>/extscache/omni.kit.*"          // Kit UI tools
"<path-to-isaac-sim>/extscache/omni.graph.*"        // Graph UI tools
"<path-to-isaac-sim>/extscache/omni.services.*"     // Services tools
...