Welcome to Elevator Saga’s Documentation!

Elevator Saga is a Python implementation of an elevator simulation game with an event-driven architecture. Design and optimize elevator control algorithms to efficiently transport passengers in buildings.

Features

🏢 Realistic Simulation: Physics-based elevator movement with acceleration, deceleration, and realistic timing

🎮 Event-Driven Architecture: React to various events such as button presses, elevator arrivals, and passenger boarding

🔌 Client-Server Model: Separate simulation server from control logic for clean architecture

📊 Performance Metrics: Track wait times, system times, completion rates, and energy consumption

⚡ Energy Tracking: Monitor and optimize energy consumption with configurable per-elevator energy rates

🎯 Flexible Control: Implement your own algorithms using a simple controller interface

Installation

Basic Installation

pip install elevator-py

Quick Start

Running the Simulation

Terminal #1: Start the backend simulator

python -m elevator_saga.server.simulator

Terminal #2: Start your controller

python -m elevator_saga.client_examples.bus_example

Architecture Overview

Elevator Saga follows a client-server architecture:

• Server (simulator.py): Manages the simulation state, physics, and event generation

• Client (base_controller.py): Implements control algorithms and reacts to events

• Communication (api_client.py): HTTP-based API for state queries and commands

• Data Models (models.py): Unified data structures shared between client and server

Contents

User Guide

• Data Models
  • Overview
  • Core Enumerations
  • Core Data Models
  • Traffic and Configuration
  • Performance Metrics
  • API Models
  • Example Usage
  • Energy System
• Client Architecture and Proxy Models
  • Overview
  • Proxy Models
  • Base Controller
  • Complete Example
  • Benefits of Proxy Architecture
  • Next Steps
• HTTP Communication Architecture
  • Architecture Overview
  • Server Side: Simulator
  • Client Side: API Client
  • Communication Flow
  • Error Handling
  • Thread Safety
  • Testing the API
  • Next Steps
• Event-Driven Simulation and Tick-Based Execution
  • Simulation Overview
  • Tick-Based Execution
  • Elevator State Machine
  • Movement Physics
  • Event System
  • Event Processing in Controller
  • Control Flow: Bus Example
  • Key Timing Concepts
  • Performance Metrics
  • Summary
  • Next Steps

API Reference

• API Reference

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under MIT License - see the LICENSE file for details.

Indices and tables

• Index

• Module Index

• Search Page