ProtoMotions

https://nvlabs.github.io/ProtoMotions/
Admin
ProtoMotions is a GPU-accelerated simulation and learning framework for training physically...
Tokens:256,845
Snippets:1,807
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Newton environment

Source: https://nvlabs.github.io/ProtoMotions/getting_started/installation.html

Setup virtual environment and install Newton physics dependencies.

```bash
git clone git@github.com:newton-physics/newton.git
cd newton
git checkout 8a2abf2  # checkout last tested commit
uv venv
source .venv/bin/activate
```

```bash
uv pip install mujoco --pre -f https://py.mujoco.org/
uv pip install warp-lang --pre -U -f https://pypi.nvidia.com/warp-lang/
uv pip install git+https://github.com/google-deepmind/mujoco_warp.git@main
uv pip install -e .[examples]
```

```bash
uv pip install -e /path/to/protomotions
uv pip install -r /path/to/protomotions/requirements_newton.txt
```

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

### Install IsaacLab environment

Source: https://nvlabs.github.io/ProtoMotions/getting_started/installation.html

Setup virtual environment using uv and install IsaacLab dependencies.

```bash
uv venv --python 3.11 env_isaaclab
source env_isaaclab/bin/activate
```

```bash
uv pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
uv pip install isaaclab[isaacsim,all]==2.3.0 --extra-index-url https://pypi.nvidia.com
```

```bash
uv pip install -e /path/to/protomotions
uv pip install -r /path/to/protomotions/requirements_isaaclab.txt
```

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

### Setup Pre-commit Hooks

Source: https://nvlabs.github.io/ProtoMotions/contributing.html

Install and configure pre-commit to automate linting and formatting.

```bash
pip install pre-commit
pre-commit install
```

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

### Model and Optimizer Setup

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/base_agent/agent.html

This section covers the setup of the model and optimizers, including materializing lazy modules and moving the model to the appropriate device.

```APIDOC
## POST /api/setup

### Description
Initializes the model and optimizers. This involves creating the model, moving it to the correct device, materializing any lazy modules through a dummy forward pass, and then creating the optimizers.

### Method
POST

### Endpoint
/api/setup

### Parameters
#### Query Parameters
- **root_dir** (Path) - Optional - The root directory for logging and checkpoints.
- **load_env** (bool) - Optional - Whether to load the environment state from a checkpoint.

### Request Body
This endpoint does not explicitly define a request body in the provided text.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful setup.

#### Response Example
{
  "status": "Setup complete"
}
```

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

### RobotConfig Initialization Example

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/robot_configs/base.html

Example of creating a RobotConfig instance with essential parameters like asset file name and control type. Subclasses should provide robot-specific values.

```python
config = RobotConfig(
            asset=RobotAssetConfig(asset_file_name="robot.xml"),
            control=ControlConfig(control_type=ControlType.BUILT_IN_PD)
        )
```

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

### Install Genesis environment

Source: https://nvlabs.github.io/ProtoMotions/getting_started/installation.html

Setup conda environment and install Genesis dependencies.

```bash
conda create -n genesis python=3.10
conda activate genesis
```

```bash
pip install -e /path/to/protomotions
pip install -r /path/to/protomotions/requirements_genesis.txt
```

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

### Setup Model and Optimizers

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/base_agent/agent.html

Initializes the model, materializes lazy modules, and sets up optimizers.

```python
def setup(self):
        self.fabric.call("on_model_init_start")
        model = self.create_model()

        # Move model to device BEFORE materializing lazy modules
        model = model.to(self.device)
        self.model = model

        # Once model is created, we pass fabric to the RunningMeanStd modules.
        # This allows the modules to internally handle distributed aggregation of normalization moments.
        def pass_fabric_to_running_mean_std(module):
            if isinstance(module, RunningMeanStd):
                module.fabric = self.fabric

        self.model.apply(pass_fabric_to_running_mean_std)

        # Materialize lazy modules (LazyLinear, RunningMeanStd)
        # by running a dummy forward pass before wrapping with DDP
        log.info("Materializing lazy modules...")
        with torch.no_grad():
            dummy_obs = self.env.get_obs()
            dummy_obs = self.add_agent_info_to_obs(dummy_obs)
            dummy_obs_td = self.obs_dict_to_tensordict(dummy_obs)
            _ = self.model(dummy_obs_td)

        self.fabric.call("on_model_init_end")

        self.fabric.call("on_optimizer_init_start")
        self.create_optimizers(model)
        self.fabric.call("on_optimizer_init_end")
```

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

### PPO Agent Initialization and Setup

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/ppo/agent.html

Details the initialization of the PPO agent, including its dependencies on Fabric, environment, and configuration. It also covers the setup of actor and critic networks with separate optimizers.

