Heuristic:Haosulab ManiSkill Physics Solver Tuning
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Physics_Simulation |
| Last Updated | 2026-02-15 08:00 GMT |
Overview
Physics simulation tuning guide for balancing speed vs. accuracy through contact_offset, solver_iterations, and CPU worker parameters in SceneConfig.
Description
The SAPIEN PhysX SceneConfig exposes several physics parameters that control the trade-off between simulation speed and physical accuracy. The most impactful parameters are `contact_offset` (controls the distance at which contacts are detected), `solver_position_iterations` (controls constraint convergence), and `cpu_workers` (controls parallel CPU collision processing). These parameters can dramatically affect both simulation performance and physical fidelity.
Usage
Use this heuristic when you need to optimize simulation speed (e.g., training is too slow) or improve physical accuracy (e.g., grasps are unstable, objects pass through each other). This is especially relevant for:
- Dexterous manipulation tasks requiring stable grasps
- Humanoid tasks with many self-collisions
- Tasks where simulation speed is the training bottleneck
The Insight (Rule of Thumb)
- contact_offset:
- Action: Reduce from default 0.02 to 0.01 for tasks where many potential contacts slow down simulation.
- Value: Default 0.02; reduce to 0.01 for humanoid tasks, 0.005 for very sparse contacts.
- Trade-off: Smaller values = faster (fewer contacts checked) but may miss rapid contacts.
- solver_position_iterations:
- Action: Increase from default 15 to >= 20 for tasks requiring stable grasps.
- Value: Default 15; use >= 20 for grasping; >= 30 for dexterous manipulation.
- Trade-off: More iterations = more accurate constraints but slower simulation step.
- cpu_workers:
- Action: Increase from default 0 if there are many collisions.
- Value: Default 0; try `min(os.cpu_count(), 4)` for collision-heavy tasks.
- Trade-off: More workers = faster collision filtering (which runs on CPU) but uses more CPU cores.
- enable_ccd (Continuous Collision Detection):
- Action: Enable for fast-moving objects that tunnel through thin surfaces.
- Value: Default False.
- Trade-off: Prevents tunneling but adds significant computational cost.
Reasoning
Developer notes in the source code reveal extensive tuning experience:
From `mani_skill/utils/structs/types.py:58-63`:
# NOTE (fxiang): smaller contact_offset is faster as less contacts are considered,
# but some contacts may be missed if distance changes too fast
# NOTE (fxiang): solver iterations 15 is recommended to balance speed and accuracy.
# If stable grasps are necessary >= 20 is preferred.
# NOTE (fxiang): can try using more cpu_workers as it may also make it faster
# if there are a lot of collisions, collision filtering is on CPU
# NOTE (fxiang): enable_enhanced_determinism is for CPU probably.
# If there are 10 far apart sub scenes, this being True makes it so they do not
# impact each other at all
Real-world example of contact_offset tuning from `mani_skill/envs/tasks/humanoid/humanoid_pick_place.py:252-254`:
# and slow down simulation. A temporary fix is to reduce contact_offset value
# down so that we don't check so many possible contacts
scene_config=SceneConfig(contact_offset=0.01)
SceneConfig defaults from `mani_skill/utils/structs/types.py:37-53`:
@dataclass
class SceneConfig:
contact_offset: float = 0.02
solver_position_iterations: int = 15
solver_velocity_iterations: int = 1
enable_pcm: bool = True
enable_ccd: bool = False
enable_enhanced_determinism: bool = False
cpu_workers: int = 0