# snkas/hypatia architecture

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

- Interactive diagram: https://gitdiagram.com/snkas/hypatia
- Repository: https://github.com/snkas/hypatia

## Overview

##### Main Components
- satgenpy (Python network‑state generator & analysis)
- ns3‑sat‑sim (ns‑3 packet‑level simulator)
- satviz (CesiumJS visualization pipeline)
- paper (experiment orchestration & plotting)
- integration_tests (end‑to‑end test harness)

##### Relationships & Data Flows
- satgenpy → outputs “network state over time” (static topology + dynamic link state + routing tables)
- ns3‑sat‑sim ← consumes satgenpy outputs → runs ns‑3 simulations → produces raw trace files, logs, gnuplot scripts
- paper ← uses satgenpy outputs & ns3‑sat‑sim results → runs Python scripts + gnuplot → generates publication figures
- satviz ← consumes satgenpy outputs (optionally ns3‑sat‑sim link‑utilization logs) → generates CesiumJS code and static HTML
- integration_tests orchestrate: call satgenpy scripts → call ns3‑sat‑sim build & run → call paper & satviz scripts → verify final outputs

##### Architectural Patterns & Principles
- Modular pipeline: clear producer/consumer boundaries via file‐based I/O
- Layered abstraction:
- “Network‐state generation” (pure Python)
- “Simulate” (ns‑3 C++ + Python glue)
- “Post‐process & plot” (Python + gnuplot)
- Reuse of open‐source modules: ns‑3 satellite module, basic‑sim, Cesium API

##### Technologies & External Dependencies
- Python 3.7+, numpy, networkx, astropy, sgp4, exputil, matplotlib, statsmodels, cartopy
- ns‑3 (v3.31) + satellite & basic‑sim modules, OpenMPI, lcov, gnuplot
- Cesium API (requires access token), CesiumJS
- Bash scripts to install deps, build modules, run tests

- Titles: “Hypatia Simulation Framework Architecture”
- Clouds: Python runtime + libs, ns‑3 engine, Cesium API, gnuplot

## Diagram (Mermaid)

```mermaid
flowchart TD
    title["Hypatia Simulation Framework Architecture"]

    %% External Services/Dependencies
    subgraph "External Dependencies"
        direction TB
        python_libs(["Python 3.7+ & Libraries"]):::cloud
        ns3_engine(["ns-3 v3.31 + satellite & basic-sim modules"]):::cloud
        cesium_api(["Cesium API (access token)"]):::cloud
        gnuplot_tool(["gnuplot"]):::cloud
    end

    %% Main Pipeline
    subgraph "Network-State Generation"
        direction TB
        satgenpy["satgenpy"]:::python
        satgenpy_tles["tles"]:::python
        satgenpy_dyn["dynamic_state"]:::python
        satgenpy_gs["ground_stations"]:::python
        satgenpy_if["interfaces"]:::python
        satgenpy_isls["isls"]:::python
        satgenpy_pa["post_analysis"]:::python
    end

    network_state["network_state (csv, properties, tar.gz)"]:::data

    subgraph "Simulation"
        direction TB
        ns3_sat_sim["ns3-sat-sim"]:::cplus
        sim_output["simulation_output (logs, traces, gnuplot scripts)"]:::data
    end

    subgraph "Post-Process & Plot"
        direction TB
        paper["paper"]:::python
        figures["figures_output (.plt, .png)"]:::data
    end

    subgraph "Visualization"
        direction TB
        satviz["satviz"]:::python
        html_vis["static_html"]:::data
    end

    %% Integration Tests
    integration_tests["integration_tests"]:::python

    %% DevOps Layer
    subgraph "DevOps Scripts"
        direction TB
        build_script["hypatia_build.sh"]:::shell
        install_deps["hypatia_install_dependencies.sh"]:::shell
        run_tests["hypatia_run_tests.sh"]:::shell
    end

    %% Connections
    python_libs --> satgenpy
    python_libs --> paper
    python_libs --> satviz

    satgenpy --> network_state
    satgenpy_tles --> satgenpy
    satgenpy_dyn --> satgenpy
    satgenpy_gs --> satgenpy
    satgenpy_if --> satgenpy
    satgenpy_isls --> satgenpy
    satgenpy_pa --> satgenpy

    network_state -->|".tar.gz, .properties, .csv"| ns3_sat_sim
    ns3_engine --> ns3_sat_sim
    ns3_sat_sim --> sim_output

    satgenpy -->|".csv, .json"| paper
    sim_output -->|".py→gnuplot"| paper
    gnuplot_tool --> paper
    paper --> figures

    satgenpy -->|".json, .czml"| satviz
    sim_output -->|"(optional) traces"| satviz
    cesium_api --> satviz
    satviz --> html_vis

    %% Integration Tests Orchestration
    integration_tests --> satgenpy
    integration_tests --> ns3_sat_sim
    integration_tests --> paper
    integration_tests --> satviz

    %% DevOps triggers
    build_script --> satgenpy
    build_script --> ns3_sat_sim
    install_deps --> satgenpy
    install_deps --> ns3_sat_sim
    run_tests --> integration_tests

    %% Click Events
    click satgenpy "https://github.com/snkas/hypatia/tree/master/satgenpy/"
    click satgenpy_tles "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/tles/"
    click satgenpy_dyn "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/dynamic_state/"
    click satgenpy_gs "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/ground_stations/"
    click satgenpy_if "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/interfaces/"
    click satgenpy_isls "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/isls/"
    click satgenpy_pa "https://github.com/snkas/hypatia/tree/master/satgenpy/satgen/post_analysis/"
    click integration_tests "https://github.com/snkas/hypatia/tree/master/integration_tests/"
    click ns3_sat_sim "https://github.com/snkas/hypatia/tree/master/ns3-sat-sim/"
    click paper "https://github.com/snkas/hypatia/tree/master/paper/"
    click satviz "https://github.com/snkas/hypatia/tree/master/satviz/"

    %% Styles
    classDef python fill:#D0E1F9,stroke:#0B5394,color:#073763
    classDef cplus fill:#D5E8D4,stroke:#82B366,color:#38610B
    classDef data fill:#FFF2CC,stroke:#D6B656,color:#7F6000,shape:ellipse
    classDef cloud fill:#E1D5E7,stroke:#9673A6,color:#5B386F,shape:cloud
    classDef shell fill:#FDE9D9,stroke:#E69138,color:#974806
    class title fill:none,stroke:none,color:#000000,font-size:16px,font-weight:bold
```
