Implementation:Isaac sim IsaacGymEnvs RunDescription

Knowledge Sources	IsaacGymEnvs
Domains	Experiment_Management, Hyperparameter_Search
Last Updated	2026-02-15 11:00 GMT

Overview

RunDescription and its supporting classes (ParamGenerator, ParamList, ParamGrid, Experiment) provide a structured system for defining and generating experiment configurations with parameter combinations for PBT hyperparameter sweeps.

Description

This module implements a layered experiment description system. At the foundation, ParamGenerator is an abstract base class whose generate_params() method yields dictionaries of parameter key-value pairs. Two concrete implementations are provided: ParamList, which iterates over an explicit list of parameter dictionaries (optionally randomized), and ParamGrid, which performs grid search by recursively generating all combinations from an OrderedDict of parameter names to value lists.

The Experiment class wraps a base command string with a parameter generator. Its generate_experiments() method yields tuples of (full command string, experiment name) by appending each parameter combination to the base command. Experiment names are automatically generated from parameter shorthands, truncated to keep them manageable, with a two-digit index prefix. The class also supports environment variable overrides via its env_vars attribute.

The top-level RunDescription class ties everything together, holding a run name, a list of Experiment objects, and configuration for argument naming conventions. Its generate_experiments(train_dir) method iterates over all experiments and their parameter combinations, creating directory structures and yielding final command strings with the training directory argument appended. It supports customizable experiment argument names, directory argument names, parameter prefixes (e.g., -- for standard CLI or empty for Hydra), and an experiment suffix for distinguishing runs.

Usage

Use these classes when defining PBT or hyperparameter sweep experiments. Create ParamGrid or ParamList instances to specify the parameter space, wrap them in Experiment objects with base training commands, and combine them into a RunDescription. The resulting RunDescription is consumed by the PBT launcher backends (processes, SLURM, NGC) to execute all experiment configurations.

Code Reference

Source Location

• Repository: IsaacGymEnvs
• File: isaacgymenvs/pbt/launcher/run_description.py
• Lines: 1-185

Signature

class ParamGenerator:
    def generate_params(self, randomize=True):

class ParamList(ParamGenerator):
    def __init__(self, combinations):
    def generate_params(self, randomize=True):

class ParamGrid(ParamGenerator):
    def __init__(self, grid_tuples):
    def generate_params(self, randomize=False):

class Experiment:
    def __init__(self, name, cmd, param_generator=(), env_vars=None):
    def generate_experiments(self, experiment_arg_name, customize_experiment_name, param_prefix):

class RunDescription:
    def __init__(self, run_name, experiments, experiment_arg_name="--experiment",
                 experiment_dir_arg_name="--train_dir", customize_experiment_name=True,
                 param_prefix="--"):
    def generate_experiments(self, train_dir, makedirs=True):

Import

from isaacgymenvs.pbt.launcher.run_description import RunDescription, Experiment, ParamGrid

I/O Contract

Inputs

Name	Type	Required	Description
run_name	str	Yes	Overall name of the experiment run, used as root folder name
experiments	list[Experiment]	Yes	List of Experiment objects defining the commands and parameter spaces
experiment_arg_name	str	No	CLI argument name for experiment identifier (default: --experiment)
experiment_dir_arg_name	str	No	CLI argument name for training directory (default: --train_dir)
customize_experiment_name	bool	No	Whether to include parameter shorthands in experiment names (default: True)
param_prefix	str	No	Prefix for parameter arguments (default: --, use empty string for Hydra)

Outputs

Name	Type	Description
experiment_cmd	str	Complete command string with all parameters and directory arguments
experiment_name	str	Generated experiment name including parameter shorthands
root_dir	str	Relative directory path for the experiment output
env_vars	dict or None	Environment variable overrides for the experiment process

Usage Examples

from isaacgymenvs.pbt.launcher.run_description import RunDescription, Experiment, ParamGrid

# Define a parameter grid for hyperparameter search
param_grid = ParamGrid([
    ('learning_rate', [1e-3, 3e-4, 1e-4]),
    ('gamma', [0.99, 0.995]),
    ('mini_epochs', [4, 8]),
])

# Create an experiment with a base command and parameter grid
experiment = Experiment(
    name='humanoid_amp',
    cmd='python train.py task=HumanoidAMP',
    param_generator=param_grid.generate_params(randomize=False),
)

# Combine into a run description
run_description = RunDescription(
    run_name='humanoid_amp_sweep',
    experiments=[experiment],
    param_prefix='',  # Hydra-style parameters (no -- prefix)
)

# Generate all experiment commands
for cmd, name, root_dir, env_vars in run_description.generate_experiments('./train_dir'):
    print(f"Experiment: {name}")
    print(f"Command: {cmd}")
    print(f"Directory: {root_dir}")

Related Pages

• Isaac_sim_IsaacGymEnvs_PBT_Launcher - The CLI entry point that consumes RunDescription objects
• Isaac_sim_IsaacGymEnvs_PBT_Process_Backend - Local process backend that executes generated experiments
• Isaac_sim_IsaacGymEnvs_PBT_Slurm_Backend - SLURM backend that submits generated experiments
• Isaac_sim_IsaacGymEnvs_PBT_NGC_Backend - NGC backend that submits generated experiments