mjlab

https://mujocolab.github.io/mjlab/main/
Admin
mjlab is a lightweight, GPU-accelerated framework for robot learning that combines composable...
Tokens:50,146
Snippets:629
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Verify mjlab installation

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Run the demo to verify that the installation is successful.

```bash
uv run demo
```

```bash
demo
```

--------------------------------

### Install and Login to Weights & Biases

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Installs the wandb CLI and authenticates the user session.

```bash
uv tool install wandb
wandb login
```

--------------------------------

### Run mjlab demo

Source: https://mujocolab.github.io/mjlab/main/index.html

Execute the mjlab demo directly without a full installation.

```bash
uvx --from mjlab --refresh demo
```

--------------------------------

### Install uv

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Install the uv package manager if it is not already present on your system.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install via pip

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Install mjlab using classic pip in an activated virtual environment.

```bash
pip install mjlab
```

--------------------------------

### Specify GPU resources

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Examples of requesting different GPU types and counts during task launch.

```bash
sky launch scripts/cloud/train.yaml --gpus H100:1    # 1x H100
sky launch scripts/cloud/train.yaml --gpus A100:8    # 8x A100
sky launch scripts/cloud/train.yaml --gpus A10:1     # 1x A10 (cheaper)
```

--------------------------------

### Install SkyPilot CLI

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Installs the SkyPilot CLI tool with Lambda support as a standalone tool.

```bash
uv tool install "skypilot[lambda]"
```

--------------------------------

### Example Logged Metric Keys

Source: https://mujocolab.github.io/mjlab/main/source/metrics.html

Example of how metrics appear in the training logger under the Episode_Metrics prefix.

```text
Episode_Metrics/base_height
Episode_Metrics/contact_force
```

--------------------------------

### Launch a training run

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

Basic command to start a training session with a specified environment and number of parallel environments.

```bash
uv run train Mjlab-Velocity-Flat-Unitree-G1 --num-envs 4096
```

--------------------------------

### Verify SkyPilot Lambda Setup

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Checks if the Lambda cloud provider is correctly enabled in SkyPilot.

```bash
sky check lambda
```

--------------------------------

### Configure Action Clipping

Source: https://mujocolab.github.io/mjlab/main/source/actions.html

Example of applying per-actuator clipping constraints to an action configuration.

```python
JointPositionActionCfg(
    entity_name="robot",
    actuator_names=(".*",),
    scale=0.5,
    clip={".*_hip_.*": (-1.0, 1.0), ".*_knee_.*": (-0.5, 2.0)},
)
```

--------------------------------

### Configure ray alignment

Source: https://mujocolab.github.io/mjlab/main/source/sensors/raycast_sensor.html

Example configuration for a raycast sensor using yaw-based alignment.

```python
RayCastSensorCfg(
    name="height_scan",
    frame=ObjRef(type="body", name="base", entity="robot"),
    pattern=GridPatternCfg(size=(1.0, 1.0), resolution=0.1),
    ray_alignment="yaw",
)
```

--------------------------------

### Add mjlab as a dependency

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Add mjlab to your project using different installation sources.

```bash
uv add mjlab
```

```bash
uv add "mjlab @ git+https://github.com/mujocolab/mjlab"
```

```bash
git clone https://github.com/mujocolab/mjlab.git
```

```bash
uv add --editable /path/to/cloned/mjlab
```

--------------------------------

### Configure BuiltinSensor instances

Source: https://mujocolab.github.io/mjlab/main/source/sensors/index.html

Examples of configuring various sensor types including accelerometers, joint limits, and relative frame positions using BuiltinSensorCfg.

```python
from mjlab.sensor import BuiltinSensorCfg, ObjRef

# Accelerometer attached to a site.
BuiltinSensorCfg(
    name="imu_acc",
    sensor_type="accelerometer",
    obj=ObjRef(type="site", name="imu_site", entity="robot"),
)

# Joint limit sensor with output clamping.
BuiltinSensorCfg(
    name="knee_limit",
    sensor_type="jointlimitpos",
    obj=ObjRef(type="joint", name="knee_joint", entity="robot"),
    cutoff=0.1,
)

# Relative frame position (end-effector w.r.t. base).
BuiltinSensorCfg(
    name="ee_pos",
    sensor_type="framepos",
    obj=ObjRef(type="body", name="end_effector", entity="robot"),
    ref=ObjRef(type="body", name="base", entity="robot"),
)
```