```APIDOC
## PPO Agent Class

### Description
Implements the Proximal Policy Optimization (PPO) algorithm for training reinforcement learning policies. PPO uses clipped surrogate objectives to enable stable policy updates while maintaining sample efficiency. This implementation supports actor-critic architecture with separate optimizers for policy and value networks.

The agent collects experience through environment interaction, computes advantages using Generalized Advantage Estimation (GAE), and performs multiple epochs of minibatch updates on the collected data.

### Method
`__init__`

### Parameters
- **fabric** (Fabric) - Lightning Fabric instance for distributed training.
- **env** (BaseEnv) - Environment instance to train on.
- **config** (PPOAgentConfig) - PPO-specific configuration including learning rates, clip parameters, etc.
- **root_dir** (Optional[Path]) - Optional root directory for saving outputs.

### Attributes
- **tau** (float) - GAE lambda parameter for advantage estimation.
- **e_clip** (float) - PPO clipping parameter for policy updates.
- **actor** (torch.nn.Module) - Policy network.
- **critic** (torch.nn.Module) - Value network.

### Example
```python
fabric = Fabric(devices=4)
env = Steering(config, robot_config, simulator_config, device)
agent = PPO(fabric, env, config)
agent.setup()
agent.train()
```

## Model Creation and Optimization

### Description
This section covers the methods for creating the PPO actor-critic model and setting up separate optimizers for the policy and value networks. It utilizes `get_class` for dynamic model instantiation and `instantiate` for optimizer creation, integrating with Lightning Fabric for distributed training.

### Method
`create_model`

### Description
Creates the PPO actor-critic model. Instantiates the PPO model with actor and critic networks, applies weight initialization, and returns the model.

### Returns
- **PPOModel** - PPOModel instance with initialized weights.

### Method
`create_optimizers`

### Description
Creates separate optimizers for the actor and critic. Sets up Adam optimizers for policy and value networks with independent learning rates. Uses Fabric for distributed training setup.

### Parameters
- **model** (PPOModel) - PPOModel with actor and critic networks.

```

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

### Install IsaacGym environment

Source: https://nvlabs.github.io/ProtoMotions/getting_started/installation.html

Setup conda environment and install IsaacGym dependencies.

```bash
conda create -n isaacgym python=3.8
conda activate isaacgym
```

```bash
wget https://developer.nvidia.com/isaac-gym-preview-4
tar -xvzf isaac-gym-preview-4
```

```bash
pip install -e isaacgym/python
```

```bash
pip install -e /path/to/protomotions
pip install -r /path/to/protomotions/requirements_isaacgym.txt
```

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

### AMASS Conversion Examples

Source: https://nvlabs.github.io/ProtoMotions/getting_started/amass_preparation.html

Practical examples for creating dataset splits and using SMPL-X humanoid types.

```bash
# Create train/test/validation splits from YAML configs
python data/scripts/convert_amass_to_motionlib.py /path/to/amass_root /path/to/output \
    --motion-config data/yaml_files/amass_smpl_train.yaml \
    --motion-config data/yaml_files/amass_smpl_test.yaml \
    --motion-config data/yaml_files/amass_smpl_validation.yaml

# Use SMPL-X humanoid
python data/scripts/convert_amass_to_motionlib.py /path/to/amass_root /path/to/output \
    --humanoid-type smplx \
    --motion-config data/yaml_files/amass_smplx_train.yaml
```

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

### ASE Agent Setup

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.ase.agent.html

Performs the setup for the ASE agent.

```APIDOC
## Method: setup

### Description
Sets up the ASE agent.

### Endpoint
N/A (Method within a class)
```

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

### Install PyRoki environment

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/retargeting_pyroki.html

Commands to create a dedicated Python environment and install the PyRoki repository.

```bash
# Create a new environment for PyRoki
conda create -n pyroki python=3.10
conda activate pyroki

# Clone and install PyRoki
git clone https://github.com/chungmin99/pyroki.git
cd pyroki
pip install -e .
```

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

### Execute retargeting examples

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/retargeting_pyroki.html

Example commands for running the retargeting script for testing or full processing.

```bash
# Retarget every 50th motion to G1 (for quick testing)
./scripts/retarget_amass_to_robot.sh \
    ~/miniconda3/envs/protomotions/bin/python \
    ~/miniconda3/envs/pyroki/bin/python \
    /path/to/amass_train.pt \
    g1 50

# Retarget all motions to H1_2
./scripts/retarget_amass_to_robot.sh \
    ~/miniconda3/envs/protomotions/bin/python \
    ~/miniconda3/envs/pyroki/bin/python \
    /path/to/amass_train.pt \
    h1_2 1
```

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

