PyBulletFleet

Contents

  • Quick Start
    • Prerequisites
    • Installation
      • From PyPI (recommended)
      • From source (for development)
    • Running Your First Simulation
    • YAML Configuration Basics
    • Keyboard Controls
    • Examples
    • Next Steps
  • Examples
    • Which tutorial should I read?
      • Tutorial 1: Spawning Objects and Controlling Agents
        • 1. Initialize the Simulation
        • 2. Spawn a SimObject from a Mesh
        • 3. Wrap an Existing PyBullet Body
        • 4. Spawn an Agent from a Mesh
        • 5. Spawn an Agent from a URDF
        • 6. Getting and Setting Poses
        • 7. Setting a Goal Pose (Smooth Movement)
        • 8. Periodic Logic with Callbacks
        • 9. Controlling Arm Joints
        • 10. Running the Simulation
        • Full Example
        • See Also
      • Tutorial 2: High-Level Actions — Pick, Drop, Move, Wait
        • 1. Why Use Actions Instead of set_goal_pose?
        • 2. Setup
        • 3. Spawn a Pickable Object
        • 4. MoveAction — Navigate Along a Path
        • 5. PickAction — Approach and Attach
        • 6. DropAction — Approach and Release
        • 7. WaitAction — Pause for a Fixed Duration
        • 8. Queue the Task Sequence
        • 9. Monitor Action Progress
        • 10. Run
        • Full Example
        • See Also
      • Tutorial 3: Managing a 100-Robot Fleet
        • 1. When to Use AgentManager
        • 2. Load Config from YAML
        • 3. Create an AgentManager
        • 4. Define a Grid Layout with GridSpawnParams
        • 5. Define Agent Types
        • 6. Spawn 100 Agents in a Mixed Grid
        • 7. Build a Path and Assign it to an Agent
        • 8. Assign Individual Paths to All 100 Agents
        • 9. Bulk Operations with the Manager
        • 10. Write a Monitoring Callback
        • 11. Camera Setup
        • 12. Run
        • Performance Notes
        • See Also
      • Tutorial 4: Robot Arm — Joint Control & Pick/Drop
        • 1. Fixed-Base Arm Setup
        • 2. Kinematic vs Physics Joint Control
        • 3. Joint Control API
        • 4. Link-Level Object Attachment
        • 5. Approach A — Low-Level Callback (pick_drop_arm_demo.py)
        • 6. Approach B — Action Queue (pick_drop_arm_action_demo.py)
        • 7. JointAction Reference
        • 8. Running the Demos
        • See Also
      • Tutorial 5: End-Effector Control — IK & PoseAction
        • 1. Why EE Position Control?
        • 2. Direct EE Control: move_end_effector()
        • 3. PoseAction — EE Control in the Action Queue
        • 4. EE-Based Pick & Drop
        • 5. Tuning IK with IKParams
        • 6. Mobile Manipulator IK
        • 7. Low-Level Callback Approach
        • 8. Running the Demos
        • 9. Prismatic Joints & Rail Arms
        • API Summary
        • See Also
    • API Quick-Reference
  • Architecture
    • PyBulletFleet - Design Documentation
      • Architecture Overview
      • Core Components
        • 1. core_simulation.py
        • 2. agent.py
        • 3. agent_manager.py
        • 4. action.py
        • 5. geometry.py
        • 6. tools.py
        • 7. data_monitor.py
      • Performance Considerations
        • Bottlenecks:
        • Optimizations:
    • Collision Detection Overview
      • TL;DR
      • Overview & Design Philosophy
        • Why This Design?
        • Core Principles
      • Architecture Overview
        • Two-Phase Collision Detection
        • Why Two Phases?
        • Spatial Hash Grid: How It Works
      • System Flow & Object Lifecycle
        • Object Lifecycle
        • Mode-Specific Flow Examples
      • FAQ & Troubleshooting
        • Q: How do I debug collision detection?
        • Q: Performance is slow. How to optimize?
      • Further Reading
    • Collision Detection Broad-Phase Details: Spatial Hash Grid
      • Cell Size & Grid Mapping
        • Cell Size Calculation Modes
        • Calculation Algorithm
        • Position → Cell Mapping
        • Usage
      • AABB Caching
      • Neighbor Search Patterns
      • Multi-Cell Registration
      • Movement-Based Optimization
      • Incremental Updates
      • See Also
    • Collision Detection Narrow-Phase Details
      • Narrow-Phase Details: PyBullet APIs
        • API Comparison
        • getClosestPoints(distance) - Recommended for Kinematics
        • getContactPoints() - For Physics Mode
        • stepSimulation() - The Physics Update
        • Two-Mode Design Philosophy
      • Collision Mode Details
        • NORMAL_3D - Full 3D Collision
        • NORMAL_2D - 2D Collision (XY Plane)
        • STATIC - Fixed Objects
        • DISABLED - No Collision
        • Runtime Mode Changes
      • Implementation & Configuration
        • SimulationParams
        • Per-Object Configuration
        • Config File (YAML)
        • Auto-Selection Logic
        • Collision Margin Recommendations
      • See Also
    • Real-time Synchronization Design
      • Overview
      • Design Philosophy
        • Absolute Time-based Control
      • Core Algorithm
        • 1. Time Difference Calculation
        • 2. Adaptive Step Execution
        • 3. Sleep Strategy
      • Pause/Resume Handling
        • Reset start_time on Resume
      • RTF Multiplier Support
        • Variable RTF Control
      • Best Practices
        • 1. Spawn Objects Before run_simulation() ✅
        • 2. Use Pause/Resume for Dynamic Spawning of large/complex objects ✅
  • How-to Guides
    • Collision Configuration Guide
      • Quick Decision Guide
      • Collision Detection Method
        • Configuration
        • Auto-Selection
      • Per-Object Collision Mode
        • Setting via AgentSpawnParams
        • Setting via SimObject
        • Runtime Mode Changes
      • Collision Margin
      • Spatial Hash Cell Size
        • Mode 1: auto_initial (Default — Recommended)
        • Mode 2: constant (Fastest)
        • Mode 3: auto_adaptive (Dynamic)
        • Manual Recalculation
        • Performance Comparison
      • Multi-Cell Threshold
      • Complete YAML Reference
      • See Also
    • Custom Class Profiling Guide
      • Overview
      • Approach 1: Built-in Profiling (Recommended First Step)
        • 1-1. Adding Custom Fields — Agent Subclass (record_profiling)
        • 1-2. Adding Custom Fields — SimulationCore Subclass (Direct Write)
        • How the Unified Design Works
      • Approach 2: cProfile (Find Slow Custom Functions)
        • External (No Code Changes)
        • Programmatic (Targeted Profiling)
      • Approach 3: Standalone perf_counter (Per-Agent, Non-Integrated)
      • Comparing Custom vs Base Performance
      • Tips
      • See Also
    • Time Profiling User Guide
      • Overview
      • Quick Start
        • 1. Enable Time Profiling in Configuration
        • 2. Run Your Simulation
        • 3. Read the Output
      • Configuration Reference
      • Interpreting Results
        • Healthy Profile (kinematics mode, 100 robots)
        • Bottleneck: Collision Detection
        • Bottleneck: Agent Update
        • Bottleneck: Physics Step
      • Programmatic Access
      • Best Practices
      • Troubleshooting
        • No profiling output appears
        • Output appears too frequently / infrequently
      • References
    • Memory Profiling User Guide
      • Overview
      • Quick Start
        • 1. Enable Memory Profiling in Configuration
        • 2. Run Your Simulation
        • 3. Check Memory Usage Output
      • API Reference
        • Enable/Disable Memory Profiling
        • Get Current Memory Usage
      • Understanding Memory Statistics
        • Memory Report Fields
        • Interpreting Growth Values
      • Use Case: Detecting Memory Leaks in Long-Running Simulations
      • Best Practices
        • ✅ DO
        • ❌ DON’T
      • Performance Impact
      • Troubleshooting
        • Memory profiling returns None
        • No memory statistics printed
        • Memory keeps growing
      • Example Output
        • Normal Memory Usage (Healthy)
        • Memory Leak Detected (Unhealthy)
      • References
    • Logging Utilities - Usage Guide
      • Overview
      • Performance Impact
      • When to Use Lazy Logging
      • Usage Examples
        • Method 1: LazyLogger (Recommended for New Code)
        • Method 2: isEnabledFor Check (Good for Existing Code)
      • API Reference
        • get_lazy_logger(name: str) -> LazyLogger
        • wrap_existing_logger(logger: logging.Logger) -> LazyLogger
        • LazyLogger Methods
      • Testing
      • Best Practices
        • ✅ DO
        • ❌ DON’T
      • Performance Tips
      • Migration Checklist
      • Related Files
  • Configuration
    • Configuration Files Guide
      • Overview
      • Configuration Files
        • Production Configurations
        • Benchmark Configurations
      • Usage Examples
        • Load Configuration in Python
        • Run Config-Based Benchmark
      • Key Parameters Explained
        • physics (bool)
        • collision_detection_method (string)
        • collision_margin (float, meters)
        • multi_cell_threshold (float, dimensionless multiplier)
      • Auto-Selection Logic
      • Choosing the Right Configuration
        • Decision Tree
        • Common Use Cases
      • See Also
  • Benchmarking
    • PyBullet Fleet - Performance Optimization Guide
      • Key Parameters
        • RTF Control (target_rtf)
        • Timestep
        • Collision Detection
        • Profiling
      • Configuration Examples
        • Offline / Production
        • Development / Debugging
      • Performance Reference
        • Benchmark Results
        • Step Time Targets
        • Component Breakdown (1000 agents)
        • Memory
      • Troubleshooting
        • Low RTF / High Step Time
        • Memory Growth
      • Performance Hierarchy
      • See Also
    • Benchmark Results Reference
      • Test Environment
      • Simulation Throughput
      • Step Time Component Breakdown
      • Agent Update Cost
        • Stationary vs Moving (500 agents)
        • Motion Mode Comparison (500 agents, all moving)
      • Wrapper Layer Overhead
      • Collision Mode Comparison (DISABLED / NORMAL_2D / NORMAL_3D)
      • Collision Algorithm Comparison (Spatial Hashing vs Alternatives)
      • Differential Drive Optimization
      • Collision Config-Based Comparison (Physics ON vs OFF)
      • Arm Joint Control Performance
        • Physics vs Kinematic Scaling
        • Component Breakdown (10 arms)
        • Kinematic Joint Cache Optimization
      • See Also
    • PyBullet Fleet - Performance Benchmark Suite
      • Performance Optimization Workflow
        • Typical Bottlenecks
        • Tool Categories
      • Quick Start
      • Benchmark Results
        • TL;DR
        • Test Environment
        • Performance Summary
        • Component Breakdown
        • Scaling Analysis
      • Directory Structure
      • Architecture: Worker + Orchestrator Pattern
        • Workers (mobile_benchmark.py, arm_benchmark.py)
        • Shared Helpers (tools.py)
        • Orchestrator (run_benchmark.py)
        • CLI Reference
      • Benchmark Configs
      • Further Reading
    • Profiling Guide
      • Tool Summary
      • Measurement Methods by Script
      • Measurement Method Comparison
      • When to Use Each Tool
      • Simulation Profiler (simulation_profiler.py)
        • Measured Components
        • Analysis Methods
        • CLI Usage
        • Output Example
        • Follow-Up Analysis
      • Collision Check Profiler (collision_check.py)
        • 4-Step Breakdown
        • CLI Usage
        • Output Example
        • Optimization Hints
      • Agent Update Profiler (agent_update.py)
        • Five Analysis Methods
        • CLI Usage
        • Output Summary
        • When to Use Which Method
      • Goal Setting Profiler (agent_manager_set_goal.py)
        • CLI Usage
        • Output Example
      • Typical Bottlenecks and Fixes
        • 1. Collision Check is slow (> 20% of step time)
        • 2. Agent Update is slow (> 40% of step time)
        • 3. Goal setting is slow (set_goal_pose > 100ms)
      • Wrapper Overhead (wrapper_overhead.py)
        • What It Measures
        • CLI Usage
        • Metrics
      • Troubleshooting
        • Profiling logs are not displayed
        • Segfault with cProfile
        • High variance in measurement results
    • Experiment Scripts
      • Collision Detection Experiments
        • collision_methods_config_based.py (Recommended)
        • collision_method_comparison.py
        • collision_mode_comparison.py
  • Testing
    • Tests
      • Running Tests
      • Shared Fixtures
      • Visual Demos
  • API Reference
    • pybullet_fleet package
      • Submodules
      • pybullet_fleet.action module
      • pybullet_fleet.agent module
      • pybullet_fleet.agent_manager module
      • pybullet_fleet.config_utils module
      • pybullet_fleet.core_simulation module
      • pybullet_fleet.data_monitor module
      • pybullet_fleet.geometry module
      • pybullet_fleet.logging_utils module
      • pybullet_fleet.sim_object module
      • pybullet_fleet.tools module
      • pybullet_fleet.types module
      • Module contents
    • Full API Documentation
    • Module Overview
  • Roadmap
    • Assets
    • Features
    • Interfaces
    • Refactoring
    • CI / DevOps
PyBulletFleet
  • Architecture
  • View page source

Architecture

Overview of PyBulletFleet’s system design and core components.

General

  • PyBulletFleet - Design Documentation
    • Architecture Overview
    • Core Components
    • Performance Considerations

Collision Detection

  • Collision Detection Overview
    • TL;DR
    • Overview & Design Philosophy
    • Architecture Overview
    • System Flow & Object Lifecycle
    • FAQ & Troubleshooting
    • Further Reading
  • Collision Detection Broad-Phase Details: Spatial Hash Grid
    • Cell Size & Grid Mapping
    • AABB Caching
    • Neighbor Search Patterns
    • Multi-Cell Registration
    • Movement-Based Optimization
    • Incremental Updates
    • See Also
  • Collision Detection Narrow-Phase Details
    • Narrow-Phase Details: PyBullet APIs
    • Collision Mode Details
    • Implementation & Configuration
    • See Also

Other Subsystems

  • Real-time Synchronization Design
    • Overview
    • Design Philosophy
    • Core Algorithm
    • Pause/Resume Handling
    • RTF Multiplier Support
    • Best Practices
Previous Next

© Copyright 2026, Yu Okamoto.

Built with Sphinx using a theme provided by Read the Docs.