--------------------------------

### Registering Multiple Action Terms

Source: https://mujocolab.github.io/mjlab/main/source/actions.html

Example of defining a dictionary of action configurations for different joint groups in the environment.

```python
from mjlab.envs.mdp.actions import (
    JointPositionActionCfg,
    JointVelocityActionCfg,
)

actions = {
    "arm_joints": JointPositionActionCfg(
        entity_name="robot",
        actuator_names=(".*_arm_.*",),
        scale=0.5,
    ),
    "wheel_joints": JointVelocityActionCfg(
        entity_name="robot",
        actuator_names=(".*_wheel_.*",),
        scale=10.0,
    ),
}
```

--------------------------------

### Calculate environment timing parameters

Source: https://mujocolab.github.io/mjlab/main/source/environment_config.html

Example calculation for determining physics frequency, policy frequency, and total episode steps based on timestep and decimation.

```python
physics_dt  = 0.005        # seconds per physics step (200 Hz)
decimation  = 4            # physics steps per policy step
step_dt     = 0.005 * 4   # = 0.02 s per policy step (50 Hz)
episode_len = 20.0 / 0.02  # = 1000 policy steps per episode
```

--------------------------------

### Launch Hyperparameter Sweep via Script

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Executes the convenience script to provision a cluster and start agents across all available GPUs.

```bash
./scripts/cloud/sweep-launch.sh A100:8   # 8 agents on an 8xA100
```

--------------------------------

### Implement Function-based vs Class-based Terms

Source: https://mujocolab.github.io/mjlab/main/source/environment_config.html

Demonstrates the difference between stateless function-based terms and stateful class-based terms for caching setup.

```python
# Function-based (stateless)
RewardTermCfg(func=mdp.joint_torques_l2, weight=-0.01)

# Class-based (caches joint indices at init)
class MyReward:
    def __init__(self, cfg, env):
        self.joint_ids = resolve_joint_ids(cfg.params, env)

    def __call__(self, env) -> torch.Tensor:
        return compute_reward(env, self.joint_ids)

RewardTermCfg(func=MyReward, weight=1.0)
```

--------------------------------

### Install pre-commit hooks

Source: https://mujocolab.github.io/mjlab/main/source/contributing.html

Configures pre-commit hooks to ensure code quality and formatting standards are met before committing.

```bash
uvx pre-commit install
```

--------------------------------

### Configure Built-in Actuators

Source: https://mujocolab.github.io/mjlab/main/source/actuators.html

Example of configuring position and velocity actuators for a mobile manipulator using built-in MuJoCo types.

```python
from mjlab.actuator import BuiltinPositionActuatorCfg, BuiltinVelocityActuatorCfg

# Mobile manipulator: PD for arm joints, velocity control for wheels.
actuators = (
    BuiltinPositionActuatorCfg(
        target_names_expr=(".*_shoulder_.*", ".*_elbow_.*", ".*_wrist_.*"),
        stiffness=100.0,
        damping=10.0,
        effort_limit=150.0,
    ),
    BuiltinVelocityActuatorCfg(
        target_names_expr=(".*_wheel_.*",),
        damping=20.0,
        effort_limit=50.0,
    ),
)
```

--------------------------------

### Define sensor frame attachment

Source: https://mujocolab.github.io/mjlab/main/source/sensors/raycast_sensor.html

Examples of defining the sensor frame using body, site, or geom references.

```python
frame = ObjRef(type="body", name="base", entity="robot")
frame = ObjRef(type="site", name="scan_site", entity="robot")
frame = ObjRef(type="geom", name="sensor_mount", entity="robot")
```

--------------------------------

### Exporting Scenes via Command Line

Source: https://mujocolab.github.io/mjlab/main/source/debugging/export_scene.html

Examples of using the export-scene script to export built-in entities, registered tasks, custom entities, or compressed archives.