### Install MuJoCo environment

Source: https://nvlabs.github.io/ProtoMotions/getting_started/installation.html

Setup conda environment and run inference with MuJoCo.

```bash
conda create -n protomotions_mujoco python=3.10
conda activate protomotions_mujoco
```

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
```

```bash
pip install -e /path/to/protomotions
pip install -r /path/to/protomotions/requirements_mujoco.txt
```

```bash
python protomotions/inference_agent.py \
  --checkpoint results/experiment/last.ckpt \
  --simulator mujoco \
  --num-envs 1
```

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

### Install huggingface_hub

Source: https://nvlabs.github.io/ProtoMotions/getting_started/phuma_preparation.html

Install huggingface_hub to resolve potential errors related to Hugging Face.

```bash
conda install -c conda-forge huggingface_hub
```

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

### Initialize Training and Experience Buffer

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/base_agent/agent.html

Sets up the experience buffer and registers observation and model output keys before starting the training loop.

```python
# Setup experience buffer
self.experience_buffer = ExperienceBuffer(
    self.num_envs, self.num_steps, device=self.device
)

# Get initial observations from environment
obs, _ = self.env.reset()
obs = self.add_agent_info_to_obs(obs)
obs_td = self.obs_dict_to_tensordict(obs)

# Register environment observation keys
for key, env_tensor in obs_td.items():
    shape = env_tensor.shape
    dtype = env_tensor.dtype
    self.experience_buffer.register_key(key, shape=shape[1:], dtype=dtype)

# Auto-register model output keys by running one forward pass
with torch.no_grad():
    output_td = self.model(obs_td)

    # Track which keys are model outputs (not from environment)
    self.model_output_keys = self.model.out_keys
    for key in self.model_output_keys:
        value = output_td[key]
        if isinstance(value, torch.Tensor):
            # Handle both scalar and tensor outputs
            if value.ndim == 1:  # Scalar per env
                self.experience_buffer.register_key(key)
            else:  # Tensor per env
                self.experience_buffer.register_key(
                    key, shape=value.shape[1:], dtype=value.dtype
                )

    log.info(f"Auto-registered model output keys: {self.model_output_keys}")

# Basic keys always needed
self.experience_buffer.register_key("rewards")
if self.config.normalize_rewards:
    self.experience_buffer.register_key("unnormalized_rewards")
self.experience_buffer.register_key("dones", dtype=torch.long)
self.register_algorithm_experience_buffer_keys()
```

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

### MaskedMimic Agent Initialization and Setup

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.masked_mimic.agent.html

This snippet demonstrates how to initialize and set up the MaskedMimic agent, including loading the expert model and preparing the environment.

```APIDOC
## Initialize and Setup MaskedMimic Agent

### Description
Initializes the MaskedMimic agent with a given fabric instance, environment, configuration, and optional root directory. It then sets up the agent for training.

### Method
Constructor and `setup()` method

### Parameters
- **fabric** (MockFabric) - Required - Lightning Fabric instance for distributed training.
- **env** (BaseEnv) - Required - Mimic environment for motion tracking.
- **config** (MaskedMimicAgentConfig) - Required - Configuration for the MaskedMimic agent, including expert model path and masking parameters.
- **root_dir** (Path | None) - Optional - Root directory for saving outputs.

### Request Example
```python
from protomotions.agents.masked_mimic.agent import MaskedMimic
from lightning.fabric import Fabric
# Assuming env, config, device are defined elsewhere

fabric = Fabric(devices=4)
# env = Mimic(config, robot_config, simulator_config, device)
# config.expert_model_path = "results/expert_tracker/"

# agent = MaskedMimic(fabric, env, config)
# agent.setup()
```

### Notes
- Requires a pre-trained expert tracker model specified in `config.expert_model_path`.
```

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

### Hook: Pre-reset Setup

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/evaluators/base_evaluator.html

Hook called before an episode is reset. Override in subclasses for any setup required before resetting environments.

```python
def _on_episode_start(self, env_ids: Tensor) -> None:
    """Hook called before episode reset. Override in subclasses for pre-reset setup.
    
    Args:
        env_ids: Environment IDs about to be reset
    """
    pass
```

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

### General Training Entry Point

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.base_agent.agent.html

The main entry point for training, requiring setup before fitting.

```APIDOC
## fit

### Description
Main entry point for training.
Call setup() before fit().

