Troubleshooting Common Physics Simulation Challenges

Effective troubleshooting is essential for successful physics simulation in Gazebo. This section addresses common issues that arise during simulation setup and execution, providing diagnostic techniques and solutions to help maintain productive development workflows.

Common Simulation Instabilities

Jittering and Oscillation

Symptoms:

• Objects vibrate rapidly at joints or contacts
• Robot joints oscillate around desired positions
• Small objects exhibit unstable behavior

Root Causes:

• Insufficient solver iterations
• Poor mass/inertia ratios
• Inappropriate timestep settings
• Incorrect constraint formulations

Solutions:

<physics name="default_physics" type="ode">
  <ode>
    <solver>
      <iters>200</iters>  <!-- Increase from default -->
      <sor>1.3</sor>
    </solver>
    <constraints>
      <cfm>1e-5</cfm>
      <erp>0.8</erp>  <!-- Increase ERP for better constraint enforcement -->
    </constraints>
  </ode>
</physics>

Additional Steps:

• Verify mass properties are physically realistic
• Check that collision meshes align with visual meshes
• Reduce timestep if increasing solver iterations doesn't help
• Add damping to joints if appropriate

Object Penetration

Symptoms:

• Objects pass through each other
• Robots fall through ground planes
• Collision detection fails intermittently

Root Causes:

• Large timesteps relative to object speeds
• Insufficient contact surface layer
• Poor collision geometry
• Inadequate constraint force mixing

Solutions:

<physics name="default_physics" type="ode">
  <max_step_size>0.0005</max_step_size>  <!-- Smaller timestep -->
  <ode>
    <constraints>
      <contact_surface_layer>0.01</contact_surface_layer>  <!-- Increase from default -->
      <cfm>1e-6</cfm>  <!-- Reduce CFM for stiffer contacts -->
    </constraints>
  </ode>
</physics>

Additional Steps:

• Verify collision geometry is properly defined
• Check that static objects have <static>true</static>
• Ensure adequate mesh resolution for complex shapes

Explosive Behavior

Symptoms:

• Objects suddenly fly apart
• Joint limits violated dramatically
• Simulation crashes or becomes unresponsive

Root Causes:

• Extreme mass ratios
• Invalid inertia matrices
• Excessive applied forces
• Numerical instability

Diagnostic Steps:

1. Check mass ratios between connected bodies (should be < 100:1)
2. Verify inertia matrices satisfy triangle inequality (Ix + Iy ≥ Iz, etc.)
3. Examine force/torque limits on actuators
4. Reduce all force magnitudes temporarily to isolate the issue

Robot-Specific Issues

Joint Limit Problems

Symptoms:

• Joints exceeding specified limits
• Robot behaving erratically near joint boundaries
• Unusual torques reported near limits

Solutions:

<joint name="problematic_joint" type="revolute">
  <axis>
    <limit>
      <lower>-1.0</lower>
      <upper>1.0</upper>
      <effort>100.0</effort>
      <velocity>1.0</velocity>
    </limit>
    <dynamics>
      <damping>10.0</damping>  <!-- Add damping near limits -->
      <friction>5.0</friction>
    </dynamics>
  </axis>
</joint>

Additional Considerations:

• Ensure joint limits are physically achievable
• Add soft position limits with controllers
• Check for singularity conditions in kinematic chains

Balance Instability in Humanoid Robots

Symptoms:

• Humanoid falls over immediately
• Excessive swaying during standing
• Inability to maintain stable gaits

Solutions:

1. Check Center of Mass: Ensure COM is within support polygon
2. Verify Mass Distribution: Use realistic mass properties for each link
3. Adjust Control Parameters: Tune balance controllers appropriately
4. Increase Simulation Fidelity: Use smaller timesteps and more solver iterations

<physics name="humanoid_physics" type="ode">
  <max_step_size>0.0005</max_step_size>
  <real_time_update_rate>2000</real_time_update_rate>
  <ode>
    <solver>
      <iters>200</iters>
    </solver>
  </ode>
</physics>

Performance Issues

Slow Simulation Speed

Symptoms:

• Real-time factor significantly below 1.0
• High CPU usage
• Frame rate drops in visualization

Diagnosis:

• Check number of active objects and contacts
• Verify physics engine parameters
• Examine collision complexity
• Monitor plugin overhead

Solutions:

1. Reduce Collision Complexity: Simplify collision meshes for distant objects
2. Adjust Physics Parameters:

   <physics name="performance_physics" type="ode">
     <max_step_size>0.002</max_step_size>  <!-- Larger timestep -->
     <real_time_update_rate>500</real_time_update_rate>  <!-- Lower update rate -->
     <ode>
       <solver>
         <iters>50</iters>  <!-- Fewer iterations -->
       </solver>
     </ode>
   </physics>