```bash
# Export a built-in entity by alias.
uv run export-scene g1 --output-dir /tmp/g1

# Export a registered task scene.
uv run export-scene Mjlab-Velocity-Flat-Unitree-Go1 --output-dir /tmp/task

# Export as a zip archive.
uv run export-scene yam --output-dir /tmp/yam --zip True

# Export a custom entity via import path.
uv run export-scene my_pkg.robots:get_my_robot_cfg --output-dir /tmp/custom
```

--------------------------------

### Wrap Existing XML Actuators

Source: https://mujocolab.github.io/mjlab/main/source/actuators.html

Example of using XmlActuatorCfg to interface with actuators already defined in the robot's XML file.

```python
from mjlab.actuator import XmlActuatorCfg

# Robot XML already has:
# <actuator>
#   <position name="hip_joint" joint="hip_joint" kp="100"/>
# </actuator>

# Wrap existing XML actuators.
actuators = (
    XmlActuatorCfg(target_names_expr=("hip_joint",)),
)
```

--------------------------------

### Configure Explicit Actuators

Source: https://mujocolab.github.io/mjlab/main/source/actuators.html

Example of using Ideal PD and DC Motor models to control robot joints with specific torque-speed characteristics.

```python
from mjlab.actuator import IdealPdActuatorCfg, DcMotorActuatorCfg

# Ideal PD for hips, DC motor model with torque-speed curve for knees.
actuators = (
    IdealPdActuatorCfg(
        target_names_expr=(".*_hip_.*",),
        stiffness=80.0,
        damping=10.0,
        effort_limit=100.0,
    ),
    DcMotorActuatorCfg(
        target_names_expr=(".*_knee_.*",),
        stiffness=80.0,
        damping=10.0,
        effort_limit=25.0,       # Continuous torque limit
        saturation_effort=50.0,  # Peak torque at stall
        velocity_limit=30.0,     # No-load speed (rad/s)
    ),
)
```

--------------------------------

### Initialize a uv project

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Create a new Python project managed by uv.

```bash
# Create a new package-based project
uv init --package my_mjlab_project
cd my_mjlab_project
```

--------------------------------

### Build documentation

Source: https://mujocolab.github.io/mjlab/main/source/contributing.html

Commands to build the project documentation locally or enable live reloading.

```bash
make docs
make docs-watch
```

--------------------------------

### Clone and sync dependencies

Source: https://mujocolab.github.io/mjlab/main/source/contributing.html

Initializes the local development environment by cloning the repository and syncing dependencies using uv.

```bash
git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv sync
```

--------------------------------

### Launch training tasks

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Commands to initiate training jobs using standard or Docker-based YAML configurations.

```bash
sky launch scripts/cloud/train.yaml \
  --env TASK=Mjlab-Velocity-Flat-Unitree-G1

# Or with Docker:
sky launch scripts/cloud/train-docker.yaml \
  --env TASK=Mjlab-Velocity-Flat-Unitree-G1
```

--------------------------------

### Initialize and access CameraSensor

Source: https://mujocolab.github.io/mjlab/main/source/sensors/rgbd_camera.html

Demonstrates configuring a camera sensor by wrapping an existing XML camera and accessing the resulting image data at runtime.

```python
from mjlab.sensor import CameraSensorCfg

# Wrap an existing MuJoCo camera from the robot's XML.
cam = CameraSensorCfg(
    name="wrist_cam",
    camera_name="robot/wrist_camera",
    data_types=("rgb", "depth"),
    width=160,
    height=120,
)

scene_cfg = SceneCfg(
    entities={"robot": robot_cfg},
    sensors=(cam,),
)

# Access at runtime.
data = env.scene["wrist_cam"].data
data.rgb      # [B, 120, 160, 3] uint8
data.depth    # [B, 120, 160, 1] float32
```

--------------------------------

### Filter geoms by group

Source: https://mujocolab.github.io/mjlab/main/source/sensors/raycast_sensor.html

Example configuration restricting ray hits to specific geom groups.

```python
RayCastSensorCfg(
    name="terrain_only",
    frame=ObjRef(type="body", name="base", entity="robot"),
    pattern=GridPatternCfg(),
    include_geom_groups=(0, 1),
)
```

--------------------------------