The loop runs for max_epochs epochs, where each epoch collects num_steps of experience from num_envs parallel environments, then performs multiple optimization steps on the collected data.
```

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

### Initialize and Train an AMP Agent

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/amp/agent.html

Demonstrates the basic setup and training workflow for an AMP agent using Lightning Fabric and a compatible environment.

```python
>>> fabric = Fabric(devices=4)
>>> env = Mimic(config, robot_config, simulator_config, device)
>>> agent = AMP(fabric, env, config)
>>> agent.setup()
>>> agent.train()
```

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

### MotionLib Packaging Output

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/vaulting.html

Example output from the MotionLib packaging process.

```text
Loading 1/1 motion files: examples/data/rigv1-vaulting/proto/generated_vault_over_small_obstacle.motion
Loaded 1 motions with a total length of 2.633s.
Motion library saved to examples/data/rigv1-vaulting/proto.pt
```

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

### AMP Agent Initialization

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.amp.html

Demonstrates how to initialize and start the training process for the Adversarial Motion Priors (AMP) agent.

```APIDOC
## Python Initialization

### Description
Initializes the AMP agent with the provided fabric, environment, and configuration, then triggers the training process.

### Request Example
```python
from protomotions.agents.amp.agent import AMP
agent = AMP(fabric, env, config)
agent.train()
```
```

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

### Initialize and Export Observation Module

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/export_utils.html

Usage example for initializing the ObservationExportModule and exporting it to ONNX.

```python
>>> from protomotions.envs.mdp_component import MdpComponent
>>> from protomotions.envs.context_views import EnvContext
>>> configs = {
...     "max_coords_obs": MdpComponent(
...         compute_func=compute_max_coords,
...         dynamic_vars={"body_pos": EnvContext.current.rigid_body_pos},
...     )
... }
>>> context = env.context
>>> module = ObservationExportModule(configs, context, device)
>>> export_observations(module, context, "observations.onnx")
```

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

### Configuring Observation Components with ContextRouter

Source: https://nvlabs.github.io/ProtoMotions/concepts/environment_context.html

Example of setting up observation components using ContextRouter, demonstrating dynamic bindings to EnvContext properties for type-safe access.

```python
from protomotions.envs.context_views import EnvContext
from protomotions.envs.context_router import ContextRouter
from protomotions.envs.obs import compute_humanoid_max_coords_observations

observation_components = {
    "max_coords_obs": ContextRouter(
        kernel=compute_humanoid_max_coords_observations,
        dynamic_bindings={
            "body_pos": EnvContext.current.rigid_body_pos,     # Type-safe!
            "body_rot": EnvContext.current.rigid_body_rot,
            "body_vel": EnvContext.current.rigid_body_vel,
            "body_ang_vel": EnvContext.current.rigid_body_ang_vel,
            "ground_height": EnvContext.ground_heights,
            "body_contacts": EnvContext.body_contacts,
        },
        static_params={"local_obs": True, "root_height_obs": True, "w_last": True},
    ),
}
```

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

### ContextRouter Usage Example

Source: https://nvlabs.github.io/ProtoMotions/concepts/environment_context.html

Demonstrates how to use ContextRouter with dynamic bindings to observation components, referencing EnvContext fields.

```APIDOC
## Using Context in ContextRouter

### Description
This section illustrates how to configure observation components using `ContextRouter` and `EnvContext` fields, enabling type-safe access to environment data.

### Class Access (for configuration)
Use `EnvContext` with dot notation to get `FieldPath` objects.

```python
# Returns FieldPath objects with .path property
EnvContext.current.rigid_body_pos           # FieldPath("current.rigid_body_pos")
EnvContext.mimic.future_pos                 # FieldPath("mimic.future_pos")
EnvContext.ground_heights                   # FieldPath("ground_heights")
```

### Instance Access (at runtime)
Access the `EnvContext` instance to get actual tensor values.

```python
# Returns actual tensor values
ctx = env.context                           # EnvContext instance
ctx.current.rigid_body_pos                  # Tensor [num_envs, num_bodies, 3]
ctx.mimic.future_pos                        # Tensor [num_envs, future_steps, ...]
```

### In Experiment Configs
Example of defining observation components using `ContextRouter` and `EnvContext` bindings.

```python
from protomotions.envs.context_views import EnvContext
from protomotions.envs.context_router import ContextRouter
from protomotions.envs.obs import compute_humanoid_max_coords_observations

observation_components = {
    "max_coords_obs": ContextRouter(
        kernel=compute_humanoid_max_coords_observations,
        dynamic_bindings={
            "body_pos": EnvContext.current.rigid_body_pos,     # Type-safe!
            "body_rot": EnvContext.current.rigid_body_rot,
            "body_vel": EnvContext.current.rigid_body_vel,
            "body_ang_vel": EnvContext.current.rigid_body_ang_vel,
            "ground_height": EnvContext.ground_heights,
            "body_contacts": EnvContext.body_contacts,
        },
        static_params={"local_obs": True, "root_height_obs": True, "w_last": True},
    ),
}
```
```

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

### Configure Observation Components

Source: https://nvlabs.github.io/ProtoMotions/concepts/abstractions.html

Example configuration for observation components, using factory functions to create pre-configured instances. Imports are necessary for accessing factory functions.

```python
from protomotions.envs.obs import (
    max_coords_obs_factory,
    mimic_target_poses_max_coords_factory,
)

