# a-pru/descent architecture

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

- Interactive diagram: https://gitdiagram.com/a-pru/descent
- Repository: https://github.com/a-pru/descent

## Overview

DESCENT is a research system for predicting airport surface movement trajectories from Amelia-10 scenes and directed lane context. Its main workflow prepares airport-specific scene data, transforms agents and lane segments into an ego frame, predicts multimodal trajectories, and trains or evaluates them with displacement and lane-adherence objectives. Separate entry points generate lane maps and visualize predictions. The README documents these capabilities; some script and configuration wiring is not shown in the excerpts, so those links are cited to the README rather than inferred from module names.

Main entry points: [`descent/data/dataset.py`](https://github.com/a-pru/descent/blob/main/descent/data/dataset.py) (Scene dataset), [`descent/models/descent.py`](https://github.com/a-pru/descent/blob/main/descent/models/descent.py) (DESCENT network), [`descent/models/trajpred.py`](https://github.com/a-pru/descent/blob/main/descent/models/trajpred.py) (Prediction task), [`scripts/eval.py`](https://github.com/a-pru/descent/blob/main/scripts/eval.py) (Evaluation command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Scene and Maps"]
  node_datamodule["Data module<br/>[datamodule.py]"]
  node_dataset["Scene dataset<br/>[dataset.py]"]
  node_data_helpers["Data helpers<br/>[data_utils.py]"]
  node_feature_defs["Feature masks<br/>[global_masks.py]"]
  node_lane_maps["Directed lane maps"]
end

subgraph group_prediction["Prediction Model"]
  node_lane_encoder["Lane encoder<br/>[lane_embedding.py]"]
  node_transformer["Attention blocks"]
  node_decoder["Trajectory decoder<br/>[decoder.py]"]
  node_descent_model["DESCENT network<br/>[descent.py]"]
end

subgraph group_learning["Training and Evaluation"]
  node_trajpred["Prediction task<br/>[trajpred.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_metrics["Trajectory metrics<br/>[metrics.py]"]
  node_checkpoints["Model checkpoints"]
end

subgraph group_operations["User Workflows"]
  node_train_cli["Training command<br/>[train.py]"]
  node_eval_cli["Evaluation command<br/>[eval.py]"]
  node_visualize_cli["Visualization command<br/>[visualize.py]"]
  node_mapgen["Map generation<br/>[generate_maps.py]"]
  node_visualization["Prediction figures<br/>[visualize.py]"]
end

node_engineer(("Researcher"))
node_amelia[("Amelia-10 scenes")]

node_engineer -->|"starts training"| node_train_cli
node_engineer -->|"requests evaluation"| node_eval_cli
node_engineer -->|"requests visualization"| node_visualize_cli
node_engineer -->|"generates maps"| node_mapgen
node_amelia -->|"provides scenes"| node_dataset
node_mapgen -->|"writes maps"| node_lane_maps
node_dataset -->|"uses listing helpers"| node_data_helpers
node_datamodule -->|"uses utilities"| node_data_helpers
node_dataset -->|"uses feature indices"| node_feature_defs
node_lane_maps -->|"supplies lane context"| node_dataset
node_train_cli -->|"configures data"| node_datamodule
node_eval_cli -->|"evaluates test data"| node_datamodule
node_datamodule -->|"provides datasets"| node_dataset
node_dataset -.->|"provides scene inputs"| node_descent_model
node_descent_model -->|"encodes lane segments"| node_lane_encoder
node_descent_model -->|"applies attention blocks"| node_transformer
node_descent_model -->|"decodes trajectories"| node_decoder
node_trajpred -->|"runs network"| node_descent_model
node_trajpred -->|"computes loss"| node_losses
node_trajpred -->|"computes metrics"| node_metrics
node_train_cli -->|"trains task"| node_trajpred
node_eval_cli -->|"loads checkpoint"| node_checkpoints
node_eval_cli -->|"evaluates task"| node_trajpred
node_visualize_cli -.->|"uses predictions"| node_checkpoints
node_visualize_cli -->|"writes figures"| node_visualization

click node_train_cli "https://github.com/a-pru/descent/blob/main/scripts/train.py"
click node_eval_cli "https://github.com/a-pru/descent/blob/main/scripts/eval.py"
click node_visualize_cli "https://github.com/a-pru/descent/blob/main/scripts/visualize.py"
click node_mapgen "https://github.com/a-pru/descent/blob/main/scripts/generate_maps.py"
click node_datamodule "https://github.com/a-pru/descent/blob/main/descent/data/datamodule.py"
click node_dataset "https://github.com/a-pru/descent/blob/main/descent/data/dataset.py"
click node_data_helpers "https://github.com/a-pru/descent/blob/main/descent/utils/data_utils.py"
click node_feature_defs "https://github.com/a-pru/descent/blob/main/descent/utils/global_masks.py"
click node_lane_maps "https://github.com/a-pru/descent/tree/main/maps"
click node_lane_encoder "https://github.com/a-pru/descent/blob/main/descent/models/layers/lane_embedding.py"
click node_transformer "https://github.com/a-pru/descent/blob/main/descent/models/layers/transformer_blocks.py"
click node_decoder "https://github.com/a-pru/descent/blob/main/descent/models/layers/decoder.py"
click node_descent_model "https://github.com/a-pru/descent/blob/main/descent/models/descent.py"
click node_trajpred "https://github.com/a-pru/descent/blob/main/descent/models/trajpred.py"
click node_losses "https://github.com/a-pru/descent/blob/main/descent/utils/losses.py"
click node_metrics "https://github.com/a-pru/descent/blob/main/descent/utils/metrics.py"
click node_checkpoints "https://github.com/a-pru/descent/tree/main/checkpoints"
click node_visualization "https://github.com/a-pru/descent/blob/main/scripts/visualize.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_datamodule,node_dataset,node_data_helpers,node_feature_defs,node_lane_maps toneBlue
class node_lane_encoder,node_transformer,node_decoder,node_descent_model,node_amelia toneAmber
class node_trajpred,node_losses,node_metrics,node_checkpoints toneMint
class node_train_cli,node_eval_cli,node_visualize_cli,node_mapgen,node_visualization toneRose
class node_engineer toneIndigo
```

## Components

### Scene and Maps

- [Data module](https://github.com/a-pru/descent/blob/main/descent/data/datamodule.py): `descent/data/datamodule.py`
- [Scene dataset](https://github.com/a-pru/descent/blob/main/descent/data/dataset.py): `descent/data/dataset.py`
- [Data helpers](https://github.com/a-pru/descent/blob/main/descent/utils/data_utils.py): `descent/utils/data_utils.py`
- [Feature masks](https://github.com/a-pru/descent/blob/main/descent/utils/global_masks.py): `descent/utils/global_masks.py`
- [Directed lane maps](https://github.com/a-pru/descent/tree/main/maps): `maps`

### Prediction Model

- [Lane encoder](https://github.com/a-pru/descent/blob/main/descent/models/layers/lane_embedding.py): `descent/models/layers/lane_embedding.py`
- [Attention blocks](https://github.com/a-pru/descent/blob/main/descent/models/layers/transformer_blocks.py): `descent/models/layers/transformer_blocks.py`
- [Trajectory decoder](https://github.com/a-pru/descent/blob/main/descent/models/layers/decoder.py): `descent/models/layers/decoder.py`
- [DESCENT network](https://github.com/a-pru/descent/blob/main/descent/models/descent.py): `descent/models/descent.py`

### Training and Evaluation

- [Prediction task](https://github.com/a-pru/descent/blob/main/descent/models/trajpred.py): `descent/models/trajpred.py`
- [Training losses](https://github.com/a-pru/descent/blob/main/descent/utils/losses.py): `descent/utils/losses.py`
- [Trajectory metrics](https://github.com/a-pru/descent/blob/main/descent/utils/metrics.py): `descent/utils/metrics.py`
- [Model checkpoints](https://github.com/a-pru/descent/tree/main/checkpoints): `checkpoints`

### User Workflows

- [Training command](https://github.com/a-pru/descent/blob/main/scripts/train.py): `scripts/train.py`
- [Evaluation command](https://github.com/a-pru/descent/blob/main/scripts/eval.py): `scripts/eval.py`
- [Visualization command](https://github.com/a-pru/descent/blob/main/scripts/visualize.py): `scripts/visualize.py`
- [Map generation](https://github.com/a-pru/descent/blob/main/scripts/generate_maps.py): `scripts/generate_maps.py`
- [Prediction figures](https://github.com/a-pru/descent/blob/main/scripts/visualize.py): `scripts/visualize.py`

### Other components

- **Researcher**
- **Amelia-10 scenes**

## Connections

- Researcher → Training command: starts training (evidence: `README.md`)
- Researcher → Evaluation command: requests evaluation (evidence: `README.md`)
- Researcher → Visualization command: requests visualization (evidence: `README.md`)
- Researcher → Map generation: generates maps (evidence: `README.md`)
- Amelia-10 scenes → Scene dataset: provides scenes (evidence: `README.md`)
- Map generation → Directed lane maps: writes maps (evidence: `README.md`)
- Scene dataset → Data helpers: uses listing helpers (evidence: `descent/data/dataset.py`)
- Data module → Data helpers: uses utilities (evidence: `descent/data/datamodule.py`)
- Scene dataset → Feature masks: uses feature indices (evidence: `descent/data/dataset.py`)
- Directed lane maps → Scene dataset: supplies lane context (evidence: `README.md`)
- Training command → Data module: configures data (evidence: `README.md`)
- Evaluation command → Data module: evaluates test data (evidence: `README.md`)
- Data module → Scene dataset: provides datasets (evidence: `descent/data/datamodule.py`)
- Scene dataset → DESCENT network: provides scene inputs
- DESCENT network → Lane encoder: encodes lane segments (evidence: `descent/models/descent.py`)
- DESCENT network → Attention blocks: applies attention blocks (evidence: `descent/models/descent.py`)
- DESCENT network → Trajectory decoder: decodes trajectories (evidence: `descent/models/descent.py`)
- Prediction task → DESCENT network: runs network (evidence: `descent/models/trajpred.py`)
- Prediction task → Training losses: computes loss (evidence: `descent/models/trajpred.py`)
- Prediction task → Trajectory metrics: computes metrics (evidence: `descent/models/trajpred.py`)
- Training command → Prediction task: trains task (evidence: `README.md`)
- Evaluation command → Model checkpoints: loads checkpoint (evidence: `README.md`)
- Evaluation command → Prediction task: evaluates task (evidence: `README.md`)
- Visualization command → Model checkpoints: uses predictions
- Visualization command → Prediction figures: writes figures (evidence: `README.md`)
