SimElevatorTraffic - Elevator Traffic Simulation and Analysis Software

中文版 README

Project Overview

Note: This project has been migrated from the Maven build system to Gradle 8.14 to provide better build performance and a more modern build experience.

SimElevatorTraffic is a professional elevator traffic simulation and analysis tool designed to address key issues in modern building elevator system design and optimization. Developed based on the latest research materials and best practices in elevator engineering, this project has the following features:

• Supports precise simulation of 4 elevator control methods: Single Control, Parallel Control, Group Control, and Destination Dispatch
• Simulates traffic characteristics of different building types (office buildings, shopping malls, residential buildings, mixed-use)
• Models traffic patterns during different time periods such as morning rush, lunch rush, evening rush, and off-peak hours
• Supports passenger batch arrival models that conform to the "non-homogeneous Poisson process" characteristic
• Implements OD matrix estimation methods (LP, BILS, CP algorithms)
• Provides detailed performance indicator analysis, including waiting time, transportation time, system utilization, etc.
• Supports simulation of emergency evacuation scenarios
• Provides RESTful API interfaces for integration with other building management systems

Technology Stack

• Core Language: Java 21
• Build Tool: Gradle 8.14
• Web Framework: Javalin
• Database: PostgreSQL
• JSON Processing: Jackson
• PDF Generation: iText 7
• Constraint Programming: Choco Solver
• Mathematical Computing: Apache Commons Math
• Testing Frameworks: JUnit 5, Mockito

System Architecture

SimElevatorTraffic/
├── src/
│   └── main/
│       └── java/
│           └── com/github/charles/works/simelevatortriffic/
│               ├── Main.java                 # Application entry point
│               ├── api/                      # REST API layer
│               ├── config/                   # Configuration management
│               ├── domain/                   # Domain model
│               ├── service/                  # Business logic layer
│               └── simulation/               # Simulation engine
├── build.gradle                              # Gradle build configuration
├── settings.gradle                           # Gradle settings
├── gradlew                                   # Gradle Wrapper script
└── README.md                                 # Project documentation

Quick Start

Environment Requirements

• Java 21 JDK
• PostgreSQL 13+
• Gradle 8.14+

Building the Project

# Clone the project
git clone <repository-url>
cd SimElevatorTraffic

# Build the project
./gradlew build

# Run the application
./gradlew run

API Usage Example

# Execute simulation with uniform floor configuration
curl -X POST http://localhost:7000/api/v1/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "buildingConfig": {
      "id": "1",
      "name": "Office Building",
      "floors": 30,
      "floorHeight": 4.0,
      "type": "OFFICE"
    },
    "elevatorGroups": [
      {
        "id": "1",
        "controlType": "GROUP_CONTROL",
        "servedFloors": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30],
        "elevators": [
          {
            "id": "1",
            "capacity": 16,
            "ratedSpeed": 3.0,
            "acceleration": 1.0,
            "deceleration": 1.0,
            "doorWidth": 1.0,
            "standbyFloor": 1,
            "serviceFloors": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
          },
          {
            "id": "2",
            "capacity": 13,
            "ratedSpeed": 3.0,
            "acceleration": 1.0,
            "deceleration": 1.0,
            "doorWidth": 1.0,
            "standbyFloor": 1,
            "serviceFloors": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
          },
          {
            "id": "3",
            "capacity": 13,
            "ratedSpeed": 3.0,
            "acceleration": 1.0,
            "deceleration": 1.0,
            "doorWidth": 1.0,
            "standbyFloor": 1,
            "serviceFloors": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
          }
        ]
      }
    ],
    "simulationConfig": {
      "duration": 3600
    }
  }'

