Principle:Isaac sim IsaacGymEnvs Task Configuration Files

Field	Value
Principle Name	Task Configuration Files
Overview	Convention for defining task environment parameters and training hyperparameters in separate Hydra YAML configuration files.
Domains	Configuration, Training
Related Implementation	Isaac_sim_IsaacGymEnvs_Hydra_Task_Train_YAML
Last Updated	2026-02-15 00:00 GMT

Knowledge Sources	IsaacGymEnvs Isaac Gym Docs
Domains	Configuration, Training
Last Updated	2026-02-15 00:00 GMT

Description

Each IsaacGymEnvs task requires two YAML configuration files that are composed at runtime by the Hydra configuration framework:

1. Task config (cfg/task/MyTask.yaml): Defines the environment's structural parameters including the number of parallel environments (numEnvs), observation and action dimensions (numObservations, numActions), simulation physics settings (sim.dt, sim.substeps, sim.physx.*), and task-specific parameters (reward weights, reset thresholds, asset paths).

1. Train config (cfg/train/MyTaskPPO.yaml): Defines the rl_games training algorithm hyperparameters including the network architecture (params.network.mlp.units), learning rate (params.config.learning_rate), batch and minibatch sizes, PPO-specific parameters (clip range, entropy coefficient, GAE lambda), and training duration (params.config.max_epochs).

The top-level cfg/config.yaml uses Hydra's defaults list to compose these two files together with general settings (experiment name, device selection, logging).

Theoretical Basis

The dual-config pattern implements separation of concerns at the configuration level:

• Task parameters define what the environment is: its state space, action space, physical properties, and reward structure. These are properties of the MDP itself.
• Training parameters define how the agent learns: network capacity, optimization hyperparameters, and sampling strategy. These are properties of the learning algorithm.

This separation enables several important workflows:

• Algorithm comparison: Train the same task with different algorithms or hyperparameters by swapping only the train config.
• Task variant exploration: Test the same training setup across different task configurations (e.g., different numbers of environments, different reward weights).
• Hydra override composition: Override individual parameters from the command line without modifying files: task.env.numEnvs=1024 train.params.config.learning_rate=1e-4.
• Reproducibility: The complete configuration for any experiment is captured in two files plus any CLI overrides, which Hydra logs automatically.

When to Use

Use this principle when:

• Creating configuration files for a new custom task.
• Understanding how existing task configurations are structured.
• Tuning hyperparameters for an existing task.
• Setting up experiment sweeps across different configurations.

Structure

Task Config Structure

cfg/task/MyTask.yaml
|
+-- name: MyTask
+-- physics_engine: ${..physics_engine}    # inherited from top-level
+-- env:
|     +-- numEnvs: ${resolve_default:512,...}
|     +-- numObservations: N
|     +-- numActions: M
|     +-- envSpacing: 2.0
|     +-- episodeLength: 500
|     +-- ... (task-specific params)
+-- sim:
      +-- dt: 0.0166  # 1/60
      +-- substeps: 2
      +-- gravity: [0.0, 0.0, -9.81]
      +-- physx:
            +-- num_threads: 4
            +-- solver_type: 1
            +-- num_position_iterations: 4
            +-- num_velocity_iterations: 0
            +-- contact_offset: 0.02
            +-- rest_offset: 0.001

Train Config Structure

cfg/train/MyTaskPPO.yaml
|
+-- params:
      +-- seed: ${...seed}
      +-- algo:
      |     +-- name: a2c_continuous
      +-- model:
      |     +-- name: continuous_a2c_logstd
      +-- network:
      |     +-- name: actor_critic
      |     +-- mlp:
      |           +-- units: [256, 128, 64]
      |           +-- activation: elu
      +-- config:
            +-- name: ${resolve_default:MyTask,...}
            +-- env_name: rlgpu
            +-- max_epochs: ${resolve_default:500,...}
            +-- minibatch_size: 1024
            +-- learning_rate: 3e-4
            +-- clip_param: 0.2
            +-- entropy_coef: 0.0
            +-- gamma: 0.99
            +-- tau: 0.95     # GAE lambda
            +-- horizon_length: 16

Top-Level Config Composition

cfg/config.yaml
|
+-- defaults:
|     +-- task: Cartpole        # loads cfg/task/Cartpole.yaml
|     +-- train: ${task}PPO     # loads cfg/train/CartpolePPO.yaml
|
+-- task_name: ${task.name}
+-- experiment: ''
+-- num_envs: ''               # override for task.env.numEnvs
+-- seed: 42
+-- physics_engine: physx
+-- sim_device: "cuda:0"
+-- rl_device: "cuda:0"
+-- headless: ${...headless}

Key Configuration Parameters

Parameter	File	Default	Description
env.numEnvs	Task YAML	Task-dependent (512-4096)	Number of parallel environments on GPU
env.numObservations	Task YAML	Task-dependent	Observation vector dimension
env.numActions	Task YAML	Task-dependent	Action vector dimension
env.episodeLength	Task YAML	Task-dependent	Maximum steps per episode
sim.dt	Task YAML	0.0166 (60Hz)	Physics timestep in seconds
sim.substeps	Task YAML	2	Physics substeps per control step
params.config.learning_rate	Train YAML	3e-4	PPO learning rate
params.network.mlp.units	Train YAML	[256, 128, 64]	MLP hidden layer sizes
params.config.max_epochs	Train YAML	Task-dependent	Training duration in epochs

Related Pages

• Isaac_sim_IsaacGymEnvs_Hydra_Task_Train_YAML - implements - Concrete YAML file templates with Cartpole as reference.
• Isaac_sim_IsaacGymEnvs_Task_Requirements_Design - prerequisite - Design decisions that determine configuration values.
• Isaac_sim_IsaacGymEnvs_Task_Registration - next step - After creating configs, register the task class in the task map.
• Isaac_sim_IsaacGymEnvs_Train_Py_Task_Execution - consumer - The training pipeline reads and composes these configs.

Implementation:Isaac_sim_IsaacGymEnvs_Hydra_Task_Train_YAML