3. Disable Unnecessary Features: Turn off physics for static objects
4. Optimize Plugin Usage: Minimize number of active plugins

Memory Leaks

Symptoms:

• Increasing memory usage over time
• Simulation becoming slower over extended runs
• Potential crashes after long simulation periods

Diagnostic Tools:

• Use system monitoring tools (htop, task manager)
• Monitor Gazebo's internal statistics
• Check for resource cleanup in custom plugins

Solutions:

• Implement proper cleanup in custom plugins
• Periodically reset simulation if appropriate
• Use memory profiling tools to identify problematic components

Sensor-Related Issues

Inconsistent Sensor Data

Symptoms:

• Sensor readings jump unexpectedly
• Missing sensor updates
• Delayed sensor responses

Common Causes:

• High update rates overwhelming processing
• Network latency in distributed setups
• Collision geometry affecting sensor beams

Solutions:

<sensor name="lidar_sensor" type="ray">
  <ray>
    <scan>
      <horizontal>
        <samples>360</samples>
        <resolution>1.0</resolution>
        <min_angle>-3.14159</min_angle>
        <max_angle>3.14159</max_angle>
      </horizontal>
    </scan>
    <range>
      <min>0.1</min>
      <max>10.0</max>
      <resolution>0.01</resolution>
    </range>
  </ray>
  <update_rate>10</update_rate>  <!-- Reduce update rate if needed -->
</sensor>

Contact Sensor Problems

Symptoms:

• Contact sensors not detecting expected contacts
• False positives in contact detection
• Delayed contact reporting

Solutions:

• Verify collision name matches in sensor configuration
• Check that objects can actually make contact
• Adjust contact surface layer if needed
• Ensure sufficient update rate for contact detection

Model Loading Issues

Model Not Appearing

Symptoms:

• Model fails to load in simulation
• Empty space where model should be
• Error messages about missing files

Diagnostic Steps:

1. Verify model path exists: gz model -m model_name
2. Check model directory structure follows Gazebo conventions
3. Ensure model.config and model.sdf files are properly formatted
4. Check GAZEBO_MODEL_PATH environment variable

Solutions:

• Verify file permissions on model directory
• Check XML syntax in SDF files
• Ensure all referenced mesh files exist
• Validate model using gz sdf -k model.sdf

Visual vs. Collision Mismatch

Symptoms:

• Robot appears in wrong position/orientation
• Physics behavior doesn't match visual appearance
• Unexpected collision behavior

Solutions:

• Verify that visual and collision geometries have same pose relative to link
• Check that both visual and collision elements are properly defined
• Use Gazebo's visualization tools to inspect both geometries separately

Debugging Techniques

Logging and Monitoring

Enable detailed logging for diagnosis:

# Enable Gazebo logging
export GAZEBO_LOG_LEVEL=4
gzserver --verbose world_file.world

# Monitor physics statistics
gz stats

Visualization Tools

• Contact Visualization: Enable to see contact points and forces
• Frames Display: Show coordinate frames for debugging transforms
• Wireframe Mode: Visualize collision geometries
• Force/Torque Display: Show applied forces and torques

Incremental Testing

1. Start Simple: Begin with basic models and minimal complexity
2. Add Components Gradually: Introduce complexity one element at a time
3. Validate at Each Step: Ensure stability before adding more complexity
4. Document Working Configurations: Keep records of successful parameter sets

Prevention Strategies

Model Validation

• Unit Testing: Test individual joints and links separately
• Parameter Validation: Verify all physical parameters are realistic
• Kinematic Testing: Ensure model can achieve intended poses
• Stress Testing: Test model under extreme conditions

Configuration Management

• Version Control: Keep simulation files under version control
• Parameter Documentation: Document all critical parameters
• Baseline Comparisons: Maintain reference configurations for regression testing
• Automated Checks: Implement automated validation of models and worlds

Quick Reference for Common Fixes

Issue	Likely Cause	Quick Fix
Robot falls through floor	Bad pose or collision	Check Z-position, verify static flag
Jittery joints	Insufficient solver iterations	Increase solver iterations
Slow simulation	High complexity	Reduce timestep, simplify collisions
Sensor noise	Physics approximations	Adjust sensor parameters, add filtering
Explosive behavior	Mass ratio issues	Check mass properties, reduce forces

Remember that troubleshooting often requires systematic isolation of components. When encountering complex issues, start with a minimal working configuration and gradually add complexity until the problem reappears. This approach helps identify the specific cause of simulation issues.