API Reference#

Complete API reference for GenesisLab.

Module Overview#

Engine (genesislab.engine)#

Core simulation management:

  • LabScene: Central simulation orchestrator

  • Scene builder/controller/querier patterns

  • MDP (reset, step) implementation

Managers (genesislab.managers)#

Specialized manager components:

  • ObservationManager: Observation computation

  • ActionManager: Action processing

  • RewardManager: Reward calculation

  • CommandManager: Command generation

  • TerminationManager: Termination checking

  • CurriculumManager: Training curriculum

  • EventManager: Domain randomization

  • ObjectManager: Object management

Components (genesislab.components)#

Reusable components:

  • Sensors (cameras, LiDAR, IMU, etc.)

  • Actuators (PD controllers, motor models)

  • Terrains (flat, rough, mesh)

  • Robots (configurations for various robots)

Environments (genesislab.envs)#

Pre-built Gymnasium environments:

  • Quadruped locomotion

  • Humanoid locomotion

  • Custom task registration

Utilities (genesislab.utils)#

Helper functions and utilities:

  • Configuration system (@configclass)

  • Math utilities

  • Timing and profiling

  • I/O utilities

Quick Reference#

Creating a Task#

from genesislab.tasks import LocomotionTask

class MyTask(LocomotionTask):
    cfg: MyTaskCfg
    
    def setup_scene(self):
        # Build scene
        pass
    
    def setup_managers(self):
        # Configure managers
        pass

Defining Observations#

from genesislab.managers import ObservationTermCfg

@configclass
class MyObservationsCfg:
    base_lin_vel = ObservationTermCfg(
        func=observations.base_lin_vel,
        noise=UniformNoiseCfg(min=-0.1, max=0.1)
    )

Defining Rewards#

from genesislab.managers import RewardTermCfg

@configclass
class MyRewardsCfg:
    forward_vel = RewardTermCfg(
        func=rewards.forward_velocity,
        weight=1.0
    )

Defining Actions#

from genesislab.managers import ActionTermCfg

@configclass
class MyActionsCfg:
    joint_pos = ActionTermCfg(
        func=actions.joint_position_action,
        scale=0.25
    )

Common Patterns#

Accessing Scene Data#

# In an observation/reward function
def my_function(scene: LabScene) -> torch.Tensor:
    # Query robot state
    joint_pos = scene.robot.get_joint_positions()
    joint_vel = scene.robot.get_joint_velocities()
    base_pos = scene.robot.get_base_position()
    
    # Access sensor data
    if hasattr(scene, 'imu'):
        imu_data = scene.imu.get_data()
    
    # Compute and return
    return compute_result(joint_pos, joint_vel)

Manager Term Structure#

All manager terms follow this pattern:

def term_function(
    scene: LabScene,
    param1: float = default_value,
    param2: str = "default"
) -> torch.Tensor:
    """
    Compute the term value.
    
    Args:
        scene: The simulation scene
        param1: Description of parameter 1
        param2: Description of parameter 2
        
    Returns:
        Tensor of shape [num_envs] or [num_envs, dim]
    """
    # Implementation
    return result

# Configuration
@configclass
class TermCfg:
    func: Callable = term_function
    params: dict = field(default_factory=lambda: {
        "param1": 1.0,
        "param2": "value"
    })

Configuration Pattern#

from genesislab.utils.configclass import configclass
from dataclasses import field

@configclass
class MyConfig:
    # Basic types
    name: str = "default"
    value: float = 1.0
    count: int = 10
    enabled: bool = True
    
    # Collections
    values: list[float] = field(default_factory=lambda: [1.0, 2.0, 3.0])
    mapping: dict = field(default_factory=dict)
    
    # Nested configs
    sub_config: SubConfig = SubConfig()

Type Hints#

Common type hints used throughout GenesisLab:

from typing import Callable, Any
import torch
import numpy as np
import genesis as gs

# Common types
ObsDict = dict[str, torch.Tensor]
RewardDict = dict[str, torch.Tensor]
ActionArray = np.ndarray | torch.Tensor

# Function signatures
ObservationFunc = Callable[[LabScene], torch.Tensor]
RewardFunc = Callable[[LabScene, ...], torch.Tensor]
ActionFunc = Callable[[LabScene, torch.Tensor], None]

Conventions#

Naming#

  • Classes: PascalCase (e.g., ObservationManager)

  • Functions: snake_case (e.g., compute_reward)

  • Constants: UPPER_CASE (e.g., MAX_EPISODE_LENGTH)

  • Private: Leading underscore (e.g., _internal_function)

Tensor Shapes#

  • Observations: [num_envs, obs_dim]

  • Actions: [num_envs, action_dim]

  • Rewards: [num_envs]

  • Terminations: [num_envs] (boolean)

  • Commands: [num_envs, cmd_dim]

Units#

  • Distance: meters (m)

  • Angle: radians (rad)

  • Time: seconds (s)

  • Velocity: meters/second (m/s)

  • Angular velocity: radians/second (rad/s)

  • Force: Newtons (N)

  • Torque: Newton-meters (Nm)

Next Steps#