Heuristic:Haosulab ManiSkill Initial Pose Performance
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Physics_Simulation |
| Last Updated | 2026-02-15 08:00 GMT |
Overview
Setting reasonable non-colliding initial poses for actors and articulations prevents significant simulation slowdown during scene initialization.
Description
When objects are created in SAPIEN without explicit initial poses, they default to the world origin `(q=[1,0,0,0], p=[0,0,0])`. If multiple objects spawn at the same position, they overlap, and PhysX spends many solver iterations resolving the resulting collisions during the first simulation steps. This can cause orders-of-magnitude slowdown in scene initialization, particularly with GPU simulation where all parallel environments are affected simultaneously.
Usage
Use this heuristic when you are creating custom environments with multiple actors or articulations. Always set explicit initial poses via `ActorBuilder.set_initial_pose()` or `ArticulationBuilder.set_initial_pose()` before building the actor. This is especially important when:
- Spawning multiple objects on a table
- Creating scenes with robots and obstacles
- Using GPU simulation where initialization cost is multiplied across all environments
The Insight (Rule of Thumb)
- Action: Always call `builder.set_initial_pose(sapien.Pose(p=[x, y, z]))` with non-overlapping positions before building actors.
- Value: Ensure objects are separated by at least `contact_offset` (default 0.02m) in their initial placement.
- Trade-off: None. This is strictly better than the default. The only cost is writing a few extra lines of code.
Reasoning
The ManiSkill codebase issues explicit warnings when initial poses are not set, linking to a GitHub issue that documents the performance impact.
Warning from `mani_skill/utils/building/actor_builder.py:217`:
logger.warn(
f"No initial pose set for actor builder of {self.name}, "
"setting to default pose q=[1,0,0,0], p=[0,0,0]. "
"Not setting reasonable initial poses may slow down simulation, "
"see https://github.com/haosulab/ManiSkill/issues/421."
)
Warning from `mani_skill/utils/building/articulation_builder.py:132-136`:
logger.warn(
f"No initial pose set for articulation builder of {self.name}, "
"setting to default pose q=[1,0,0,0], p=[0,0,0]. "
"Not setting reasonable initial poses may slow down simulation, "
"see https://github.com/haosulab/ManiSkill/issues/421."
)
The `TableSceneBuilder` provides a reference implementation that sets reasonable default positions for robots on the table surface, avoiding overlap issues by design.