# Physics Tuning
>
---
name: physics-tuning
description: 'Tune Gazebo physics simulation. Use when adjusting step size, solver iterations, contact parameters, or debugging simulation instability.'
---
# Physics Engine Tuning for Stable Simulation
## Step Size
The physics step size (`max_step_size`) is the fundamental timestep of the simulation. Smaller steps are more accurate but slower.
| Step Size | Use Case | Notes |
|-----------|----------|-------|
| 0.001s (1ms) | Default, general robotics | Good balance for most robots |
| 0.0005s (0.5ms) | Fast-moving robots, complex contacts | 2× slower than default |
| 0.002s (2ms) | Simple scenes, slow robots | Faster but less stable |
```xml
0.0011.01000
```
Signs you need a smaller step size: robot jitters at rest, wheels bounce, objects pass through each other (tunneling), joints oscillate.
## DART Solver Configuration
DART is the default physics engine. Its solver resolves contacts and constraints.
```xml
0.0011.0fcldantzig
```
`dantzig`: direct solver, more accurate for contacts and constraints. Default choice.
`pgs` (Projected Gauss-Seidel): iterative solver, faster for many contacts but can be less stable.
## Real-Time Factor Optimization
If RTF < 1.0, the simulation can't keep up with real-time. Diagnose and fix:
```bash
gz stats # Shows RTF, sim time, wall time
```
**Performance fixes (ordered by impact)**:
1. **Collision geometry**: Replace trimesh collisions with primitive shapes (boxes, cylinders, spheres). A bookshelf visual mesh can have thousands of triangles; its collision should be a single box.
```xml
meshes/detailed_table.dae1.2 0.6 0.75
```
2. **Static models**: Mark all non-moving objects as `true`. Static objects skip dynamics calculations entirely.
3. **Sensor rates**: Reduce `` on sensors. A lidar at 40Hz is 4× the cost of 10Hz.
4. **Rendering**: GPU lidar and cameras require rendering. Use `--headless-rendering` in CI or reduce resolution/FPS. Set `ogre2` (default, faster than ogre).
5. **Model count**: Each dynamic model adds solver cost. Combine small static objects into a single model where possible.
## Wheel-Ground Contact (Critical for Diff-Drive)
Incorrect friction causes wheels to slip (robot moves less than commanded) or spin freely. Set friction on both wheels and ground:
```xml
1.01.00 0 10.00.01.00.050.0true1e61000.10.001true0 0 1100 1001.01.0
```
Effective friction = `min(mu_wheel, mu_ground)`. If either is 0, wheels slide freely.
## Inertia
Physically realistic inertia is **essential**. Bad inertia causes: robot launching into space, oscillating uncontrollably, or passing through the ground.
Common formulas (uniform density):
```
Box (mass m, dimensions x,y,z):
Ixx = m/12 * (y² + z²)
Iyy = m/12 * (x² + z²)
Izz = m/12 * (x² + y²)
Cylinder (mass m, radius r, length h, about center):
Ixx = Iyy = m/12 * (3r² + h²)
Izz = m/2 * r²
Sphere (mass m, radius r):
Ixx = Iyy = Izz = 2/5 * m * r²
```
In URDF:
```xml
```
**Rules of thumb**:
- Never set mass to 0 (infinite inertia) or extremely small values
- Off-diagonal terms (ixy, ixz, iyz) should usually be 0 unless the object is asymmetric
- All diagonal terms must be positive
- If `ixx + iyy < izz` (triangle inequality violation) for a physical object, something is wrong
## Caster Wheel / Support
For passive casters, use a sphere with low friction to avoid interfering with diff-drive:
```xml
0.010.01
```
## Common Problems and Fixes
| Problem | Cause | Fix |
|---------|-------|-----|
| Robot flies into space | Bad inertia or mass=0 in a link | Calculate realistic inertia |
| Wheels slip, no traction | Friction mu=0 or missing | Set mu=1.0 on wheels and ground |
| Robot jitters at rest | Step size too large, high stiffness | Reduce step to 0.5ms, lower kp |
| Objects pass through each other | Step too large, thin geometry | Smaller step, thicker collision shapes |
| Simulation too slow (RTF < 0.5) | Complex collisions, high sensor rates | Simplify meshes, reduce update rates |
| Robot sinks into ground | min_depth too large | Set min_depth=0.001 or smaller |
| Wheels bounce | kp too high, kd too low | Reduce kp to 1e5, increase kd to 1e2 |