# v2xgithub/wilabv2xsim architecture

> Architecture diagram of the GitHub repository v2xgithub/wilabv2xsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/v2xgithub/wilabv2xsim
- Repository: https://github.com/v2xgithub/wilabv2xsim

## Overview

##### Project type and purpose
- This is an open-source MATLAB/Octave simulator (WiLabV2Xsim) for vehicular sidelink communications (LTE-V2V, 5G-V2X, IEEE 802.11p).
- It provides a dynamic, modular framework to investigate resource-allocation algorithms, channel modeling (SINR, PER), mobility, and KPI extraction.

##### High-level architecture and file-structure analysis
- Top-level directories:
- ConfigFiles – user-editable .cfgs for scenarios (highway, urban, RSU…).
- MainFiles (with subfolders MainFilesCV2X, MainFilesIEEE802.11p) – core simulation loop and protocol-specific handlers for TX/RX events.
- MatFilesInit – initialization routines (parameters, random seed, reading cfg).
- MatFilesPosition – mobility and trace‐based position updates.
- MatFilesSINR – channel gain and path-loss/PER lookups.
- MatFilesResourceAllocationCV2X – 5G-V2X resource-allocation procedures.
- MatCBRcalculations – channel busy ratio computations.
- MatFilesCoexistence – cross-technology coexistence logic.
- MatFilesUtility (plus subfolders for LTE, 5G, IEEE802.11p) – shared math/helpers (distance, angles, neighbor detection, RB tables).
- MatFilesOut – output writers (PRR, delays, power, neighbor stats).
- DebugFiles – debugging plots and print routines.
- PERcurves – precomputed PER curves and lookup scripts.
- codeForPaper – example scripts & configs used in publications.
- Root scripts: WiLabV2Xsim.m, Simulations.m orchestrate runs.

##### README for insights
- Confirms MATLAB ≥2021b requirement, GPLv3 license, focus on sidelink C-V2X with backward support for 802.11p.
- Defines dependency on Statistics and ML Toolbox for traffic generation.
- Points to Wiki for detailed docs.

