Elevator Simulator

A comprehensive Python-based elevator simulation system for discrete event simulation and elevator control algorithm research. Features realistic passenger traffic generation, advanced performance analytics, and interactive visualizations.

🚀 Quick Start

# Install the simulator
pip install -e .

# Generate traffic, simulate elevator, and analyze results
traffic-generator --floors 10 --rate 4 --duration 30 | \
elevator-sim --floors 10 --capacity 10 --enhanced | \
jq '.efficiency.passengers_per_minute'

Overview

The elevator simulator is designed with a modular architecture following Unix philosophy principles, where each component can work independently or as part of a pipeline. The system generates realistic passenger traffic, simulates elevator operations, and provides comprehensive analysis and visualization capabilities.

Architecture & Components

1. Traffic Generation (traffic/)

Purpose: Generates realistic passenger arrival patterns

Key Features:

• Multiple arrival distributions: Poisson, Uniform, Bursty, Fixed interval
• Origin/Destination policies: Uniform, Morning rush (up), Evening rush (down)
• Configurable parameters: arrival rates, building floors, simulation duration
• CLI Tool: traffic-generator - outputs CSV data with passenger arrivals

2. Elevator Simulation (elevator/)

Core Algorithm: Event-driven discrete simulation using priority queue (heapq)

Key Components:

• Passenger, Floor, Car, Building data structures
• Configurable timing parameters (travel time, door operations, boarding/alighting)
• FIFO passenger queuing system
• Simple elevator control logic (serves requests in order)
• CLI Tool: elevator-sim - processes CSV input and outputs simulation results

3. Analysis & Visualization (analysis/)

Capabilities:

• Metrics: Wait times, ride times, service rates, elevator efficiency
• Visualizations: Traffic pattern plots, time-bucketed analysis
• CLI Tool: traffic-viz - creates plots and summary statistics from CSV data

4. Shared Types (shared/)

Common data structures and enums used across modules, including Passenger and Direction types with factory methods.

📚 Documentation

For detailed information about specific components:

• Traffic Generation Guide - Complete guide to the traffic generator and visualizer tools
• Elevator Simulation Guide - Comprehensive documentation of the elevator simulation engine
• Performance Analysis - Comprehensive performance analysis with capacity curves and scenario comparisons

These guides provide in-depth information about CLI options, configuration parameters, and advanced usage scenarios.

Key Features

1. Unix Philosophy Design: Tools work as filters, accepting stdin and producing stdout
2. Configurable Parameters:
   • Building: floors, elevator capacity
   • Timing: travel speed, door operations, boarding times
   • Traffic: arrival rates, distributions, rush hour patterns
3. Comprehensive Analytics:
   • Basic metrics: Wait times, service efficiency, elevator utilization
   • Enhanced metrics: Detailed performance analysis with 50+ KPIs
   • Advanced visualizations with service quality breakdowns
   • Automated insights and recommendations
4. Professional Development Setup:
   • Modern Python packaging (pyproject.toml)
   • Code quality tools (Black, isort, mypy, pylint)
   • Optional ML/analysis dependencies

Installation

# Install the package
pip install -e .

# Install with optional dependencies
pip install -e ".[dev,analysis,ml]"

Usage

Basic Usage Pipeline

The tools work together in a Unix-style pipeline:

# Generate traffic → Simulate elevator → Visualize results
traffic-generator --floors 10 --rate 4 --duration 30 | \
elevator-sim --floors 10 --capacity 10 --sec-per-floor 2.5 | \
traffic-viz --save-plot results.png

Realistic Example Scenarios

# Morning rush hour simulation
traffic-generator --floors 12 --rate 4 --duration 45 \
  --od-policy morning_up --ground-origin-prob 0.75 | \
elevator-sim --floors 12 --capacity 10 --enhanced

# Evening rush hour with visualization
traffic-generator --floors 10 --rate 3.5 --duration 30 \
  --od-policy evening_down --upper-origin-prob 0.7 | \
enhanced-viz --floors 10 --capacity 10 --save-plot evening_rush.png

Individual Tools

Traffic Generator

# Generate realistic office building traffic
traffic-generator --floors 12 --rate 4 --duration 45 \
  --distribution poisson --od-policy morning_up --output morning.csv

# Create bursty traffic patterns
traffic-generator --floors 8 --rate 3 --duration 30 \
  --distribution bursty --burst-rate 8 --seed 42

Elevator Simulation

# Run simulation with optimized parameters
cat traffic.csv | elevator-sim --floors 10 --capacity 10 \
  --sec-per-floor 2.5 --door-open-sec 1.5