### Launch viewer with dummy policy

Source: https://mujocolab.github.io/mjlab/main/source/viewers.html

Run the viewer without a trained checkpoint by specifying a zero or random agent.

```bash
uv run play Mjlab-Velocity-Flat-Unitree-G1 --agent zero --viewer viser
```

--------------------------------

### Sensor Delay Logic

Source: https://mujocolab.github.io/mjlab/main/source/observations.html

Example of how a 2-step lag affects observation availability at 50Hz control.

```text
50Hz control (20ms/step), lag=2:

Sensor captures:  A     B     C     D     E     F     G     H
Control steps:    0     1     2     3     4     5     6     7

Policy sees:      A     A     A     B     C     D     E     F
                  └clamp┘     └ 40ms delay from here on

Steps 0-1: lag clamped because the buffer is not yet full.
Step 2 onward: each step returns the observation from 2 steps ago.
```

--------------------------------

### Launch viewers via CLI

Source: https://mujocolab.github.io/mjlab/main/source/viewers.html

Use the --viewer flag with the play script to select between native desktop or browser-based Viser viewers.

```bash
# Desktop window (MuJoCo native viewer).
uv run play Mjlab-Velocity-Flat-Unitree-G1 --viewer native \
    --wandb-run-path your-entity/your-project/run_id

# Browser-based viewer (opens localhost:8080).
uv run play Mjlab-Velocity-Flat-Unitree-G1 --viewer viser \
    --wandb-run-path your-entity/your-project/run_id
```

--------------------------------

### Configure Scenes

Source: https://mujocolab.github.io/mjlab/main/source/migration_isaac_lab.html

Compare scene configuration using USD prim paths in Isaac Lab versus direct MuJoCo specification in mjlab.

```python
from whole_body_tracking.robots.g1 import G1_ACTION_SCALE, G1_CYLINDER_CFG
from isaaclab.scene import InteractiveSceneCfg
from isaaclab.sensors import ContactSensorCfg
from isaaclab.terrains import TerrainImporterCfg
import isaaclab.sim as sim_utils
from isaaclab.assets import ArticulationCfg, AssetBaseCfg

@configclass
class MySceneCfg(InteractiveSceneCfg):
    """Configuration for the terrain scene with a legged robot."""

    # ground terrain
    terrain = TerrainEntityCfg(
        prim_path="/World/ground",
        terrain_type="plane",
        collision_group=-1,
        physics_material=sim_utils.RigidBodyMaterialCfg(
            friction_combine_mode="multiply",
            restitution_combine_mode="multiply",
            static_friction=1.0,
            dynamic_friction=1.0,
        ),
        visual_material=sim_utils.MdlFileCfg(
            mdl_path="{NVIDIA_NUCLEUS_DIR}/Materials/Base/Architecture/Shingles_01.mdl",
            project_uvw=True,
        ),
    )
    # lights
    light = AssetBaseCfg(
        prim_path="/World/light",
        spawn=sim_utils.DistantLightCfg(
            color=(0.75, 0.75, 0.75), intensity=3000.0
        ),
    )
    sky_light = AssetBaseCfg(
        prim_path="/World/skyLight",
        spawn=sim_utils.DomeLightCfg(
            color=(0.13, 0.13, 0.13), intensity=1000.0
        ),
    )
    robot = G1_CYLINDER_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot")
```

```python
from dataclasses import replace

from mjlab.scene import SceneCfg
from mjlab.asset_zoo.robots.unitree_g1.g1_constants import get_g1_robot_cfg
from mjlab.utils.spec_config import ContactSensorCfg
from mjlab.terrains import TerrainEntityCfg

# Configure contact sensor
self_collision_sensor = ContactSensorCfg(
    name="self_collision",
    subtree1="pelvis",
    subtree2="pelvis",
    data=("found",),
    reduce="netforce",
    num=10,  # report up to 10 contacts
)

# Add sensor to robot config
g1_cfg = replace(get_g1_robot_cfg(), sensors=(self_collision_sensor,))

# Create scene
SCENE_CFG = SceneCfg(
    terrain=TerrainEntityCfg(terrain_type="plane"),
    entities={"robot": g1_cfg},
)
```

