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
      • How this tutorial relates to the runnable demo
      • 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 (standalone API example)
      • 7. Setting a Goal Pose (Smooth Movement)
      • 8. Periodic Logic with Callbacks
      • 9. Controlling Arm Joints
      • 10. Running the Simulation
      • Run the complete 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. Two Fleet Concepts, Two Layers
      • 3. Load, Adapt, and Instantiate Config
      • 4. Declare Named Managers in Config
        • fleet_controller — execution type and shared parameter defaults
        • Controller vs command interface
        • Alternative: Python API
      • 5. Build a Path and Assign it to an Agent
      • 6. Assign Individual Paths to All 100 Agents
      • 7. Write a Monitoring Callback
      • 8. Camera Setup
      • 9. 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_model & Model Catalog
      • 1. Loading Robots by Name
      • 2. How resolve_model() 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
    • Tutorial 7: SDF and Mesh Assets
      • Run the demo
      • Load an SDF asset
      • Load mesh files in bulk
      • See also
    • Tutorial 10: OpenUSD Static Worlds
      • Isaac Sim asset-pack examples
    • Tutorial 8: Event Bus
      • Run the demo
      • Built-in events
      • Choosing the event scope
      • Registration, order, and cleanup
      • Custom events
      • Handler rules
      • See also
    • Tutorial 9: Plugins
      • Run the demo
      • Choose the plugin scope
      • Simulation plugin lifecycle
      • Per-agent plugins
      • Step-order rule
      • See also
    • Tutorials
    • Run bundled examples
    • Switching Robot Models with --robot
    • API Quick-Reference
  • Architecture
    • PyBulletFleet - Design Documentation
      • Architecture Overview
      • Core Components
        • 1. core_simulation.py
        • 2. sim_object.py
        • 3. agent.py
        • 4. controller.py and fleet execution
        • 5. agent_manager.py
        • 6. sim_plugin.py, agent_plugin.py, and events.py
        • 7. action.py
        • 8. geometry.py
        • 9. tools.py
        • 10. World, asset, and device loading
        • 11. data_monitor.py and recorder.py
        • 12. robot_models.py
      • Performance Considerations
        • Bottlenecks:
        • Optimizations:
    • Two-Phase Step
      • Design rationale
      • Two-phase pose commit in the full step timeline
      • set_pose() behaviour: buffered vs immediate
        • Rule of thumb
        • Which time a pose belongs to
        • Frequency-limited handlers
        • What Phase 1 does not promise
      • Profiling
      • See also
      • Owned navigation replay sessions
    • Plugins and Events
      • Choose the extension point
      • Plugin lifecycle
      • EventBus contract
      • Per-step hooks
      • Step-order and pose rule
      • Related public examples
    • Batch Execution
      • Ownership and lifecycle
      • What remains per-agent
      • Extension contract
      • User-facing configuration
    • Fleet API Architecture
      • Components
      • Command flow
      • Transport mappings
      • Developer rules
      • Opt-in replay execution boundary
    • 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
        • Standard step ordering
      • 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
      • Registration and Candidate Search
      • 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 - No Clearance in Z (Deprecated)
        • STATIC - Fixed Objects
        • DISABLED - No Collision
        • Runtime Mode Changes
      • Implementation & Configuration
        • SimulationParams
        • Per-Object Configuration
        • Config File (YAML)
        • Auto-Selection Logic
        • Ignoring Expected Contact
        • 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 ✅
      • Relationship to Simulation Steps
      • Maximum-Speed Mode
      • See Also
  • How-to Guides
    • Collision Configuration Guide
      • Quick Decision Guide
      • Read collision observations
      • Try the visual collision demo
      • Collision Detection Method
        • Configuration
        • Auto-Selection
      • Per-Object Collision Mode
        • Setting via AgentSpawnParams
        • Setting via SimObject
        • Runtime Mode Changes
      • Collision Margin
        • Per-axis clearance
      • Spatial Hash Cell Size
        • Mode 1: auto_initial (Default — Recommended)
        • Mode 2: constant (Fixed)
        • Mode 3: auto_adaptive (Dynamic)
        • Manual Recalculation
        • Recalculation Behavior
      • Multi-Cell Threshold
      • Static-Collision Filter
      • Complete YAML Reference
      • See Also
    • Controller Configuration
      • Choose a controller
        • Accepted controller forms
      • Controller chains
      • motion_mode compatibility
      • ControllerParams
        • A new goal while moving
        • Stopping: brake() and stop()
        • Path requests and the action queue
        • Stopping on a collision
      • Batch controllers
        • Python API
        • YAML: named managers
        • Custom batch controllers
      • See also
    • Custom Class Profiling Guide
      • Start with built-in timing
      • Add named custom fields
        • Custom Agent
        • Callback or plugin work
        • Programmatic timing results
      • Function-level profiling with cProfile
      • Per-agent measurements
      • Compare a custom agent with the base class
      • 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
    • Supported kinematic recording and restore (development)
    • Run the synthetic fleet corridor evaluation
      • Watch a policy in the GUI
    • Run the one-sided corridor traffic experiment
    • Time Profiling User Guide
      • Overview
        • ROS 2 Bridge state publication
      • 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
        • Return value fields
        • Example: per-step CSV logging
        • Latest completed result during run_simulation()
      • Best Practices
      • Troubleshooting
        • No profiling output appears
        • Output appears too frequently / infrequently
      • Benchmark scripts
      • 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
        • Illustrative Stable Trend
        • Illustrative Growth Requiring Investigation
      • References
    • Logging
      • Configure Simulation Logs
        • Application integration
      • Write Efficient Logs in Custom Code
      • Lazy Logger APIs
        • Module-level logger
        • Instance-level logger with a prefix
      • Choosing an Approach
      • Verify Changes
      • See Also
  • Configuration
    • Configuration Reference
      • Simulation
        • Profiling
        • Collision and visualisation
        • Camera
        • GUI lighting
      • World
      • Entity classes and entities
        • Grid entities
        • Controller selection
      • Named managers and fleet controllers
      • Plugins
      • Defaults and environment overrides
      • Included configurations and benchmarks
      • See Also
  • Benchmarking
    • Performance Optimization Guide
      • Optimisation workflow
      • Pacing and timestep
      • Controllers and command ingress
      • Collision work
      • Rendering, monitors, and profiling
      • Diagnose common bottlenecks
      • Reproducible measurements
      • See Also
    • Benchmark Results Reference
      • Test Environment
      • Simulation Throughput
      • ROS 2 Bridge Scale Check
        • Manager-Scoped State Check
      • Mobile Control Path Comparison
      • 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
      • Reading Benchmark Results
      • 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
        • Scenarios (general.yaml)
      • 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 Example
        • When to Use Which Method
      • Goal Setting Profiler (agent_manager_set_goal.py)
        • CLI Usage
        • Reading Output
      • Typical Bottlenecks and Fixes
        • 1. Collision check is a material part of the measured step
        • 2. Agent update dominates the measured step
        • 3. Goal setup is slow for the target fleet size
      • 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
      • Goal Replacement Experiments
        • goal_replacement_cost.py
      • Collision Detection Experiments
        • collision_methods_config_based.py
        • collision_method_comparison.py
        • collision_mode_comparison.py
        • Output Example
  • Testing
    • Tests
      • Everyday Checks
      • Targeted Core Tests
      • What the Core Suite Covers
      • Fixtures and Test Isolation
      • ROS 2 and Open-RMF Checks
      • Manual GUI Checks
  • ROS 2 Bridge and Open-RMF
    • Run Your First ROS 2 Bridge
      • 1. Install PyBulletFleet
      • 2. Add the Jazzy APT preview
      • 3. Run the TurtleBot3 demo
      • 4. Run a Fleet ROS demo
        • Alternative: configurable single fleet
      • Optional: fleet smoke test
      • Docker alternative
    • ROS 2 Demo Catalog
      • TurtleBot3
      • Navigation
      • Panda arm
      • Attach and detach
      • Configurable Fleet ROS demo
      • Multi-manager Fleet ROS demo
      • Docker-only model catalog
    • Bridge Interfaces
      • ROS communication patterns
      • Per-robot API
      • Fleet ROS API
        • Agent scope
      • Simulation services
        • Choose the control boundary
        • Dynamic spawning
      • Scale guidance
    • Bridge Configuration
      • Exported API groups
        • Limit per-robot interfaces to controlled robots
        • Manager-scoped Fleet API endpoints
      • Common deployment choices
      • Configuration files and assets
    • Run Your First RMF Demo
      • 1. Install the RMF adapter package
      • 2. Add rmf_demos to a workspace
      • 3. Optional: start RMF Web without building a PyBulletFleet image
      • 4. Run an office patrol
      • Full Docker alternative
    • Open-RMF Integration
      • RMF client modes
      • Two independent choices
      • Supported scenarios and task behavior
      • Run and validate
    • RMF Demo Catalog
      • Scenarios
      • Native Jazzy
        • Native simulator with RMF Web containers
      • Docker
        • Full RMF Web stack
      • Dispatch Examples
    • Choose an environment
    • Start here
    • Which control path should I use?
  • API Reference
    • pybullet_fleet package
      • Subpackages
        • pybullet_fleet.controllers package
        • pybullet_fleet.devices package
        • pybullet_fleet.plugins package
      • Submodules
      • pybullet_fleet.action module
      • pybullet_fleet.action_parser module
      • pybullet_fleet.agent module
      • pybullet_fleet.agent_manager module
      • pybullet_fleet.agent_plugin module
        • Registry
      • pybullet_fleet.camera_controller module
      • pybullet_fleet.cli module
      • pybullet_fleet.collision_visualizer module
      • pybullet_fleet.commands module
      • pybullet_fleet.config_utils module
      • pybullet_fleet.controller module
        • Hierarchy
        • Mode state machine (B3 — input-based + interruption)
        • Registry
      • pybullet_fleet.controller_params module
        • Design rationale
      • pybullet_fleet.core_simulation module
      • pybullet_fleet.data_monitor module
      • pybullet_fleet.entity_registry module
      • pybullet_fleet.events module
      • pybullet_fleet.fleet_api module
      • pybullet_fleet.geometry module
      • pybullet_fleet.logging_utils module
      • pybullet_fleet.path_request module
      • pybullet_fleet.plugin_utils module
      • pybullet_fleet.recorder module
      • pybullet_fleet.robot_models module
      • pybullet_fleet.sdf_loader module
      • pybullet_fleet.sim_object module
      • pybullet_fleet.sim_plugin module
      • pybullet_fleet.states module
      • pybullet_fleet.tools module
      • pybullet_fleet.types module
      • pybullet_fleet.world_loader module
      • Module contents
    • Full Module Reference
    • User-Facing API
    • Advanced and Developer Modules
  • Roadmap
    • Assets
    • Simulation Capabilities
      • Crowd Simulation (lightweight)
        • Crowd-as-dynamic-obstacle throughput benchmark
      • Devices
    • RMF Demo Feature Coverage
    • Interfaces
    • Refactoring
    • GUI / Interactive Tools
    • Performance
      • Two-Phase Pose Commit: Decouple Computation from PyBullet C API ✅ (batch controller path)
      • Vectorized Agent Update (NumPy Batch) ✅
      • C++ Extensions for Hot-Path Functions
      • Deferred AABB Update
    • SDF & DAE Support Improvements
      • SDF → URDF Conversion: gz sdf -p Replacement
      • DAE → OBJ Automatic Conversion
      • Multi-material mesh textures (per-material visuals)
      • Priority
    • Environments
    • CI / DevOps
    • Observability
    • Long-Term: Backend Abstraction & Beyond PyBullet
      • Short / Mid-Term Performance TODOs
      • 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
  • Configuration
  • View page source

Configuration

  • Configuration Reference
    • Simulation
    • World
    • Entity classes and entities
    • Named managers and fleet controllers
    • Plugins
    • Defaults and environment overrides
    • Included configurations and benchmarks
    • See Also
Previous Next

© Copyright 2026, Yu Okamoto.

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