# efontesp90/llsim5g architecture

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

- Interactive diagram: https://gitdiagram.com/efontesp90/llsim5g
- Repository: https://github.com/efontesp90/llsim5g

## Overview

##### Project Type and Purpose
- LLSim5G is an open-source, Python-based link-level simulator for heterogeneous 5G networks (TNs, NTNs, UAVs).
- It is not a full-stack web app but a modular simulation tool that reads configuration, generates scenarios, applies channel models, computes link metrics, and writes outputs.

##### Main Architectural Components
A. Configuration & Initialization
- SimulationConfiguration (PDF + Excel under simulation_settings/)
- main.py (entry point)
B. Scenario Generator
- scenario/ (defines BSs, EDs, mobility models, topology)
C. Channel Modeling Layer
- channel_models/geometry/ (3D geometry)
- channel_models/path_loss_models_* (TR 38.901, 38.811)
- channel_models/ff_models_* (fast-fading)
- channel_models/spectroscopic_data, atmospheric absorption
D. Link Computation Engine
- link_computation/link_computation.py
- Uses scenario definitions + channel model outputs to compute per-link SINR, etc.
E. Link-to-System Adaptation
- link_to_system_adaptation/ (bler_curves.py, link_to_system.py)
- Converts SINR → BLER, CQI metrics
F. Output & Persistence
- output/ (writes Excel, pickle, videos under output/metrics and output/scenario)
G. Validation & Testing
- validation/ (scripts to validate atmospheric absorption, antenna models, HDF5 realizations)
H. Environment & Dependencies
- requirements.txt, myenv/ (Python venv)
- External libs: numpy, pandas, h5py, openpyxl, etc.

##### Data Flows & Interactions
- main.py loads SimulationConfiguration → passes parameters to the Scenario Generator and Channel Modeling Layer.
- Scenario Generator defines nodes (BS, ED) positions + mobility profiles → feeds Link Computation.
- Channel Modeling Layer processes geometry & path-loss → provides channel coefficients to Link Computation.
- Link Computation Engine iterates over simulation time, invoking channel models per link, producing SINR results.
- Link‐to‐System Adaptation consumes SINR values → yields BLER & CQI.
- Output Layer aggregates and writes metrics & scenario traces.
- Validation modules can be invoked independently to verify specific model fidelity.

