# yutailin1993/ns3-wifi-multilateration architecture

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

- Interactive diagram: https://gitdiagram.com/yutailin1993/ns3-wifi-multilateration
- Repository: https://github.com/yutailin1993/ns3-wifi-multilateration

## Overview

##### Project Type and Purpose
- CO2P is a domain-specific extension of the NS-3 network simulator, not a web app or microservices system. It injects new positioning algorithms (centralizedCP, centralizedIP, distributedCP) into the NS-3 simulation framework.
- The goal is to simulate “communication-aware collaborative positioning” in FutureG wireless networks, using C++ modules under NS-3 and a Python helper (graph.py) for topology and MDS localization.

##### High-Level File Structure Analysis
- NS-3 Core & Modules (src/, bindings/, examples/, scratch/, build-support/, utils/, etc.)
- src/*: hundreds of standard NS-3 C++ modules (core, internet, wifi, mobility, propagation, etc.)
- bindings/python: Python support for NS-3 modules
- build-support: CMake macros and templates for building NS-3
- Application-Specific Code
- scratch/
– multilateration.cc – entry point for all paradigms
– multilateralation-core.{cc,h} – shared core functions
- graph.py – Python script for graph operations (rigid topology, MDS)
- Configuration & Build
- CMakeLists.txt at root and under scratch/
- ./ns3 build multilateration – custom NS-3 build invocation
- Documentation & README
- README.md explains branches, build and run steps
- README.md points to paper, NS-3 docs and wifi-ftm-ns3 repository

##### Key Components
A. CO2P User Code
- Entry Layer: scratch/multilateration.cc
- Core Library: scratch/multilateration-core.{cc,h}
- Graph Module: graph.py (Python process)
B. NS-3 Simulation Framework
- NS-3 Core Engine (src/core, src/network, src/mobility, etc.)
- NS-3 Protocol Modules (wifi, propagation, internet, etc.)
C. Build & Execution
- Build System: CMake + ns3 build scripts
- Runtime: ./ns3 run multilateration
D. External Dependencies
- Python runtime for graph.py
- NS-3 libraries (linked at build time)

##### Relationships and Data Flows
- Build Phase:
[CMakeLists.txt] → generates build targets → compiles NS-3 modules + scratch code → links into ns3 executable
- Runtime Phase:
1. User invokes `./ns3 run multilateration`
2. multilateration.cc initializes NS-3 simulator
3. When graph operations are needed:
→ calls out to Python interpreter running graph.py (via system call or embedded Python binding)
→ Python script computes rigid topology or MDS positions → returns data (via file, stdout or API)
4. NS-3 simulation uses computed positions, mobility models, wifi propagation modules to run experiments
5. Results (traces, logs) are output by NS-3 trace sinks

##### Architectural Patterns and Principles
- Plug-in Architecture: CO2P logic plugs into NS-3 core as “scratch” modules
- Separation of Concerns:
- C++ for high-performance simulation
- Python for high-level graph computations
- Modular Design: leverage existing NS-3 modules (mobility, wifi, propagation) without modifying them

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        CMakeRoot["Root CMakeLists.txt"]:::build
        CMakeScratch["Scratch CMakeLists.txt"]:::build
        BuildSupport["NS-3 Build Support"]:::build
    end

    %% Compiled Executable
    Exec["ns3 Executable"]:::build

    %% CO2P Plugin Layers
    subgraph "CO2P Plugin"
        EntryLayer["Entry Layer\n(scratch/multilateration.cc)"]:::co2p
        CoreLib["Core Library\n(scratch/multilateration-core.{cc,h})"]:::co2p
    end

    %% Python Module
    GraphModule["Python Graph Module\n(graph.py)"]:::python

    %% NS-3 Framework
    subgraph "NS-3 Framework"
        NS3Core["NS-3 Core Engine"]:::ns3core
        subgraph "Protocol Modules"
            Internet["Internet Stack"]:::ns3core
            WiFi["WiFi Module"]:::ns3core
            Mobility["Mobility Models"]:::ns3core
            Propagation["Propagation Models"]:::ns3core
            TraceUtils["Trace & Utils\n(trace-helper.{cc,h})"]:::ns3core
        end
    end

    %% External Runtime & Output
    PythonRuntime["Python Runtime"]:::external
    OutputLogs["Output Logs/Traces"]:::external

    %% Build Phase
    CMakeRoot -->|compile| Exec
    CMakeScratch -->|compile| Exec
    BuildSupport -->|compile| Exec

    %% Runtime Phase
    Exec -->|invoke| EntryLayer
    EntryLayer -->|calls| CoreLib
    CoreLib -->|uses NS-3 API| NS3Core
    NS3Core -->|simulate| Internet
    NS3Core -->|simulate| WiFi
    NS3Core -->|simulate| Mobility
    NS3Core -->|simulate| Propagation
    NS3Core -->|trace| TraceUtils

    CoreLib <-->|compute topology| GraphModule
    GraphModule -->|runs on| PythonRuntime

    NS3Core -->|output traces| OutputLogs

    %% Click Events
    click EntryLayer "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/scratch/multilateration.cc"
    click CoreLib "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/scratch/multilateration-core.cc"
    click CoreLib "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/scratch/multilateration-core.h"
    click GraphModule "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/graph.py"
    click CMakeRoot "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/CMakeLists.txt"
    click CMakeScratch "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/scratch/CMakeLists.txt"
    click BuildSupport "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/build-support/"
    click NS3Core "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/src/core/"
    click Internet "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/src/internet/"
    click WiFi "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/src/wifi/"
    click Mobility "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/src/mobility/"
    click Propagation "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/src/propagation/"
    click TraceUtils "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/src/network/helper/trace-helper.cc"
    click TraceUtils "https://github.com/yutailin1993/ns3-wifi-multilateration/blob/main/src/network/helper/trace-helper.h"
    click Exec "https://github.com/yutailin1993/ns3-wifi-multilateration/tree/main/ns3"

    %% Styles
    classDef build fill:#ffeb99,stroke:#cc9900,color:#333;
    classDef co2p fill:#ffd1dc,stroke:#d47a7a,color:#333;
    classDef python fill:#d1ffd6,stroke:#7abd8b,color:#333;
    classDef ns3core fill:#d1e0ff,stroke:#5a75cc,color:#333;
    classDef external fill:#ffc0c0,stroke:#cc6666,color:#333;
```
