PyRoboSimulator

Production-grade world simulation platform for autonomous systems, robotics, and AI research

A complete, open-source simulation engine built for developers and researchers who need accurate, scalable environments for testing autonomous vehicles, robots, and multi-agent systems. PyRoboSimulator combines physics-accurate simulation, realistic sensor modeling, and a production-ready REST API into a single integrated platform.

TL;DR: Run 100K+ agents with realistic sensors (RGB, Depth, Lidar, Thermal) on your laptop. Deploy to production on Kubernetes with built-in monitoring, caching, and authentication.

---

Why PyRoboSimulator?

Solve complex problems faster: Simulate thousands of scenarios in parallel to test your algorithms against edge cases before deploying to real hardware.

Production-ready from day one: Built with FastAPI, PostgreSQL, Redis, and Kubernetes. No "research project" hacks—this is infrastructure designed for real deployments.

Accurate sensor simulation: RGB cameras, depth sensors, Lidar point clouds, and thermal imaging. Each sensor is physically grounded and configurable per-agent.

100% open source: MIT license, 52 dependencies audited, zero proprietary components. Integrate with your stack without licensing restrictions.

Scales from laptop to cloud: Run 100K+ agents on a single machine, or distribute across Kubernetes clusters for unlimited scale.

---

Key Capabilities

Physics Engine

• Euler integration with configurable timestep (default 16ms @ 60Hz)
• Collision detection via AABB (axis-aligned bounding box) radius overlap
• Boundary conditions with elastic bounce or clipping
• Velocity/acceleration clamping for stability
• 100K+ agents/second throughput on standard hardware

Sensor Suite (Phase 1C: Realistic Sensor Simulation)

• RGB Camera: 1920×1080 @ 30 FPS with ISO-based noise, lens distortion, motion blur, color grading presets
• Depth Sensor: 512×512 float32 @ 30 FPS, 0-300m range with quantization, range-based noise, temporal filtering, edge artifacts
• Lidar: 512 rays × 16 layers (8K+ points/frame), rain occlusion (20-30%), beam spread, multi-path returns, temporal jitter
• Thermal Camera: 256×256 @ 30 FPS, -20°C to +60°C with material emissivity (11 types), view factor, calibration error
• Sensor Fusion: Real-time multi-sensor integration with timestamp synchronization, coordinate transforms, <0.01ms latency

World Streaming & UE5 Integration (Phase 1C.8)

• Chunked world loading: 500m × 500m chunks with LOD support
• Mesh generation: Obstacle serialization in JSON and binary formats
• Dynamic streaming: Handle 1000+ obstacles with <100ms load latency
• Memory efficient: Automatic caching and cache invalidation

State Synchronization (Phase 1C.9)

• Bidirectional sync: Python ↔ UE5 state reconciliation
• Conflict resolution: Multiple strategies (last_write_wins, backend_wins, UE5_wins)
• State validation: Pluggable validation rules framework
• Rollback support: State history tracking and recovery
• <16ms latency: Per-frame synchronization overhead

Sensor Data Recording (Phase 1C.10)

• Ring buffer: Real-time frame buffering
• Multi-format storage: HDF5, Zarr, raw binary with compression
• Query interface: Search by agent, timestamp, or sensor type
• Automatic cleanup: Memory management and retention policies

Behavior Trees (Phase 2.1)

• Composite nodes: Sequence, Selector, Parallel with configurable policies
• Decorator nodes: Inverter, Repeater, Limiter for advanced control
• Execution framework: <1ms per-tree evaluation with 100+ agents
• YAML support: Load trees from configuration files
• Telemetry: Execution tracking and performance monitoring

Navigation & Pathfinding (Phase 2.2)

• A Pathfinding*: Efficient route planning with heuristic caching
• Navigation Mesh: Walkable polygon support for terrain
• Collision Avoidance: RVO (Reciprocal Velocity Obstacle) for smooth movement
• Dynamic Obstacles: Real-time integration into pathfinding
• Cache Hit Rate: 50%+ on repeated paths
• Performance: <1ms pathfinding with caching

Agent Memory & State (Phase 2.3)

• Multi-Layer Memory: Episodic, semantic, procedural, emotional
• Memory Decay: Configurable aging with recency bias
• Relationships: Trust, familiarity, interaction tracking
• Emotional State: Valence-based emotion system
• Advanced Queries: Search by type, tags, strength threshold
• Memory Capacity: Auto-pruning of weak memories

