# khachatryan_artavazd — Project

# Yerevan Metro Digital Twin & Simulation Engine, v0.0.1
Video: https://ijevan.greenhosting.am/db/get?id=6febc033-2171-4c24-b430-680f24d96e0d#bebc951c-d35a-4d06-b3f5-90f4be652cdc-266fa7c0-cc9c-400c-836c-7eb7dc041140 

## 1. System Overview & Functionality
This project is a macroscopic, discrete-event simulation and live digital twin of the Yerevan Metro system. It models passenger influx, train movement, and stochastic crowd dynamics across all 9 active stations. 

**Supported Functionality:**
* **1:1 Real-Time Telemetry:** The C engine operates on a 1-second discrete tick rate, exporting live physical state data to CSV logs.
* **Cyberpunk Dashboard:** A Python/Matplotlib frontend reads the telemetry continuously, rendering train positions, track routing, and passenger queues in a live Graphical User Interface.
* **7-Phase State Machine:** Trains physically traverse the tracks, dwell at platforms, and execute turnarounds in the terminus dead-ends.
* **Dynamic Fleet Management:** Supports 6 concurrent trains pre-spaced to maintain ~7-minute headways.

## 2. Architecture & Code Structure
The system uses a decoupled architecture to separate high-speed logic from visual rendering.

* `topography.h/c`: Defines the structural layout of the 9 stations, including empirical capacity and routing constants.
* `passenger.h/c`: Handles the memory management (malloc/free) of discrete human entities and manages the linked-list queues for each platform.
* `train.h/c`: Houses the train structures and the 7-Phase State Machine loop, dictating physical movement and dwell delays.
* `main.c`: The master loop that synchronizes the time tick, triggers passenger generation, updates the fleet, and exports `metro_log.csv` and `train_log.csv`.
* `visualizer.py`: The frontend UI loop that interpolates the CSV data into smooth animations.

## 3. Main Algorithms & Components
To accurately reflect reality, the simulation relies on empirical 2023 Yerevan Metro ridership data integrated with stochastic (randomized) algorithms.

Davtyan K., Khcheyan M. (2025). Analysis of Passenger Flows of Yerevan Metro and Other Means of Transport in the Context of the Newly Constructed Ajapnyak Station. 
Messenger of ASUE, 3(81), 36-52. DOI: 10.52174/1829-0280_2025.3-36

* **Fractional Accumulator (Passenger Generation):** To convert continuous daily demand (1.67 passengers/second) into discrete human spawns, the system multiplies the global rate by each station's historical influx fraction (e.g., Barekamutyun = 17.81%). Decimal fractions are banked in an accumulator until they form whole integers, ensuring zero data loss.
* **Stochastic Boarding Distribution:** Each station has a base probability for Northbound vs. Southbound travel. During boarding, Gaussian noise ($\mu$) between -10% and +10% is injected into this probability to simulate the unpredictable nature of human crowds. 
* **Dynamic Alighting Probability:** Passengers do not exit randomly. Alighting probability is dynamically calculated by dividing the current station's volume weight by the sum of all *remaining* stations on the route. This naturally forces passengers to gravitate toward massive hubs like Yeritasardakan.

## 4. Build & Run Instructions

**Prerequisites:**
* **Operating System:** This application is designed for **Linux-based environments** (e.g., Ubuntu, Debian) or **WSL (Windows Subsystem for Linux)**. It utilizes POSIX-standard libraries (`unistd.h`, `pkill`) which are not natively available on standard Windows environments.
* **Compiler:** GCC compiler (C11 standard)
* **Build Tool:** `make`
* **Dependencies:** Python 3.x with `matplotlib` installed.

**Compilation:**
Open your terminal in the project directory and run:
`make clean`
`make simulate`

**Execution:**
The `make simulate` command will automatically compile the C engine, launch it in the background as a detached process (`./metro_simulator &`), and immediately launch the Python visualizer dashboard. 
*To gracefully exit the simulation and kill the background C process, click the red "TERMINATE" button in the Python UI.*

## 5. Testing Strategy
Given the stochastic and visual nature of the digital twin, testing was divided into three core manual and automated validation strategies:
1. **Memory Leak Validation:** Ensured that every `malloc` call in `passenger.c` during queue generation was strictly paired with a `free` call in `train.c` during the alighting phase. 
2. **State Machine Verification (Visual Testing):** Validated the terminus boundary logic by observing trains transition from `STATE_TURNAROUND_OUT` (sliding into the dead-end) to `STATE_TURNAROUND_IN` (flipping direction and returning to the platform) without crashing or jumping tracks.
3. **Macroscopic Flow Testing:** Let the simulation run for extended 1-hour digital periods to verify that Barekamutyun and Republic Square naturally formed the largest queues, proving the `influx_fraction` algorithms functioned identically to physical daily reporting.