# ebhrz/tdl-gnss architecture

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

- Interactive diagram: https://gitdiagram.com/ebhrz/tdl-gnss
- Repository: https://github.com/ebhrz/tdl-gnss

## Overview

1. **Overall shape**
   - This repo is a **command-line GNSS learning pipeline**, not a general-purpose application.
   - The architecture is centered on a single flow: **dataset/config → preprocessing cache → model training or evaluation → GNSS position output**.

2. **Primary entry points**
   - `preprocess.py` prepares data and builds cached intermediate artifacts.
   - `train.py` trains the deep model using cached GNSS features and ground truth.
   - `evaluate.py` runs inference and produces final positioning results.
   - `baseline.py` runs a non-learning comparison baseline, described in the README as **GoGPS**.

3. **Configuration is the main control boundary**
   - The project is entirely **config-driven** through JSON files in `config/`.
   - There are two data modes:
     - **Custom datasets**: specify `obs`, `gt`, `start_utc`, `end_utc`, etc.
     - **KLT datasets**: specify `prefix` plus a list of dataset config files under `datasets`.
   - The config also controls `mode`, `loss_type`, `save_path`, `model_path`, `device`, and `epoch`.

4. **Dataset boundary and input sources**
   - Input data is external to the codebase and expected to live under a local folder such as `data/` or `KLTDataset/`.
   - The repo consumes:
     - GNSS observation files,
     - ephemeris files,
     - ground-truth CSVs,
     - and, for KLT, dataset metadata configs.
   - This makes the repo a **processing and learning layer on top of dataset files**, not a dataset host.

5. **Preprocessing/cache layer**
   - The README says preprocessing generates `preprocess.pkl` files in the target folder.
   - This layer exists to avoid recomputing positioning-related quantities during training.
   - Architecturally, it is the key performance boundary: expensive GNSS feature generation is moved out of the inner training loop.

6. **GNSS computation core lives outside this repo**
   - The README explicitly says core functionality has moved to **TASGNSS** and the project is built on **pyrtklib** and **TASGNSS**.
   - That means this repo mainly orchestrates:
     - feature extraction,
     - learning,
     - and feedback into GNSS positioning,
     while the underlying GNSS math/solver functions come from external libraries.

7. **Model subsystem**
   - The only model code in-tree is `model/model.py`, so the learned component is intentionally compact.
   - The README describes the network as predicting **pseudorange corrections and weights** from GNSS-derived features such as:
     - C/N0,
     - elevation angle,
     - residuals from an equal-weight WLS solution,
     - and in the newer update, **azimuth** and **system one-hot encoding**.
   - This is a **tightly coupled model**, not a standalone classifier or regressor.

8. **Training loop and feedback path**
   - During training, the network output is fed back into a **weighted least squares (WLS)** GNSS solver.
   - The solver produces the final position estimate, which is compared against ground truth.
   - The loss is computed on the **position error** rather than directly on the network outputs, so the model learns through the GNSS solver boundary.
   - This is the repo’s most important data flow: **raw GNSS features → neural adjustments → WLS position → loss vs GT**.

9. **Inference/evaluation path**
   - `evaluate.py` uses the same preprocessing and solver path, but without backpropagation.
   - The README states that the **WLS output is the final predicted position** during prediction.
   - This implies training and inference share the same GNSS/solver pipeline, with only the learning step removed at evaluation time.

10. **Model variants and training behavior**
   - The README mentions bias-only, weight-only, and hybrid network training behavior.
   - This suggests the model layer is configurable in terms of what it predicts, but the repository keeps those details behind the training script and `model/model.py`.

11. **Outputs and artifacts**
   - Results are written under `save_path`.
   - Typical artifacts include:
     - cached preprocessing files,
     - trained model checkpoints,
     - evaluation outputs/results.
   - The filesystem layout is therefore part of the architecture: each experiment is isolated by config and output directory.

12. **Technology/runtime boundaries that matter**
   - The repo is a **Python** project with pip-based dependencies in `requirements.txt`.
   - It is designed to run on CPU as a practical default; the README notes training is often faster on CPU because the workload is logic-heavy rather than GPU-heavy.
   - The project is therefore best understood as a **Python GNSS processing pipeline with a lightweight learned module**, rather than a large deep-learning stack.

13. **External integrations**
   - The dataset boundary is important: KLT support is special-cased, and custom datasets must match the expected GNSS/GT file conventions.
   - The baseline comparison is external to the learned pipeline.
   - The repo also references linked external projects and datasets as part of the broader system: **TASGNSS**, **pyrtklib**, and **KLTDataset**.

