How yang-mingzhou/eco-pinn works
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