# yang-mingzhou/eco-pinn architecture

> Architecture diagram of the GitHub repository yang-mingzhou/eco-pinn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yang-mingzhou/eco-pinn
- Repository: https://github.com/yang-mingzhou/eco-pinn

## Overview

##### Project Type and Purpose
- This is a research‐oriented machine learning application: a physics‐informed neural network (Eco-PiNN) for estimating eco-tolls (environmental cost metrics) on road segments.
- It implements a full ML pipeline: data ingestion, graph‐based embedding (node2vec), contextual encoding, physics‐informed decoding, training/testing, and result evaluation.

##### File Structure Analysis
- Top‐level files:
- config.py – hyperparameter and experiment settings
- training_testing_EcoPiNN.py – orchestrates training and evaluation
- requirements.txt – Python dependencies (PyTorch, torch_geometric, GeoPandas, etc.)
- pretained model/ – precomputed node2vec artifacts (dualGraphNodes.pkl, edge_index.pkl, node2vec.mdl, node2vec.py)
- utils/ directory:
- obdDataLoader.py – loads OBD datasets and constructs sub-path queries
- ciEncoder.py – attention‐based contextual information encoder
- piDecoder.py – physics‐informed decoder integrating engine physics
- funcs.py – aggregation functions to combine encoder + decoder outputs
- No separate “frontend” or web service; components are all Python processes in a single monolithic project.

##### Key Architecture Elements
a. Data Sources and Preprocessing
- OBD dataset (external; not included) is read by obdDataLoader
- Road network graph data (edge_index.pkl, dualGraphNodes.pkl) loaded for node2vec
- node2vec.py loads a pretrained embedding model (node2vec.mdl) to generate node features
b. Feature Encoding
- Contextual Information Encoder (ciEncoder): takes node2vec features + OBD‐derived segment attributes → generates context‐aware embeddings via attention
c. Physics‐Informed Decoding
- piDecoder: applies known vehicle physics equations as a decoder layer, enforcing physical consistency
d. Aggregation & Loss/Regularization
- funcs.py: merges encoder and decoder outputs, implements physics‐informed regularization as part of the training loss
e. Training & Evaluation Orchestration
- training_testing_EcoPiNN.py:
- reads config.py parameters
- invokes data loader → encoder → decoder → aggregation → loss computation
- manages training loops, validation/testing, metric logging
- outputs model checkpoints and evaluation reports

##### Relationships & Data Flow
- From OBD Dataset → obdDataLoader
- From Road Graph Data → node2vec → node features
- From obdDataLoader & node features → CIEncoder
- From CIEncoder → PiDecoder → Aggregator
- From Aggregator → Training/Testing Orchestrator
- From config.py → Training/Testing Orchestrator (read configs)
- From orchestrator → Model Checkpoints + Metrics

##### Technologies & Frameworks
- Python 3.x, PyTorch & torch_geometric (graph neural network ops)
- NetworkX & osmnx (graph manipulation)
- GeoPandas, Shapely (geospatial data handling)
- pandas, numpy (data processing)

##### Architectural Patterns & Principles
- Modular ML pipeline: separate data loading, feature encoding, model decoding, and orchestration
- Physics‐informed neural network: embedding domain knowledge in model layers
- Pretraining + fine‐tuning: node2vec embeddings reused for contextual encoding
- Single‐process batch training with clear separation of concerns

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        OBDSource["OBD Dataset"]:::data
        subgraph "Pretrained Artifacts"
            direction TB
            dual["dualGraphNodes.pkl"]:::data
            edge["edge_index.pkl"]:::data
            mdl["node2vec.mdl"]:::data
            node2vecfile["node2vec.py"]:::data
        end
        requirements["requirements.txt"]:::data
        readme["README.md"]:::data
    end

    %% Preprocessing & Embedding Layer
    subgraph "Preprocessing & Embedding"
        direction TB
        OBDLoader["obdDataLoader"]:::pre
        Node2VecMod["node2vec Module"]:::pre
    end

    %% Modeling Layer
    subgraph "Modeling Layer"
        direction TB
        CIEnc["CIEncoder"]:::model
        PIDec["PiDecoder"]:::model
        Agg["Aggregator (funcs.py)"]:::model
    end

    %% Orchestrator Layer
    subgraph "Orchestrator"
        direction TB
        Config["Config Manager (config.py)"]:::orch
        Orch["training_testing_EcoPiNN.py"]:::orch
    end

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        Checkpoints["Model Checkpoints"]:::output
        Metrics["Evaluation Metrics & Plots"]:::output
    end

    %% Connections
    OBDSource --> OBDLoader
    dual --> Node2VecMod
    edge --> Node2VecMod
    mdl --> Node2VecMod
    node2vecfile --> Node2VecMod
    requirements --> OBDLoader
    readme --> OBDLoader

    OBDLoader --> CIEnc
    Node2VecMod --> CIEnc
    CIEnc --> PIDec
    PIDec --> Agg
    Agg --> Orch
    Config --> Orch
    Orch --> Checkpoints
    Orch --> Metrics

    %% Click Events
    click Config "https://github.com/yang-mingzhou/eco-pinn/blob/main/config.py"
    click Orch "https://github.com/yang-mingzhou/eco-pinn/blob/main/training_testing_EcoPiNN.py"
    click dual "https://github.com/yang-mingzhou/eco-pinn/blob/main/pretained model/dualGraphNodes.pkl"
    click edge "https://github.com/yang-mingzhou/eco-pinn/blob/main/pretained model/edge_index.pkl"
    click mdl "https://github.com/yang-mingzhou/eco-pinn/blob/main/pretained model/node2vec.mdl"
    click node2vecfile "https://github.com/yang-mingzhou/eco-pinn/blob/main/pretained model/node2vec.py"
    click OBDLoader "https://github.com/yang-mingzhou/eco-pinn/blob/main/utils/obdDataLoader.py"
    click CIEnc "https://github.com/yang-mingzhou/eco-pinn/blob/main/utils/ciEncoder.py"
    click PIDec "https://github.com/yang-mingzhou/eco-pinn/blob/main/utils/piDecoder.py"
    click Agg "https://github.com/yang-mingzhou/eco-pinn/blob/main/utils/funcs.py"
    click requirements "https://github.com/yang-mingzhou/eco-pinn/blob/main/requirements.txt"
    click readme "https://github.com/yang-mingzhou/eco-pinn/blob/main/README.md"

    %% Styles
    classDef data fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef pre fill:#FFF9C4,stroke:#F57F17,color:#E65100
    classDef model fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef orch fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef output fill:#ECEFF1,stroke:#607D8B,color:#37474F
```
