PyBulletFleet

Contents

  • Quick Start
    • Prerequisites
    • Installation
      • From PyPI (recommended)
      • From source (for development)
    • Running Your First Simulation
    • YAML Configuration Basics
    • Keyboard Controls
    • Examples
      • Basics (examples/basics/)
      • Arm (examples/arm/)
      • Mobile (examples/mobile/)
      • Scale (examples/scale/)
      • Models (examples/models/)
    • Next Steps
  • Examples
    • 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
        • Understanding mass and Kinematic Mode
      • 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
        • Scale Demos
        • Switching Robot Models
      • Performance Notes
      • See Also
    • Tutorial 4: Robot Arm — Joint Control & Pick/Drop
      • 1. Fixed-Base Arm Setup
      • 2. Kinematic vs Physics Joint Control
        • Performance
      • 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
        • Tolerance
        • Prismatic (linear) joints
      • 8. Running the Demos
        • Switching Robot Models
      • See Also
    • Tutorial 5: End-Effector Control — IK & PoseAction
      • 1. Why EE Position Control?
      • 2. Direct EE Control: move_end_effector()
        • With Orientation
        • Checking Convergence
      • 3. PoseAction — EE Control in the Action Queue
      • 4. EE-Based Pick & Drop
      • 5. Tuning IK with IKParams
      • 6. Mobile Manipulator IK
        • Explicit control with ik_joint_names
        • drop_relative_pose — Relative Drop Positioning
      • 7. Low-Level Callback Approach
      • 8. Running the Demos
        • Switching Robot Models
      • 9. Prismatic Joints & Rail Arms
      • API Summary
      • See Also
    • Tutorial 6: Robot Models — resolve_urdf & Model Catalog
      • 1. Loading Robots by Name
      • 2. How resolve_urdf() Works
      • 3. Listing All Models
        • Local Models (project robots/ directory)
        • Third-Party Models
      • 4. Auto-Detecting Robot Capabilities
      • 5. Using Third-Party Models
        • Registered models (in KNOWN_MODELS)
        • Auto-discovery of unlisted models
        • When auto-discovery isn’t enough
        • Installing robot_descriptions
      • 6. Runnable Demos
        • The --robot Argument
      • 7. Custom Search Paths
        • API
    • Tutorials
    • Switching Robot Models with --robot
    • 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
        • 8. robot_models.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
    • Capturing Demo Videos
      • Capture Pipeline Overview
      • Python API
      • Environment Variable
      • Batch Capture Scripts
        • Headless Capture — capture_demo.py
        • GUI Screen Capture — capture_screen_demo.py
        • Parameter resolution (3-layer merge)
        • Per-demo delay
        • demos.yaml Format
        • Output
    • 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
      • Centralized Default Management (_defaults.py)
        • Override priority
        • Using defaults in your code
      • 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)
      • 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
    • Performance
      • Profiling Baseline (measured 2026-04-03)
      • Two-Phase Step: Decouple Computation from PyBullet C API
      • Vectorized Agent Update (NumPy Batch)
      • C++ Extensions for Hot-Path Functions
      • Deferred AABB Update
      • Summary: Expected Impact (500 agents, measured baseline)
    • Environments
    • CI / DevOps
    • Long-Term: Backend Abstraction & Beyond PyBullet
      • Phase 1: SimBackend ABC + Numpy Pure Kinematic Backend
      • Phase 2: Native Backend (Rust/C++ via PyO3/pybind11)
      • Phase 3: GPU Backend (optional)
      • Phase 4: ECS Architecture (v2.0 candidate)
PyBulletFleet
  • Search

© Copyright 2026, Yu Okamoto.

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