##### Architectural Patterns & Principles
- Layered pipeline: initialization → scenario → channel models → computation → adaptation → output.
- Modular plug-in structure: each channel model (path-loss, fast-fading) exists as a separate module.
- Separation of concerns: scenario generation, physics modeling, computation, and output are in distinct packages.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & Initialization
    subgraph "Configuration & Initialization"
        SimulationConfiguration["Simulation Settings (PDF/Excel)"]:::config
        Main["main.py (Entry Point)"]:::config
    end

    %% Scenario Generator
    subgraph "Scenario Generator"
        Scenario["scenario/"]:::core
        ScenarioDefinition["scenario_definition.py"]:::core
        MobilityModels["mobility/models.py"]:::core
        SatellitesInfo["satellites_lla_info.py"]:::core
        ScenarioShow["show.py"]:::core
    end

    %% Channel Modeling Layer
    subgraph "Channel Modeling Layer"
        GeometryDir["geometry/"]:::core
        CMTR811["channel_model_tr_38_811.py"]:::core
        CMTR901["channel_model_tr_38_901.py"]:::core
        PLTR811["path_loss_models_tr_38_811.py"]:::core
        PLTR901["path_loss_models_tr_38_901.py"]:::core
        PLA2G["path_loss_models_a2g.py"]:::core
        FFJakes["ff_model_jakes.py"]:::core
        FFDir["ff_models_tr_38_901and811/"]:::core
        Spectroscopic["spectroscopic_data.py"]:::core
    end

    %% Link Computation Engine
    subgraph "Link Computation Engine"
        LinkComp["link_computation.py"]:::core
    end

    %% Link-to-System Adaptation
    subgraph "Link-to-System Adaptation"
        Bler["bler_curves.py"]:::adaptation
        L2S["link_to_system.py"]:::adaptation
    end

    %% Output & Persistence
    subgraph "Output & Persistence"
        OutputsConfig["outputs_config.py"]:::output
        MetricsDir["metrics/"]:::output
        ScenarioOut["scenario/"]:::output
    end

    %% Validation & Testing
    subgraph "Validation & Testing"
        ATMNTN["atmospheric_absorption_ntn.py"]:::validation
        ATMtn["atmospheric_absorption_tn.py"]:::validation
        Realization["realization.h5"]:::validation
        SATVal["sattellite_antenna_model.py"]:::validation
        TERVal["terrestrial_antenna_model.py"]:::validation
    end

    %% Environment & Dependencies
    subgraph "Environment & Dependencies"
        Requirements["requirements.txt"]:::env
        VirtualEnv["myenv/"]:::env
    end

    %% Data Flows
    SimulationConfiguration --> Main
    Main --> Scenario
    Main --> GeometryDir
    Scenario --> LinkComp
    GeometryDir --> LinkComp
    CMTR811 --> LinkComp
    CMTR901 --> LinkComp
    PLTR811 --> LinkComp
    PLTR901 --> LinkComp
    PLA2G --> LinkComp
    FFJakes --> LinkComp
    FFDir --> LinkComp
    Spectroscopic --> LinkComp
    LinkComp --> Bler
    LinkComp --> L2S
    Bler --> OutputsConfig
    L2S --> MetricsDir
    L2S --> ScenarioOut

    %% Click Events
    click SimulationConfiguration "https://github.com/efontesp90/llsim5g/tree/main/simulation_settings/"
    click Main "https://github.com/efontesp90/llsim5g/blob/main/main.py"
    click Scenario "https://github.com/efontesp90/llsim5g/tree/main/scenario/"
    click ScenarioDefinition "https://github.com/efontesp90/llsim5g/blob/main/scenario/scenario_definition.py"
    click MobilityModels "https://github.com/efontesp90/llsim5g/blob/main/scenario/mobility/models.py"
    click SatellitesInfo "https://github.com/efontesp90/llsim5g/blob/main/scenario/satellites_lla_info.py"
    click ScenarioShow "https://github.com/efontesp90/llsim5g/blob/main/scenario/show.py"
    click GeometryDir "https://github.com/efontesp90/llsim5g/tree/main/channel_models/geometry/"
    click CMTR811 "https://github.com/efontesp90/llsim5g/blob/main/channel_models/channel_model_tr_38_811.py"
    click CMTR901 "https://github.com/efontesp90/llsim5g/blob/main/channel_models/channel_model_tr_38_901.py"
    click PLTR811 "https://github.com/efontesp90/llsim5g/blob/main/channel_models/path_loss_models_tr_38_811.py"
    click PLTR901 "https://github.com/efontesp90/llsim5g/blob/main/channel_models/path_loss_models_tr_38_901.py"
    click PLA2G "https://github.com/efontesp90/llsim5g/blob/main/channel_models/path_loss_models_a2g.py"
    click FFJakes "https://github.com/efontesp90/llsim5g/blob/main/channel_models/ff_model_jakes.py"
    click FFDir "https://github.com/efontesp90/llsim5g/tree/main/channel_models/ff_models_tr_38_901and811/"
    click Spectroscopic "https://github.com/efontesp90/llsim5g/blob/main/channel_models/spectroscopic_data.py"
    click LinkComp "https://github.com/efontesp90/llsim5g/blob/main/link_computation/link_computation.py"
    click Bler "https://github.com/efontesp90/llsim5g/blob/main/link_to_system_adaptation/bler_curves.py"
    click L2S "https://github.com/efontesp90/llsim5g/blob/main/link_to_system_adaptation/link_to_system.py"
    click OutputsConfig "https://github.com/efontesp90/llsim5g/blob/main/output/outputs_config.py"
    click MetricsDir "https://github.com/efontesp90/llsim5g/tree/main/output/metrics/"
    click ScenarioOut "https://github.com/efontesp90/llsim5g/tree/main/output/scenario/"
    click ATMNTN "https://github.com/efontesp90/llsim5g/blob/main/validation/atmospheric_absorption_ntn.py"
    click ATMtn "https://github.com/efontesp90/llsim5g/blob/main/validation/atmospheric_absorption_tn.py"
    click Realization "https://github.com/efontesp90/llsim5g/blob/main/validation/realization.h5"
    click SATVal "https://github.com/efontesp90/llsim5g/blob/main/validation/sattellite_antenna_model.py"
    click TERVal "https://github.com/efontesp90/llsim5g/blob/main/validation/terrestrial_antenna_model.py"
    click Requirements "https://github.com/efontesp90/llsim5g/blob/main/requirements.txt"
    click VirtualEnv "https://github.com/efontesp90/llsim5g/tree/main/myenv/"

    %% Styles
    classDef config fill:#D6E9FF,stroke:#0066CC,color:#000000
    classDef core fill:#DFFFE0,stroke:#009933,color:#000000
    classDef adaptation fill:#FFE5CC,stroke:#CC6600,color:#000000
    classDef output fill:#E0E0E0,stroke:#666666,color:#000000
    classDef validation fill:#E0E0E0,stroke:#666666,color:#000000
    classDef env fill:#E0E0E0,stroke:#666666,color:#000000
```
