PyBulletFleet Documentation

Mixed Fleet Grid 100robots_grid_demo.py	Cube Patrol 100robots_cube_patrol_demo.py
Mobile Pick & Drop pick_drop_mobile_100robots_demo.py	Arm Pick & Drop pick_drop_arm_100robots_demo.py

A kinematics-first simulation framework for large-scale multi-robot fleets, built on PyBullet and designed for fast N× real-time evaluation.

What is PyBulletFleet?

Different simulation goals call for different tools. Physics-focused simulators (Gazebo, Isaac Sim, MuJoCo, etc.) excel at accurate contact dynamics, sensor modelling, and single-robot control — but stepping a full physics engine for every robot becomes the bottleneck when you need to evaluate fleet-level systems at scale.

PyBulletFleet sits in a different part of the design space: it is a kinematics-first, fleet-scale simulation engine whose primary goal is to enable fast development and testing of the software that orchestrates robot fleets rather than the software that controls individual robots.

Design priorities

• Speed over fidelity — Fleet algorithms (task allocation, traffic control, path planning) must be tested with hundreds to thousands of robots running much faster than real time. Kinematics-based stepping — teleporting each robot to its next pose without calling stepSimulation() — removes the physics bottleneck and enables N× real-time execution.

• System integration over low-level control — The primary consumers are high-level systems: WMS (Warehouse Management Systems), task orchestrators, fleet managers, and monitoring dashboards. These systems issue goals, observe progress via state snapshots, and react to events — they do not need joint-level torque feedback.

• Scale over detail — Validating behaviour at 100+ robot scale matters more than modelling individual link dynamics or sensor noise.

• Interoperability — The simulation is designed around a callback-driven step loop and snapshot-friendly state model, so that it can be plugged into larger orchestration frameworks, replay pipelines, or external control systems (e.g., gRPC / ROS 2) as those interfaces are built out.

• Physics as an option — When physical interaction is needed (grasping, conveyor dynamics, contact verification), full PyBullet physics can be switched on per-scenario without changing the rest of the stack.

Contents

• Quick Start
  • Prerequisites
  • Installation
  • Running Your First Simulation
  • YAML Configuration Basics
  • Keyboard Controls
  • Examples
  • Next Steps
• Examples
  • Tutorials
  • Switching Robot Models with --robot
  • API Quick-Reference
• Architecture
  • PyBulletFleet - Design Documentation
  • Collision Detection Overview
  • Collision Detection Broad-Phase Details: Spatial Hash Grid
  • Collision Detection Narrow-Phase Details
  • Real-time Synchronization Design
• How-to Guides
  • Collision Configuration Guide
  • Custom Class Profiling Guide
  • Capturing Demo Videos
  • Time Profiling User Guide
  • Memory Profiling User Guide
  • Logging Utilities - Usage Guide
• Configuration
  • Configuration Files Guide
• Benchmarking
  • PyBullet Fleet - Performance Optimization Guide
  • Benchmark Results Reference
  • PyBullet Fleet - Performance Benchmark Suite
  • Profiling Guide
  • Experiment Scripts
• Testing
  • Tests
• API Reference
  • Full API Documentation
  • Module Overview
• Roadmap
  • Assets
  • Features
  • Interfaces
  • Refactoring
  • Performance
  • Environments
  • CI / DevOps
  • Long-Term: Backend Abstraction & Beyond PyBullet

How to read this documentation

📘 Simulation Users — building simulations with PyBulletFleet:

Section	What you’ll find	When to read
Quickstart	Installation and first simulation	First visit
Examples	Step-by-step tutorials: spawn objects, action queue, 100-robot fleet	Writing your first simulation
How-to › Collision Config	Detection method, per-object modes, spatial hash tuning	Configuring collision for your scene
How-to › Custom Profiling	Adding your own profiling metrics	Measuring your custom logic
Configuration	YAML parameter reference	Looking up a specific setting
Architecture › Collision Overview	Design goals, mode summary, two-phase pipeline	Understanding the collision system
Benchmarking › Optimization Guide	Performance tuning workflow	Improving simulation speed
API Reference	Auto-generated module docs	Looking up a specific class or method

🔧 PyBulletFleet Developers — extending or debugging the framework:

Section	What you’ll find	When to read
Architecture	Design decisions, collision internals, spatial hash grid	Understanding why things work the way they do
How-to › Time / Memory Profiling	Internal component profiling	Diagnosing bottlenecks
How-to › Logging	LazyLogger, performance-safe logging	Adding or reviewing log output
Benchmarking	Benchmark suite, profiling scripts, experiments	Deep performance analysis
Testing	Test strategy, running tests, coverage	Contributing or debugging

Key Features

• N× real-time simulation — Kinematics-based (teleport) stepping as the default motion mode

• Scalability — Tested with 100+ robots; spatial-hash collision keeps per-step cost low as fleet size grows

• Physics as an option — Full PyBullet physics can be enabled per-scenario when needed

• High-level abstractions — Action system (MoveTo, Pick, Drop, Wait), agent managers, YAML-driven configuration

Performance at a Glance

Single test environment (Intel i7-1185G7, 32 GB RAM, Ubuntu 20.04). Results will vary by hardware.

Agents	Real-Time Factor	Step Time
100	46×	2.2 ms
500	7.6×	13.2 ms
1000	3.3×	30.0 ms
2000	1.1×	94.8 ms

Kinematics mode (physics OFF), headless. See PyBullet Fleet - Performance Benchmark Suite for full data, component breakdown, and methodology.

See the Roadmap for upcoming features and integrations.

Indices and tables

• Index

• Module Index

• Search Page