observation_components = {
    "max_coords_obs": max_coords_obs_factory(),
    "target_poses": mimic_target_poses_max_coords_factory(),
}

```

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

### Configure Control Components

Source: https://nvlabs.github.io/ProtoMotions/concepts/abstractions.html

Example configuration for control components, specifying component types and their parameters. Bootstrap on episode end is a common setting for mimic components.

```python
control_components = {
    "mimic": MimicControlConfig(
        bootstrap_on_episode_end=True,
    )
}

```

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

### Run Scene Creation Tutorial

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Executes the scene creation tutorial script.

```bash
python examples/tutorial/3_scene_creation.py --simulator isaacgym --robot smpl
```

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

### Configure and Create Simulator

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Demonstrates robot configuration and simulator instantiation using the factory pattern.

```python
# Robot configuration with per-simulator params
robot_cfg = RobotConfig(
    asset=RobotAssetConfig(asset_file_name="mjcf/g1_bm.xml", ...),
    simulation_params=SimulatorParams(
        isaacgym=IsaacGymSimParams(fps=100, decimation=2, substeps=2),
        isaaclab=IsaacLabSimParams(fps=200, decimation=4),
        ...
    ),
)

# Create simulator via factory
simulator_cfg = simulator_config(args.simulator, robot_cfg, headless=False, num_envs=4)
SimulatorClass = get_class(simulator_cfg._target_)
simulator = SimulatorClass(config=simulator_cfg, robot_config=robot_cfg, ...)
```

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

### Export PPO Actor Network to ONNX

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.utils.export_utils.html

Exports the mean network (mu) of a PPO actor to ONNX format. It uses real observations from the environment for proper tracing. Ensure you have a valid environment and agent setup to get sample observations.

```python
# Get real observations from environment
env.reset()
sample_obs = agent.get_obs()
export_ppo_actor(agent.model._actor, sample_obs, "ppo_actor.onnx")
```

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

### Run Simulator Tutorial

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Executes the simulator creation tutorial script.

```bash
python examples/tutorial/0_create_simulator.py --simulator isaacgym
```

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

### Initialize and train a PPO agent

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.base_agent.html

Demonstrates the basic workflow of importing, setting up, and training a PPO agent.

```python
>>> from protomotions.agents.ppo.agent import PPO
>>> agent = PPO(fabric, env, config)
>>> agent.setup()
>>> agent.train()
```

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

### Initialize and Sample from ReplayBuffer

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.utils.replay_buffer.html

Demonstrates initializing a ReplayBuffer with a specified size and device, storing data, and then sampling transitions. Ensure PyTorch is imported and the device is correctly set.

```python
>>> buffer = ReplayBuffer(buffer_size=10000, device=torch.device("cuda"))
>>> buffer.store({"obs": observations, "actions": actions})
>>> samples = buffer.sample(256)  # Sample 256 transitions
```

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

### Install RoboJuDo

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/g1_deployment.html

Install RoboJuDo using pip and download mesh assets with git lfs.

```bash
pip install -e .
git lfs pull
```

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

### Initialize and Run IsaacGym Simulator

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.simulator.html

Demonstrates the basic workflow of initializing an IsaacGym simulator and executing a control loop.

```python
sim = IsaacGymSimulator(config, robot_config, device=device)
sim.reset()
for _ in range(1000):
    actions = policy(sim.robot_state)
    sim.step(actions)
```

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

### Initialize Smoothness Calculator for Testing

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/evaluators/smoothness_calculator.html

Sets up the SmoothnessCalculator with device, frame rate, and jerk threshold parameters for testing purposes.

```python
if __name__ == "__main__":
    import torch
    import math
    from protomotions.agents.evaluators.smoothness_calculator import SmoothnessCalculator
    from protomotions.agents.evaluators.metrics import MotionMetrics

    device = torch.device("cpu")
    # Use realistic values for testing
    evaluator = SmoothnessCalculator(
        device=device,
        dt=1.0 / 30.0,  # 30 FPS
        window_sec=0.4,  # 0.4s window
        high_jerk_threshold=6500.0,  # FPS-invariant threshold (was 50000 with T^3)
    )

    # Create diverse test data
    num_motions, max_frames, num_bodies = 3, 40, 4
    motion_lens = torch.tensor([40, 35, 30])

    pos_data = torch.zeros(num_motions, max_frames, num_bodies * 3)

    # Motion 0: Very smooth motion
    for t in range(40):
        pos_data[0, t, :] = t * 0.02  # Linear motion
