Architecture#

GenesisLab follows a manager-based architecture where different aspects of the robot learning problem are handled by specialized manager components.

Overview#

┌────────────────────────────────────────────────────────────┐
│                     GenesisEnv (Gymnasium)                  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                      LabScene                         │  │
│  │                                                       │  │
│  │  ┌─────────────────┐         ┌──────────────────┐   │  │
│  │  │ SceneBuilder    │────────▶│ Genesis Scene    │   │  │
│  │  └─────────────────┘         └──────────────────┘   │  │
│  │                                      │               │  │
│  │  ┌─────────────────┐                │               │  │
│  │  │ SceneController │◀───────────────┘               │  │
│  │  └─────────────────┘                                │  │
│  │           │                                          │  │
│  │  ┌─────────────────┐                                │  │
│  │  │ SceneQuerier    │                                │  │
│  │  └─────────────────┘                                │  │
│  │                                                       │  │
│  │  ┌──────────────────────────────────────────────┐   │  │
│  │  │             Manager System                    │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ ObservationManager                     │  │   │  │
│  │  │  │  ├─ base_pos, base_lin_vel, ...       │  │   │  │
│  │  │  │  ├─ joint_pos, joint_vel, ...          │  │   │  │
│  │  │  │  └─ [ObservationTerm, ...]             │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ ActionManager                          │  │   │  │
│  │  │  │  └─ Processes and applies actions      │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ RewardManager                          │  │   │  │
│  │  │  │  ├─ forward_velocity                   │  │   │  │
│  │  │  │  ├─ energy_penalty                     │  │   │  │
│  │  │  │  └─ [RewardTerm, ...]                  │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ CommandManager                         │  │   │  │
│  │  │  │  └─ Generates command targets          │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ TerminationManager                     │  │   │  │
│  │  │  │  └─ Checks termination conditions      │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ CurriculumManager                      │  │   │  │
│  │  │  │  └─ Manages training curriculum        │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ EventManager                           │  │   │  │
│  │  │  │  └─ Domain randomization events        │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  └──────────────────────────────────────────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

Core Components#

1. LabScene#

LabScene is the central orchestrator that:

  • Manages the Genesis scene lifecycle

  • Coordinates all managers

  • Implements MDP (Markov Decision Process) functions

  • Provides the interface between Gymnasium and Genesis

Key Responsibilities:

class LabScene:
    def reset(self) -> Observations
    def step(self, actions) -> tuple[Observations, Rewards, Terminated, Truncated, Info]
    def compute_observations(self) -> dict[str, torch.Tensor]
    def compute_rewards(self) -> torch.Tensor
    def compute_terminations(self) -> tuple[torch.Tensor, torch.Tensor]

2. Scene Patterns#

Three key patterns for interacting with the Genesis scene:

SceneBuilder#

Constructs the initial scene:

class SceneBuilder:
    def build_terrain(self) -> None
    def build_robot(self) -> None
    def build_sensors(self) -> None
    def build_objects(self) -> None

SceneController#

Modifies scene state during simulation:

class SceneController:
    def apply_actions(self, actions: torch.Tensor) -> None
    def reset_robots(self, env_ids: torch.Tensor) -> None
    def randomize_dynamics(self) -> None

SceneQuerier#

Reads data from the scene:

class SceneQuerier:
    def get_robot_state(self) -> dict[str, torch.Tensor]
    def get_sensor_data(self) -> dict[str, torch.Tensor]
    def get_contact_forces(self) -> torch.Tensor

3. Manager System#

Managers are specialized components handling specific aspects:

ObservationManager#

  • Computes observation tensors from individual observation terms

  • Supports policy observations and privileged (critic) observations

  • Handles observation noise and normalization

ActionManager#

  • Processes raw actions from the policy

  • Applies action scaling and clipping

  • Converts actions to motor commands (e.g., PD targets)

RewardManager#

  • Computes total reward from weighted reward terms

  • Supports per-term logging

  • Handles reward scaling and clipping

CommandManager#

  • Generates command targets for the robot

  • Supports resampling commands on reset

  • Examples: velocity commands, pose targets

TerminationManager#

  • Checks termination conditions

  • Distinguishes between truncation and termination

  • Examples: timeout, falling, out-of-bounds

CurriculumManager#

  • Implements training curricula

  • Adjusts difficulty over training

  • Examples: terrain difficulty, disturbance magnitude

EventManager#

  • Handles episodic events and randomization

  • Domain randomization for sim-to-real transfer

  • Examples: dynamics randomization, robot state randomization

ObjectManager#

  • Manages dynamic objects in the scene

  • Object spawning and tracking

  • Object interaction rewards

Term-Based Composition#

Managers use a term-based composition pattern:

@configclass
class ObservationManagerCfg:
    # Each term is a configuration for an observation computation
    base_lin_vel = ObservationTermCfg(
        func=observations.base_lin_vel,
        noise=UniformNoiseCfg(min=-0.1, max=0.1)
    )
    
    joint_pos = ObservationTermCfg(
        func=observations.joint_pos,
        scale=1.0
    )

Benefits:

  • Modularity: Each term is independent

  • Reusability: Terms can be shared across tasks

  • Configurability: Easy to add/remove terms

  • Clarity: Clear separation of concerns

Data Flow#

During reset():#

1. EventManager.reset()      → Apply randomization events
2. SceneController.reset()    → Reset robot states
3. CommandManager.reset()     → Sample new commands  
4. ObservationManager.reset() → Compute initial observations
   └─ SceneQuerier.query()    → Read robot/sensor state

During step(actions):#

1. ActionManager.process(actions)
   └─ SceneController.apply_actions()
2. Genesis.step()              → Physics step
3. ObservationManager.compute()
   └─ SceneQuerier.query()
4. RewardManager.compute()
5. TerminationManager.check()

Configuration System#

GenesisLab uses @configclass decorators for all configurations:

from genesislab.utils.configclass import configclass

@configclass
class MyTaskCfg:
    # Scene configuration
    scene: LabSceneCfg = LabSceneCfg(
        num_envs=4096,
        env_spacing=4.0
    )
    
    # Manager configurations
    observations: ObservationManagerCfg = ObservationManagerCfg(...)
    actions: ActionManagerCfg = ActionManagerCfg(...)
    rewards: RewardManagerCfg = RewardManagerCfg(...)

Critical Rule: Always use @configclass, never @dataclass.

Execution Flow#

sequenceDiagram
    participant Gym as Gymnasium
    participant Scene as LabScene
    participant Mgrs as Managers
    participant GS as Genesis

    Gym->>Scene: reset()
    Scene->>Mgrs: reset()
    Mgrs->>GS: reset states
    GS-->>Mgrs: 
    Mgrs-->>Scene: observations
    Scene-->>Gym: obs, info

    loop Training
        Gym->>Scene: step(actions)
        Scene->>Mgrs: process(actions)
        Mgrs->>GS: apply actions
        GS->>GS: simulate
        Scene->>Mgrs: compute()
        Mgrs->>GS: query state
        GS-->>Mgrs: state data
        Mgrs-->>Scene: obs, rew, term
        Scene-->>Gym: obs, rew, term, trunc, info
    end

Extension Points#

GenesisLab is designed to be extended:

  1. Custom Observation Terms: Add new observation functions

  2. Custom Reward Terms: Define new reward calculations

  3. Custom Managers: Implement specialized managers

  4. Custom Tasks: Compose managers for new tasks

  5. Custom Robots: Add new robot configurations

Next Steps#