# vita-epfl/unitraj architecture

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

- Interactive diagram: https://gitdiagram.com/vita-epfl/unitraj
- Repository: https://github.com/vita-epfl/unitraj

## Overview

##### Project type and purpose
- UniTraj is a Python-based research framework for vehicle trajectory prediction.
- It unifies data loading (nuScenes, Waymo, Argoverse2, etc.), model definition (Autobot, MTR, Wayformer), training, evaluation, and logging under one Hydra-configured pipeline.
- Core use case: train & evaluate multiple trajectory prediction models on large real-world datasets.

##### File structure
- Top-level scripts:
- train.py – entry point for training.
- evaluation.py – entry point for evaluation.
- data_analysis.py – exploratory data analysis.
- Configuration: unitraj/configs/ (config.yaml + per-method YAMLs) → Hydra manages hierarchical configs.
- Dataset layer: unitraj/datasets/ – base_dataset.py + model-specific dataset classes.
- Model layer: unitraj/models/ –
- base_model/ – abstract base LightningModule, evaluation utilities, model utils, plus built-in eval configs.
- subfolders autobot/, mtr/, wayformer/ – method implementations, utilities, custom ops (C++/CUDA for MTR).
- Utilities: unitraj/utils/ – helper functions (config loader, TSNE, visualization).
- Data samples: unitraj/data_samples/ – example nuScenes pickled files.
- Third-party dependencies and build: setup.py, requirements.txt.

##### Readme insights
- Depicts a high-level “framework.png” showing data flow: ScenarioNet → UniTraj pipeline → model → metrics → WandB.
- Highlights Hydra, PyTorch-Lightning, WandB integration.
- Mentions optional evaluation tools (nuscenes-devkit, waymo-open-dataset).