Main entry points: [`evaluate.py`](https://github.com/ebhrz/tdl-gnss/blob/main/evaluate.py) (Evaluate), [`train.py`](https://github.com/ebhrz/tdl-gnss/blob/main/train.py) (Train), [`preprocess.py`](https://github.com/ebhrz/tdl-gnss/blob/main/preprocess.py) (Preprocess), [`baseline.py`](https://github.com/ebhrz/tdl-gnss/blob/main/baseline.py) (Baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry points"]
  node_n_preprocess["Preprocess<br/>CLI<br/>[preprocess.py]"]
  node_n_train["Train<br/>CLI<br/>[train.py]"]
  node_n_evaluate["Evaluate<br/>CLI<br/>[evaluate.py]"]
  node_n_baseline["Baseline<br/>CLI<br/>[baseline.py]"]
end

subgraph group_grp_config["Config layer"]
  node_n_train_cfg["Train config<br/>json config<br/>[train.json]"]
  node_n_cross_cfg["Cross config<br/>json config<br/>[train_cross.json]"]
  node_n_test_klt1_cfg["KLT test 1<br/>json config<br/>[test_klt1.json]"]
  node_n_test_klt2_cfg["KLT test 2<br/>json config<br/>[test_klt2.json]"]
  node_n_whampoa_cfg["Whampoa<br/>json config<br/>[whampoa_0521.json]"]
end

subgraph group_grp_core["GNSS pipeline"]
  node_n_cache[("Preprocess cache<br/>artifact")]
  node_n_solver{{"WLS solver<br/>GNSS solver"}}
  node_n_loss(("Position loss<br/>objective"))
end

subgraph group_grp_model["Learning module"]
  node_n_model["Model<br/>neural net<br/>[model.py]"]
  node_n_features["GNSS features<br/>feature set"]
end

subgraph group_grp_external["External systems"]
  node_n_data[("Dataset files<br/>external data")]
  node_n_tasgnss{{"TASGNSS<br/>external GNSS lib"}}
  node_n_pyrtklib{{"pyrtklib<br/>external GNSS lib"}}
end

node_n_train_cfg -->|"drives"| node_n_preprocess
node_n_test_klt1_cfg -->|"drives"| node_n_evaluate
node_n_test_klt2_cfg -->|"drives"| node_n_evaluate
node_n_whampoa_cfg -->|"drives"| node_n_preprocess
node_n_whampoa_cfg -->|"drives"| node_n_train
node_n_preprocess -->|"reads"| node_n_data
node_n_preprocess -->|"writes"| node_n_cache
node_n_train -->|"reads"| node_n_cache
node_n_evaluate -->|"reads"| node_n_cache
node_n_train -->|"consumes"| node_n_features
node_n_evaluate -->|"consumes"| node_n_features
node_n_features -->|"inputs"| node_n_model
node_n_model -->|"predicts corrections"| node_n_solver
node_n_solver -->|"produces position"| node_n_loss
node_n_loss -->|"backpropagates"| node_n_train
node_n_solver -->|"final output"| node_n_evaluate
node_n_train -.->|"depends on"| node_n_tasgnss
node_n_evaluate -.->|"depends on"| node_n_tasgnss
node_n_tasgnss -.->|"built on"| node_n_pyrtklib
node_n_baseline -->|"reads"| node_n_data
node_n_baseline -.->|"compares against"| node_n_solver

click node_n_preprocess "https://github.com/ebhrz/tdl-gnss/blob/main/preprocess.py"
click node_n_train "https://github.com/ebhrz/tdl-gnss/blob/main/train.py"
click node_n_evaluate "https://github.com/ebhrz/tdl-gnss/blob/main/evaluate.py"
click node_n_baseline "https://github.com/ebhrz/tdl-gnss/blob/main/baseline.py"
click node_n_train_cfg "https://github.com/ebhrz/tdl-gnss/blob/main/config/train.json"
click node_n_cross_cfg "https://github.com/ebhrz/tdl-gnss/blob/main/config/train_cross.json"
click node_n_test_klt1_cfg "https://github.com/ebhrz/tdl-gnss/blob/main/config/test_klt1.json"
click node_n_test_klt2_cfg "https://github.com/ebhrz/tdl-gnss/blob/main/config/test_klt2.json"
click node_n_whampoa_cfg "https://github.com/ebhrz/tdl-gnss/blob/main/config/whampoa_0521.json"
click node_n_model "https://github.com/ebhrz/tdl-gnss/blob/main/model/model.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_n_preprocess,node_n_train,node_n_evaluate,node_n_baseline toneBlue
class node_n_train_cfg,node_n_cross_cfg,node_n_test_klt1_cfg,node_n_test_klt2_cfg,node_n_whampoa_cfg toneAmber
class node_n_cache,node_n_solver,node_n_loss toneMint
class node_n_model,node_n_features toneRose
class node_n_data,node_n_tasgnss,node_n_pyrtklib toneIndigo
```

## Components

### Entry points

CLI scripts that drive preprocessing, training, evaluation, and baseline comparison.

- [Preprocess](https://github.com/ebhrz/tdl-gnss/blob/main/preprocess.py): CLI · Builds cached GNSS preprocessing artifacts for later runs. · `preprocess.py`
- [Train](https://github.com/ebhrz/tdl-gnss/blob/main/train.py): CLI · Runs model training against cached features and ground truth. · `train.py`
- [Evaluate](https://github.com/ebhrz/tdl-gnss/blob/main/evaluate.py): CLI · Runs inference and emits final positioning results. · `evaluate.py`
- [Baseline](https://github.com/ebhrz/tdl-gnss/blob/main/baseline.py): CLI · Runs the GoGPS comparison baseline. · `baseline.py`

### Config layer

JSON experiment definitions and dataset selection boundary.

- [Train config](https://github.com/ebhrz/tdl-gnss/blob/main/config/train.json): json config · Main training experiment settings and dataset selection. · `config/train.json`
- [Cross config](https://github.com/ebhrz/tdl-gnss/blob/main/config/train_cross.json): json config · Alternative training configuration for cross-dataset setup. · `config/train_cross.json`
- [KLT test 1](https://github.com/ebhrz/tdl-gnss/blob/main/config/test_klt1.json): json config · KLT evaluation configuration for one dataset set. · `config/test_klt1.json`
- [KLT test 2](https://github.com/ebhrz/tdl-gnss/blob/main/config/test_klt2.json): json config · KLT evaluation configuration for another dataset set. · `config/test_klt2.json`
- [Whampoa](https://github.com/ebhrz/tdl-gnss/blob/main/config/whampoa_0521.json): json config · Dataset-specific configuration example. · `config/whampoa_0521.json`

### GNSS pipeline

Preprocessing, solver-backed training, and inference flow.

- **Preprocess cache**: artifact · Cached preprocessing output such as preprocess.pkl.
- **WLS solver**: GNSS solver · Weighted least squares position solver used in both training and inference.
- **Position loss**: objective · Compares solver-derived position against ground truth.

### Learning module

Compact neural network used to predict GNSS corrections and weights.

- [Model](https://github.com/ebhrz/tdl-gnss/blob/main/model/model.py): neural net · Predicts pseudorange corrections and weights from GNSS features. · `model/model.py`
- **GNSS features**: feature set · Inputs such as C/N0, elevation, residuals, azimuth, and system encoding.

### External systems

Datasets and third-party GNSS libraries that sit outside the repository.

- **Dataset files**: external data · Observation files, ephemeris, ground truth, and dataset metadata outside the repo.
- **TASGNSS**: external GNSS lib · External GNSS core functionality used by the pipeline.
- **pyrtklib**: external GNSS lib · Underlying RTK/GNSS library dependency.

## Connections

- Train config → Preprocess: drives · Config selects dataset mode, paths, and preprocessing behavior.
- KLT test 1 → Evaluate: drives · Evaluation config selects KLT datasets and output paths.
- KLT test 2 → Evaluate: drives · Evaluation config selects KLT datasets and output paths.
- Whampoa → Preprocess: drives · Dataset-specific config is consumed by preprocessing.
- Whampoa → Train: drives · Same config family controls training runs and experiment output.
- Preprocess → Dataset files: reads · Consumes observation, ephemeris, and ground-truth files.
- Preprocess → Preprocess cache: writes · Generates cached preprocessing artifacts.
- Train → Preprocess cache: reads · Uses cached features instead of recomputing preprocessing.
- Evaluate → Preprocess cache: reads · Uses the same cached preprocessing path for inference.
- Train → GNSS features: consumes · Builds model inputs from GNSS-derived features.
- Evaluate → GNSS features: consumes · Builds inference inputs from the same feature set.
- GNSS features → Model: inputs · Feature vectors feed the compact prediction model.
- Model → WLS solver: predicts corrections · Model outputs adjust pseudorange weights/corrections used by WLS.
- WLS solver → Position loss: produces position · Solver returns the estimated position used for supervision.
- Position loss → Train: backpropagates · Training optimizes position error rather than raw network outputs.
- WLS solver → Evaluate: final output · Inference returns WLS position as the final predicted result.
- Train → TASGNSS: depends on · Training pipeline relies on external GNSS functionality.
- Evaluate → TASGNSS: depends on · Evaluation uses the same external GNSS computation layer.
- TASGNSS → pyrtklib: built on · External GNSS stack sits on pyrtklib.
- Baseline → Dataset files: reads · Baseline compares against the same dataset inputs.
- Baseline → WLS solver: compares against · GoGPS baseline is used as a non-learning reference.
