protomotions.utils.component_builder module#

Utility functions for building environment components.

This module provides helper functions to create terrain, scene_lib, motion_lib, and simulator objects from their configs, reducing boilerplate in entry scripts, and build_env_from_configs(), the environment of a resolved-config bundle as every entry point builds it.

protomotions.utils.component_builder.build_terrain_from_config(terrain_config, num_envs, device)[source]#

Build Terrain from config.

Parameters:

  • terrain_config – TerrainConfig or None (exception: can be None for no terrain)

  • num_envs (int) – Number of environments

  • device (<Mock object at 0x7a9276b439d0>[]) – PyTorch device

Returns:

Terrain instance or None if config is None

protomotions.utils.component_builder.build_scene_lib_from_config(
scene_lib_config,
num_envs,
device,
terrain,
scene_weights=None,
motion_weights=None,
)[source]#

Build SceneLib from config.

Always returns a SceneLib instance. If config.scene_file is None, creates an empty SceneLib (Null Object pattern).

Parameters:

  • scene_lib_config – SceneLibConfig (required, scene_file can be None for empty)

  • num_envs (int) – Number of environments

  • device (<Mock object at 0x7a9276b20ad0>[]) – PyTorch device

  • terrain – Terrain instance (required by SceneLib)

  • scene_weights (list | None) – Optional scene weights for curriculum learning

Returns:

SceneLib instance (empty if scene_file is None)

protomotions.utils.component_builder.build_motion_lib_from_config(motion_lib_config, device, shard_cycle=0)[source]#

Build MotionLib from config.

Always returns a MotionLib instance. If config.motion_file is None, creates an empty MotionLib (Null Object pattern).

Note: Contact smoothing is NOT applied here - it’s the Env’s responsibility to modify the motion_lib during initialization based on its config.

Parameters:

  • motion_lib_config – MotionLibConfig (required, motion_file can be None for empty)

  • device (<Mock object at 0x7a9276bbc9d0>[]) – PyTorch device

  • shard_cycle (int) – Distributed shard-selection cycle.

Returns:

MotionLib instance (empty if motion_file is None)

protomotions.utils.component_builder.build_simulator_from_config(
simulator_config,
robot_config,
terrain,
scene_lib,
device,
**simulator_extra_params,
)[source]#

Build Simulator from config.

Creates simulator shell (deferred initialization - will be finalized by Env).

Parameters:

  • simulator_config – SimulatorConfig

  • robot_config – RobotConfig

  • terrain – Terrain instance

  • scene_lib – SceneLib instance or None

  • device (<Mock object at 0x7a9276b43b50>[]) – PyTorch device

  • **simulator_extra_params – Simulator-specific params (e.g., simulation_app for IsaacLab)

Returns:

Simulator instance (shell, not yet initialized)

protomotions.utils.component_builder.apply_motion_weights_to_scene_weights(save_dir, motion_file, device)[source]#

Apply motion weights from checkpoint as scene weights for curriculum learning.

Loads motion weights from a previous training checkpoint and uses them as scene replication weights, allowing over-sampling of scenes corresponding to failed motions in curriculum learning. Called from build_all_components() only; it reads a checkpoint the env wrote (env_<motion file>.ckpt).

The returned per-motion weights reach each scene by its humanoid_motion_id in SceneLib (scene_weights_by_clip_id), so no 1:1 scene-to-motion ordering is assumed.

Parameters:

  • save_dir (str | None) – Directory where checkpoints are saved (or None)

  • motion_file (str | None) – Motion file path to identify checkpoint (or None)

  • device (<Mock object at 0x7a9276a476d0>[]) – PyTorch device

Returns:

List of scene weights from motion training or None if not available

Return type:

list | None

Missing checkpoints or checkpoints without a motion manager have no curriculum to restore. Corrupt files and malformed manager state must raise rather than silently changing a resumed run to uniform sampling.

protomotions.utils.component_builder.build_all_components(
terrain_config,
scene_lib_config,
motion_lib_config,
simulator_config,
robot_config,
device,
save_dir=None,
motion_shard_cycle=0,
**simulator_extra_params,
)[source]#

Build all environment components from configs.

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

Parameters:

  • 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 (<Mock object at 0x7a9276bbc190>[]) – PyTorch device

  • save_dir (str | None) – Optional save directory for loading motion weights as scene weights

  • motion_shard_cycle (int) – Distributed shard-selection cycle.

  • **simulator_extra_params – Simulator-specific params (e.g., simulation_app for IsaacLab)

Returns:

terrain, scene_lib, motion_lib, simulator

Return type:

Dict with keys

protomotions.utils.component_builder.build_env_from_configs(
configs,
device,
motion_shard_cycle=0,
**simulator_extra_params,
)[source]#

Build the environment of a resolved-config bundle.

The one path from configs to a constructed env, shared by training, inference, the examples and the tests: the friction conversion the simulator’s combine mode needs, written back into configs.terrain and configs.simulator so a bundle saved afterwards describes what the env was built from; build_all_components(); the env class configs.env._target_ names. The curriculum weights of a resumed run come from configs.env.save_dir.

Parameters:

  • configs – ExperimentConfigs (terrain, scene_lib, motion_lib, simulator, robot, env); terrain and simulator are replaced by their converted forms.

  • device (<Mock object at 0x7a9276f05150>[]) – PyTorch device of the components and the env.

  • motion_shard_cycle (int) – Distributed shard-selection cycle (a resumed run’s).

  • **simulator_extra_params – Simulator-specific params (simulation_app for IsaacLab).

Returns:

The constructed env (the simulator initialises inside its constructor).