##### Main components
a. Data Ingestion
- ScenarioNet data source (external service) → raw scenario files.
- local cache in unitraj/data_samples or H5 cache.
b. Configuration Service
- Hydra config manager (unitraj/configs/config.yaml + method/*.yaml).
c. Dataset Loader
- BaseDataset → method-specific dataset classes → PyTorch DataLoader.
d. Model Trainer
- PyTorch-Lightning Trainer orchestrates training loops, calls model modules.
- BaseModel defines common training, validation, logging hooks.
- Method modules (Autobot, MTR, Wayformer) implement forward, loss, inference.
- Custom ops (C++/CUDA) for performance in MTR.
e. Logging & Monitoring
- WandB (external service) for metrics, visualizations.
f. Evaluation
- evaluation.py orchestrates model checkpoint loading, running inference, computing metrics with nuscenes-devkit / waymo toolkits.
g. Utilities
- Visualization, TSNE, config helper functions.

##### Relationships and interactions
- ScenarioNet → Dataset Loader
- Hydra → Dataset Loader, Model Trainer, Evaluation scripts
- Dataset Loader → Lightning Trainer
- Lightning Trainer ↔ Model modules
- Trainer → WandB (logging)
- Evaluation script → Model checkpoint + Dataset → Evaluation metrics
- Utils are side-services called by Dataset, Model, or Training.

##### Architectural patterns and principles
- Plugin architecture: new models/datasets hook into base classes.
- Inheritance & polymorphism: base_dataset.py and base_model.py are extended.
- Configuration as code via Hydra: decouples code from hyperparameters.
- Modularization: clear separation of data, model, training, evaluation, utils.

##### Technologies and frameworks
- Hydra (config management)
- PyTorch-Lightning (training orchestration)
- PyTorch + custom C++/CUDA ops (compute)
- WandB (experiment tracking)
- ScenarioNet, nuscenes-devkit, waymo-open-dataset (data)
- Python build: setuptools (setup.py)

##### Detailed capture of essential elements
- Include:
- unitraj/train.py and train loop.
- unitraj/configs Hydra tree.
- Dataset classes hierarchy.
- Model classes hierarchy and custom ops.
- WandB integration hook.
- evaluation.py + external eval toolkit connections.
- Plugin points for new models/datasets.
- Control flow: CLI invocation → Hydra instantiation → object creation → training/eval.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        SN["ScenarioNet"]:::external
        CACHE["Local Cache\n(unitraj/data_samples/)"]:::data
    end

    %% Config Layer
    subgraph "Config Layer"
        HYDRA["Hydra Config\n(unitraj/configs/)"]:::config
    end

    %% Compute Layer
    subgraph "Compute Layer"
        subgraph "Dataset Loader"
            BD["BaseDataset"]:::compute
            AD["AutobotDataset"]:::compute
            MD["MTRDataset"]:::compute
            WD["WayformerDataset"]:::compute
            CU1["common_utils"]:::compute
            TY["types"]:::compute
            DL["PyTorch DataLoader"]:::compute
        end

        subgraph "Model Trainer"
            TRAIN["train.py"]:::compute
            PLTR["PyTorch-Lightning Trainer"]:::compute
            BASEM["BaseModel"]:::compute
            MU["Model Utils"]:::compute
        end

        subgraph "Model Modules"
            AUT["Autobot"]:::compute
            subgraph "MTR"
                MTRM["MTR"]:::compute
                MTRU["MTR_utils"]:::compute
                MU2["loss_utils"]:::compute
                MOTU["motion_utils"]:::compute
                OPS["Custom C++/CUDA Ops"]:::compute
            end
            WAY["Wayformer"]:::compute
            WAYU["Wayformer_utils"]:::compute
        end
    end

    %% Logging & Evaluation Layer
    subgraph "Logging & Eval Layer"
        WB["WandB"]:::external
        EVAL["evaluation.py"]:::compute
        subgraph "Evaluation Toolkits"
            NSK["nuscenes-devkit"]:::external
            WYO["waymo-open-dataset"]:::external
        end
        subgraph "Utilities"
            U1["config.py"]:::compute
            U2["tsne.py"]:::compute
            U3["visualization.py"]:::compute
            U4["utils.py"]:::compute
        end
    end

    %% Connections
    SN --> CACHE
    SN --> BD
    CACHE --> BD
    HYDRA --> BD
    HYDRA --> TRAIN
    HYDRA --> EVAL

    BD --> AD
    BD --> MD
    BD --> WD
    CU1 --> BD
    TY --> BD
    AD --> DL
    MD --> DL
    WD --> DL
    DL --> PLTR

    TRAIN --> PLTR
    PLTR --> BASEM
    PLTR --> AUT
    PLTR --> MTRM
    PLTR --> WAY

    BASEM --> MU
    BASEM --> WB

    MTRM --> MTRU
    MTRM --> MU2
    MTRM --> MOTU
    MTRM --> OPS

    EVAL --> BD
    EVAL --> BASEM
    EVAL --> NSK
    EVAL --> WYO

    U1 --> BD
    U1 --> BASEM
    U2 --> AUT
    U3 --> AUT
    U4 --> MD

    %% Click Events
    click CACHE "https://github.com/vita-epfl/unitraj/tree/main/unitraj/data_samples/"
    click HYDRA "https://github.com/vita-epfl/unitraj/blob/main/unitraj/configs/config.yaml"
    click BD "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/base_dataset.py"
    click AD "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/autobot_dataset.py"
    click MD "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/MTR_dataset.py"
    click WD "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/wayformer_dataset.py"
    click CU1 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/common_utils.py"
    click TY "https://github.com/vita-epfl/unitraj/blob/main/unitraj/datasets/types.py"
    click TRAIN "https://github.com/vita-epfl/unitraj/blob/main/unitraj/train.py"
    click BASEM "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/base_model/base_model.py"
    click MU "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/base_model/model_utils.py"
    click AUT "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/autobot/autobot.py"
    click MTRM "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/mtr/MTR.py"
    click MTRU "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/mtr/MTR_utils.py"
    click MU2 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/mtr/loss_utils.py"
    click MOTU "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/mtr/motion_utils.py"
    click OPS "https://github.com/vita-epfl/unitraj/tree/main/unitraj/models/mtr/ops/"
    click WAY "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/wayformer/wayformer.py"
    click WAYU "https://github.com/vita-epfl/unitraj/blob/main/unitraj/models/wayformer/wayformer_utils.py"
    click EVAL "https://github.com/vita-epfl/unitraj/blob/main/unitraj/evaluation.py"
    click U1 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/utils/config.py"
    click U2 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/utils/tsne.py"
    click U3 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/utils/visualization.py"
    click U4 "https://github.com/vita-epfl/unitraj/blob/main/unitraj/utils/utils.py"

    %% Styles
    classDef compute fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef data fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef config fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
```