```

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

### Setup MaskedMimic Environment

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/masked_mimic/agent.html

Initializes VAE noise tensors if configured, ensuring they are available for lazy linear layer initialization before the base agent setup.

```python
def setup(self):
    # Initialize VAE noise for each environment.
    # Create vae_noise tensor before super().setup() to ensure it can be used to initialize the lazy linear layers in the model.
    if self.config.model.vae is not None:
        self.vae_noise = torch.zeros(
            self.num_envs,
            self.config.model.vae.vae_latent_dim,
            dtype=torch.float,
            device=self.device,
        )
    super().setup()
```

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

### Initialize and Train PPO Agent

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.ppo.html

Instantiate the PPO agent with fabric, environment, and configuration, then initiate the training process.

```python
>>> from protomotions.agents.ppo.agent import PPO
>>> agent = PPO(fabric, env, config)
>>> agent.train()
```

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

### Start and End Timer within TimeReport

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/utils/metering.html

Use the TimeReport manager to start and end specific timers. Ensure the timer name exists before calling these methods.

```python
time_report.start_timer("data_collection")
# ... do work ...
time_report.end_timer("data_collection")
```

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

### Initialize and Use BaseEnv

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.envs.html

Demonstrates the basic usage of a BaseEnv-derived environment. Requires configuration objects for the environment, robot, and simulator, along with a PyTorch device.

```python
config = SteeringEnvConfig()
env = Steering(config, robot_config, simulator_config, device)
obs, _ = env.reset()
next_obs, rewards, dones, info = env.step(actions)
```

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

### Run Robot Loading Tutorial

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Executes the robot loading tutorial script for different robot types.

```bash
# Load G1 humanoid
python examples/tutorial/2_load_robot.py --simulator isaacgym --robot g1

# Load SMPL humanoid
python examples/tutorial/2_load_robot.py --simulator isaacgym --robot smpl
```

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

### Initialize and Use Timer

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/utils/metering.html

Instantiate a Timer for a named operation, start it, perform work, and then stop it to record elapsed time. Ensure the timer is not already on or not started before calling.

```python
timer = Timer(name="my_operation")
timer.on()
# ... perform operation ...
timer.off()
```

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

### Setup RoboJuDo for ProtoMotions BM Tracker

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/g1_deployment.html

Instructions to set up RoboJuDo by cloning the repository, checking out a compatible commit, and applying the ProtoMotions patch for BM tracker support.

```bash
# 1. Clone RoboJuDo at the compatible commit
git clone https://github.com/hansz8/robojudo.git
cd robojudo
git checkout 1199579188964bf82a90f0f320b4ff781907684b

# 2. Apply the ProtoMotions patch
git am /path/to/protomotions/g1_deploy/robojudo_patch/protomotions-bm-tracker.patch

```

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

### ObservationExportModule.get_output_keys

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/export_utils.html

Get ordered list of output observation names.

```APIDOC
## get_output_keys ObservationExportModule

### Description
Get ordered list of output observation names.

