README.md

# Urban Mobility Integrated Neural Dynamics (U-MIND)

## 📖 Model Summary

**Urban Mobility Integrated Neural Dynamics (U-MIND)** constitutes the specialized algorithmic core (Layer 2) of the "Traffic Large Model" architecture. Unlike monolithic Large Language Models (LLMs), **U-MIND** is engineered as a **collaborative cluster of four parallel micro-models**, specifically optimized for the physical constraints of urban transportation. It functions as the high-precision reasoning engine that grounds the L1 model's intent understanding into accurate, mathematically rigorous mobility forecasts by fusing static road semantics with dynamic sensor streams.

The **U-MIND** cluster integrates four specialized engines:

1.  **PM (Perception Engine):** Captures high-frequency dynamics and implicit couplings.
2.  **RM (Representation Engine):** Encodes static topology and semantic patterns.
3.  **FM (Fusion Engine):** Aligns heterogeneous multimodal data.
4.  **PredM (Evolution Engine):** Forecasts future spatio-temporal states.

---

## 🏗️ Model Architecture

The cluster adopts a **Parallel Collaborative Architecture**, where each model specializes in a specific domain of the urban traffic system.

### 1. PM: Perception Model
* **Role:** **Dynamic State Extractor**
* **Core Function:** Processes raw, noisy sensor data (Flow, Speed, Occupancy). It utilizes 1D convolution and adaptive pooling to extract short-term trends and denoise signal fluctuations caused by random events.
* **Key Capability:** Identifies traffic anomalies (e.g., sudden congestion) and compresses high-dimensional time-series into a compact context fingerprint.

![Perception Model](PM.png)

### 2. RM: Representation Model
* **Role:** **Semantic Pattern Encoder**
* **Core Function:** Focuses on the static and semi-static attributes of the road network (POI distribution, road geometry). It learns a low-dimensional manifold representation of diverse traffic patterns (e.g., "Residential Area" vs. "Business District").
* **Key Capability:** Distinguishes between different functional zones based on their daily peak-hour signatures (morning/evening rush).

![Representation Model](RM.png)

### 3. FM: Fusion Model
* **Role:** **Cross-Modal Aligner**
* **Core Function:** Acts as the bridge between ground traffic, rail transit, and environmental factors. It employs Multi-Head Attention to dynamically weigh different data sources based on real-time contexts (e.g., increasing rail weight during rainy days).
* **Key Capability:** Resolves the heterogeneity between static embeddings and dynamic flows, outputting a unified multimodal context vector.

![Fusion Model](FM.png)

### 4. PredM: Prediction Model
* **Role:** **Future State Estimator**
* **Core Function:** A specialized graph-based predictor that models the propagation of traffic waves. It combines dilated convolutions for long-range temporal reception with graph structures for spatial dependency.
* **Key Capability:** Provides high-precision forecasts for both urban ground and rail mobility demands, serving as the calculation engine for the upper-layer applications.

![Prediction Model](PredM.png)

---

## 💻 Usage: Simulation & Loading

This section demonstrates how to generate physics-consistent simulated data and load the pre-trained model weights.