# Execute simulation with different configuration for each floor
curl -X POST http://localhost:7000/api/v1/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "buildingConfig": {
      "id": "2",
      "name": "Mixed-use Building",
      "floors": 20,
      "floorHeight": 4.0,
      "type": "MIXED",
      "floorConfigs": [
        {
          "floorNumber": 1,
          "usage": "LOBBY",
          "population": 50,
          "arrivalRate": 2.0,
          "floorHeight": 5.0
        },
        {
          "floorNumber": 2,
          "usage": "RETAIL",
          "population": 100,
          "arrivalRate": 3.0,
          "floorHeight": 4.5
        },
        {
          "floorNumber": 3,
          "usage": "OFFICE",
          "population": 200,
          "arrivalRate": 5.0,
          "floorHeight": 4.0
        },
        {
          "floorNumber": 4,
          "usage": "OFFICE",
          "population": 180,
          "arrivalRate": 4.5,
          "floorHeight": 4.0
        }
      ]
    },
    "elevatorGroups": [
      {
        "id": "1",
        "controlType": "GROUP_CONTROL",
        "servedFloors": [1,2,3,4],
        "elevators": [
          {
            "id": "1",
            "capacity": 16,
            "ratedSpeed": 3.0,
            "acceleration": 1.0,
            "deceleration": 1.0,
            "doorWidth": 1.0,
            "standbyFloor": 1,
            "serviceFloors": [1,2,3,4]
          },
          {
            "id": "2",
            "capacity": 13,
            "ratedSpeed": 3.0,
            "acceleration": 1.0,
            "deceleration": 1.0,
            "doorWidth": 1.0,
            "standbyFloor": 1,
            "serviceFloors": [1,2,3,4]
          }
        ]
      }
    ],
    "simulationConfig": {
      "duration": 3600
    }
  }'

Core Features

1. Elevator Control Strategy Simulation

Supports four elevator control methods:

• Single Control: Each elevator independently responds to its own call signals
• Parallel Control: Two elevators share calls, using a minimum waiting time algorithm
• Group Control: Multiple elevators work together, considering overall performance optimization
• Destination Dispatch: Passengers first input their destination floor, and the system optimizes allocation

2. Passenger Flow Modeling

Implements high-fidelity passenger flow models based on research materials:

• Batch Arrival Model: Implements "non-homogeneous Poisson process"
• Traffic Pattern Modeling: Supports inbound, outbound, and inter-floor traffic components
• OD Matrix Estimation: Implements LP, BILS, and CP algorithms

3. Performance Analysis

Provides comprehensive performance indicator analysis:

• Waiting time analysis (average, maximum, distribution)
• Transportation time analysis (average, maximum, distribution)
• System utilization analysis
• 5-minute handling capacity (HC)
• Elevator energy consumption estimation

4. Visualization and Reporting

• Real-time simulation animation display
• Interactive data analysis interface
• Professional PDF report generation
  • Executive summary with key findings
  • Detailed performance metrics with charts and tables
  • Waiting time analysis with distribution charts
  • Travel time analysis with comparative charts
  • Elevator utilization heatmap and statistics
  • Optimization recommendations based on simulation results
  • Bilingual support (Chinese/English)
• Elevator utilization heatmap

Development Guide

Domain Model

Core domain objects include:

• Building: Building model
• Floor: Floor information
• ElevatorGroup: Elevator group
• Elevator: Elevator instance
• Passenger: Passenger object
• ODMetricMatrix: OD matrix

Service Layer

Main service interfaces:

• ODEstimationService: OD matrix estimation
• PassengerFlowService: Passenger flow generation
• ElevatorControlService: Elevator control strategy
• SimulationService: Simulation coordination management

Simulation Engine

ElevatorSimulationScheduler is the core simulation scheduler, using discrete event simulation methods:

• Event-driven architecture
• Real-time performance optimization
• Support for large-scale simulation

Configuration

Application configuration is managed through the ApplicationConfig class, with main configuration items including:

Database Configuration

# Database connection URL
database.url=jdbc:postgresql://localhost:5432/sim_elevator
# Database username
database.username=sim_user
# Database password
database.password=sim_password

Simulation Configuration

# Maximum concurrent simulations
simulation.maxConcurrentSimulations=10
# Default simulation duration (seconds)
simulation.defaultSimulationDuration=3600
# Default time slice (seconds)
simulation.defaultTimeSlice=5

API Configuration

# API service port
api.port=7000
# Request timeout (milliseconds)
api.requestTimeoutMs=30000

Testing Strategy

Unit Testing

Uses JUnit 5 and Mockito for unit testing, covering core algorithms and business logic.

Integration Testing

Validates integration with databases and external services.

Performance Testing

Uses JMH for performance benchmark testing to ensure real-time requirements are met.

Deployment Instructions

Production Environment Deployment

1. Build the project:

./gradlew build

2. Configure the database:

CREATE DATABASE sim_elevator;
CREATE USER sim_user WITH PASSWORD 'sim_password';
GRANT ALL PRIVILEGES ON DATABASE sim_elevator TO sim_user;

3. Run the application:

java -jar build/libs/SimElevatorTriffic-1.0-SNAPSHOT.jar

Docker Deployment

Dockerfile is provided for containerized deployment.

Contribution Guidelines

Issues and Pull Requests are welcome to improve the project.

License

This project is licensed under the Apache 2.0 License.

Contact

For any questions, please contact the project maintainer.