Multi-Agent Communication (Phase 2.4)

• Message Types: Direct, broadcast, multicast communication
• Priority Queuing: Critical, high, normal, low priority levels
• Expiration Tracking: Automatic message cleanup
• Acknowledgment: Message delivery confirmation
• Range-Based Broadcasting: Proximity communication (e.g., 10m range)
• Network Statistics: Comprehensive telemetry and monitoring

World Generation

• Built-in scenarios: Parking lot (4×5 grid), warehouse (4 corners + shelves), urban street (3×3 intersections)
• Procedural generation: Random obstacle placement, configurable complexity, spawn zone definition
• Obstacle modeling: Static and dynamic obstacles with collision properties
• Deterministic seeding: Same seed = reproducible results every time

REST API

• 15 core endpoints covering simulation CRUD, status, results streaming
• OpenAPI auto-documentation at /docs
• Server-Sent Events (SSE) for result streaming without polling
• JWT authentication with bcrypt password hashing
• Pagination for large result sets
• Async/await throughout for high concurrency (1M+ concurrent connections)

Deployment

• Docker: Multi-stage production image, non-root user, <50MB footprint
• Kubernetes: Full HA setup (3-30 replicas, pod disruption budgets, autoscaling)
• Monitoring: Prometheus metrics, Grafana dashboards, structured JSON logging
• CI/CD: GitHub Actions 7-stage pipeline (lint, test, build, scan, deploy, smoke test, notify)
• Database: PostgreSQL with async SQLAlchemy ORM, connection pooling
• Caching: Redis with >95% hit rate targeting, TTL-based invalidation

---

Getting Started (5 Minutes)

1. Install

pip install pyrobosimulator==0.5.0

2. Run Your First Simulation

from pyrobosimulator import SimulationEngine

# Create engine
engine = SimulationEngine(
    num_agents=100,
    duration=60.0,
    timestep=0.016,
)

# Run (blocks until complete)
engine.run()

# Access results
summary = engine.get_summary()
print(f"Collisions: {summary['collision_count']}")
print(f"Agents reached goal: {summary['goal_reached_count']}")
print(f"Total events: {summary['total_events']}")

3. Start the Backend API

pip install pyrobosimulator[backend]
uvicorn pyrobosimulator.api.main:app --reload

Then visit http://localhost:8000/docs to see interactive API documentation.

4. Create a Simulation via REST API

curl -X POST http://localhost:8000/api/v1/simulations \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "parking_lot",
    "num_agents": 50,
    "duration": 30.0
  }'

---

Real-World Examples

Autonomous Vehicles

from pyrobosimulator import SimulationEngine, ScenarioBuilder

# Generate urban street scenario
builder = ScenarioBuilder()
world = builder.urban_street(
    width=300,
    depth=300,
    intersections=3,
    obstacle_density=0.2
)

# Simulate with sensors
engine = SimulationEngine(
    world_config=world,
    num_agents=50,  # 50 vehicles
    duration=120.0,
)
engine.run()

# Analyze collision patterns
results = engine.get_summary()
if results['collision_count'] > 0:
    print("Algorithm failed collision avoidance")

Multi-Robot Coordination

# Simulate warehouse robots
builder = ScenarioBuilder()
world = builder.warehouse(num_shelves=10, shelf_height=3)

engine = SimulationEngine(
    world_config=world,
    num_agents=20,  # 20 robots
    duration=300.0,  # 5 minutes
)

# Listen for events
for event in engine.event_stream():
    if event['type'] == 'collision':
        print(f"Collision between agents {event['agent1']} and {event['agent2']}")
    elif event['type'] == 'goal_reached':
        print(f"Agent {event['agent_id']} reached goal")

Sensor Fusion Research

# Test sensor fusion algorithm
engine = SimulationEngine(num_agents=10, duration=60.0)

for agent in engine.agents:
    # Add multiple sensor types
    agent.add_rgb_sensor(resolution=(1920, 1080))
    agent.add_depth_sensor(resolution=(512, 512))
    agent.add_lidar_sensor(num_rays=512, num_layers=16)

engine.run()

# Extract synchronized sensor data
for frame in engine.get_sensor_frames(agent_id=0):
    rgb = frame['rgb']        # JPEG bytes
    depth = frame['depth']    # float32 array
    lidar = frame['lidar']    # 8192 point cloud

---

Architecture

┌────────────────────────────────────────────┐
│   Client Application (Python/REST)         │
└────────────────────┬───────────────────────┘
                     │
                     │ HTTP/gRPC
                     ▼