# Get comprehensive performance analysis
cat traffic.csv | elevator-sim --floors 10 --capacity 10 --enhanced

Analysis & Visualization

# Basic traffic visualization
cat traffic.csv | traffic-viz --bucket-sec 30 --save-plot traffic.png

# Comprehensive performance dashboard
cat traffic.csv | enhanced-viz --floors 10 --capacity 10 \
  --save-plot performance_analysis.png

Technical Stack

• Core: Python 3.11+, NumPy, Pandas, SciPy
• Visualization: Matplotlib, PyQt5
• CLI: Click framework
• Optional: ML libraries (scikit-learn, TensorFlow, PyTorch), Jupyter

Use Cases

This simulator is valuable for:

• Testing elevator control algorithms
• Analyzing building traffic patterns
• Optimizing elevator configurations
• Educational purposes in discrete event simulation
• Research in vertical transportation systems

CSV Data Format

All tools work with a standardized CSV schema where each row represents a passenger arrival:

• passenger_id: unique identifier
• arrival_time_minutes: simulated arrival time (float, minutes)
• origin_floor: floor where the passenger appears
• destination_floor: floor the passenger wants to go
• direction: "up" or "down"

Enhanced Analytics

The simulator provides comprehensive performance analysis through enhanced metrics:

Key Performance Indicators

• Service Rate: Percentage of passengers successfully served
• Wait Time Analysis: Mean, median, percentiles (75th, 90th, 95th, 99th)
• Service Quality Tiers: Excellent (<30s), Good (30-60s), Poor (>120s)
• Elevator Efficiency: Passengers/minute, passengers/stop, utilization

Advanced Metrics Categories

• Travel Patterns: Trip distance distribution, floor usage patterns
• Traffic Analysis: Direction bias, peak period detection
• Temporal Patterns: Service span, arrival clustering
• Consistency Scoring: Service reliability and predictability

Automated Insights

The system generates actionable recommendations:

• Capacity optimization suggestions
• Traffic pattern analysis
• Bottleneck identification
• Performance improvement opportunities

Example Output

{
  "passengers": {"served": 180, "total_generated": 180, "service_rate_pct": 100.0},
  "wait_times": {"avg_seconds": 32.4, "p95_seconds": 89.2, "max_seconds": 156.8},
  "service_quality": {"excellent_service_under_30s": 98, "consistency_score": 87.3},
  "efficiency": {"passengers_per_minute": 4.2, "passengers_per_stop": 2.1},
  "traffic_patterns": {"up_percentage": 72.8, "traffic_bias": "up_heavy"}
}

Performance Benchmarks

• Typical wait times: 20-60 seconds average
• Service rate: 99-100% passenger completion
• Throughput: 2-6 passengers per minute (depending on traffic)
• Simulation speed: ~1000 passengers/second processing

Troubleshooting

Common Issues

Command not found errors:

# Ensure package is installed in development mode
pip install -e .

High wait times (>200s):

• Reduce traffic rate (--rate 3-4 instead of 8+)
• Increase elevator capacity (--capacity 10-12)
• Decrease travel time (--sec-per-floor 2.0-2.5)

No output from pipeline:

• Check that CSV headers match expected format
• Verify all commands are in PATH after installation

Parameter Guidelines

Building Type	Floors	Rate (pass/min)	Capacity	Speed (s/floor)
Small Office	5-8	2-3	8	2.5
Office Tower	10-15	3-5	10-12	2.0
High-rise	20+	4-8	15-20	1.5

Development

The project follows modern Python development practices:

# Install development dependencies
pip install -e ".[dev]"

# Run code formatting
black src/
isort src/

# Run type checking
mypy src/

# Run linting
pylint src/

# Run tests (if available)
pytest tests/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make changes and add tests
4. Run linting and formatting
5. Submit a pull request

FAQ

Q: Can I simulate multiple elevators? A: Currently only single-car simulation is supported. Multi-car support is planned for future versions.

Q: How accurate are the timing parameters? A: Default parameters are based on typical commercial elevators. Adjust based on your specific use case.

Q: Can I integrate this with real elevator control systems? A: The simulator is designed for analysis and research. Integration would require additional safety and control layer development.

Q: What's the maximum building size supported? A: No hard limits, but performance may degrade with >50 floors or >1000 passengers due to visualization constraints.

License

MIT License

Author

Don Cruver (donald@cruver.network)

---

Version: 1.0.0
Status: Production Ready