Skip to content

Architecture

This page is the conceptual map of GeneLab and, in particular, where the boundary with the Genesis simulator lies: which features are thin wrappers over Genesis, which are implemented in GeneLab, and which wrap external RL libraries. For the import-time rules that keep the layers honest, see Contracts.

A one-line mental model:

GeneLab ≈ Genesis (physics backend) + a lightweight re-implementation of the Isaac Lab API + adapters to three RL libraries.

Layered overview

flowchart TD
    CLI[genelab CLI] --> Registry[Registry + extensions]
    CLI --> Runner[RL runner]
    Registry --> Tasks[Tasks / envs / robots]
    Runner --> Backends[rsl_rl / skrl / sb3]
    Runner --> VecEnv[VecEnv adapters]
    VecEnv --> Env[ManagerBasedRlEnv]
    Tasks --> Env
    Env --> Managers[MDP managers]
    Env --> Scene[InteractiveScene]
    Managers --> MDP[mdp term library]
    Scene --> Entities[articulations / rigid objects / sensors]
    Scene --> Genesis[(Genesis sim)]
    Entities --> Genesis
    MDP --> Entities

What wraps Genesis vs what GeneLab implements

The abstraction seam sits at InteractiveScene / Articulation / Sensor.build(). Below it Genesis owns physics, rendering, terrain heightfields and the built-in PD controller; above it the code is implemented in GeneLab and is simulator-agnostic (still a re-implementation of the Isaac Lab API and wrappers over various libraries — not original work).

flowchart TB
    subgraph NAT["Implemented in GeneLab"]
        direction LR
        Managers[managers]
        MDPlib[mdp terms]
        EnvLoop[envs step loop]
        Derived[derived sensors]
        ActLaws[actuator laws]
        Infra[registry · cli · asset_zoo]
    end
    subgraph WRAP["Wraps Genesis"]
        direction LR
        Scene2[scene + entity]
        ImplAct[built-in PD]
        Terr[terrains]
        Rec[recording]
        HwSens[hardware sensors]
        Kb[keyboard bridge]
    end
    subgraph EXT["Wraps external RL libs"]
        direction LR
        RL[rl runner + backends]
        Libs[(rsl_rl · skrl · sb3)]
    end
    GenesisSim[(Genesis sim)]

    NAT --> WRAP --> GenesisSim
    EXT --> EnvLoop
    RL --> Libs

    classDef nat fill:#e8f5e9,stroke:#2e7d32;
    classDef wrap fill:#e3f2fd,stroke:#1565c0;
    classDef ext fill:#fff3e0,stroke:#e65100;
    classDef sim fill:#eceff1,stroke:#37474f;
    class Managers,MDPlib,EnvLoop,Derived,ActLaws,Infra nat;
    class Scene2,ImplAct,Terr,Rec,HwSens,Kb wrap;
    class RL,Libs ext;
    class GenesisSim sim;

The table below lists the exact packages in each bucket.

Three categories

Category Packages What it means
Wraps Genesis scene, entity, actuator.implicit_pd / mujoco_style, terrains, recording, hardware sensors (camera, mesh_ray_cast, tactile_*, proximity, temperature, kinematic_contact), bridges.keyboard a thin layer over gs.* calls
Implemented in GeneLab managers, mdp (+ DR / commands / curricula / metrics), envs step loop, registry / extensions, asset_zoo, cli, utils.math, actuator laws (ideal_pd, dc_motor, mlp_residual), derived sensors (contact, self_contact, ray_cast, terrain_height, body_velocity, angular_momentum, frame_transformer) logic lives in GeneLab, no gs.* calls
Wraps external RL libs rl (runner, backends, vecenvs, eval_task, benchmark, exporter) targets rsl_rl / skrl / sb3 / gymnasium — no Genesis dependency

Derived sensors are dual: they read Genesis raw data (contact forces, link state) but compute their output (air-time state machines, orbital angular momentum, body-frame velocities) in GeneLab.

Terrain

Complex terrain is generated by Genesis, not by GeneLab. gs.morphs.Terrain synthesises the procedural heightfield (stairs, slopes, rough, obstacles, stepping-stones, fractal — Genesis reuses the IsaacGym terrain algorithms). GeneLab only orchestrates around it:

  • terrains/generator.py — decides which sub-terrain goes in which grid cell and the difficulty curriculum (easy → hard by row); emits the kwargs for gs.morphs.Terrain.
  • terrains/importer.py — hands the layout to Genesis and reads the heightfield back for sensor sampling.
  • terrains/sub_terrain.py — per-sub-terrain parameter configs.

So GeneLab owns the layout + curriculum; Genesis owns the heightfield synthesis.

See also