# quancore/social-lstm architecture

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

- Interactive diagram: https://gitdiagram.com/quancore/social-lstm
- Repository: https://github.com/quancore/social-lstm

## Overview

##### Project type and purpose
- This is a research‐oriented machine‐learning pipeline for pedestrian trajectory forecasting (“Social LSTM implementation in PyTorch”).
- It includes data handling (train/validation/test splits), multiple LSTM model definitions (Social LSTM, Occupancy LSTM, Vanilla LSTM), training scripts, evaluation and visualization.

##### File‐structure analysis
- data/… — raw datasets organized into train, validation, test with subfolders per benchmark (biwi, crowds, stanford, mot).
- generator.py — synthetic data generator.
- utils.py & helper.py — data loaders, batching, common utilities.
- model.py, olstm_model.py, vlstm_model.py — neural‐network definitions.
- train.py, olstm_train.py, vlstm_train.py — training orchestrators for each model variant.
- validation.py — external evaluation logic.
- test.py — inference & output formatting for submission.
- hyperparameter.py — random hyperparameter selector.
- make_directories.sh — directory scaffolding.

##### Key insights from README
- Core stack: Python + PyTorch.
- Three model families share a common training/evaluation pipeline.
- Automatic directory creation and data‐flow handled by training scripts.

a. Components
- Data Storage (data/)
- Data Generation (generator.py)
- Preprocessing & Batching (utils.py, helper.py)
- Model Definitions (model.py, olstm_model.py, vlstm_model.py)
- Training Orchestrators (train.py, olstm_train.py, vlstm_train.py)
- Hyperparameter Selector (hyperparameter.py)
- Evaluation (validation.py)
- Inference & Submission (test.py)
- Setup Script (make_directories.sh)
b. Relationships & data flow
1. Raw data → (generator.py for synthetic) → data/
2. data/ → utils.py/helper.py → batched datasets
3. batched data + hyperparameter.py → training scripts → model definitions → updated model weights
4. Trained model → validation.py → metrics → logs
5. Validated model → test.py → prediction output
7. make_directories.sh can be invoked at start of any training script to ensure directories exist
c. Architectural patterns & principles
- Modular separation: data layer, model layer, training/eval layer, visualization.
- Reuse: single utils/helpers across all model variants.
- Orchestrator scripts (train.py, olstm_train.py, vlstm_train.py) call common routines.
d. Technologies/Frameworks
- PyTorch for NN implementations.
- Bash for environment setup.
- Standard Python I/O libs for file handling.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        DS["Data Storage"]:::storage
        DG["Data Generation"]:::processing
    end

    %% Preprocessing
    subgraph "Preprocessing & Batching"
        U["utils.py"]:::processing
        H["helper.py"]:::processing
        B["Batched Datasets"]:::processing
    end

    %% Model Definitions
    subgraph "Model Definitions"
        SM["Social LSTM Model"]:::model
        OM["Occupancy LSTM Model"]:::model
        VM["Vanilla LSTM Model"]:::model
    end

    %% Training Orchestrator
    subgraph "Training Orchestrator"
        T1["train.py"]:::orchestration
        T2["olstm_train.py"]:::orchestration
        T3["vlstm_train.py"]:::orchestration
    end

    %% Other Components
    HP["hyperparameter.py"]:::utility
    EV["validation.py"]:::orchestration
    INF["test.py"]:::orchestration
    VIS["visualize.py"]:::utility
    SET["make_directories.sh"]:::utility

    %% Data Flow
    DS -->|"raw data"| DG
    DG -->|"synthetic data"| DS
    DS -->|dataset| U
    DS -->|dataset| H
    U -->|batched tensors| B
    H -->|batched tensors| B
    B -->|batched tensors| T1
    B -->|batched tensors| T2
    B -->|batched tensors| T3
    HP -.->|params| T1
    HP -.->|params| T2
    HP -.->|params| T3
    T1 -->|train| SM
    T2 -->|train| OM
    T3 -->|train| VM
    SM -->|model weights| EV
    OM -->|model weights| EV
    VM -->|model weights| EV
    EV -->|metrics| T1
    EV -->|metrics| INF
    VIS -.->|plots| T1
    VIS -.->|plots| EV
    VIS -.->|plots| INF
    SET -->|setup| T1
    SET -->|setup| T2
    SET -->|setup| T3

    %% Click Events
    click DS "https://github.com/quancore/social-lstm/tree/master/data/"
    click DG "https://github.com/quancore/social-lstm/blob/master/generator.py"
    click U "https://github.com/quancore/social-lstm/blob/master/utils.py"
    click H "https://github.com/quancore/social-lstm/blob/master/helper.py"
    click SM "https://github.com/quancore/social-lstm/blob/master/model.py"
    click OM "https://github.com/quancore/social-lstm/blob/master/olstm_model.py"
    click VM "https://github.com/quancore/social-lstm/blob/master/vlstm_model.py"
    click T1 "https://github.com/quancore/social-lstm/blob/master/train.py"
    click T2 "https://github.com/quancore/social-lstm/blob/master/olstm_train.py"
    click T3 "https://github.com/quancore/social-lstm/blob/master/vlstm_train.py"
    click HP "https://github.com/quancore/social-lstm/blob/master/hyperparameter.py"
    click EV "https://github.com/quancore/social-lstm/blob/master/validation.py"
    click INF "https://github.com/quancore/social-lstm/blob/master/test.py"
    click VIS "https://github.com/quancore/social-lstm/blob/master/visualize.py"
    click SET "https://github.com/quancore/social-lstm/blob/master/make_directories.sh"

    %% Styles
    classDef storage fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32
    classDef processing fill:#e3f2fd,stroke:#1565c0,color:#1565c0
    classDef model fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef orchestration fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef utility fill:#fffde7,stroke:#f9a825,color:#f57f17
```