┌────────────────────────────────────────────┐
│   PyRoboSimulator Backend (FastAPI)        │
│  - Simulation Engine (physics loop)        │
│  - World Generation (procedural)           │
│  - Sensor Simulation (realistic)           │
│  - Event Processing (async)                │
└────────┬──────────────────────┬────────────┘
         │                      │
         ▼                      ▼
    ┌─────────┐           ┌──────────┐
    │PostgreSQL│           │  Redis   │
    │Database  │           │  Cache   │
    └─────────┘           └──────────┘
         ▲                      ▲
         │                      │
    Optional: Kubernetes Deployment
    - 3-30 replicas (autoscaling)
    - Pod disruption budgets
    - Network policies
    - Prometheus monitoring

Core Components:

• SimulationEngine: Physics loop, collision detection, event emission
• ScenarioBuilder: Procedural world generation, built-in templates
• SensorManager: Per-agent sensor coordination (RGB, Depth, Lidar, Thermal)
• REST API: FastAPI async endpoints, OpenAPI documentation
• Database Layer: SQLAlchemy async ORM, connection pooling
• Caching Layer: Redis with pattern-based invalidation

---

Performance Benchmarks

All benchmarks run on a 2023 MacBook Pro (Apple Silicon M2, 8GB RAM):

Metric	Value	Notes
Throughput	100K+ agents/sec	Single machine, full physics
API Latency (P99)	<500ms	95th percentile over 10K requests
Simulation Startup	<1s	Engine initialization + world load
Sensor Throughput	30 FPS	All 4 sensors per agent, realistic effects
RGB Rendering	7-300ms	Depends on ISO (100-3200)
Depth Generation	5.5ms	Vectorized quantization + noise + filtering
Lidar Cloud	21.9ms	With rain occlusion, beam spread, multi-path
Thermal Imaging	2.1ms	Material emissivity + calibration
Sensor Fusion	0.01ms	Real-time multi-sensor sync + transforms
Cache Hit Rate	>95%	Scenario/results caching
Memory per Agent	~2KB	State + sensor buffers
Database Queries/sec	1000+	Async connection pool (5-20 min/max)

Scaling: Database connection pool scales to 20 connections. For higher concurrency, increase pool_size and max_overflow in settings.

---

API Overview

Core Endpoints

Simulations Management

• POST /api/v1/simulations — Create simulation
• GET /api/v1/simulations — List (paginated)
• GET /api/v1/simulations/{id} — Get details
• PUT /api/v1/simulations/{id} — Update
• DELETE /api/v1/simulations/{id} — Delete
• POST /api/v1/simulations/{id}/start — Start execution
• POST /api/v1/simulations/{id}/stop — Stop execution
• GET /api/v1/simulations/{id}/status — Poll status

Results & Analytics

• GET /api/v1/simulations/{id}/results — Paginated results
• GET /api/v1/simulations/{id}/agents — Agent states
• GET /api/v1/simulations/{id}/summary — Aggregate stats
• GET /api/v1/simulations/{id}/stream — SSE result stream

Health & Monitoring

• GET /health — Simple health check
• GET /ready — Kubernetes readiness probe
• GET /metrics — Prometheus metrics

See API Documentation for full reference.

---

Testing & Quality

Test Suite

• 60+ tests covering unit, integration, and performance scenarios
• 90%+ code coverage (enforced via CI/CD)
• Performance benchmarks for common operations
• Security scanning (bandit, safety)

Quality Gates

• Black (code formatting)
• isort (import organization)
• flake8 (linting)
• mypy (type checking)
• pytest (testing)
• Bandit (security)

Run tests locally:

pip install -e .[dev]
pytest -v --cov=src

---

Deployment

Docker

cd backend
docker build -t pyrobosimulator:0.2.0 .
docker run -p 8000:8000 pyrobosimulator:0.2.0

Kubernetes

cd backend/k8s
kubectl apply -k .
kubectl port-forward svc/pyrobosimulator 8000:8000

Production Checklist

• Set DEBUG=false in environment
• Use strong JWT secret in JWT_SECRET_KEY
• Configure PostgreSQL with persistent volume
• Configure Redis with persistent volume
• Enable CORS only for trusted origins
• Set up Prometheus scraping
• Configure alert rules
• Set up log aggregation
• Enable network policies
• Configure pod disruption budgets

See Deployment Guide for detailed instructions.

---

Technology Stack