--------------------------------

### Define Joint Position Action

Source: https://mujocolab.github.io/mjlab/main/source/actions.html

Example of configuring a joint position action term using JointPositionActionCfg.

```python
from mjlab.envs.mdp.actions import JointPositionActionCfg

actions = {
    "joint_pos": JointPositionActionCfg(
        entity_name="robot",
        actuator_names=(".*",),   # regex matching actuator names
        scale=0.5,
        use_default_offset=True,  # action 0 = default pose
    ),
}
```

--------------------------------

### Run mjlab with Docker

Source: https://mujocolab.github.io/mjlab/main/source/installation.html

Execute the demo using pre-built images or local build scripts.

```bash
docker run --rm --runtime=nvidia --gpus all \
  ghcr.io/mujocolab/mjlab uv run demo
```

```bash
./scripts/run_docker.sh uv run demo
```

--------------------------------

### Define spec_fn callables

Source: https://mujocolab.github.io/mjlab/main/source/entity/index.html

Examples of defining spec_fn using lambdas or regular functions to load MuJoCo specifications.

```python
spec_fn = lambda: mujoco.MjSpec.from_file("robot.xml")
```

```python
def get_spec() -> mujoco.MjSpec:
    return mujoco.MjSpec.from_file(str(ROBOT_XML))
```

--------------------------------

### Configure and access sensors

Source: https://mujocolab.github.io/mjlab/main/source/sensors/index.html

Demonstrates defining built-in and contact sensors within a SceneCfg and accessing their data at runtime.

```python
from mjlab.sensor import (
    BuiltinSensorCfg, ContactSensorCfg, ContactMatch, ObjRef,
)

# A robot with an IMU accelerometer and foot contact detection.
scene_cfg = SceneCfg(
    entities={"robot": robot_cfg},
    sensors=(
        BuiltinSensorCfg(
            name="imu_acc",
            sensor_type="accelerometer",
            obj=ObjRef(type="site", name="imu_site", entity="robot"),
        ),
        ContactSensorCfg(
            name="feet_contact",
            primary=ContactMatch(
                mode="geom", pattern=r".*_foot$", entity="robot",
            ),
            secondary=ContactMatch(mode="body", pattern="terrain"),
            fields=("found", "force"),
        ),
    ),
)

# Access at runtime.
imu = env.scene["robot/imu_acc"].data        # [B, 3] acceleration
feet = env.scene["feet_contact"].data         # ContactData
feet.found                                    # [B, P] contact count per foot
feet.force                                    # [B, P, 3] contact force per foot
```

--------------------------------

### Configure Lambda Cloud API Key

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Creates the configuration directory and file for Lambda Cloud API authentication.

```bash
mkdir -p ~/.lambda_cloud && chmod 700 ~/.lambda_cloud
echo "api_key = <your-api-key>" > ~/.lambda_cloud/lambda_keys
chmod 600 ~/.lambda_cloud/lambda_keys
```

--------------------------------

### Mesh Variant Body Structure Example

Source: https://mujocolab.github.io/mjlab/main/source/entity/per_world_mesh.html

Visual representation of how mesh geoms are structured across different variants for a single body.

```text
sphere variant body              cone variant body
-------------------              -------------------
prop body                        prop body
  [visual] sphere_vis              [visual] cone_vis
  [coll]   sphere_col_0            [coll]   cone_col_0
  [coll]   sphere_col_1            [coll]   cone_col_1
                                   [coll]   cone_col_2
                                   [coll]   cone_col_3
```

--------------------------------

### Execute Jobs on Existing Clusters

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Rerun jobs on an existing cluster after local code fixes without re-running the setup phase.

```bash
sky exec sky-<cluster-name> scripts/cloud/train.yaml
```

--------------------------------

### Manual Hyperparameter Sweep Execution

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Step-by-step commands to create a W&B sweep, provision a SkyPilot cluster, and submit individual agents to GPUs.

```bash
# 1. Create the sweep (returns a SWEEP_ID).
wandb sweep scripts/cloud/sweep.yaml

# 2. Provision the cluster (runs setup, no agents yet).
sky launch scripts/cloud/sweep-cluster.yaml \
  -c mjlab-sweep --gpus A100:8

# 3. Submit one agent per GPU.
sky exec mjlab-sweep scripts/cloud/sweep-agent.yaml \
  --gpus A100:1 --env SWEEP_ID=<entity/project/sweep_id> -d
```

