🎬 Watch Demo Video 🎬
A next-generation, AI-powered smart grid simulation platform integrating power flow analysis, traffic simulation, electric vehicles, and intelligent Vehicle-to-Grid (V2G) energy management.
Features • Quick Start • Documentation • Demo • Team
- Natural Language Interface: Control the entire grid using conversational commands
- OpenAI GPT Integration: Advanced natural language understanding with typo correction
- Real-time Command Execution: Instant response to operator requests
- Scenario Orchestration: Execute complex multi-step scenarios with cinematic camera movements
- Smart Suggestions: Context-aware recommendations based on grid state
Example Commands:
"start vehicles"
"show charging near Times Square"
"run v2g scenario"
"fail Times Square substation"
"activate v2g for Broadway"
"show me the power grid status"
- PyPSA Integration: Real-time DC power flow analysis with millisecond precision
- 8 Manhattan Substations: Realistic NYC power infrastructure modeling
- Multi-Voltage Distribution: 13.8kV primary and 480V secondary systems
- Dynamic Load Balancing: Intelligent load redistribution during failures
- Cascading Failure Detection: Automatic identification and mitigation
- Eclipse SUMO Integration: Industry-standard traffic simulation
- Smart Battery Management: SOC-based routing and charging decisions
- Real-time Fleet Tracking: Live monitoring of 1000+ vehicles
- Charging Infrastructure: 24 strategically placed EV charging stations
- Autonomous Routing: Vehicles automatically find charging when needed
- Bidirectional Energy Flow: EVs provide emergency backup power
- Automatic Emergency Response: Instant V2G activation during grid failures
- Dynamic Market Pricing: Real-time energy trading optimization
- Revenue Tracking: Individual earnings for each participating vehicle
- Smart Vehicle Selection: AI-powered selection of optimal V2G participants
- V2G Emergency Rescue: Dramatic demonstration of V2G saving the grid
- Citywide Blackout: Cascading failure with emergency recovery
- Automated Camera Control: Cinematic views of key events
- Live Narration: Real-time commentary during scenario execution
- Interactive Confirmations: User-controlled scenario progression
- GPU-Accelerated Rendering: WebGL-based rendering for 1000+ vehicles at 144 FPS
- Mapbox Integration: High-quality interactive Manhattan map
- Glassmorphic Design: Modern, premium UI/UX with blur effects
- Real-time Performance Stats: Live FPS, vehicle count, and update metrics
- Multi-tab Dashboard: Organized interface for grid, V2G, and ML analytics
- Responsive Controls: Optimized for desktop and large displays
- Demand Prediction: LSTM-based load forecasting
- Pattern Recognition: Historical demand analysis
- Grid Optimization: AI-powered efficiency recommendations
- Predictive Maintenance: Early failure detection
- Real-time Insights: Live ML-powered analytics
- Substation Control: Click to fail/restore substations
- EV Station Visualization: Real-time charging station status
- Traffic Light Integration: Dynamic traffic light control during outages
- Vehicle Highlighting: Track individual vehicles by ID
- Route Visualization: See vehicle paths and destinations
- Layer Toggles: Show/hide substations, EV stations, traffic lights
Natural language commands directly control map visualization and grid operations:
| Command Example | Action on Map | Visual Result |
|---|---|---|
 |
"Fail Times Square" | Substation turns red, traffic lights yellow |
 |
"Blackout scenario" | Multiple substations fail, citywide impact |
 |
