pybullet-fleet 0.2.0

Multi-robot simulation framework with PyBullet

PyBulletFleet

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.

Target Use Cases

Use Case	Description
Fleet algorithm evaluation	Test path planning, task allocation, and traffic control for large robot fleets at N× real-time speed
Warehouse simulation	Simulate pick-and-place, patrol, and transport operations with mobile robots and arms
Scalability benchmarking	Measure how fleet software scales from tens to thousands of agents
Rapid prototyping	Quickly iterate on multi-robot behaviors with minimal boilerplate

Quick Start

Install from PyPI

pip install pybullet-fleet

Or install from source (for development)

git clone https://github.com/yuokamoto/PyBulletFleet.git
cd PyBulletFleet
pip install -e ".[dev]"

Run a demo

# If installed from source:
python examples/100robots_grid_demo.py

Performance

Results from a single test environment (Intel i7-1185G7, 32 GB RAM, Ubuntu 20.04). Your numbers will vary depending on hardware.

Agents	Real-Time Factor	Step Time
100	48×	2.1 ms
500	6.8×	14.7 ms
1000	2.4×	40.9 ms
2000	1.1×	94.8 ms

Kinematics mode (physics OFF), headless. See Benchmark Results for full data, component breakdown, and methodology.

Documentation

📖 Full documentation: Read the Docs

For local builds:

cd docs && sphinx-build -b html . _build/html

Development Setup

A root Makefile provides all common dev commands. Run make help to list targets.

make verify        # Lint + test (CI subset, excludes docs/security)
make test          # Tests with coverage (75% threshold)
make test-fast     # Quick test (stop on first failure)
make lint          # All pre-commit hooks (black, pyright, flake8)
make format        # Auto-format with black
make typecheck     # Pyright type check
make bench-smoke   # Quick benchmark (~10s)
make docs          # Sphinx docs (warnings = errors)
make clean         # Remove caches and build artifacts

Pre-commit hooks

Install pre-commit hooks for automatic formatting and linting on commit:

pip install pre-commit
pre-commit install