--------------------------------

### Configure Cartpole Reset Events

Source: https://mujocolab.github.io/mjlab/main/source/tutorials/cartpole.html

Specifies reset events to randomize joint positions and velocities for the slider and hinge at the start of each episode.

```python
events = {
    "reset_slider": EventTermCfg(
        func=reset_joints_by_offset,
        mode="reset",
        params={
            "position_range": (-0.1, 0.1),
            "velocity_range": (-0.01, 0.01),
            "asset_cfg": SceneEntityCfg("cartpole", joint_names=("slider",)),
        },
    ),
    "reset_hinge": EventTermCfg(
        func=reset_joints_by_offset,
        mode="reset",
        params={
            "position_range": (-0.034, 0.034),
            "velocity_range": (-0.01, 0.01),
            "asset_cfg": SceneEntityCfg("cartpole", joint_names=("hinge_1",)),
        },
    ),
}
```

--------------------------------

### Bundle Entity Configuration

Source: https://mujocolab.github.io/mjlab/main/source/tutorials/cartpole.html

Assemble the spec loader, articulation, and initial state into a single EntityCfg.

```python
# Bundle the spec loader, actuator, and initial state into one config.
def _get_cartpole_cfg(swing_up: bool = False) -> EntityCfg:
    return EntityCfg(
        spec_fn=_get_spec,
        articulation=_CARTPOLE_ARTICULATION,
        init_state=_SWINGUP_INIT if swing_up else _BALANCE_INIT,
    )
```

--------------------------------

### Configure Pseudo-inertia Randomization

Source: https://mujocolab.github.io/mjlab/main/source/randomization.html

Examples of configuring isotropic mass scaling and anisotropic stretching using the dr.pseudo_inertia function within an event configuration dictionary.

```python
events = {
    # Isotropic mass scaling + small COM variation.
    "body_inertia_dr": EventTermCfg(
        mode="reset",
        func=dr.pseudo_inertia,
        params={
            "asset_cfg": SceneEntityCfg("robot", body_names=["torso"]),
            "alpha_range": (-0.1, 0.1),   # ±10% mass/inertia scaling
            "t_range": (-0.02, 0.02),     # ±2 cm COM shift
        },
    ),
    # Anisotropic stretching (x stiffer than y/z).
    "body_inertia_aniso_dr": EventTermCfg(
        mode="startup",
        func=dr.pseudo_inertia,
        params={
            "asset_cfg": SceneEntityCfg("robot", body_names=[".*"]),
            "alpha_range": (-0.2, 0.2),
            "d1_range": (-0.1, 0.1),
            "d2_range": (-0.3, 0.3),
            "d3_range": (-0.3, 0.3),
        },
    ),
}
```

--------------------------------

### Playback a trained policy

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

Commands to run a policy using either a W&B run path or a local checkpoint file.

```bash
# From W&B.
uv run play Mjlab-Velocity-Flat-Unitree-G1 \
    --wandb-run-path your-entity/mjlab/run-id

# From a local checkpoint.
uv run play Mjlab-Velocity-Flat-Unitree-G1 \
    --checkpoint-file logs/rsl_rl/g1_velocity/2025-01-27_14-30-00/model_1000.pt
```

--------------------------------

### load_rl_cfg()

Source: https://mujocolab.github.io/mjlab/main/source/api/tasks.html

Loads the reinforcement learning configuration.

```APIDOC
## load_rl_cfg()

### Description
Loads the reinforcement learning configuration.
```

--------------------------------

### Implement a custom event term using a class

Source: https://mujocolab.github.io/mjlab/main/source/events.html

Use a class-based approach for event terms that require expensive setup, such as loading datasets, to ensure initialization occurs only once.

