Skip to main content

cli_args

Module: GBC.gyms.isaaclab_45.workflows.rsl_rl.cli_args

Overview 📖​

Command line argument management module for RSL-RL workflows. This module extends the standard IsaacLab CLI argument system with additional parameters for RSL-RL training and inference, providing comprehensive configuration management through command line interfaces.

Core Functions 🔧​

add_rsl_rl_args() ⚙️​

Function Signature:

def add_rsl_rl_args(parser: argparse.ArgumentParser):

Purpose: Adds RSL-RL specific command line arguments to an ArgumentParser instance.

Parameters:

  • parser (argparse.ArgumentParser): The parser to add arguments to

Added Arguments:

📁 Experiment Management​

  • --experiment_name (str)

    • Purpose: Name of the experiment folder where logs will be stored
    • Default: None
    • Usage: Organizes training runs under specific experiment names

  • --run_name (str)

    • Purpose: Run name suffix to the log directory
    • Default: None
    • Usage: Differentiates multiple runs within the same experiment

🔄 Checkpoint Management​

  • --resume (bool)

    • Purpose: Whether to resume training from a checkpoint
    • Default: None
    • Usage: Enables continuation of interrupted training sessions

  • --load_run (str)

    • Purpose: Name of the run folder to resume from
    • Default: None
    • Usage: Specifies which run directory to load checkpoint from

  • --checkpoint (str)

    • Purpose: Specific checkpoint file to resume from
    • Default: None
    • Usage: Allows loading of specific checkpoint iterations

  • --abs_ckpt (str)

    • Purpose: Absolute path to the checkpoint file
    • Default: None
    • Usage: Direct checkpoint loading with full file path

📊 Logging Configuration​

  • --logger (str)

    • Purpose: Logger module to use for training metrics
    • Choices: {"wandb", "tensorboard", "neptune"}
    • Default: None
    • Usage: Selects logging backend for experiment tracking

  • --log_project_name (str)

    • Purpose: Name of the logging project when using wandb or neptune
    • Default: None
    • Usage: Organizes experiments under specific project names

Configuration Functions 🛠️​

parse_rsl_rl_cfg() 📋​

Function Signature:

def parse_rsl_rl_cfg(task_name: str, args_cli: argparse.Namespace) -> RslRlRefOnPolicyRunnerCfg:

Purpose: Parses and loads RSL-RL configuration based on task name and CLI arguments.

Parameters:

  • task_name (str): The name of the environment/task
  • args_cli (argparse.Namespace): Parsed command line arguments

Returns:

  • RslRlRefOnPolicyRunnerCfg: Configured RSL-RL runner configuration

Process:

  1. 📥 Registry Loading: Loads default configuration from task registry
  2. 🔧 CLI Override: Applies command line argument overrides
  3. ✅ Validation: Ensures configuration consistency

update_rsl_rl_cfg() 🔄​

Function Signature:

def update_rsl_rl_cfg(agent_cfg: RslRlRefOnPolicyRunnerCfg, args_cli: argparse.Namespace) -> RslRlRefOnPolicyRunnerCfg:

Purpose: Updates existing RSL-RL configuration with command line arguments.

Parameters:

  • agent_cfg (RslRlRefOnPolicyRunnerCfg): Base configuration to update
  • args_cli (argparse.Namespace): Command line arguments for overrides

Returns:

  • RslRlRefOnPolicyRunnerCfg: Updated configuration

CLI Override Logic 🎯​

Seed Management 🎲​

if hasattr(args_cli, "seed") and args_cli.seed is not None:
    # Special case: random seed generation
    if args_cli.seed == -1:
        args_cli.seed = random.randint(0, 10000)
    agent_cfg.seed = args_cli.seed

Features:

  • 🎯 Explicit Seed: Direct seed specification for reproducibility
  • 🎲 Random Seed: Use -1 for automatic random seed generation
  • 📊 Range: Random seeds generated in range [0, 10000]

Checkpoint Override Priority ⚡​

# Checkpoint loading priority (highest to lowest):
1. --abs_ckpt        # Absolute path (highest priority)
2. --load_run + --checkpoint  # Relative path specification
3. --resume          # Resume from latest checkpoint

Logger Configuration 📈​

if agent_cfg.logger in {"wandb", "neptune"} and args_cli.log_project_name:
    agent_cfg.wandb_project = args_cli.log_project_name
    agent_cfg.neptune_project = args_cli.log_project_name

