# suvambasak/leocraft architecture

> Architecture diagram of the GitHub repository suvambasak/leocraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suvambasak/leocraft
- Repository: https://github.com/suvambasak/leocraft
- Video tour (about a minute): https://gitdiagram.com/suvambasak/leocraft/video

## Overview

LEOCraft is a flow-level low-Earth-orbit network simulator. Users provide terminal/traffic data and constellation parameters; the simulator builds the satellite network and routes, then evaluates throughput, stretch/latency, and coverage, with visualization and design-optimization workflows as additional capabilities. The graph covers the documented aviation branch and research workflows as well. Edges use README statements or SOURCE INDEX references; unsampled modules are represented only at supported paths, so some internal links are intentionally omitted.

Main entry points: [`LEOCraft/simulator/LEO_constellation_simulator.py`](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/simulator/LEO_constellation_simulator.py) (Simulation runner), [`LEOCraft/constellations/constellation.py`](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/constellation.py) (Constellation network), [`LEOCraft/satellite_topology/plus_grid_shell.py`](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/plus_grid_shell.py) (+Grid shell), [`LEOCraft/constellations/LEO_constellation.py`](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_constellation.py) (Ground constellation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and terminals"]
  node_datasets["Traffic datasets<br/>[dataset.py]"]
  node_groundstations["Ground stations<br/>[ground_station.py]"]
  node_aircraft["Aircraft terminals<br/>[aircraft.py]"]
  node_terminal["Terminal coordinates<br/>[terminal.py]"]
end

subgraph group_network["Constellation modeling"]
  node_loss["FSPL loss model<br/>[fspl.py]"]
  node_shell["+Grid shell<br/>[plus_grid_shell.py]"]
  node_satellite["Satellite model<br/>[satellite.py]"]
  node_topology["Satellite topology"]
  node_constellation["Constellation network<br/>[constellation.py]"]
  node_leo["Ground constellation"]
  node_aviation["Aviation constellation"]
  node_routes["Route generation"]
end

subgraph group_evaluation["Simulation and metrics"]
  node_simulator["Simulation runner"]
  node_aviation_sim["Aviation runner"]
  node_throughput["Throughput<br/>[throughput.py]"]
  node_lp["Throughput optimizer<br/>[throughput_LP.py]"]
  node_coverage["Coverage<br/>[coverage.py]"]
  node_stretch["Stretch and latency<br/>[stretch.py]"]
  node_aviation_metrics["Aviation metrics"]
end

subgraph group_research["Analysis and visualization"]
  node_optimization["Design optimization"]
  node_visualization["Network visualization<br/>[view.py]"]
  node_visual3d["3D satellite views<br/>[sat_view_3D.py]"]
end

node_user(("Researcher"))

node_user -->|"supplies terminals"| node_groundstations
node_user -->|"selects traffic"| node_datasets
node_groundstations -->|"builds coordinates"| node_terminal
node_aircraft -->|"uses coordinates"| node_terminal
node_user -->|"configures link model"| node_loss
node_user -->|"sets shell parameters"| node_shell
node_shell -->|"extends topology"| node_topology
node_shell -->|"builds satellites"| node_satellite
node_constellation -->|"uses shells"| node_topology
node_constellation -->|"uses terminals"| node_terminal
node_constellation -->|"uses link loss"| node_loss
node_leo -->|"extends base"| node_constellation
node_aviation -->|"extends base"| node_constellation
node_leo -->|"generates routes"| node_routes
node_user -->|"runs simulation"| node_simulator
node_simulator -->|"runs constellation"| node_leo
node_simulator -->|"computes coverage"| node_coverage
node_simulator -->|"computes stretch"| node_stretch
node_simulator -->|"computes throughput"| node_throughput
node_aviation_sim -->|"runs constellation"| node_aviation
node_aviation_sim -->|"computes metrics"| node_aviation_metrics
node_throughput -->|"forms LP"| node_lp
node_user -->|"optimizes design"| node_optimization
node_optimization -->|"evaluates candidates"| node_simulator
node_user -->|"views network"| node_visualization
node_visualization -->|"reads network state"| node_constellation
node_visual3d -->|"uses view layer"| node_visualization

click node_datasets "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/dataset.py"
click node_groundstations "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/ground_station.py"
click node_aircraft "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/aircraft.py"
click node_terminal "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/terminal.py"
click node_loss "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/attenuation/fspl.py"
click node_shell "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/plus_grid_shell.py"
click node_satellite "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/satellite.py"
click node_topology "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/LEO_sat_topology.py"
click node_constellation "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/constellation.py"
click node_leo "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_constellation.py"
click node_aviation "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_aviation_constellation.py"
click node_routes "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_constellation.py"
click node_simulator "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/simulator/LEO_constellation_simulator.py"
click node_aviation_sim "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/simulator/LEO_aviation_constellation_simulator.py"
click node_throughput "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/basic/throughput.py"
click node_lp "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/throughput_LP.py"
click node_coverage "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/basic/coverage.py"
click node_stretch "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/stretch.py"
click node_aviation_metrics "https://github.com/suvambasak/leocraft/tree/main/LEOCraft/performance/aviation"
click node_optimization "https://github.com/suvambasak/leocraft/blob/main/experiments/blackbox_optimization/variable_neighborhood_search.py"
click node_visualization "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/visuals/view.py"
click node_visual3d "https://github.com/suvambasak/leocraft/blob/main/LEOCraft/visuals/sat_view_3D.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_datasets,node_groundstations,node_aircraft,node_terminal toneBlue
class node_loss,node_shell,node_satellite,node_topology,node_constellation,node_leo,node_aviation,node_routes toneAmber
class node_simulator,node_aviation_sim,node_throughput,node_lp,node_coverage,node_stretch,node_aviation_metrics toneMint
class node_optimization,node_visualization,node_visual3d toneRose
class node_user toneIndigo
```

## Components

### Inputs and terminals

- [Traffic datasets](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/dataset.py): `LEOCraft/dataset.py`
- [Ground stations](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/ground_station.py): `LEOCraft/user_terminals/ground_station.py`
- [Aircraft terminals](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/aircraft.py): `LEOCraft/user_terminals/aircraft.py`
- [Terminal coordinates](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/user_terminals/terminal.py): `LEOCraft/user_terminals/terminal.py`

### Constellation modeling

- [FSPL loss model](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/attenuation/fspl.py): `LEOCraft/attenuation/fspl.py`
- [+Grid shell](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/plus_grid_shell.py): `LEOCraft/satellite_topology/plus_grid_shell.py`
- [Satellite model](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/satellite.py): `LEOCraft/satellite_topology/satellite.py`
- [Satellite topology](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/satellite_topology/LEO_sat_topology.py): `LEOCraft/satellite_topology/LEO_sat_topology.py`
- [Constellation network](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/constellation.py): `LEOCraft/constellations/constellation.py`
- [Ground constellation](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_constellation.py): `LEOCraft/constellations/LEO_constellation.py`
- [Aviation constellation](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_aviation_constellation.py): `LEOCraft/constellations/LEO_aviation_constellation.py`
- [Route generation](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/constellations/LEO_constellation.py): `LEOCraft/constellations/LEO_constellation.py`

### Simulation and metrics

- [Simulation runner](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/simulator/LEO_constellation_simulator.py): `LEOCraft/simulator/LEO_constellation_simulator.py`
- [Aviation runner](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/simulator/LEO_aviation_constellation_simulator.py): `LEOCraft/simulator/LEO_aviation_constellation_simulator.py`
- [Throughput](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/basic/throughput.py): `LEOCraft/performance/basic/throughput.py`
- [Throughput optimizer](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/throughput_LP.py): `LEOCraft/performance/throughput_LP.py`
- [Coverage](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/basic/coverage.py): `LEOCraft/performance/basic/coverage.py`
- [Stretch and latency](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/performance/stretch.py): `LEOCraft/performance/stretch.py`
- [Aviation metrics](https://github.com/suvambasak/leocraft/tree/main/LEOCraft/performance/aviation): `LEOCraft/performance/aviation`

### Analysis and visualization

- [Design optimization](https://github.com/suvambasak/leocraft/blob/main/experiments/blackbox_optimization/variable_neighborhood_search.py): `experiments/blackbox_optimization/variable_neighborhood_search.py`
- [Network visualization](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/visuals/view.py): `LEOCraft/visuals/view.py`
- [3D satellite views](https://github.com/suvambasak/leocraft/blob/main/LEOCraft/visuals/sat_view_3D.py): `LEOCraft/visuals/sat_view_3D.py`

### Other components

- **Researcher**

## Connections

- Researcher → Ground stations: supplies terminals (evidence: `README.md`)
- Researcher → Traffic datasets: selects traffic (evidence: `README.md`)
- Ground stations → Terminal coordinates: builds coordinates (evidence: `LEOCraft/user_terminals/ground_station.py`)
- Aircraft terminals → Terminal coordinates: uses coordinates (evidence: `LEOCraft/constellations/LEO_aviation_constellation.py`)
- Researcher → FSPL loss model: configures link model (evidence: `README.md`)
- Researcher → +Grid shell: sets shell parameters (evidence: `README.md`)
- +Grid shell → Satellite topology: extends topology (evidence: `LEOCraft/satellite_topology/plus_grid_shell.py`)
- +Grid shell → Satellite model: builds satellites (evidence: `LEOCraft/satellite_topology/plus_grid_shell.py`)
- Constellation network → Satellite topology: uses shells (evidence: `LEOCraft/constellations/constellation.py`)
- Constellation network → Terminal coordinates: uses terminals (evidence: `LEOCraft/constellations/constellation.py`)
- Constellation network → FSPL loss model: uses link loss (evidence: `LEOCraft/constellations/constellation.py`)
- Ground constellation → Constellation network: extends base (evidence: `LEOCraft/constellations/LEO_constellation.py`)
- Aviation constellation → Constellation network: extends base (evidence: `LEOCraft/constellations/LEO_aviation_constellation.py`)
- Ground constellation → Route generation: generates routes (evidence: `LEOCraft/constellations/LEO_constellation.py`)
- Researcher → Simulation runner: runs simulation (evidence: `README.md`)
- Simulation runner → Ground constellation: runs constellation (evidence: `LEOCraft/simulator/LEO_constellation_simulator.py`)
- Simulation runner → Coverage: computes coverage (evidence: `LEOCraft/simulator/LEO_constellation_simulator.py`)
- Simulation runner → Stretch and latency: computes stretch
- Simulation runner → Throughput: computes throughput (evidence: `LEOCraft/simulator/LEO_constellation_simulator.py`)
- Aviation runner → Aviation constellation: runs constellation (evidence: `LEOCraft/simulator/LEO_aviation_constellation_simulator.py`)
- Aviation runner → Aviation metrics: computes metrics (evidence: `LEOCraft/simulator/LEO_aviation_constellation_simulator.py`)
- Throughput → Throughput optimizer: forms LP (evidence: `LEOCraft/performance/basic/throughput.py`)
- Researcher → Design optimization: optimizes design (evidence: `experiments/blackbox_optimization/variable_neighborhood_search.py`)
- Design optimization → Simulation runner: evaluates candidates (evidence: `experiments/blackbox_optimization/variable_neighborhood_search.py`)
- Researcher → Network visualization: views network (evidence: `README.md`)
- Network visualization → Constellation network: reads network state (evidence: `LEOCraft/visuals/view.py`)
- 3D satellite views → Network visualization: uses view layer (evidence: `LEOCraft/visuals/sat_view_3D.py`)