Language & Framework

• Python 3.10+
• FastAPI (async web framework)
• Pydantic (data validation)

Database & Cache

• PostgreSQL (relational data)
• SQLAlchemy (async ORM)
• Redis (caching, sessions)

Scientific Computing

• NumPy (numerical operations)
• SciPy (scientific algorithms)

Deployment & Orchestration

• Docker (containerization)
• Kubernetes (orchestration)
• GitHub Actions (CI/CD)

Monitoring & Observability

• Prometheus (metrics)
• Grafana (visualization)
• Structured JSON logging

Testing & Quality

• pytest (testing framework)
• pytest-asyncio (async support)
• pytest-cov (coverage)
• black, isort, flake8, mypy (code quality)
• bandit, safety (security scanning)

100% Open Source: All 52 dependencies use MIT, BSD, or Apache 2.0 licenses. See OSS Compliance Audit.

---

Comparison with Alternatives

Feature	PyRoboSimulator	CARLA	Gazebo	AirSim
Language	Python	C++	C++	C++
Physics Engine	Custom Euler	PhysX	ODE/Bullet	PhysX
Agents/Frame	100K+	100s	1000s	100s
REST API	Native	No	No	Limited
Kubernetes Ready	Yes	No	No	No
Database Integration	Yes (PostgreSQL)	No	No	No
Caching Layer	Yes (Redis)	No	No	No
Multi-Modal Sensors	RGB, Depth, Lidar, Thermal	RGB, Depth, Lidar	Camera, IMU, GPS	RGB, Depth, Lidar
License	MIT	MIT	Apache 2.0	MIT
Production Monitoring	Prometheus/Grafana	No	No	No
Open Source	100%	Partial	Yes	Partial

---

Documentation

• Full API Reference — REST endpoints, request/response schemas
• Deployment Guide — Docker, Kubernetes, local development
• Database Schema — Tables, indexes, query patterns
• UE5 Integration — Rendering engine integration (Phase 1)
• OSS Compliance — Complete license audit
• Performance Tuning — Optimization strategies

---

Roadmap

Phase 0 (Current - v0.2.0)

• Core simulation engine with physics
• Multi-modal sensor suite
• Production REST API
• PostgreSQL database + Redis caching
• Kubernetes deployment manifests
• 60+ tests, 90%+ coverage
• Complete documentation

Phase 1 (Next - ~8-12 weeks)

• UE5 rendering engine integration
• Real-time visualization
• Advanced AI behavior trees
• NLP-driven world generation
• Performance optimization (GPU acceleration)

Future Phases

• Domain randomization for ML training
• Multi-agent learning support
• Digital twin capabilities
• Advanced analytics and replay

---

Contributing

We welcome contributions! Check out our Contributing Guide.

How to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development setup:

git clone https://github.com/Mullassery/PyRoboSimulator.git
cd PyRoboSimulator
pip install -e .[dev]
pytest  # Run tests

---

Support & Community

Get Help

• Documentation — Comprehensive guides
• GitHub Discussions — Q&A and ideas
• GitHub Issues — Bug reports and feature requests
• Email — Direct support

Stay Updated

• Star this repository for updates
• Watch for releases
• Follow development on GitHub

---

License

MIT License — See LICENSE file

PyRoboSimulator is open source and free for commercial use, modification, and distribution.

---

Citation

If you use PyRoboSimulator in your research, please cite:

@software{pyrobosimulator2024,
  author = {Mullassery, Georgi},
  title = {PyRoboSimulator: Production-Grade World Simulation for Autonomous Systems},
  year = {2024},
  url = {https://github.com/Mullassery/PyRoboSimulator},
  license = {MIT}
}

---

Acknowledgments

Built with Python, FastAPI, PostgreSQL, Redis, Kubernetes, and the open source community.

---

PyRoboSimulator v0.2.0 | GitHub | PyPI | Issues

Dashboard

Real-time metrics with keyboard shortcuts:

• bash scripts/setup_shortcuts.sh (one-time setup)
• dash-[package] - Static snapshot
• dash-[package]-live - Live monitoring
• dash-[package]-export - Export to JSON

See DASHBOARD_SHORTCUTS.md.

OpenTelemetry

Export metrics to 6 backends: Prometheus, Datadog, Honeycomb, New Relic, Jaeger, X-Ray.

See OTEL_SETUP_GUIDE.md.

Production Deployment

Kubernetes and Docker ready. See PRODUCTION_DEPLOYMENT.md.