# API Reference

Complete API reference for GenesisLab.

```{toctree}
:maxdepth: 2

engine/index
managers/index
components/index
envs/index
utils/index
```

## Module Overview

### Engine ([genesislab.engine](engine/index.md))

Core simulation management:
- `LabScene`: Central simulation orchestrator
- Scene builder/controller/querier patterns
- MDP (reset, step) implementation

### Managers ([genesislab.managers](managers/index.md))

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](components/index.md))

Reusable components:
- Sensors (cameras, LiDAR, IMU, etc.)
- Actuators (PD controllers, motor models)
- Terrains (flat, rough, mesh)
- Robots (configurations for various robots)

### Environments ([genesislab.envs](envs/index.md))

Pre-built Gymnasium environments:
- Quadruped locomotion
- Humanoid locomotion
- Custom task registration

### Utilities ([genesislab.utils](utils/index.md))

Helper functions and utilities:
- Configuration system (`@configclass`)
- Math utilities
- Timing and profiling
- I/O utilities

## Quick Reference

### Creating a Task

```python
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

```python
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

```python
from genesislab.managers import RewardTermCfg

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

### Defining Actions

```python
from genesislab.managers import ActionTermCfg

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

## Common Patterns

### Accessing Scene Data

```python
# 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:

```python
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

```python
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:

```python
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

- Browse [Engine API](engine/index.md)
- Explore [Manager API](managers/index.md)
- Check [Component API](components/index.md)
- See [Environment API](envs/index.md)