# Elevator Traffic Analysis

<a href="https://github.com/tkosman/contemplate-whirlpool/actions">
  <img src="https://img.shields.io/github/actions/workflow/status/tkosman/contemplate-whirlpool/main.yml?branch=main&label=CI&style=flat-square" alt="CI Status"/>
</a>

A Python package for simulating and analyzing elevator traffic using various scheduling algorithms. This tool allows you to model building elevator systems, simulate passenger traffic patterns, and visualize elevator movements and waiting times.

## Features

- **Multiple Elevator Algorithms**: Supports FCFS (First Come First Served), SCAN, LOOK, and SSTF (Shortest Seek Time First) scheduling algorithms
- **Flexible Scenario Configuration**: Define custom scenarios using YAML files
- **Visualization**: Generate plots showing elevator trajectories and passenger movements
- **Comprehensive Testing**: Includes unit tests with coverage reporting
- **Docker Support**: Easy deployment using containerization
- **CLI Interface**: Simple command-line interface for running simulations

## Requirements

To run the project, you need:

- **Docker** version `24.0.0` or higher (for Docker-based execution)
- **Operating system** supporting `bash` shell
- **Python 3.8+** (for alternative PyPI installation)

## Running with Docker

The project includes an `elevator-traffic-analysis` script that simplifies working with containers and running simulations.

### List Available Scenarios

```bash
cd elevator-traffic-analysis
./elevator-traffic-analysis list-scenarios
```

To add your own scenario, create a new YAML file (e.g., `new_scenario.yaml`) in the `scenarios` directory.

### Run an Example Scenario

The following command runs the `example` scenario, generates a plot, and displays passenger IDs on trajectories:

```bash
./elevator-traffic-analysis run example --plot --show-passenger-ids
```

### Display Available Options

```bash
./elevator-traffic-analysis --help
```

### Run Tests with Coverage

```bash
./elevator-traffic-analysis test
```

### Run Linter

```bash
./elevator-traffic-analysis lint
```

## Alternative Installation (PyPI)

The project is also available as a `pip` package. The example below uses a virtual environment for installation:

```bash
python3 -m venv myenv
source myenv/bin/activate
pip install elevator-traffic-analysis
```

After installation, you can list available scenarios:

```bash
elevator-traffic-analysis list-scenarios
```

Running simulations, generating plots, and other parameters work the same way as in the Docker version.

## Scenario Configuration

Scenarios are defined in YAML format. Example structure:

```yaml
n_floors: 10
n_elevators: 1
elevator_capacity: 8
elevator_logic: shortest_seek_time_first
passenger_schedule:
  0:
    - passenger_id: P__0
      appear_floor: F__0
      destination_floor: F__5
```

## Available Algorithms

- **FCFS** (First Come First Served): Services requests in the order they arrive
- **SCAN**: Elevator moves in one direction until no more requests, then reverses
- **LOOK**: Similar to SCAN but reverses immediately after the last request
- **SSTF** (Shortest Seek Time First): Services the closest request first

## Output

Simulations generate:
- Output YAML files with detailed simulation results (in `scenarios_out/`)
- Visualization plots showing elevator movements (in `scenarios_plots/`)

## License

MIT License - see the [LICENSE](LICENSE) file for details.