### Returns
- list: Ordered list of output observation names.
```

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

### Get State Dictionary

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/base_agent/agent.html

Collects agent state for checkpointing.

```python
def get_state_dict(self, state_dict):
        """Get complete state dictionary for checkpointing.

        Collects all agent state including model weights, training progress,
        and normalization statistics into a single dictionary for saving.

        Args:
            state_dict: Existing state dict to update (typically empty dict).
```

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

### Initialize and use RunningMeanStd

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.utils.normalization.html

Demonstrates the basic workflow for tracking moments and normalizing observations.

```python
>>> rms = RunningMeanStd(fabric, shape=(128,), device="cuda")
>>> rms.record_moments(observations)
>>> normalized_obs = rms.normalize(new_observations)
```

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

### Initialize Mimic Environment

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.envs.html

Shows how to initialize the Mimic environment for motion imitation tasks. This environment requires specific configuration objects and a PyTorch device.

```python
config = MimicEnvConfig()
env = Mimic(config, robot_config, simulator_config, device)
obs, _ = env.reset()
```

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

### ObservationExportModule.get_input_keys

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/export_utils.html

Get ordered list of input context keys needed.

```APIDOC
## get_input_keys ObservationExportModule

### Description
Get ordered list of input context keys needed.

### Returns
- list: Ordered list of input context keys.
```

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

### Clone the Repository

Source: https://nvlabs.github.io/ProtoMotions/contributing.html

Initial steps to clone the repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/ProtoMotions.git
cd ProtoMotions
```

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

### Get Basis Vector

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/rotations.html

Applies a quaternion rotation to an arbitrary vector.

```APIDOC
## GET_BASIS_VECTOR

### Description
Applies a quaternion rotation to a given vector.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
- **q** (Tensor) - The input quaternion tensor.
- **v** (Tensor) - The vector to rotate.
- **w_last** (bool) - If True, the scalar part (w) is the last element; otherwise, it's the first.

### Response
- **Tensor** - The rotated vector.
```

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

### Get Device

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/utils/step_tracker.html

Retrieves the device on which the StepTracker's buffers are located.

```python
    @property
    def device(self) -> torch.device:
        """Get device from registered buffers."""
        return self.steps.device

```

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

### Run Terrain Tutorial

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Executes the terrain generation tutorial script.

```bash
python examples/tutorial/1_add_terrain.py --simulator isaacgym
```

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

### GET /weights/encoder/final

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/ase/model.html

Retrieves the weight parameter of the final encoder layer.

```APIDOC
## GET /weights/encoder/final

### Description
Returns the weights of the final encoder layer only.

### Method
GET

### Response
#### Success Response (200)
- **weights** (List[nn.Parameter]) - List containing the weight parameter of the encoder's output layer.
```

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

### GET /weights/logits

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/ase/model.html

Retrieves the weight parameter of the final discriminator layer.

```APIDOC
## GET /weights/logits

### Description
Returns the weights of the final discriminator layer (disc_logits).

### Method
GET

### Response
#### Success Response (200)
- **weights** (List[nn.Parameter]) - List containing the weight parameter of the discriminator's output layer.
```

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

### Train Agent Modes

Source: https://nvlabs.github.io/ProtoMotions/user_guide/developer_tips.html

Commands for starting, resuming, or warm-starting training experiments.

```bash
python protomotions/train_agent.py \
    --experiment-name new_experiment \
    ...
```

```bash
# First run
python protomotions/train_agent.py --experiment-name my_exp ...

# Resume (uses saved configs, ignores CLI overrides!)
python protomotions/train_agent.py --experiment-name my_exp ...
```

```bash
python protomotions/train_agent.py \
    --experiment-name new_exp_with_changes \
    --checkpoint results/old_exp/last.ckpt \
    ...
```

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

### Quaternion Axis Extraction

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/rotations.html

Function to get a basis vector after rotation by a quaternion.

```APIDOC
## QUAT_AXIS

### Description
Applies a quaternion rotation to a basis vector.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
- **q** (Tensor) - The input quaternion tensor.
- **axis** (int) - The index of the basis vector to extract (0 for X, 1 for Y, 2 for Z).
- **w_last** (bool) - If True, the scalar part (w) is the last element; otherwise, it's the first.

### Response
- **Tensor** - The rotated basis vector.
```

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

### Initialize Simulator Parameters

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/robot_configs/base.html

Sets up default parameters for various supported simulators.

```python
simulator_params = SimulatorParams()
print(simulator_params.isaacgym)
```

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

### Define Observation Components

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/export_utils.html

Example configuration format for observation components using MdpComponent.

```python
observation_components = {
    "max_coords_obs": MdpComponent(
        compute_func=compute_humanoid_max_coords_observations,
        dynamic_vars={"body_pos": EnvContext.current.rigid_body_pos, ...},
        static_params={"local_obs": True},
    ),
}
```

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

### Load and Configure Motion Library

Source: https://nvlabs.github.io/ProtoMotions/tutorials/code_tutorials.html

Load motion data from .motion files and object trajectories from numpy files. Configure motion manager parameters like init_start_prob. Track motion progress during simulation.

```python
motion_lib_config = MotionLibConfig(motion_file="examples/data/grab_teapot_pour/s1_teapot_pour_1.motion")
motion_lib = MotionLib(config=motion_lib_config, device=device)

# Motion manager controls sampling
motion_manager = MimicMotionManagerConfig(init_start_prob=1.0)  # Always start from t=0
```

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

### Configure Reset Noise

Source: https://nvlabs.github.io/ProtoMotions/tutorials/workflows/domain_randomization.html

Defines initial state perturbations for the robot at the start of each episode.

```python
RobotNoiseConfig(
    dof_pos_noise=0.1,
    root_pos_noise=[0.05, 0.05, 0.01],
    root_rot_noise=[0.1, 0.1, 0.2],
    root_vel_noise=[0.1, 0.1, 0.05],
    root_ang_vel_noise=[0.1, 0.1, 0.1],
)
```

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

### GET /reduce

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/evaluators/metrics.html

Reduces the stored motion data using min or max operations.

```APIDOC
## GET /reduce

### Description
Reduces the data by taking the min or max of each motion, accounting for unfilled frames.

### Methods
- **max_reduce_each_motion(with_frame: bool)**: Returns the max value per motion. If with_frame is True, also returns the frame indices.
- **min_reduce_each_motion()**: Returns the min value per motion.
```

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

### Initialize RobotConfig

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.robot_configs.html

Use this to create a base robot configuration. Specify asset files and control types.

```python
config = RobotConfig(
    asset=RobotAssetConfig(asset_file_name="robot.xml"),
    control=ControlConfig(control_type=ControlType.BUILT_IN_PD)
)

```

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

### GET /weights/discriminator

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/ase/model.html

Retrieves the weights of the discriminator part of the model, excluding the encoder head.

```APIDOC
## GET /weights/discriminator

### Description
Returns weights of the discriminator part only by walking through sequential models and skipping the encoder head.

### Method
GET

### Response
#### Success Response (200)
- **weights** (List[nn.Parameter]) - List of discriminator weight parameters.
```

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

### Build All Environment Components

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/utils/component_builder.html

Convenience function to instantiate all core environment components simultaneously.

```python
def build_all_components(
    terrain_config,
    scene_lib_config,
    motion_lib_config,
    simulator_config,
    robot_config,
    device: torch.device,
    save_dir: Optional[str] = None,
    **simulator_extra_params,
) -> Dict:
    """Build all environment components from configs.

    Convenience function that builds terrain, scene_lib, motion_lib, and simulator.

    Args:
        terrain_config: TerrainConfig (or None for no terrain - exception)
        scene_lib_config: SceneLibConfig (always provided, scene_file can be None for empty)
        motion_lib_config: MotionLibConfig (always provided, motion_file can be None for empty)
        simulator_config: SimulatorConfig
        robot_config: RobotConfig
        device: PyTorch device
        save_dir: Optional save directory for loading motion weights as scene weights
        **simulator_extra_params: Simulator-specific params (e.g., simulation_app for IsaacLab)

    Returns:
        Dict with keys: terrain, scene_lib, motion_lib, simulator
    """
    # Create terrain (can be None)
    terrain = build_terrain_from_config(
        terrain_config, simulator_config.num_envs, device
    )

    # Load motion weights from checkpoint to use as scene weights for prioritized sampling
    scene_weights = None
```

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

### Get State Dictionary

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/masked_mimic/agent.html

Retrieves the current state dictionary of the model, including optimizer states.

```APIDOC
## GET /get_state_dict

### Description
Retrieves the state dictionary of the model, which includes optimizer states and other relevant parameters.

### Method
GET

### Endpoint
/get_state_dict

### Parameters
#### Query Parameters
- **state_dict** (dict) - Required - The initial state dictionary to update.

### Response
#### Success Response (200)
- **state_dict** (dict) - The updated state dictionary containing model and optimizer states.

### Response Example
```json
{
  "state_dict": {
    "maskedmimic_optimizer": "[optimizer state data]"
  }
}
```
```

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

### Get Done Indices

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/utils/step_tracker.html

Returns the indices of environments that have reached or exceeded their maximum step count.

```python
[docs]
    def done_indices(self):
        return torch.nonzero(
            torch.greater_equal(self.steps, self.cur_max_steps), as_tuple=False
        ).squeeze(-1)

```

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

### Initialize and Train MaskedMimic Agent

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/masked_mimic/agent.html

Demonstrates the basic setup and training workflow for the MaskedMimic agent. Requires a pre-trained expert tracker model path to be specified in the configuration.

```python
>>> fabric = Fabric(devices=4)
>>> env = Mimic(config, robot_config, simulator_config, device)
>>> config.expert_model_path = "results/expert_tracker/"
>>> agent = MaskedMimic(fabric, env, config)
>>> agent.setup()
>>> agent.train()
```

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

### GET /weights/encoder

Source: https://nvlabs.github.io/ProtoMotions/_modules/protomotions/agents/ase/model.html

Retrieves all weights associated with the encoder part, including the trunk and encoder head.

```APIDOC
## GET /weights/encoder

### Description
Returns all weights of the encoder part only, including the trunk and the encoder head.

### Method
GET

### Response
#### Success Response (200)
- **weights** (List[nn.Parameter]) - List of encoder weight parameters.
```

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

### Initialize and execute Transformer model

Source: https://nvlabs.github.io/ProtoMotions/api_reference/protomotions.agents.common.transformer.html

Demonstrates the instantiation of a Transformer model using a configuration object and performing a forward pass with a TensorDict.

```python
>>> config = TransformerConfig()
>>> model = Transformer(config)
>>> output_td = model(tensordict)
```
Tokens:
Raw