```python
import torch
from mjlab.managers.manager_base import ManagerTermBase
from mjlab.managers.scene_entity_config import SceneEntityCfg

class ResetFromDataset(ManagerTermBase):
    """Reset the robot to a random pose from a dataset."""

    def __init__(self, cfg, env):
        super().__init__(env)
        self._robot = env.scene["robot"]
        self._poses = torch.load(
            cfg.params["dataset_path"],
            map_location=env.device,
        )

    def __call__(self, env, env_ids, **kwargs):
        # Sample with replacement: each env gets an independent pose.
        indices = torch.randint(
            len(self._poses), (len(env_ids),), device=env.device,
        )
        self._robot.write_joint_position_to_sim(
            self._poses[indices], env_ids=env_ids,
        )
```

--------------------------------

### Makefile development commands

Source: https://mujocolab.github.io/mjlab/main/source/contributing.html

Common shortcuts for formatting, type checking, and testing the project.

```makefile
make format      # Format code and fix lint errors (ruff)
make type        # Type check (ty + pyright)
make check       # Format + type check
make test-fast   # Run tests, excluding slow ones
make test        # Run the full test suite
make test-all    # Format + type check + full test suite
```

--------------------------------

### load_env_cfg()

Source: https://mujocolab.github.io/mjlab/main/source/api/tasks.html

Loads the environment configuration.

```APIDOC
## load_env_cfg()

### Description
Loads the environment configuration.
```

--------------------------------

### Configure initial state

Source: https://mujocolab.github.io/mjlab/main/source/entity/index.html

Setting root pose and joint positions using regex patterns for joint mapping.

```python
init_state = EntityCfg.InitialStateCfg(
    pos=(0.0, 0.0, 0.8),       # root position
    rot=(1.0, 0.0, 0.0, 0.0),  # root quaternion (w, x, y, z)
    joint_pos={
        ".*": 0.0,              # all joints to zero
        ".*_hip_.*": 0.5,       # then override hips to 0.5
    },
)
```

--------------------------------

### Run custom tasks

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Command to launch a specific task using the training YAML.

```bash
sky launch scripts/cloud/train.yaml \
  --env TASK=Mjlab-Velocity-Flat-Unitree-Go1
```

--------------------------------

### Configure a basic scene

Source: https://mujocolab.github.io/mjlab/main/source/scene.html

Define a scene with a robot on a flat ground plane for parallel environments.

```python
from mjlab.scene import SceneCfg
from mjlab.terrains import TerrainEntityCfg

# A robot on a flat ground plane with 4096 parallel environments.
scene_cfg = SceneCfg(
    num_envs=4096,
    env_spacing=2.5,
    terrain=TerrainEntityCfg(terrain_type="plane"),
    entities={"robot": robot_cfg},
)
```

--------------------------------

### Configure and access TerrainHeightSensor data

Source: https://mujocolab.github.io/mjlab/main/source/sensors/raycast_sensor.html

Sets up a TerrainHeightSensor for foot clearance and demonstrates how to access the resulting height and distance data at runtime.

```python
from mjlab.sensor import TerrainHeightSensorCfg, RingPatternCfg, ObjRef

cfg = TerrainHeightSensorCfg(
    name="foot_height",
    frame=(
        ObjRef(type="site", name="left_foot", entity="robot"),
        ObjRef(type="site", name="right_foot", entity="robot"),
    ),
    pattern=RingPatternCfg.single_ring(radius=0.04, num_samples=4),
    max_distance=1.0,
    include_geom_groups=(0,),
)

# At runtime:
sensor = env.scene["foot_height"]
sensor.data.heights    # [B, F] vertical clearance per foot
sensor.data.distances  # [B, N] raw ray distances (inherited)
```

--------------------------------

### Create a new camera programmatically

Source: https://mujocolab.github.io/mjlab/main/source/sensors/rgbd_camera.html

Configures a new camera sensor by specifying position, orientation, and field of view parameters directly.

```python
# Fixed overhead camera on the worldbody.
CameraSensorCfg(
    name="overhead",
    pos=(0.0, 0.0, 2.0),
    quat=(0.0, 0.707, 0.707, 0.0),
    fovy=60.0,
    width=320,
    height=240,
    data_types=("rgb", "depth"),
)
```

--------------------------------

### Configure GPU usage for training

Source: https://mujocolab.github.io/mjlab/main/source/training/distributed_training.html

