# kumarr99/gnn_pathplanning_do architecture

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

- Interactive diagram: https://gitdiagram.com/kumarr99/gnn_pathplanning_do
- Repository: https://github.com/kumarr99/gnn_pathplanning_do

## Overview

##### Project Type and Purpose
- This is a research‐oriented PyTorch codebase implementing Graph Neural Networks (GNNs) for decentralized multi‐robot path finding (MAPF), integrating ML training pipelines with “expert” solvers for data generation and curriculum learning.
- It is *not* a web app or microservice ensemble, but rather a modular ML framework combining data generation, transformation, training/inference, evaluation, and visualization.

##### Main Components
A. Data Generation & Expert Solvers
- offlineExpert: classical MAPF case generator (random maps + agent start/goal pairs) and solver modules (CBS, ECBS, SIPP)
- onlineExpert: online‐expert fallback for failed cases during training
B. Data Transformation
- offlineExpert/DataGen_Transformer.py & onlineExpert/DataTransformer_local_onlineExpert.py
- Convert solver outputs into tensors, graph shift operators (GSO), map encodings for model ingestion
C. Data Loading
- dataloader/: custom PyTorch Dataset classes (e.g. Dataloader_dcplocal_notTF_onlineExpert.py)
D. Core Model & Training
- graphs/models/decentralplanner.py: CNN→GNN→MLP pipeline
- graphs/losses: loss functions (cross‐entropy, Huber, BCE, etc.)
- agents/: high‐level abstractions for training/testing loops (decentralplannerlocal, with/without online expert)
- main.py: orchestrates config parsing, mode selection (train/test), experiment logging
E. Configuration & Scripts
- configs/*.json: hyperparameters & file‐paths for each training/inference scenario
- scripts/: shell scripts for running experiments locally or on clusters
F. Utilities
- utils/: visualization (paths, communication links), metrics collection, directory management, graph utilities, movie generation
G. Analysis & Results
- statistic_analysis/: generate figures and error‐bar/histogram plots for published results

##### Relationships & Data Flow
1. offlineExpert → (raw cases) → DataGen_Transformer → serialized dataset files
2. onlineExpert (optional) → augment training set with expert solutions for failure cases
3. dataloader → reads serialized datasets → yields training batches
4. agents.train loop
└─> graphs/models (forward on batch)
└─> graphs/losses (compute loss)
└─> optimizer.step()
6. statistic_analysis consumes experiment logs → plots

##### Architectural Patterns & Design Principles
- Modular separation: data gen, data transform, data load, model definition, agent logic, visualization, analysis
- Dependency injection via JSON configs: decouples hyperparameters and filesystem paths from code
- Clear layering:
- Layer 1: Data sources (expert solvers)
- Layer 2: Data adaptors (transformers, dataloader)
- Layer 3: Model & training orchestration (agents, graphs)
- Layer 4: Post‐processing (metrics, visualization, analysis)
- Reuse & extensibility: “agents” base class, configurable solver backends, plug‐in loss modules

##### Technologies & Frameworks
- PyTorch for neural networks and training loop
- tensorboardX for logging
- numpy, scipy, scikit‐image for data manipulation
- Custom graph utilities for GSO construction
- Shell scripts for HPC/cluster integration

##### Detailed Element Checklist
- Optional: annotate external dependencies (PyTorch, numpy) at the periphery

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Data Generation
    subgraph "Layer 1: Data Generation"
        direction TB
        offlineExpert["offlineExpert"]:::expert
        onlineExpert["onlineExpert"]:::expert
    end

    %% Layer 2: Data Transformation
    subgraph "Layer 2: Data Transformation"
        direction TB
        DataGenTransformer["DataGen_Transformer.py"]:::data
        OnlineTransformer["DataTransformer_local_onlineExpert.py"]:::data
    end

    %% Data Store
    DatasetStore["Serialized Datasets"]:::storage

    %% Layer 3: Data Loading
    subgraph "Layer 3: Data Loading"
        direction TB
        Dataloader_dcplocal["Dataloader_dcplocal_notTF_onlineExpert.py"]:::data
        StateTransformer["statetransformer.py"]:::data
    end

    %% Layer 4: Training & Testing
    subgraph "Layer 4: Training & Testing"
        direction TB
        main["main.py"]:::ml
        Configs["configs/*.json"]:::util
        subgraph "agents"
            direction TB
            BaseAgent["base.py"]:::ml
            DCPAgent["decentralplannerlocal.py"]:::ml
            DCPAgentOE["decentralplannerlocal_OnlineExpert.py"]:::ml
        end
        subgraph "graphs/models"
            direction TB
            DecentralPlanner["decentralplanner.py"]:::ml
            InitWeights["weights_initializer.py"]:::ml
        end
        subgraph "graphs/losses"
            direction TB
            CE["cross_entropy.py"]:::ml
            Huber["huber_loss.py"]:::ml
            BCE["bce.py"]:::ml
            MaskNLL["maskNLLLoss.py"]:::ml
            Reg1["regularizer.py"]:::ml
            Reg2["regularizer2.py"]:::ml
        end
    end

    %% Layer 5: Utilities
    subgraph "Layer 5: Utilities"
        direction TB
        Utils["utils/"]:::util
    end

    %% Layer 6: Analysis & Results
    subgraph "Layer 6: Analysis & Results"
        direction TB
        Analysis["statistic_analysis/"]:::util
    end

    %% Connections - Data Flow
    offlineExpert --> DataGenTransformer
    onlineExpert --> OnlineTransformer
    DataGenTransformer --> DatasetStore
    OnlineTransformer --> DatasetStore
    DatasetStore --> Dataloader_dcplocal
    DatasetStore --> StateTransformer
    Dataloader_dcplocal --> main
    StateTransformer --> main
    main --> BaseAgent
    main --> DCPAgent
    main --> DCPAgentOE
    BaseAgent --> DecentralPlanner
    DCPAgent --> DecentralPlanner
    DCPAgentOE --> DecentralPlanner
    DecentralPlanner --> CE
    DecentralPlanner --> Huber
    DecentralPlanner --> BCE
    DecentralPlanner --> MaskNLL
    DecentralPlanner --> Reg1
    DecentralPlanner --> Reg2
    BaseAgent --> Utils
    DCPAgent --> Utils
    DCPAgentOE --> Utils
    Utils --> Analysis

    %% Control/Config Flow
    Configs -.-> main

    %% Click Events
    click offlineExpert "https://github.com/kumarr99/gnn_pathplanning_do/tree/master/offlineExpert/"
    click DataGenTransformer "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/offlineExpert/DataGen_Transformer.py"
    click onlineExpert "https://github.com/kumarr99/gnn_pathplanning_do/tree/master/onlineExpert/"
    click OnlineTransformer "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/onlineExpert/DataTransformer_local_onlineExpert.py"
    click Dataloader_dcplocal "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/dataloader/Dataloader_dcplocal_notTF_onlineExpert.py"
    click StateTransformer "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/dataloader/statetransformer.py"
    click main "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/main.py"
    click Configs "https://github.com/kumarr99/gnn_pathplanning_do/tree/master/configs/"
    click BaseAgent "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/agents/base.py"
    click DCPAgent "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/agents/decentralplannerlocal.py"
    click DCPAgentOE "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/agents/decentralplannerlocal_OnlineExpert.py"
    click DecentralPlanner "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/models/decentralplanner.py"
    click InitWeights "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/weights_initializer.py"
    click CE "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/cross_entropy.py"
    click Huber "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/huber_loss.py"
    click BCE "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/bce.py"
    click MaskNLL "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/maskNLLLoss.py"
    click Reg1 "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/regularizer.py"
    click Reg2 "https://github.com/kumarr99/gnn_pathplanning_do/blob/master/graphs/losses/regularizer2.py"
    click Utils "https://github.com/kumarr99/gnn_pathplanning_do/tree/master/utils/"
    click Analysis "https://github.com/kumarr99/gnn_pathplanning_do/tree/master/statistic_analysis/"

    %% Styles
    classDef expert fill:#f9a,stroke:#333,stroke-width:1px
    classDef data fill:#afa,stroke:#333,stroke-width:1px
    classDef ml fill:#88f,stroke:#333,stroke-width:1px
    classDef util fill:#ccc,stroke:#333,stroke-width:1px
    classDef storage fill:#ffce00,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5

    class DatasetStore storage
```