```python
import torch
import numpy as np
# Assuming model definitions (PM, RM, FM, PredM) are imported
from urban_mobility_models import PerceptionModel, RepresentationModel, FusionModel, SpatioTemporalPredictor

class DataSimulator:
    """
    Used to generate synthetic data that reflects the characteristics of urban traffic, covering four tasks: perception, representation, fusion, and prediction.
    """
    
    @staticmethod
    def sim_perception_data(batch_size=32, seq_len=24, sensors=5):
        """1. [PM] Simulate Sensor Data: Adds Rush Hour & Random Noise"""
        data = np.random.normal(50, 15, (batch_size, seq_len, sensors))
        # Add rush hour patterns (Morning 8am / Evening 6pm)
        t = np.arange(seq_len)
        rush = 30 * (np.exp(-0.5*((t-8)/2)**2) + np.exp(-0.5*((t-18)/2)**2))
        return torch.FloatTensor(data + rush[:, np.newaxis])

    @staticmethod
    def sim_representation_data(batch_size=32, feat_dim=32):
        """2. [RM] Simulate Static Patterns: Residential vs Commercial zones"""
        data = np.zeros((batch_size, feat_dim))
        for i in range(batch_size):
            # Residential peaks at 8am/8pm; Commercial peaks at 1pm
            if np.random.rand() > 0.5:
                data[i, 8] += 2.0; data[i, 20] += 1.5 # Residential
            else:
                data[i, 13] += 2.0 # Commercial
        return torch.FloatTensor(data + np.random.normal(0, 0.5, data.shape))

    @staticmethod
    def sim_fusion_data(batch_size=32):
        """3. [FM] Simulate Multimodal Data: Ground, Rail, Weather"""
        ground = np.random.normal(0, 1, (batch_size, 32))
        # Rail correlated with ground + random variance
        rail = 0.6 * ground[:, :24] + 0.4 * np.random.normal(0, 1, (batch_size, 24))
        # Weather (Environment)
        env = np.random.normal(0, 1, (batch_size, 16))
        return [torch.FloatTensor(d) for d in [ground, rail, env]]

    @staticmethod
    def sim_prediction_data(batch_size=32, nodes=20, time_steps=12):
        """4. [PredM] Simulate Graph Inputs: History Flow + Adjacency Matrix"""
        # Historical flow sequence
        history = torch.randn(batch_size, nodes, time_steps)
        # Static Graph Adjacency Matrix (sparse connection)
        adj = torch.eye(nodes) + (torch.rand(nodes, nodes) > 0.8).float()
        return history, adj

def load_and_verify_cluster():
    # 1. Initialize Models
    pm = PerceptionModel(input_dim=5, hidden_dim=64, output_dim=32)
    rm = RepresentationModel(input_dim=32, hidden_dim=64, representation_dim=16)
    fm = FusionModel(input_dims=[32, 24, 16], hidden_dim=512, output_dim=48)
    pred_m = SpatioTemporalPredictor(num_nodes=20, in_dim=12)

    # 2. Load Pre-trained Weights
    print("Loading L2 Cluster Weights...")
    pm.load_state_dict(torch.load('perception_model.pth'))
    rm.load_state_dict(torch.load('representation_model.pth'))
    fm.load_state_dict(torch.load('fusion_model.pth'))
    pred_m.load_state_dict(torch.load('prediction_model.pth')) # Hypothetical check
    print(">>> All L2 Models Loaded Successfully.")

    # 3. Generate & Forward Simulation Data
    print("\nRunning Simulation Inference:")
    
    # PM
    pm_out = pm(DataSimulator.sim_perception_data())
    print(f"PM (Perception) Output: {pm_out.shape} - Dynamic Context Extracted")

    # RM
    rm_out, _ = rm(DataSimulator.sim_representation_data())
    print(f"RM (Representation) Output: {rm_out.shape} - Semantic Node Embeddings")

    # FM
    fm_out, attn = fm(DataSimulator.sim_fusion_data())
    print(f"FM (Fusion) Output: {fm_out.shape} - Multimodal Aligned Context")
    
    # PredM
    hist, adj = DataSimulator.sim_prediction_data()
    pred_out = pred_m(hist, adj)
    print(f"PredM (Prediction) Output: {pred_out.shape} - Future Demand Forecast")

if __name__ == "__main__":
    load_and_verify_cluster()

```

---

## ⚙️ Intended Use

* **Integrated Mobility Orchestration**
    * Cooperative scheduling of buses and subways based on fused demand.

* **Resilient Traffic Management**
    * Rapid response to anomalies (accidents, extreme weather) detected by the Perception engine.

* **Urban Planning Analytics**
    * Utilizing Representation Model embeddings to analyze the functional evolution of city districts.