1. Input & Configuration Manager (reads ConfigFiles/*.cfg)
2. Initialization Module (MatFilesInit)
3. Mobility/Position Module (MatFilesPosition)
4. Channel Model & SINR/PER (MatFilesSINR + PERcurves)
5. Resource-Allocation Module (MatFilesResourceAllocationCV2X)
6. Protocol Engines
– CV2X Engine (MainFilesCV2X)
– IEEE 802.11p Engine (MainFilesIEEE802.11p)
7. CBR & Coexistence Module (MatCBRcalculations + MatFilesCoexistence)
8. Metrics & Output Module (MatFilesOut)
9. Debug & Visualization (DebugFiles)
10. Orchestrator (WiLabV2Xsim.m, mainInit.m, mainV2X.m)

- Config → Init
- Init → Orchestrator
- Orchestrator invokes Mobility → provides positions → Channel Model
- Channel Model uses PERcurves → computes link quality → passes SINR to Protocol Engines
- Orchestrator calls Resource-Allocation → schedules transmissions
- Protocol Engines handle TX/RX events → update CBR/Coexistence → feed back into Resource-Allocation and Channel Model
- After each time step, Metrics Module gathers KPIs → writes outputs
- Debug Module can tap any data pipe for plots/logs

c. Architectural patterns & design principles:
- Layered pipeline: Configuration → Init → Simulation Loop → Output
- Modular decomposition by functionality (mobility, PHY channel, MAC/RA, metrics)
- Data-driven: cfg files, trace files, PER tables
- Extensible: separate subfolders for each radio technology, easy to plug new algorithms

d. Key technologies & frameworks:
- MATLAB (scripts & functions)
- Statistics & Machine Learning Toolbox (traffic generation)
- PER lookup via text-based curves
- Octave compatibility on separate branch

##### Detailed capture of essential elements
- Break the core simulation loop into four sub-steps: position update, channel computation, RA & TX/RX, KPI update.
- Explicitly show Inter-module dependencies: e.g., CBR module reading TX history, coexistence adjusting NAV parameters in RA.
- Reference config inputs feeding both Init and mobility modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Initialization Layer
    subgraph "Input & Initialization Layer"
        Config["Configuration Files"]:::blue
        Init["Initialization Module"]:::blue
        Orchestrator["Orchestrator Scripts"]:::blue
    end

    Config -->|"cfg files"| Init
    Init -->|"initialize simulation"| Orchestrator

    %% Core Simulation Loop
    subgraph "Core Simulation Loop"
        subgraph "Position Update"
            Mobility["Mobility/Position Module"]:::green
        end
        subgraph "Channel Model"
            Channel["Channel Model & SINR"]:::green
            PERTables[(PER Curves)]:::green
        end
        subgraph "Resource Allocation"
            RA["Resource-Allocation Module"]:::green
            CBR["CBR Calculations Module"]:::green
            Coexist["Coexistence Module"]:::green
        end
        subgraph "Protocol Engines"
            CV2X["CV2X Protocol Engine"]:::green
            W11p["IEEE 802.11p Protocol Engine"]:::green
        end
    end

    Orchestrator -->|"start loop"| Mobility
    Orchestrator -->|"start loop"| Channel
    Orchestrator -->|"start loop"| RA

    Mobility -->|"position vector"| Channel
    Channel -->|"SINR matrix"| CV2X
    Channel -->|"SINR matrix"| W11p
    PERTables -->|"lookup tables"| Channel

    Orchestrator -->|"invoke RA"| RA
    RA -->|"schedule slots"| CV2X
    RA -->|"schedule slots"| W11p

    CV2X -->|"TX/RX events"| CBR
    W11p -->|"TX/RX events"| CBR
    CV2X -->|"TX/RX events"| Coexist
    W11p -->|"TX/RX events"| Coexist

    CBR -->|"update metrics"| RA
    Coexist -->|"adjust NAV"| RA
    CBR -->|"feedback"| Channel
    Coexist -->|"feedback"| Channel

    %% Output & Metrics Layer
    subgraph "Output & Metrics Layer"
        Metrics["Metrics & Output Module"]:::orange
        Logs[(Output Data & Reports)]:::orange
    end

    CV2X -->|"event logs"| Metrics
    W11p -->|"event logs"| Metrics
    Metrics -->|"write outputs"| Logs

    %% Debug & Visualization Layer
    subgraph "Debug & Visualization Layer"
        Debug["Debug & Visualization Module"]:::gray
    end

    Mobility -.-> Debug
    Channel -.-> Debug
    RA -.-> Debug
    CV2X -.-> Debug
    W11p -.-> Debug
    Metrics -.-> Debug

    %% Click Events for component mapping
    click Config "https://github.com/v2xgithub/wilabv2xsim/tree/main/ConfigFiles/"
    click Init "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesInit/"
    click Mobility "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesPosition/"
    click Channel "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesSINR/"
    click PERTables "https://github.com/v2xgithub/wilabv2xsim/tree/main/PERcurves/"
    click RA "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesResourceAllocationCV2X/"
    click CV2X "https://github.com/v2xgithub/wilabv2xsim/tree/main/MainFilesCV2X/"
    click W11p "https://github.com/v2xgithub/wilabv2xsim/tree/main/MainFilesIEEE802.11p/"
    click CBR "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatCBRcalculations/"
    click Coexist "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesCoexistence/"
    click Metrics "https://github.com/v2xgithub/wilabv2xsim/tree/main/MatFilesOut/"
    click Debug "https://github.com/v2xgithub/wilabv2xsim/tree/main/DebugFiles/"
    click Orchestrator "https://github.com/v2xgithub/wilabv2xsim/blob/main/WiLabV2Xsim.m"
    click Orchestrator "https://github.com/v2xgithub/wilabv2xsim/blob/main/MainFiles/mainInit.m"
    click Orchestrator "https://github.com/v2xgithub/wilabv2xsim/blob/main/MainFiles/mainV2X.m"
    click Orchestrator "https://github.com/v2xgithub/wilabv2xsim/blob/main/Simulations.m"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085
    classDef green fill:#d4edda,stroke:#155724,color:#155724
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