Commands to specify GPU allocation for training tasks using the uv run interface.

```bash
# Single GPU (default).
uv run train <task-name> --gpu-ids "[0]"

# Two GPUs.
uv run train <task-name> --gpu-ids "[0, 1]"

# All available GPUs.
uv run train <task-name> --gpu-ids all

# CPU mode.
uv run train <task-name> --gpu-ids None
```

--------------------------------

### Train the Cartpole task

Source: https://mujocolab.github.io/mjlab/main/source/tutorials/cartpole.html

Launch the training process using the registered task ID and specify the number of environments.

```bash
uv run train Mjlab-Cartpole-Swingup --env.scene.num-envs 4096
```

--------------------------------

### Discover CLI flags

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

Commands to list all available configuration flags or search for specific fields using grep.

```bash
# See all flags.
uv run train Mjlab-Velocity-Flat-Unitree-G1 --help

# Search for a specific field.
uv run train Mjlab-Velocity-Flat-Unitree-G1 --help | grep learning-rate
```

--------------------------------

### Configure RSL-RL PPO Runner

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

Defines the training configuration including model architecture and PPO hyperparameters for the Unitree G1 velocity task.

```python
from mjlab.rl import (
    RslRlModelCfg,
    RslRlOnPolicyRunnerCfg,
    RslRlPpoAlgorithmCfg,
)

def unitree_g1_ppo_runner_cfg() -> RslRlOnPolicyRunnerCfg:
    return RslRlOnPolicyRunnerCfg(
        actor=RslRlModelCfg(
            hidden_dims=(512, 256, 128),
            activation="elu",
            obs_normalization=True,
        ),
        critic=RslRlModelCfg(
            hidden_dims=(512, 256, 128),
            activation="elu",
            obs_normalization=True,
        ),
        algorithm=RslRlPpoAlgorithmCfg(
            value_loss_coef=1.0,
            use_clipped_value_loss=True,
            clip_param=0.2,
            entropy_coef=0.01,
            num_learning_epochs=5,
            num_mini_batches=4,
            learning_rate=1.0e-3,
            schedule="adaptive",
            gamma=0.99,
            lam=0.95,
            desired_kl=0.01,
            max_grad_norm=1.0,
        ),
        experiment_name="g1_velocity",
        save_interval=50,
        num_steps_per_env=24,
        max_iterations=30_000,
    )
```

--------------------------------

### List available GPUs

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Command to view available GPU resources on the Lambda infrastructure.

```bash
sky show-gpus --infra lambda
```

--------------------------------

### Import Environment Classes

Source: https://mujocolab.github.io/mjlab/main/source/migration_isaac_lab.html

Compare the import paths for environment base classes between Isaac Lab and mjlab.

```python
from isaaclab.envs import ManagerBasedRLEnv
```

```python
from mjlab.envs import ManagerBasedRlEnvCfg
```

--------------------------------

### Training Artifact Directory Structure

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

The default directory structure for training logs, policy checkpoints, and configuration files.

```text
logs/rsl_rl/{experiment_name}/{timestamp}/
    model_{iteration}.pt      # policy checkpoints
    params/
        env.yaml              # full environment config
        agent.yaml            # full runner config
```

--------------------------------

### Resume Training from Local Checkpoint

Source: https://mujocolab.github.io/mjlab/main/source/training/rsl_rl.html

Command to resume training from the most recent local checkpoint.

```bash
uv run train Mjlab-Velocity-Flat-Unitree-G1 \
    --num-envs 4096 \
    --agent.resume True
```

--------------------------------

### Record video with OffscreenRenderer

Source: https://mujocolab.github.io/mjlab/main/source/viewers.html

Use the play script with the --video flag to trigger offscreen rendering for video generation.

```bash
uv run play Mjlab-Velocity-Flat-Unitree-G1 --video --video-length 300 \
    --wandb-run-path your-entity/your-project/run_id
```

--------------------------------

### List registered tasks

Source: https://mujocolab.github.io/mjlab/main/source/training/cloud.html

Commands to list available tasks, with optional keyword filtering.

```bash
uv run list-envs
uv run list-envs --keyword Velocity  # filter by keyword
```
Tokens:
Raw