Automatic Project Assignment:

  • WandB Integration: Sets wandb_project when using WandB logger
  • Neptune Integration: Sets neptune_project when using Neptune logger
  • TensorBoard: No additional project configuration needed

Usage Examples 💡​

Basic Training with Custom Experiment​

python train.py \
    --task Isaac-Humanoid-Amp-v0 \
    --experiment_name "humanoid_locomotion" \
    --run_name "baseline_v1" \
    --logger wandb \
    --log_project_name "GBC-Research"

Resume Training from Checkpoint​

python train.py \
    --task Isaac-Humanoid-Amp-v0 \
    --resume True \
    --load_run "2024-01-15_10-30-00_baseline_v1" \
    --checkpoint "model_5000.pt"

Inference with Specific Checkpoint​

python play.py \
    --task Isaac-Humanoid-Amp-v0 \
    --abs_ckpt "/path/to/logs/rsl_rl/experiment/run/checkpoints/model_8000.pt"

Random Seed Training​

python train.py \
    --task Isaac-Humanoid-Amp-v0 \
    --seed -1 \  # Auto-generate random seed
    --logger tensorboard

Configuration Integration 🔗​

With Hydra System​

# CLI arguments override Hydra configurations
@hydra_task_config(args_cli.task, "rsl_rl_cfg_entry_point")
def main(env_cfg: ManagerBasedRLEnvCfg, agent_cfg: RslRlRefOnPolicyRunnerCfg):
    # agent_cfg already includes CLI overrides via parse_rsl_rl_cfg()
    agent_cfg = cli_args.update_rsl_rl_cfg(agent_cfg, args_cli)

Configuration Precedence​

1. Command Line Arguments (--arg value)    [Highest Priority]
2. Hydra Configuration Files (.yaml)
3. Default Configuration Classes
4. Built-in Defaults                      [Lowest Priority]

Logging Backend Features 📊​

WandB Integration 🌐​

--logger wandb --log_project_name "GBC-Humanoid-Research"

Features:

  • ☁️ Cloud Logging: Automatic cloud synchronization
  • 📈 Real-time Metrics: Live training progress tracking
  • 🔗 Collaboration: Team experiment sharing
  • 📊 Advanced Visualization: Rich plotting and analysis tools

TensorBoard Integration 📈​

--logger tensorboard

Features:

  • 🖥️ Local Logging: Local file-based logging
  • 📊 Standard Metrics: Standard RL training metrics
  • 🎯 Lightweight: Minimal overhead and dependencies
  • 🔧 Offline Analysis: Works without internet connection

Neptune Integration 🌊​

--logger neptune --log_project_name "GBC-Research"

Features:

  • 🏢 Enterprise: Advanced experiment management
  • 📊 Metadata Tracking: Comprehensive experiment metadata
  • 🔄 Version Control: Model and data versioning
  • 👥 Team Collaboration: Advanced team features

Best Practices 💡​

Experiment Organization 📁​

# Recommended naming convention
--experiment_name "{project}_{task}_{date}"
--run_name "{algorithm}_{hyperparams}_{version}"

# Example:
--experiment_name "gbc_humanoid_2024"
--run_name "ppo_lr1e4_v1"

Checkpoint Management 💾​

# For long training sessions
--checkpoint "model_*.pt"  # Load latest numbered checkpoint

# For specific evaluations
--checkpoint "model_5000.pt"  # Load specific iteration

# For exact reproduction
--abs_ckpt "/full/path/to/specific/checkpoint.pt"

Logger Selection Guidelines 📊​

  • 🔬 Research: Use WandB for collaborative research with cloud sync
  • 🏠 Development: Use TensorBoard for local development and debugging
  • 🏢 Production: Use Neptune for enterprise experiment tracking

Related Components 🔗​

  • 🏋️ train.py: Main training script that uses these CLI arguments
  • 🎬 play.py: Inference script that uses checkpoint loading arguments
  • 📊 RslRlRefOnPolicyRunnerCfg: Configuration class that gets updated by CLI args
  • 🔧 Hydra Integration: Configuration system that works alongside CLI arguments

This CLI argument system provides flexible and comprehensive command line control over RSL-RL training and inference workflows, enabling easy experimentation and configuration management.