Implementation:Isaac sim IsaacGymEnvs Factory Schema Config Hierarchy

Knowledge Sources	IsaacGymEnvs
Domains	Configuration, Manipulation
Last Updated	2026-02-15 00:00 GMT

Overview

Three-tier YAML and Python dataclass configuration pattern used across all Factory and IndustReal assembly environments.

Description

This pattern defines the concrete file layout and schema classes for the Factory/IndustReal configuration hierarchy. YAML files in cfg/task/ are composed via Hydra defaults lists, with each tier having a companion Python dataclass schema for type checking. The task-level YAML is the entry point and includes both the environment and base configs through Hydra composition.

Usage

Use this pattern when adding new Factory/IndustReal task variants or modifying existing configuration parameters. Follow the three-tier structure to ensure compatibility with the class hierarchy.

Code Reference

Source Location

• Repository: IsaacGymEnvs
• File: isaacgymenvs/tasks/factory/factory_schema_config_base.py, Lines 1-86
• File: isaacgymenvs/tasks/factory/factory_schema_config_env.py, Lines 1-50
• File: isaacgymenvs/tasks/factory/factory_schema_config_task.py, Lines 1-161

Pattern

YAML Hierarchy

# cfg/task/FactoryTaskNutBoltPick.yaml (task-level entry point)
defaults:
  - FactoryBase          # base simulation config
  - FactoryEnvNutBolt    # environment-specific config
  - _self_

# Task-specific parameters
rl:
  pos_action_scale: 0.1
  rot_action_scale: 0.1
  keypoint_reward_scale: 1.0
  action_penalty_scale: 0.0

ctrl:
  controller_type: joint_space_ik
  all:
    jacobian_type: geometric

Python Dataclass Schemas

# factory_schema_config_base.py
@dataclass
class FactorySchemaConfigBase:
    """Schema for base-tier configuration."""
    sim: SimConfig = SimConfig()
    env: EnvConfig = EnvConfig()

@dataclass
class SimConfig:
    disable_gravity_dt: float = 0.1
    num_substeps: int = 4

# factory_schema_config_env.py
@dataclass
class FactorySchemaConfigEnv:
    """Schema for environment-tier configuration."""
    num_envs: int = 128
    env_spacing: float = 1.0

# factory_schema_config_task.py
@dataclass
class FactorySchemaConfigTask:
    """Schema for task-tier configuration."""
    rl: RLConfig = RLConfig()
    ctrl: CtrlConfig = CtrlConfig()

@dataclass
class RLConfig:
    pos_action_scale: float = 0.1
    rot_action_scale: float = 0.1

@dataclass
class CtrlConfig:
    controller_type: str = "joint_space_ik"

Key Parameters

Parameter	Tier	Type	Description
sim.disable_gravity_dt	Base	float	Duration to disable gravity during resets (seconds)
env.num_envs	Env	int	Number of parallel environments on GPU
rl.pos_action_scale	Task	float	Scale factor for position action deltas
rl.rot_action_scale	Task	float	Scale factor for rotation action deltas
ctrl.controller_type	Task	str	Robot controller type (e.g., joint_space_ik, task_space_impedance)
rl.keypoint_reward_scale	Task	float	Weight for keypoint-based reward terms
rl.sdf_reward_scale	Task	float	Weight for SDF-based reward terms

I/O Contract

Inputs

Name	Type	Required	Description
FactoryBase.yaml	YAML file	Yes	Base simulation and Franka parameters
FactoryEnv*.yaml	YAML file	Yes	Environment-specific object and scene parameters
FactoryTask*.yaml	YAML file	Yes	Task-specific RL, reward, and controller parameters
IndustRealBase.yaml	YAML file	Conditional	IndustReal base config (for IndustReal tasks)
IndustRealEnv*.yaml	YAML file	Conditional	IndustReal environment config
IndustRealTask*.yaml	YAML file	Conditional	IndustReal task config

Outputs

Name	Type	Description
cfg_base	FactorySchemaConfigBase	Structured base config object (simulation, Franka defaults)
cfg_env	FactorySchemaConfigEnv	Structured environment config object (scene layout, objects)
cfg_task	FactorySchemaConfigTask	Structured task config object (RL params, controller, rewards)

Usage Examples

Overriding Config from Command Line

# Train nut-bolt pick with custom environment count and controller
python train.py task=FactoryTaskNutBoltPick \
    num_envs=256 \
    task.ctrl.controller_type=task_space_impedance \
    task.rl.pos_action_scale=0.05

Accessing Config in Task Code

class FactoryTaskNutBoltPick(FactoryEnvNutBolt, FactoryABCTask):
    def __init__(self, cfg, ...):
        super().__init__(cfg, ...)
        # Config objects are available as instance attributes
        print(self.cfg_task.rl.pos_action_scale)   # 0.1
        print(self.cfg_task.ctrl.controller_type)   # "joint_space_ik"
        print(self.cfg_env.num_envs)                # 128
        print(self.cfg_base.sim.disable_gravity_dt) # 0.1

Related Pages

Implements Principle

• Principle:Isaac_sim_IsaacGymEnvs_Factory_Configuration