"Run V2G scenario" | Cinematic camera + V2G emergency response |
The AI chatbot understands natural language and translates commands into real-time map actions and grid operations.
- Python 3.8+ (Download)
- SUMO 1.15.0+ (Download)
- 8GB RAM (16GB recommended for 500+ vehicles)
- OpenAI API Key (for chatbot functionality)
- Mapbox Token (for map visualization)
-
Clone the repository
git clone https://github.com/XGraph-Team/Map-LLM.git cd Map-LLM -
Set up SUMO
# Windows set SUMO_HOME=C:\Program Files (x86)\Eclipse\Sumo # Linux/Mac export SUMO_HOME=/usr/share/sumo
-
Create virtual environment
python -m venv venv # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate
-
Install dependencies
pip install -r requirements.txt
-
Configure environment
Create a
.envfile in the project root:OPENAI_API_KEY=your_openai_api_key_here MAPBOX_TOKEN=your_mapbox_token_here FLASK_ENV=development
-
Run the application
python main_complete_integration.py
-
Open your browser
http://localhost:5000
-
Launch the Application
- Open
http://localhost:5000in Chrome/Edge (recommended for WebGL) - Wait for the map to load
- The chatbot window opens automatically
- Open
-
Start the Simulation
- Type
start vehiclesin the chatbot - Or click "Start Vehicles" button in the control panel
- 50-100 vehicles will spawn with realistic battery levels
- Type
-
Explore the Interface
- Grid Tab: View power grid status and substations
- V2G Tab: Monitor V2G sessions and earnings
- ML Tab: Access machine learning analytics
- Performance Overlay: Top-left corner shows FPS and metrics
start vehicles - Spawn 50 vehicles (also: "spawn vehicles", "create vehicles")
start 100 vehicles - Spawn specific number of vehicles
highlight vehicle_0 - Highlight and track a specific vehicle
fail Times Square - Trigger substation failure
restore Times Square - Restore failed substation
show substation status - Display all substation states
activate v2g - Enable V2G for failed substations
activate v2g for Broadway - Enable V2G for specific substation
show v2g status - Display active V2G sessions
show charging near Times Square - Highlight EV stations near substation
show all charging stations - Display all EV stations
run v2g scenario - Execute V2G emergency rescue scenario
blackout scenario - Trigger citywide blackout scenario
confirm - Confirm scenario execution
analyze grid - Get AI-powered grid analysis
predict demand - Show ML demand predictions
system status - Comprehensive system report
- Type
run v2g scenarioin chatbot - Review the scenario description
- Type
confirmto execute - Watch the cinematic presentation:
- Camera automatically moves to Times Square
- Substation fails with emergency alert
- V2G system activates automatically
- Vehicles respond and provide power
- System stabilizes and shows summary
- Top-left overlay shows:
- FPS (green >60, yellow >30, red <30)
- Vehicle count
- Update time (ms)
- Render time (ms)
- Rendering mode (WEBGL)
- Click substations: Toggle failure state
- Click EV stations: View charging status
- Zoom/Pan: Explore Manhattan grid
- Toggle layers: Show/hide different elements
Frontend:
├── Mapbox GL JS - Interactive mapping
├── WebGL - GPU-accelerated rendering
├── Vanilla JavaScript - No framework dependencies
└── Modern CSS3 - Glassmorphic design
Backend:
├── Flask 2.0+ - Web framework
├── Python 3.8+ - Core language
├── PyPSA - Power flow analysis
├── SUMO/TraCI - Traffic simulation
├── OpenAI API - Chatbot intelligence
└── SQLite - Data persistence
Machine Learning:
├── TensorFlow/Keras - Neural networks
├── scikit-learn - Classical ML
├── NumPy/Pandas - Data processing
└── Custom LSTM - Demand forecasting
┌─────────────────────────────────────────────────────────────┐
│ Web Frontend │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Mapbox │ │ Chatbot │ │WebGL Eng │ │Dashboard │ │
│ │ Map │ │ AI UI │ │ Renderer │ │ Controls │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└────────────┬────────────────────────────────────────────────┘
│ REST API / WebSocket
┌────────────┴────────────────────────────────────────────────┐
│ Flask Backend │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ API │ │ Ultra │ │ Scenario │ │ Data │ │
│ │ Routes │ │Intelligent│ │ Director │ │ Manager │ │
│ │ │ │ Chatbot │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─┬───────────┬────────────┬──────────────┬─────────────┬───┘
│ │ │ │ │
↓ ↓ ↓ ↓ ↓
┌──────┐ ┌──────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│PyPSA │ │SUMO │ │ V2G │ │ ML │ │ Event │
│Grid │ │TraCI │ │ Manager │ │ Engine │ │ System │
└──────┘ └──────┘ └──────────┘ └──────────┘ └──────────┘
Map-LLM/
├── 📁 core/ # Core system modules
│ ├── sumo_manager.py # SUMO integration & vehicle management
│ └── power_system.py # PyPSA power grid simulation
├── 📁 static/ # Frontend assets
│ ├── script.js # Main application logic (WebGL, Map)
│ ├── styles.css # Glassmorphic UI styling
│ ├── scenario-director.js # Scenario orchestration
│ ├── chatbot-scenarios.js # Chatbot-scenario integration
│ └── performance-monitor.js # FPS & metrics tracking
├── 📁 data/ # Data files
│ ├── manhattan.osm # OpenStreetMap data
│ ├── manhattan.net.xml # SUMO network
│ ├── substations.json # Substation locations
│ └── ev_stations.json # Charging station data
├── 📁 docs/ # Documentation
│ ├── FEATURES.md # Detailed feature list
│ ├── INSTALLATION.md # Setup guide
│ ├── CHATBOT_COMMANDS.md # All chatbot commands
│ └── API_REFERENCE.md # API documentation
├── main_complete_integration.py # Main Flask application
├── ultra_intelligent_chatbot.py # AI chatbot with OpenAI
├── v2g_manager.py # V2G energy trading
├── ml_engine.py # Machine learning analytics
├── manhattan_sumo_manager.py # Enhanced SUMO manager
├── ev_battery_model.py # EV battery simulation
├── ev_station_manager.py # Charging station management
├── index.html # Main web interface
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore rules
└── README.md # This file
- Installation Guide - Detailed setup instructions
- Features Documentation - Complete feature breakdown
- Chatbot Commands - All available commands
- API Reference - REST API documentation
- Contributing Guide - How to contribute
- Performance Guide - Optimization details
- ✅ Real-time vehicle simulation with 500+ EVs
- ✅ AI chatbot controlling the grid with natural language
- ✅ V2G emergency rescue scenario
- ✅ Citywide blackout and recovery
- ✅ GPU-accelerated rendering at 144 FPS
- ✅ Machine learning demand predictions
GET /api/statusReturns complete system state including vehicles, grid, and V2G sessions.
Response:
{
"status": "success",
"vehicle_count": 87,
"ev_count": 61,
"active_substations": 8,
"failed_substations": [],
"v2g_active": false,
"total_power_demand": 45.2
}POST /api/ai/chat
Content-Type: application/json
{
"message": "start vehicles",
"user_id": "operator_1"
}Response:
{
"status": "success",
"response": "✅ Starting vehicle simulation...",
"action": "spawn_vehicles",
"suggestions": ["highlight vehicle_0", "show grid status"]
}POST /api/sumo/start
Content-Type: application/json
{
"vehicle_count": 50,
"ev_percentage": 70,
"battery_min_soc": 20,
"battery_max_soc": 90
}POST /api/fail/Times%20Square
POST /api/restore/Times%20SquarePOST /api/v2g/enable/Times%20Square
GET /api/v2g/statusFor complete API documentation, see API_REFERENCE.md.
# Start the application
python main_complete_integration.py
# In browser: http://localhost:5000
# Type in chatbot: "start vehicles"
# Type: "run v2g scenario"
# Type: "confirm"# Install test dependencies
pip install pytest pytest-cov
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=. --cov-report=htmlTest 1: Basic Vehicle Simulation
- Start application
- Chatbot:
start 50 vehicles - Verify vehicles appear on map
- Verify vehicles charge at EV stations
Test 2: Substation Failure
- Chatbot:
fail Times Square - Verify substation turns red
- Verify traffic lights turn yellow
- Verify connected EV stations go offline
Test 3: V2G Emergency Response
- Chatbot:
run v2g scenario - Chatbot:
confirm - Watch cinematic scenario:
- Camera moves to Times Square
- Substation fails
- V2G activates automatically
- Vehicles provide power
- System recovers
Test 4: Performance
- Chatbot:
start 500 vehicles - Verify FPS >30 (overlay top-left)
- Verify smooth vehicle movement
- Verify no stuttering
We welcome contributions from the community! See CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
git checkout -b feature/amazing-feature
- Make your changes
- Test thoroughly
pytest tests/
- Commit with clear messages
git commit -m "Add amazing feature: description" - Push to your fork
git push origin feature/amazing-feature
- Open a Pull Request
- Follow PEP 8 for Python
- Use meaningful variable names
- Add docstrings to functions
- Include type hints
- Write unit tests for new features
- Update documentation
- Power Systems Engineers - Grid modeling and analysis
- Software Developers - Full-stack development
- AI/ML Specialists - Machine learning and chatbot
- UX/UI Designers - Interface design
- 📧 Email: [email protected]
- 🌐 Website: https://xgraph.team/
- 💬 GitHub Issues: Report bugs or request features
This project is licensed under the MIT License - see the LICENSE file for details.
- Eclipse SUMO - Traffic simulation framework
- PyPSA - Power system analysis library
- Mapbox - Interactive mapping platform
- OpenAI - GPT API for intelligent chatbot
- Flask - Lightweight web framework
- ✅ Ultra-intelligent AI chatbot with OpenAI
- ✅ GPU-accelerated rendering (WebGL)
- ✅ Cinematic scenario system
- ✅ Advanced V2G with automatic routing
- ✅ Real-time performance monitoring
- ✅ 1000+ vehicle support at high FPS
- 🔄 Mobile responsive design
- 🔄 User authentication and roles
- 🔄 Historical data playback
- 🔄 Export reports (PDF/CSV)
- 🔄 Multi-language support
- 🔄 Weather integration
- 🚀 Multi-city simulation
- 🚀 Distributed computing
- 🚀 Blockchain energy trading
- 🚀 IoT sensor integration
- 🚀 VR/AR visualization
- 🚀 Digital twin capabilities
⭐ Star • 🍴 Fork • 📝 Issues • 💬 Discussions
Built with ❤️ by XGraph Team for sustainable energy and smart city infrastructure
Empowering the future of smart grids with AI and advanced simulation