Upload 15 files

Dockerfile

@@ -0,0 +1,23 @@
+# 1. Use official lightweight Python 3.10 image to minimize build size
+FROM python:3.10-slim
+
+# 2. Define the working directory inside the container
+WORKDIR /app
+
+# 3. Create a non-root user with UID 1000 
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# 4. Copy requirements file and install dependencies
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 5. Copy the entire project source code and data assets to the container
+COPY --chown=user . /app
+
+# 6. Expose port 7860
+EXPOSE 7860
+
+# 7. Execute the Flask server script
+CMD ["python", "server.py"]

best_corr_model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:83b578e901f1f3d11421431ec5286548ae200b0ed1165afee66b6f05ad19bd76
+size 563607134

data/bs_record_energy_normalized_sampled.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:62a53c46d7cc8b0fca0fa9943eac045ca1853a4eb1df2a4f58c5c939179b66c7
+size 74859436

data/spatial_features.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:395420bb4696091d85bae743e680b861326342965ef7c85a21eb22d9c295e4ea
+size 294559

hierarchical_flow_matching_training_v4.py

@@ -0,0 +1,935 @@
+"""
+Hierarchical Flow Matching Training Framework (V4) - Generative Fusion
+======================================================================
+
+Complete training pipeline with:
+1. Three-level cascaded Flow Matching losses
+2. Hierarchical multi-periodic supervision
+3. Temporal structure preservation
+4. Adaptive learning rate scheduling
+
+[FUSION] Generative Mode: Implicit alignment via conditional flow matching.
+         Enhanced with explicit peak conditioning and auxiliary classification.
+         Physical Boundary Loss & Bias Correction.
+"""
+
+import os
+import json
+import numpy as np
+from typing import Dict, Optional, Tuple, Literal
+from tqdm import tqdm
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import DataLoader
+from torch.optim.lr_scheduler import CosineAnnealingLR
+
+from hierarchical_flow_matching_v4 import HierarchicalFlowMatchingV4
+from multimodal_spatial_encoder_v4 import MultiModalSpatialEncoderV4
+
+
+# =============================================================================
+# Hierarchical Multi-Periodic Loss Functions
+# =============================================================================
+
+class HierarchicalFlowMatchingLoss(nn.Module):
+    """
+    Hierarchical Flow Matching loss with multi-periodic supervision.
+
+    Combines:
+    1. Level 1 (Daily) Flow Matching loss
+    2. Level 2 (Weekly) Flow Matching loss
+    3. Level 3 (Residual) Flow Matching loss [Peak Conditioned]
+    4. Temporal structure preservation loss
+    5. Multi-periodic consistency loss
+    6. Peak Hour Classification Loss
+    7. Physical Boundary Loss (No-Negative Constraint)
+    8. Bias Correction Loss (Global Mean Alignment)
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    # Helper: Physical Constraint
+    def compute_boundary_loss(self, predicted_x1: torch.Tensor) -> torch.Tensor:
+        """
+        Penalize negative values in the estimated traffic.
+        Loss = ReLU(-x).mean() * scale
+        """
+        return F.relu(-predicted_x1).mean() * 10.0
+
+    # Helper: Bias Constraint
+    def compute_bias_loss(self, generated: torch.Tensor, real: torch.Tensor) -> torch.Tensor:
+        """
+        Fix 'Parallel Lines' issue by forcing global mean alignment.
+        """
+        gen_mean = generated.mean(dim=1)  # [B]
+        real_mean = real.mean(dim=1)      # [B]
+        return F.l1_loss(gen_mean, real_mean) * 20.0
+
+    def compute_level1_loss(
+        self,
+        model: HierarchicalFlowMatchingV4,
+        real_traffic: torch.Tensor,
+        spatial_cond_level1: torch.Tensor,
+    ) -> Tuple[torch.Tensor, torch.Tensor]: # [MODIFIED] Returns tuple
+        """
+        Level 1 (Day-Type Templates) Flow Matching loss.
+        """
+        B = real_traffic.shape[0]
+        device = real_traffic.device
+
+        # 672 hourly samples = 28 days * 24 hours
+        steps_per_day = 24
+        n_days = 28
+        real_reshaped = real_traffic.reshape(B, n_days, steps_per_day)  # [B, 28, 24]
+
+        # Assume sequence starts on Monday
+        day_of_week = torch.arange(n_days, device=device) % 7
+        weekday_idx = torch.where(day_of_week < 5)[0]
+        weekend_idx = torch.where(day_of_week >= 5)[0]
+
+        weekday_pattern = real_reshaped.index_select(1, weekday_idx).mean(dim=1)  # [B, 24]
+        weekend_pattern = real_reshaped.index_select(1, weekend_idx).mean(dim=1)  # [B, 24]
+
+        # Target is concatenation: [weekday(24), weekend(24)] -> [B, 48]
+        x1 = torch.cat([weekday_pattern, weekend_pattern], dim=1)
+
+        # Sample noise
+        x0 = torch.randn_like(x1)
+
+        # Sample time
+        t = torch.rand(B, 1, device=device)
+
+        # Interpolation
+        x_t = t * x1 + (1 - t) * x0
+
+        # Target velocity
+        v_target = x1 - x0
+
+        # Predict velocity
+        v_pred = model(x_t, t, spatial_cond_level1, level=1)
+
+        # Flow Matching loss
+        loss_fm = F.mse_loss(v_pred, v_target)
+
+        # Boundary Loss for Level 1
+        x1_est = x_t + (1 - t) * v_pred
+        loss_boundary = self.compute_boundary_loss(x1_est)
+
+        return loss_fm, loss_boundary
+
+    def compute_level2_loss(
+        self,
+        model: HierarchicalFlowMatchingV4,
+        real_traffic: torch.Tensor,
+        spatial_cond_level2: torch.Tensor,
+        spatial_cond_level1: torch.Tensor,
+        daily_pattern: Optional[torch.Tensor] = None,
+        use_teacher_forcing: bool = True,
+        n_steps_generate: int = 10,
+    ) -> Tuple[torch.Tensor, torch.Tensor]: # [MODIFIED] Returns tuple
+        """
+        Level 2 (Weekly Pattern, 168 hours) Flow Matching loss.
+        """
+        B = real_traffic.shape[0]
+        device = real_traffic.device
+
+        steps_per_day = 24
+        n_days = 28
+        n_weeks = 4
+        real_reshaped = real_traffic.reshape(B, n_days, steps_per_day)  # [B, 28, 24]
+
+        # Weekly pattern ground truth
+        weekly_days = []
+        for dow in range(7):
+            idx = torch.tensor([dow + 7 * w for w in range(n_weeks)], device=device, dtype=torch.long)
+            weekly_days.append(real_reshaped.index_select(1, idx).mean(dim=1))  # [B, 24]
+        weekly_pattern = torch.stack(weekly_days, dim=1).reshape(B, 7 * steps_per_day)  # [B, 168]
+
+        x1 = weekly_pattern  # target weekly pattern
+
+        # Get day-type templates (weekday/weekend)
+        if daily_pattern is None or not use_teacher_forcing:
+            with torch.no_grad():
+                daily_pattern = model.generate_daily_pattern(
+                    spatial_cond_level1, n_steps=n_steps_generate
+                )
+        else:
+            # Teacher forcing
+            day_of_week = torch.arange(n_days, device=device) % 7
+            weekday_idx = torch.where(day_of_week < 5)[0]
+            weekend_idx = torch.where(day_of_week >= 5)[0]
+            weekday_pattern = real_reshaped.index_select(1, weekday_idx).mean(dim=1)  # [B, 24]
+            weekend_pattern = real_reshaped.index_select(1, weekend_idx).mean(dim=1)  # [B, 24]
+            daily_pattern = torch.cat([weekday_pattern, weekend_pattern], dim=1)  # [B, 48]
+
+        # Sample noise
+        x0 = torch.randn_like(x1)
+
+        # Sample time
+        t = torch.rand(B, 1, device=device)
+
+        # Interpolation
+        x_t = t * x1 + (1 - t) * x0
+
+        # Target velocity
+        v_target = x1 - x0
+
+        # Predict velocity
+        v_pred = model(x_t, t, spatial_cond_level2, level=2, daily_pattern=daily_pattern)
+
+        # Flow Matching loss
+        loss_fm = F.mse_loss(v_pred, v_target)
+
+        # Boundary Loss for Level 2
+        x1_est = x_t + (1 - t) * v_pred
+        loss_boundary = self.compute_boundary_loss(x1_est)
+
+        return loss_fm, loss_boundary
+
+    def compute_level3_loss(
+        self,
+        model: HierarchicalFlowMatchingV4,
+        real_traffic: torch.Tensor,
+        spatial_cond_level3: torch.Tensor,
+        spatial_cond_level2: torch.Tensor,
+        spatial_cond_level1: torch.Tensor,
+        peak_hour_gt: torch.Tensor,  # Explicit Peak GT
+        daily_pattern: Optional[torch.Tensor] = None,
+        weekly_trend: Optional[torch.Tensor] = None,
+        use_teacher_forcing: bool = True,
+        n_steps_generate: int = 10,
+    ) -> Tuple[torch.Tensor, torch.Tensor]: # [MODIFIED] Returns tuple
+        """
+        Level 3 (Residual over 672 hours) Flow Matching loss.
+        Models fine-grained hourly fluctuations after removing periodic trends.
+        """
+        B = real_traffic.shape[0]
+        device = real_traffic.device
+
+        steps_per_day = 24
+        n_days = 28
+        n_weeks = 4
+        real_reshaped = real_traffic.reshape(B, n_days, steps_per_day)  # [B, 28, 24]
+
+        # Ground-truth weekly pattern (168)
+        weekly_days = []
+        for dow in range(7):
+            idx = torch.tensor([dow + 7 * w for w in range(n_weeks)], device=device, dtype=torch.long)
+            weekly_days.append(real_reshaped.index_select(1, idx).mean(dim=1))  # [B, 24]
+        weekly_pattern_gt = torch.stack(weekly_days, dim=1).reshape(B, 7 * steps_per_day)  # [B, 168]
+        
+        # Get daily pattern and weekly trend
+        if use_teacher_forcing:
+            # Teacher forcing
+            day_of_week = torch.arange(n_days, device=device) % 7
+            weekday_idx = torch.where(day_of_week < 5)[0]
+            weekend_idx = torch.where(day_of_week >= 5)[0]
+            weekday_pattern = real_reshaped.index_select(1, weekday_idx).mean(dim=1)  # [B, 24]
+            weekend_pattern = real_reshaped.index_select(1, weekend_idx).mean(dim=1)  # [B, 24]
+            daily_pattern = torch.cat([weekday_pattern, weekend_pattern], dim=1)  # [B, 48]
+            weekly_trend = weekly_pattern_gt
+        else:
+            if daily_pattern is None:
+                with torch.no_grad():
+                    daily_pattern = model.generate_daily_pattern(
+                        spatial_cond_level1, n_steps=n_steps_generate
+                    )
+
+            if weekly_trend is None:
+                with torch.no_grad():
+                    weekly_trend = model.generate_weekly_trend(
+                        daily_pattern, spatial_cond_level2, n_steps=n_steps_generate
+                    )
+
+        # Construct periodic component (coarse signal) from weekly pattern
+        coarse_signal = weekly_trend.repeat(1, n_weeks)  # [B, 672]
+
+        # Target residual
+        x1 = real_traffic - coarse_signal  # [B, 672]
+
+        # Sample noise
+        x0 = 0.1 * torch.randn_like(x1)
+
+        # Sample time
+        t = torch.rand(B, 1, device=device)
+
+        # Interpolation
+        x_t = t * x1 + (1 - t) * x0
+
+        # Target velocity
+        v_target = x1 - x0
+
+        # Predict velocity
+        # Pass peak_hour_gt to model
+        v_pred = model(
+            x_t, t, spatial_cond_level3, level=3,
+            daily_pattern=daily_pattern,
+            weekly_trend=weekly_trend,
+            coarse_signal=coarse_signal,
+            peak_hour=peak_hour_gt
+        )
+
+        # Flow Matching loss
+        loss_fm = F.mse_loss(v_pred, v_target)
+
+        # Boundary Loss for Level 3
+        # Ensure that (Coarse + Residual) >= 0
+        residual_est = x_t + (1 - t) * v_pred
+        final_traffic_est = coarse_signal + residual_est
+        loss_boundary = self.compute_boundary_loss(final_traffic_est)
+
+        return loss_fm, loss_boundary
+
+    def compute_temporal_structure_loss(
+        self,
+        generated: torch.Tensor,
+        real: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Temporal structure preservation loss.
+        """
+        d_gen = generated[..., 1:] - generated[..., :-1]
+        d_real = real[..., 1:] - real[..., :-1]
+        loss_deriv = F.mse_loss(d_gen, d_real)
+        return loss_deriv
+
+    def compute_multi_periodic_consistency_loss(
+        self,
+        generated: torch.Tensor,
+        real: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Multi-periodic consistency loss.
+        """
+        B = generated.shape[0]
+        device = generated.device
+
+        steps_per_day = 24
+        n_days = 28
+        n_weeks = 4
+
+        gen_days = generated.reshape(B, n_days, steps_per_day)  # [B, 28, 24]
+        real_days = real.reshape(B, n_days, steps_per_day)
+
+        # Daily mean pattern
+        gen_daily = gen_days.mean(dim=1)
+        real_daily = real_days.mean(dim=1)
+        loss_daily = F.mse_loss(gen_daily, real_daily)
+
+        # Weekly pattern
+        def weekly_pattern(x_days: torch.Tensor) -> torch.Tensor:
+            days = []
+            for dow in range(7):
+                idx = torch.tensor([dow + 7 * w for w in range(n_weeks)], device=device, dtype=torch.long)
+                days.append(x_days.index_select(1, idx).mean(dim=1))  # [B, 24]
+            return torch.stack(days, dim=1).reshape(B, 7 * steps_per_day)
+
+        gen_weekly = weekly_pattern(gen_days)
+        real_weekly = weekly_pattern(real_days)
+        loss_weekly = F.mse_loss(gen_weekly, real_weekly)
+
+        return loss_daily + loss_weekly
+
+    # Pearson Correlation Loss
+    def compute_correlation_loss(self, pred: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        """
+        Loss = 1 - Correlation. 强迫模型优化波形形状。
+        """
+        # 1. Center the data
+        pred_mean = pred - pred.mean(dim=1, keepdim=True)
+        target_mean = target - target.mean(dim=1, keepdim=True)
+
+        # 2. Normalize
+        pred_norm = torch.norm(pred_mean, p=2, dim=1) + 1e-8
+        target_norm = torch.norm(target_mean, p=2, dim=1) + 1e-8
+
+        # 3. Calculate cosine similarity (i.e., correlation after mean-shifting)
+        cosine_sim = (pred_mean * target_mean).sum(dim=1) / (pred_norm * target_norm)
+
+        # 4. Loss = 1 - Correlation
+        return 1.0 - cosine_sim.mean()
+
+    def forward(
+        self,
+        model: HierarchicalFlowMatchingV4,
+        real_traffic: torch.Tensor,
+        spatial_cond: Dict[str, torch.Tensor] | torch.Tensor,
+        fusion_method: str = 'generative',
+        lambda_level1: float = 1.0,
+        lambda_level2: float = 1.0,
+        lambda_level3: float = 1.0,
+        lambda_temporal: float = 0.1,
+        lambda_periodic: float = 0.1,
+        lambda_corr: float = 0.5, 
+        lambda_boundary: float = 1.0, 
+        lambda_bias: float = 1.0, 
+        teacher_forcing_ratio: float = 1.0,
+        n_steps_generate: int = 10,
+        **kwargs
+    ) -> Dict[str, torch.Tensor]:
+        """
+        Compute combined hierarchical loss.
+        """
+        if isinstance(spatial_cond, torch.Tensor):
+            # Compatibility fallback
+            spatial_cond = {
+                'level1_cond': spatial_cond,
+                'level2_cond': spatial_cond,
+                'level3_cond': spatial_cond,
+                'pred_peak_logits': None 
+            }
+
+        # ---------------------------------------------------------------------
+        # 1. Derive Ground Truth Peak Hour
+        # ---------------------------------------------------------------------
+        # Reshape to [B, days, 24] -> mean daily pattern -> argmax
+        B = real_traffic.shape[0]
+        avg_daily = real_traffic.reshape(B, -1, 24).mean(dim=1)
+        peak_hour_gt = avg_daily.argmax(dim=1) # [B] (0-23)
+        
+        # 2. Auxiliary Classification Loss
+        pred_peak_logits = spatial_cond.get('pred_peak_logits', None)
+        if pred_peak_logits is not None:
+            loss_peak_cls = F.cross_entropy(pred_peak_logits, peak_hour_gt)
+        else:
+            loss_peak_cls = torch.tensor(0.0, device=real_traffic.device)
+
+        # Determine teacher forcing
+        use_tf = torch.rand(1).item() < teacher_forcing_ratio
+
+        # ---------------------------------------------------------------------
+        # 3. Compute Level Losses (FM + Boundary)
+        # ---------------------------------------------------------------------
+        loss_l1_fm, loss_l1_bound = self.compute_level1_loss(
+            model, real_traffic, spatial_cond['level1_cond']
+        )
+        loss_l2_fm, loss_l2_bound = self.compute_level2_loss(
+            model,
+            real_traffic,
+            spatial_cond_level2=spatial_cond['level2_cond'],
+            spatial_cond_level1=spatial_cond['level1_cond'],
+            use_teacher_forcing=use_tf,
+            n_steps_generate=n_steps_generate,
+        )
+        # Pass peak_hour_gt
+        loss_l3_fm, loss_l3_bound = self.compute_level3_loss(
+            model,
+            real_traffic,
+            spatial_cond_level3=spatial_cond['level3_cond'],
+            spatial_cond_level2=spatial_cond['level2_cond'],
+            spatial_cond_level1=spatial_cond['level1_cond'],
+            peak_hour_gt=peak_hour_gt, # Explicit GT
+            use_teacher_forcing=use_tf,
+            n_steps_generate=n_steps_generate,
+        )
+
+        # ---------------------------------------------------------------------
+        # 4. Aux Losses (Temporal, Periodic, Bias)
+        # ---------------------------------------------------------------------
+        loss_temporal = torch.tensor(0.0, device=real_traffic.device)
+        loss_periodic = torch.tensor(0.0, device=real_traffic.device)
+        loss_bias = torch.tensor(0.0, device=real_traffic.device)
+        loss_corr = torch.tensor(0.0, device=real_traffic.device) 
+
+        # Increase Generation Sampling Frequency
+        # If lambda_corr is significant (>0.1), we increase the sampling probability from 30% to 60%
+        # This enables more frequent computation of the Correlation Loss
+        prob_threshold = 0.6 if lambda_corr > 0.1 else 0.3
+
+        # Only compute generation-based losses occasionally to save time
+        should_compute_gen_losses = (lambda_temporal > 0 or lambda_periodic > 0 or lambda_bias > 0 or lambda_corr > 0)
+        
+        if should_compute_gen_losses and torch.rand(1).item() < 0.3:
+            with torch.no_grad():
+                # Must provide peak_hour for generation
+                generated, _ = model.generate_hierarchical(
+                    spatial_cond, 
+                    peak_hour=peak_hour_gt, 
+                    n_steps_per_level=n_steps_generate
+                )
+            
+            if lambda_corr > 0:
+                loss_corr = self.compute_correlation_loss(generated, real_traffic)
+
+            if lambda_temporal > 0:
+                loss_temporal = self.compute_temporal_structure_loss(generated, real_traffic)
+            
+            if lambda_periodic > 0:
+                loss_periodic = self.compute_multi_periodic_consistency_loss(generated, real_traffic)
+            
+            if lambda_bias > 0:
+                loss_bias = self.compute_bias_loss(generated, real_traffic)
+
+        # ---------------------------------------------------------------------
+        # 5. Combined Loss
+        # ---------------------------------------------------------------------
+        
+        # FM Loss
+        loss_fm_total = (
+            lambda_level1 * loss_l1_fm +
+            lambda_level2 * loss_l2_fm +
+            lambda_level3 * loss_l3_fm
+        )
+
+        # Boundary Loss
+        loss_boundary_total = lambda_boundary * (loss_l1_bound + loss_l2_bound + loss_l3_bound)
+
+        # Bias Loss
+        loss_bias_total = lambda_bias * loss_bias
+
+        # Peak Classification Weight (static 0.5 for now)
+        lambda_peak = 5.0
+        
+        total_loss = (
+            loss_fm_total +
+            loss_boundary_total +
+            loss_bias_total +
+            lambda_temporal * loss_temporal +
+            lambda_periodic * loss_periodic +
+            lambda_peak * loss_peak_cls +
+            lambda_corr * loss_corr  # 加入总 Loss
+        )
+
+        return {
+            'loss_level1': loss_l1_fm,
+            'loss_level2': loss_l2_fm,
+            'loss_level3': loss_l3_fm,
+            'loss_boundary': loss_boundary_total, 
+            'loss_bias': loss_bias_total,        
+            'loss_temporal': loss_temporal,
+            'loss_periodic': loss_periodic,
+            'loss_peak_cls': loss_peak_cls,       
+            'loss_corr': loss_corr,
+            'loss_total': total_loss,
+        }
+    
+    
+
+
+# =============================================================================
+# Complete Hierarchical Flow Matching Model with Encoder
+# =============================================================================
+
+class HierarchicalFlowMatchingSystemV4(nn.Module):
+    """
+    Complete system combining:
+    - Multi-modal spatial encoder
+    - Hierarchical Flow Matching model
+    """
+
+    def __init__(
+        self,
+        spatial_dim: int = 192,
+        hidden_dim: int = 256,
+        poi_dim: int = 20,
+        n_layers_level3: int = 6,
+        fusion_method: Literal['generative', 'contrastive'] = 'generative' # Default
+    ):
+        super().__init__()
+        self.fusion_method = fusion_method
+        self.spatial_dim = spatial_dim
+
+        # 1. Environment Encoder (Multi-modal)
+        self.spatial_encoder = MultiModalSpatialEncoderV4(spatial_dim, poi_dim)
+        
+        # NOTE: No TrafficCLIPEncoder in Generative Mode
+        self.traffic_encoder = None
+
+        # 2. Flow Matching Generative Model
+        self.fm_model = HierarchicalFlowMatchingV4(spatial_dim, hidden_dim, n_layers_level3)
+        
+        # 3. Loss
+        self.loss_fn = HierarchicalFlowMatchingLoss()
+
+    def forward(self, batch: Dict, mode: str = 'train', loss_cfg: Optional[Dict] = None) -> Dict:
+        """
+        Args:
+            batch: dict with spatial and traffic data
+            mode: 'train' or 'generate'
+        Returns:
+            outputs: dict with losses or generated samples
+        """
+        # Encode spatial features
+        spatial_cond_dict = self.spatial_encoder(batch)
+        loss_cfg = loss_cfg or {}
+
+        if mode == 'train':
+            real_traffic = batch['traffic_seq']
+            
+            # Calculate Losses
+            losses = self.loss_fn(
+                model=self.fm_model,
+                real_traffic=real_traffic,
+                spatial_cond=spatial_cond_dict,
+                fusion_method=self.fusion_method,
+                **loss_cfg
+            )
+            return {'losses': losses}
+
+        elif mode == 'generate':
+            # Inference logic: Explicit Peak Conditioning
+            # 1. Use the auxiliary head to predict peak location
+            pred_logits = spatial_cond_dict['pred_peak_logits']
+            pred_peak_hour = pred_logits.argmax(dim=1) # [B]
+            
+            # 2. Allow manual override if 'manual_peak_hour' is in batch
+            if 'manual_peak_hour' in batch:
+                pred_peak_hour = batch['manual_peak_hour']
+
+            # Generate hierarchical samples
+            generated, intermediates = self.fm_model.generate_hierarchical(
+                spatial_cond_dict,
+                peak_hour=pred_peak_hour,
+                n_steps_per_level=loss_cfg.get('n_steps_generate', 50),
+            )
+            return {'generated': generated, 'intermediates': intermediates, 'pred_peak_hour': pred_peak_hour}
+
+        else:
+            raise ValueError(f"Unknown mode: {mode}")
+
+
+# =============================================================================
+# Trainer
+# =============================================================================
+
+class HierarchicalFlowMatchingTrainerV4:
+    """
+    Trainer for Hierarchical Flow Matching V4.
+    """
+
+    def __init__(
+        self,
+        model: HierarchicalFlowMatchingSystemV4,
+        train_loader: DataLoader,
+        val_loader: DataLoader,
+        lr: float = 1e-4,
+        weight_decay: float = 0.01,
+        checkpoint_dir: str = "checkpoints_hfm_v4",
+        lambda_level1: float = 1.0,
+        lambda_level2: float = 1.0,
+        lambda_level3: float = 1.0,
+        lambda_temporal: float = 0.1,
+        lambda_periodic: float = 0.1,
+        lambda_boundary: float = 1.0, 
+        lambda_bias: float = 1.0,     
+        lambda_corr: float = 0.5, 
+        warmup_epochs: int = 5,
+    ):
+        self.model = model
+        self.train_loader = train_loader
+        self.val_loader = val_loader
+        self.checkpoint_dir = checkpoint_dir
+
+        # Loss weights
+        self.loss_cfg = {
+            'lambda_level1': lambda_level1,
+            'lambda_level2': lambda_level2,
+            'lambda_level3': lambda_level3,
+            'lambda_temporal': lambda_temporal,
+            'lambda_periodic': lambda_periodic,
+            'lambda_boundary': lambda_boundary, 
+            'lambda_bias': lambda_bias,        
+            'lambda_corr': lambda_corr, 
+            'teacher_forcing_ratio': 1.0,
+            'n_steps_generate': 10
+        }
+
+        # Warmup
+        self.warmup_epochs = warmup_epochs
+        self.base_lr = lr
+
+        self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+        self.model = self.model.to(self.device)
+
+        # Optimizer
+        self.optimizer = torch.optim.AdamW(
+            self.model.parameters(),
+            lr=lr,
+            weight_decay=weight_decay,
+            betas=(0.9, 0.99),
+        )
+
+        os.makedirs(checkpoint_dir, exist_ok=True)
+
+        # Training history
+        self.history = {
+            'train_loss': [],
+            'val_loss': [],
+            'train_loss_level1': [],
+            'train_loss_level2': [],
+            'train_loss_level3': [],
+            'train_loss_temporal': [],
+            'train_loss_periodic': [],
+            'train_loss_peak_cls': [], 
+            'train_loss_boundary': [], 
+            'train_loss_bias': [],     
+            'train_loss_corr': [], 
+            'val_mae': [],
+            'val_corr': [],
+            'val_var_ratio': [],
+            'lr': [],
+        }
+
+    def get_lr_scale(self, epoch: int, total_epochs: int) -> float:
+        """Get learning rate scale with warmup and cosine decay."""
+        if epoch < self.warmup_epochs:
+            return (epoch + 1) / self.warmup_epochs
+        else:
+            progress = (epoch - self.warmup_epochs) / (total_epochs - self.warmup_epochs)
+            return 0.5 * (1 + np.cos(np.pi * progress))
+
+    def set_lr(self, scale: float):
+        """Set learning rate."""
+        for param_group in self.optimizer.param_groups:
+            param_group['lr'] = self.base_lr * scale
+
+    def train_epoch(self, epoch: int, total_epochs: int) -> Dict[str, float]:
+        """Train one epoch."""
+        self.model.train()
+
+        # Set learning rate
+        lr_scale = self.get_lr_scale(epoch, total_epochs)
+        self.set_lr(lr_scale)
+        current_lr = self.optimizer.param_groups[0]['lr']
+
+        # Teacher forcing ratio
+        self.loss_cfg['teacher_forcing_ratio'] = max(0.5, 1.0 - epoch / (2 * total_epochs))
+
+        total_loss = 0.0
+        loss_level1 = 0.0
+        loss_level2 = 0.0
+        loss_level3 = 0.0
+        loss_temporal = 0.0
+        loss_periodic = 0.0
+        loss_peak_cls = 0.0 
+        loss_boundary = 0.0 
+        loss_bias = 0.0     
+        loss_corr = 0.0 
+
+        pbar = tqdm(self.train_loader, desc=f"Epoch {epoch + 1} [Train]")
+        for batch in pbar:
+            batch = {
+                k: v.to(self.device) if isinstance(v, torch.Tensor) else v
+                for k, v in batch.items()
+            }
+
+            # Forward pass
+            self.optimizer.zero_grad()
+            output = self.model(
+                batch,
+                mode='train',
+                loss_cfg=self.loss_cfg,
+            )
+            losses = output['losses']
+
+            # Total loss
+            total_batch_loss = losses['loss_total']
+
+            # Backward pass
+            total_batch_loss.backward()
+            torch.nn.utils.clip_grad_norm_(self.model.parameters(), 1.0)
+            self.optimizer.step()
+
+            # Accumulate losses
+            total_loss += total_batch_loss.item()
+            loss_level1 += losses['loss_level1'].item()
+            loss_level2 += losses['loss_level2'].item()
+            loss_level3 += losses['loss_level3'].item()
+            loss_temporal += losses.get('loss_temporal', torch.tensor(0.0)).item()
+            loss_periodic += losses.get('loss_periodic', torch.tensor(0.0)).item()
+            loss_peak_cls += losses.get('loss_peak_cls', torch.tensor(0.0)).item()
+            loss_boundary += losses.get('loss_boundary', torch.tensor(0.0)).item()
+            loss_bias += losses.get('loss_bias', torch.tensor(0.0)).item()
+            loss_corr += losses.get('loss_corr', torch.tensor(0.0)).item() 
+
+            # Update progress bar
+            pbar.set_postfix({
+                'loss': total_loss / (len(pbar) + 1),
+                'corr': loss_corr / (len(pbar) + 1),
+                'peak': loss_peak_cls / (len(pbar) + 1),
+                'bnd': loss_boundary / (len(pbar) + 1),
+                'bias': loss_bias / (len(pbar) + 1),
+                'lr': f'{current_lr:.2e}',
+            })
+
+        n_batches = len(self.train_loader)
+        return {
+            'loss_total': total_loss / n_batches,
+            'loss_level1': loss_level1 / n_batches,
+            'loss_level2': loss_level2 / n_batches,
+            'loss_level3': loss_level3 / n_batches,
+            'loss_temporal': loss_temporal / n_batches,
+            'loss_periodic': loss_periodic / n_batches,
+            'loss_peak_cls': loss_peak_cls / n_batches,
+            'loss_boundary': loss_boundary / n_batches,
+            'loss_bias': loss_bias / n_batches,
+            'loss_corr': loss_corr / n_batches, 
+            'lr': current_lr,
+        }
+
+    @torch.no_grad()
+    def validate(self, epoch: int) -> Dict[str, float]:
+        """Validate."""
+        self.model.eval()
+
+        total_loss = 0.0
+        all_mae = []
+        all_corr = []
+        all_var_ratio = []
+
+        pbar = tqdm(self.val_loader, desc=f"Epoch {epoch + 1} [Val]")
+        for batch in pbar:
+            batch = {
+                k: v.to(self.device) if isinstance(v, torch.Tensor) else v
+                for k, v in batch.items()
+            }
+
+            # Loss
+            output = self.model(
+                batch,
+                mode='train',
+                loss_cfg=self.loss_cfg,
+            )
+            losses = output['losses']
+            total_loss += losses['loss_total'].item()
+
+            # Generate samples
+            # Note: generate now internally handles peak_hour logic in System.forward
+            gen_output = self.model(
+                batch,
+                mode='generate',
+                loss_cfg={'n_steps_generate': 50},
+            )
+            real = batch['traffic_seq'].cpu().numpy()
+            generated = gen_output['generated'].cpu().numpy()
+
+            # Metrics
+            mae = np.mean(np.abs(real - generated))
+            all_mae.append(mae)
+
+            # Variance ratio
+            real_var = np.var(real, axis=1).mean()
+            gen_var = np.var(generated, axis=1).mean()
+            var_ratio = gen_var / (real_var + 1e-8)
+            all_var_ratio.append(var_ratio)
+
+            # Correlation
+            for i in range(len(real)):
+                r_std = np.std(real[i])
+                g_std = np.std(generated[i])
+                if r_std > 1e-6 and g_std > 1e-6:
+                    corr = np.corrcoef(real[i], generated[i])[0, 1]
+                    if not np.isnan(corr):
+                        all_corr.append(corr)
+
+        n_batches = len(self.val_loader)
+        return {
+            'loss_total': total_loss / n_batches,
+            'mae': np.mean(all_mae),
+            'correlation': np.mean(all_corr) if all_corr else 0.0,
+            'var_ratio': np.mean(all_var_ratio),
+        }
+
+    def train(self, epochs: int):
+        """Full training loop."""
+        print("=" * 80)
+        print("Hierarchical Flow Matching V4 - Training")
+        print(f"Fusion Method: {self.model.fusion_method}")
+        print("=" * 80)
+        print(f"Device: {self.device}")
+        print(f"Epochs: {epochs}")
+        print(f"Base learning rate: {self.base_lr:.2e}")
+        print("=" * 80)
+
+        # [修改 1] 初始化两个最佳指标跟踪变量
+        best_val_loss = float('inf')
+        best_val_corr = -1.0  # 初始化相关性为 -1
+
+        for epoch in range(epochs):
+            # Train
+            train_losses = self.train_epoch(epoch, epochs)
+
+            # Validate
+            val_losses = self.validate(epoch)
+
+            # Print summary
+            print(f"\nEpoch {epoch + 1}/{epochs}")
+            print(f"  Train Loss: {train_losses['loss_total']:.6f}")
+            print(f"  Peak Cls Loss: {train_losses['loss_peak_cls']:.6f}")
+            print(f"  Boundary Loss: {train_losses['loss_boundary']:.6f}")
+            print(f"  Bias Loss: {train_losses['loss_bias']:.6f}")
+            print(f"  Val Loss: {val_losses['loss_total']:.6f}")
+            print(f"  Val MAE: {val_losses['mae']:.4f}")
+            print(f"  Val Correlation: {val_losses['correlation']:.4f}")
+            print(f"  Val Var Ratio: {val_losses['var_ratio']:.4f}")
+
+            # Save history
+            self.history['train_loss'].append(train_losses['loss_total'])
+            self.history['val_loss'].append(val_losses['loss_total'])
+            self.history['train_loss_level1'].append(train_losses['loss_level1'])
+            self.history['train_loss_level2'].append(train_losses['loss_level2'])
+            self.history['train_loss_level3'].append(train_losses['loss_level3'])
+            self.history['train_loss_temporal'].append(train_losses['loss_temporal'])
+            self.history['train_loss_periodic'].append(train_losses['loss_periodic'])
+            self.history['train_loss_peak_cls'].append(train_losses['loss_peak_cls'])
+            self.history['train_loss_boundary'].append(train_losses['loss_boundary'])
+            self.history['train_loss_bias'].append(train_losses['loss_bias'])
+            self.history['val_mae'].append(val_losses['mae'])
+            self.history['val_corr'].append(val_losses['correlation'])
+            self.history['val_var_ratio'].append(val_losses['var_ratio'])
+            self.history['lr'].append(train_losses['lr'])
+            
+            # Logic A: Save the model with the lowest loss (as the mathematically optimal fallback)
+            if val_losses['loss_total'] < best_val_loss:
+                best_val_loss = val_losses['loss_total']
+                self.save_checkpoint(epoch, val_losses, filename='best_loss_model.pt')
+                print(f"  ✓ [Best Loss model saved! Loss: {best_val_loss:.4f}]")
+
+            # Logic B: Save the model with the highest correlation (as the business-practical best)
+            if val_losses['correlation'] > best_val_corr:
+                best_val_corr = val_losses['correlation']
+                self.save_checkpoint(epoch, val_losses, filename='best_corr_model.pt')
+                print(f"  ★ [Best Correlation model saved! Corr: {best_val_corr:.4f}]")
+
+            # Always save the latest version
+            self.save_checkpoint(epoch, val_losses, filename='latest_model.pt')
+
+        # Save history
+        self.save_history()
+
+        print("\n" + "=" * 80)
+        print("Training Completed!")
+        print(f"Best validation loss: {best_val_loss:.6f}")
+        print(f"Best validation corr: {best_val_corr:.4f}") # 打印最佳相关性
+        print(f"Checkpoints saved to: {self.checkpoint_dir}")
+        print("=" * 80)
+
+    def save_checkpoint(self, epoch: int, losses: Dict, filename: str = 'best_model.pt'):
+        """Save checkpoint."""
+        checkpoint = {
+            'epoch': epoch,
+            'model_state_dict': self.model.state_dict(),
+            'optimizer_state_dict': self.optimizer.state_dict(),
+            'losses': losses,
+            'history': self.history,
+        }
+
+        path = os.path.join(self.checkpoint_dir, filename)
+        torch.save(checkpoint, path)
+
+    def save_history(self):
+        """Save training history."""
+        path = os.path.join(self.checkpoint_dir, 'training_history.json')
+
+        history_serializable = {}
+        for key, values in self.history.items():
+            history_serializable[key] = [
+                float(v) if isinstance(v, (np.floating, np.integer)) else v
+                for v in values
+            ]
+
+        with open(path, 'w') as f:
+            json.dump(history_serializable, f, indent=2)

hierarchical_flow_matching_v4.py

@@ -0,0 +1,1019 @@
+"""
+Hierarchical Flow Matching with Mamba/SSM Backbone (V4) - Generative Version
+============================================================================
+
+Architecture: Pure Diffusion/Flow Matching (No GANs).
+Fusion Method: Generative (Implicit alignment via conditional generation).
+
+Core improvements over V3:
+1. Three-level cascaded Flow Matching architecture.
+2. Multi-modal spatial context encoding.
+3. Long-sequence modeling backbone.
+4. Explicit Peak Conditioning.
+5. Physical Constraints (Non-negative output enforced).
+
+Author: Optimization Team
+Date: 2026-01-21
+"""
+
+import os
+import sys
+import math
+import numpy as np
+from typing import Dict, Optional, Tuple, List
+from dataclasses import dataclass
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+# =============================================================================
+# Mamba/SSM Backbone for Long Sequence Modeling
+# =============================================================================
+
+@dataclass
+class MambaConfig:
+    """Configuration for Mamba block."""
+    d_model: int = 256
+    d_state: int = 64
+    d_conv: int = 4
+    expand: int = 2
+    dt_rank: str = "auto"
+    dt_min: float = 0.001
+    dt_max: float = 0.1
+    dt_init: str = "random"
+    dt_scale: float = 1.0
+    dt_init_floor: float = 1e-4
+    bias: bool = True
+    conv_bias: bool = True
+    pscan: bool = True
+    use_cuda: bool = True
+
+
+def _selective_scan_diagonal(
+    log_a: torch.Tensor,  # [B, L, N]
+    b: torch.Tensor,      # [B, L, N]
+) -> torch.Tensor:
+    """
+    Parallel (vectorized) diagonal linear recurrence:
+        h_t = a_t * h_{t-1} + b_t,  h_{-1}=0
+    where a_t = exp(log_a_t), computed without Python loops.
+    """
+    # log_p[t] = sum_{i<=t} log_a[i]
+    log_p = torch.cumsum(log_a, dim=1)  # [B, L, N]
+    inv_p = torch.exp(-log_p)
+    s = torch.cumsum(b * inv_p, dim=1)  # [B, L, N]
+    h = torch.exp(log_p) * s
+    return h
+
+
+class Mamba(nn.Module):
+    """
+    Mamba block for efficient long-sequence modeling.
+
+    Based on: "Mamba: Linear-Time Sequence Modeling with Selective State Spaces"
+    Pure-PyTorch implementation (vectorized diagonal selective scan) for traffic
+    sequence generation (no external kernels / dependencies).
+    """
+
+    def __init__(self, config: MambaConfig):
+        super().__init__()
+        self.config = config
+
+        d_model = config.d_model
+        d_state = config.d_state
+        d_conv = config.d_conv
+        expand = config.expand
+
+        self.d_inner = int(expand * d_model)
+
+        # (1) Input projection: x -> (u, gate)
+        self.in_proj = nn.Linear(d_model, 2 * self.d_inner, bias=config.bias)
+
+        # (2) Depthwise conv for short-range mixing (Mamba-style local context)
+        self.dwconv = nn.Conv1d(
+            in_channels=self.d_inner,
+            out_channels=self.d_inner,
+            kernel_size=d_conv,
+            padding=d_conv - 1,
+            groups=self.d_inner,
+            bias=config.conv_bias,
+        )
+
+        # (3) Input-dependent SSM parameters (B, C, dt)
+        self.B_proj = nn.Linear(self.d_inner, d_state, bias=False)
+        self.C_proj = nn.Linear(self.d_inner, d_state, bias=False)
+        self.dt_proj = nn.Linear(self.d_inner, d_state, bias=True)
+
+        # Diagonal A (negative, stable)
+        self.A_log = nn.Parameter(torch.zeros(d_state))
+
+        # Skip connection from u (Mamba "D" term)
+        self.D = nn.Parameter(torch.ones(self.d_inner))
+
+        # (4) State -> inner -> model projections
+        self.out_state_proj = nn.Linear(d_state, self.d_inner, bias=False)
+        self.out_proj = nn.Linear(self.d_inner, d_model, bias=config.bias)
+
+        # Initialize FiLM-like stability: start close to identity
+        nn.init.zeros_(self.A_log)
+        nn.init.zeros_(self.dt_proj.weight)
+        nn.init.constant_(self.dt_proj.bias, math.log(math.expm1(0.01)))  # softplus^-1
+        nn.init.zeros_(self.out_state_proj.weight)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, D] input sequence
+        Returns:
+            y: [B, L, D] output sequence
+        """
+        B, L, _ = x.shape
+
+        # Input projection
+        u, gate = self.in_proj(x).chunk(2, dim=-1)  # [B, L, d_inner] each
+
+        # Depthwise conv (causal-ish via padding then crop)
+        u_conv = self.dwconv(u.transpose(1, 2))[:, :, :L].transpose(1, 2)  # [B, L, d_inner]
+        u_conv = F.silu(u_conv)
+
+        # Input-dependent SSM params
+        dt = F.softplus(self.dt_proj(u_conv))  # [B, L, d_state]
+        dt = dt.clamp(min=self.config.dt_min, max=self.config.dt_max)
+
+        B_t = self.B_proj(u_conv)  # [B, L, d_state]
+        C_t = self.C_proj(u_conv)  # [B, L, d_state]
+
+        # Diagonal state transition: a_t = exp(A * dt)
+        A = -torch.exp(self.A_log).view(1, 1, -1)  # [1, 1, d_state]
+        log_a = A * dt  # [B, L, d_state]
+        b = B_t * dt    # [B, L, d_state]
+
+        # Selective scan (vectorized)
+        h = _selective_scan_diagonal(log_a, b)  # [B, L, d_state]
+
+        # Output from states
+        y_state = h * C_t
+        y_inner = self.out_state_proj(y_state)  # [B, L, d_inner]
+
+        # Skip + gate (Mamba-style)
+        y_inner = y_inner + u_conv * self.D.view(1, 1, -1)
+        y_inner = y_inner * torch.sigmoid(gate)
+
+        return self.out_proj(y_inner)
+
+
+# =============================================================================
+# Multi-Scale Dilated Convolution Backbone
+# =============================================================================
+
+class MultiScaleDilatedConv(nn.Module):
+    """
+    Multi-scale dilated convolution for capturing temporal patterns at different scales.
+
+    Receptive fields:
+    - Scale 1 (dilation=1): Daily patterns (24 hours)
+    - Scale 2 (example): Weekly patterns (7 days) -> hourly would be dilation=168
+    - Scale 3 (example): Longer cycles (e.g., 28 days) -> hourly would be dilation=672
+    """
+
+    def __init__(
+        self,
+        channels: int,
+        kernel_size: int = 3,
+        dilations: Optional[List[int]] = None,
+        dropout: float = 0.0,
+    ):
+        super().__init__()
+        if dilations is None:
+            dilations = [1, 4, 16]
+        self.channels = channels
+        self.kernel_size = kernel_size
+        self.dilations = [int(d) for d in dilations if int(d) >= 1]
+        self.dropout = nn.Dropout(dropout) if dropout > 0 else nn.Identity()
+
+        padding_base = (kernel_size - 1) // 2
+
+        # Depthwise-separable conv branches
+        self.branches = nn.ModuleList()
+        for d in self.dilations:
+            self.branches.append(
+                nn.Sequential(
+                    nn.Conv1d(
+                        channels,
+                        channels,
+                        kernel_size,
+                        dilation=d,
+                        padding=padding_base * d,
+                        groups=channels,
+                        bias=True,
+                    ),
+                    nn.GELU(),
+                    nn.Conv1d(channels, channels, kernel_size=1, bias=True),
+                )
+            )
+
+        # Fusion (token-wise MLP)
+        self.fusion = nn.Sequential(
+            nn.Linear(channels * len(self.dilations), channels * 2),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(channels * 2, channels),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, C] input
+        Returns:
+            y: [B, L, C] output
+        """
+        x_t = x.transpose(1, 2)  # [B, C, L]
+        outs = []
+        for branch in self.branches:
+            outs.append(branch(x_t).transpose(1, 2))  # [B, L, C]
+        y = torch.cat(outs, dim=-1)  # [B, L, C * n_scales]
+        y = self.fusion(y)
+        return self.dropout(y)
+
+
+# =============================================================================
+# Hybrid Backbone: Mamba + Multi-Scale Dilated Conv
+# =============================================================================
+
+class HybridLongSequenceBackbone(nn.Module):
+    """
+    Hybrid backbone combining Mamba/SSM and multi-scale dilated convolutions.
+
+    Designed for efficient long-sequence modeling with multi-scale temporal patterns.
+    """
+
+    def __init__(
+        self,
+        d_model: int = 256,
+        n_layers: int = 4,
+        d_state: int = 64,
+        use_mamba: bool = True,
+        use_dilated_conv: bool = True,
+        dilations: Optional[List[int]] = None,
+        cond_dim: Optional[int] = None,
+        dropout: float = 0.1,
+    ):
+        super().__init__()
+        self.d_model = d_model
+        self.n_layers = n_layers
+        self.d_state = d_state
+        self.use_dilated_conv = use_dilated_conv
+        self.use_mamba = use_mamba
+        self.cond_dim = cond_dim
+
+        if dilations is None:
+            dilations = [1, 4, 16]
+
+        self.blocks = nn.ModuleList()
+        for _ in range(n_layers):
+            self.blocks.append(
+                _HybridBlock(
+                    d_model=d_model,
+                    d_state=d_state,
+                    use_mamba=use_mamba,
+                    use_dilated_conv=use_dilated_conv,
+                    dilations=dilations,
+                    cond_dim=cond_dim,
+                    dropout=dropout,
+                )
+            )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t_emb: Optional[torch.Tensor] = None,     # [B, D]
+        cond: Optional[torch.Tensor] = None,      # [B, C]
+    ) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, D] input sequence
+        Returns:
+            y: [B, L, D] output sequence
+        """
+        for block in self.blocks:
+            x = block(x, t_emb=t_emb, cond=cond)
+        return x
+
+
+def _valid_num_groups(channels: int, requested: int) -> int:
+    g = min(requested, channels)
+    while g > 1 and (channels % g) != 0:
+        g -= 1
+    return max(g, 1)
+
+
+class _HybridBlock(nn.Module):
+    def __init__(
+        self,
+        d_model: int,
+        d_state: int,
+        use_mamba: bool,
+        use_dilated_conv: bool,
+        dilations: List[int],
+        cond_dim: Optional[int],
+        dropout: float,
+    ):
+        super().__init__()
+        self.use_mamba = use_mamba
+        self.use_dilated_conv = use_dilated_conv
+        self.cond_dim = cond_dim
+
+        self.norm1 = nn.LayerNorm(d_model)
+        self.norm2 = nn.LayerNorm(d_model)
+        self.norm3 = nn.LayerNorm(d_model)
+
+        self.mamba = (
+            Mamba(MambaConfig(d_model=d_model, d_state=d_state))
+            if use_mamba
+            else nn.Identity()
+        )
+        self.conv = (
+            MultiScaleDilatedConv(
+                channels=d_model,
+                kernel_size=3,
+                dilations=dilations,
+                dropout=dropout,
+            )
+            if use_dilated_conv
+            else nn.Identity()
+        )
+
+        self.ffn = nn.Sequential(
+            nn.Linear(d_model, d_model * 4),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(d_model * 4, d_model),
+        )
+
+        self.dropout = nn.Dropout(dropout)
+
+        self.film = FiLMModulation(d_model, cond_dim) if cond_dim is not None else None
+        self.ada_gn = AdaptiveGroupNorm(d_model, cond_dim) if cond_dim is not None else None
+
+    def _cond(self, h: torch.Tensor, cond: Optional[torch.Tensor]) -> torch.Tensor:
+        if cond is None or self.film is None or self.ada_gn is None:
+            return h
+        h = self.film(h, cond)
+        h = self.ada_gn(h, cond)
+        return h
+
+    def forward(
+        self,
+        x: torch.Tensor,                     # [B, L, D]
+        t_emb: Optional[torch.Tensor] = None,  # [B, D]
+        cond: Optional[torch.Tensor] = None,   # [B, C]
+    ) -> torch.Tensor:
+        # Mamba/SSM
+        h = self.norm1(x)
+        if t_emb is not None:
+            h = h + t_emb.unsqueeze(1)
+        h = self._cond(h, cond)
+        h = self.mamba(h)
+        x = x + self.dropout(h)
+
+        # Multi-scale dilated conv
+        if self.use_dilated_conv:
+            h = self.norm2(x)
+            if t_emb is not None:
+                h = h + 0.5 * t_emb.unsqueeze(1)
+            h = self._cond(h, cond)
+            h = self.conv(h)
+            x = x + self.dropout(h)
+
+        # FFN
+        h = self.norm3(x)
+        if t_emb is not None:
+            h = h + 0.5 * t_emb.unsqueeze(1)
+        h = self._cond(h, cond)
+        h = self.ffn(h)
+        x = x + self.dropout(h)
+        return x
+
+
+# =============================================================================
+# FiLM Modulation for Condition Injection
+# =============================================================================
+
+class FiLMModulation(nn.Module):
+    """
+    Feature-wise Linear Modulation (FiLM) for adaptive condition injection.
+
+    Dynamically modulates intermediate features based on spatial context.
+    """
+
+    def __init__(self, d_model: int, cond_dim: int):
+        super().__init__()
+
+        self.gamma_proj = nn.Linear(cond_dim, d_model)
+        self.beta_proj = nn.Linear(cond_dim, d_model)
+
+        # Start near identity modulation
+        nn.init.zeros_(self.gamma_proj.weight)
+        nn.init.zeros_(self.gamma_proj.bias)
+        nn.init.zeros_(self.beta_proj.weight)
+        nn.init.zeros_(self.beta_proj.bias)
+
+    def forward(self, x: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, D] features
+            cond: [B, C] condition
+        Returns:
+            y: [B, L, D] modulated features
+        """
+        gamma = self.gamma_proj(cond).unsqueeze(1)  # [B, 1, D]
+        beta = self.beta_proj(cond).unsqueeze(1)    # [B, 1, D]
+        return x * (1.0 + gamma) + beta
+
+
+# =============================================================================
+# Adaptive Group Normalization
+# =============================================================================
+
+class AdaptiveGroupNorm(nn.Module):
+    """
+    Adaptive Group Normalization (AdaGN) for condition-aware normalization.
+    """
+
+    def __init__(self, d_model: int, cond_dim: int, num_groups: int = 32):
+        super().__init__()
+        self.num_groups = _valid_num_groups(d_model, num_groups)
+        self.group_norm = nn.GroupNorm(self.num_groups, d_model, affine=False)
+
+        self.weight_proj = nn.Linear(cond_dim, d_model)
+        self.bias_proj = nn.Linear(cond_dim, d_model)
+        nn.init.zeros_(self.weight_proj.weight)
+        nn.init.zeros_(self.weight_proj.bias)
+        nn.init.zeros_(self.bias_proj.weight)
+        nn.init.zeros_(self.bias_proj.bias)
+
+    def forward(self, x: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, D] features
+            cond: [B, C] condition
+        Returns:
+            y: [B, L, D] normalized features
+        """
+        # Group norm
+        x_norm = self.group_norm(x.transpose(1, 2)).transpose(1, 2)  # [B, L, D]
+
+        # Adaptive scaling
+        weight = self.weight_proj(cond).unsqueeze(1)  # [B, 1, D]
+        bias = self.bias_proj(cond).unsqueeze(1)  # [B, 1, D]
+
+        return x_norm * (1.0 + weight) + bias
+
+
+class FourierTimeEmbedding(nn.Module):
+    """Gaussian Fourier features for diffusion/FM time t in [0,1]."""
+
+    def __init__(self, d_model: int, n_freqs: int = 64):
+        super().__init__()
+        self.n_freqs = n_freqs
+        self.W = nn.Parameter(torch.randn(n_freqs) * 10.0)
+        self.proj = nn.Sequential(
+            nn.Linear(2 * n_freqs, d_model),
+            nn.GELU(),
+            nn.Linear(d_model, d_model),
+        )
+
+    def forward(self, t: torch.Tensor) -> torch.Tensor:
+        # t: [B, 1]
+        t = t.clamp(0.0, 1.0)
+        w = self.W.view(1, 1, -1)  # [1, 1, F]
+        angles = 2 * math.pi * t.unsqueeze(-1) * w  # [B, 1, F]
+        emb = torch.cat([torch.sin(angles), torch.cos(angles)], dim=-1).squeeze(1)
+        return self.proj(emb)  # [B, D]
+
+
+def sinusoidal_positional_embedding(
+    length: int,
+    dim: int,
+    device: torch.device,
+    dtype: torch.dtype,
+) -> torch.Tensor:
+    """Standard sinusoidal positional embeddings [L, D]."""
+    position = torch.arange(length, device=device, dtype=dtype).unsqueeze(1)  # [L, 1]
+    div_term = torch.exp(
+        torch.arange(0, dim, 2, device=device, dtype=dtype) * (-math.log(10000.0) / dim)
+    )  # [D/2]
+    pe = torch.zeros(length, dim, device=device, dtype=dtype)
+    pe[:, 0::2] = torch.sin(position * div_term)
+    pe[:, 1::2] = torch.cos(position * div_term)
+    return pe
+
+
+# =============================================================================
+# Level 1: Daily Pattern Flow Matching
+# =============================================================================
+
+class DailyPatternFM(nn.Module):
+    """
+    Level 1: Daily Pattern Flow Matching.
+
+    Learns to generate day-type templates for hourly traffic:
+    - weekday template (24 hours)
+    - weekend template (24 hours)
+
+    Output is a concatenation of two 24-hour patterns: [weekday | weekend] -> 48 dims.
+    """
+
+    def __init__(self, spatial_dim: int = 192, hidden_dim: int = 256, steps_per_day: int = 24):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.hidden_dim = hidden_dim
+        self.steps_per_day = steps_per_day
+        self.daytype_len = 2 * steps_per_day  # weekday + weekend
+
+        self.time_embed = FourierTimeEmbedding(hidden_dim)
+
+        self.in_proj = nn.Linear(1, hidden_dim)
+        self.backbone = HybridLongSequenceBackbone(
+            d_model=hidden_dim,
+            n_layers=3,
+            d_state=64,
+            use_mamba=True,
+            use_dilated_conv=True,
+            dilations=[1, 2, 4, 8, 16],
+            cond_dim=spatial_dim,
+            dropout=0.1,
+        )
+        self.out_proj = nn.Linear(hidden_dim, 1)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t: torch.Tensor,
+        spatial_cond: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Args:
+            x: [B, 48] day-type templates = [weekday(24), weekend(24)]
+            t: [B, 1] time step
+            spatial_cond: [B, spatial_dim] spatial context
+        Returns:
+            v: [B, 48] velocity field
+        """
+        B, L = x.shape
+        assert L == self.daytype_len, f"DailyPatternFM expects L={self.daytype_len}, got {L}"
+
+        t_emb = self.time_embed(t)  # [B, hidden_dim]
+        pos = sinusoidal_positional_embedding(L, self.hidden_dim, x.device, x.dtype)  # [L, D]
+
+        h = self.in_proj(x.unsqueeze(-1))  # [B, L, D]
+        h = h + pos.unsqueeze(0)
+        h = self.backbone(h, t_emb=t_emb, cond=spatial_cond)
+        v = self.out_proj(h).squeeze(-1)  # [B, L]
+        return v
+
+
+# =============================================================================
+# Level 2: Weekly Pattern Flow Matching
+# =============================================================================
+
+class WeeklyPatternFM(nn.Module):
+    """
+    Level 2: Weekly Pattern Flow Matching.
+
+    Learns to generate a weekly periodic pattern at hourly resolution:
+    weekly_pattern: 7 days × 24 hours = 168 time steps.
+
+    This level is conditioned on day-type templates from Level 1.
+    """
+
+    def __init__(self, spatial_dim: int = 192, hidden_dim: int = 256, steps_per_day: int = 24):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.hidden_dim = hidden_dim
+        self.steps_per_day = steps_per_day
+        self.week_len = 7 * steps_per_day
+        self.daytype_len = 2 * steps_per_day
+
+        self.time_embed = FourierTimeEmbedding(hidden_dim)
+
+        self.in_proj = nn.Linear(1, hidden_dim)
+        self.daily_token_proj = nn.Linear(1, hidden_dim)
+
+        self.daily_to_weekly_attn = nn.MultiheadAttention(
+            embed_dim=hidden_dim,
+            num_heads=8,
+            dropout=0.1,
+            batch_first=True,
+        )
+
+        self.backbone = HybridLongSequenceBackbone(
+            d_model=hidden_dim,
+            n_layers=3,
+            d_state=64,
+            use_mamba=True,
+            use_dilated_conv=True,
+            dilations=[1, 2, 4],
+            cond_dim=spatial_dim,
+            dropout=0.1,
+        )
+        self.out_proj = nn.Linear(hidden_dim, 1)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t: torch.Tensor,
+        daily_pattern: torch.Tensor,
+        spatial_cond: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Args:
+            x: [B, 168] weekly pattern
+            t: [B, 1] time step
+            daily_pattern: [B, 48] day-type templates (from Level 1)
+            spatial_cond: [B, spatial_dim] spatial context
+        Returns:
+            v: [B, 168] velocity field
+        """
+        B, Lw = x.shape
+        assert Lw == self.week_len, f"WeeklyPatternFM expects L={self.week_len}, got {Lw}"
+        Bd, Ld = daily_pattern.shape
+        assert Bd == B and Ld == self.daytype_len, (
+            f"WeeklyPatternFM expects daily_pattern [B,{self.daytype_len}], got {daily_pattern.shape}"
+        )
+
+        t_emb = self.time_embed(t)  # [B, D]
+
+        pos_w = sinusoidal_positional_embedding(Lw, self.hidden_dim, x.device, x.dtype)
+        pos_d = sinusoidal_positional_embedding(Ld, self.hidden_dim, x.device, x.dtype)
+
+        week_tokens = self.in_proj(x.unsqueeze(-1)) + pos_w.unsqueeze(0)  # [B, 168, D]
+        day_tokens = self.daily_token_proj(daily_pattern.unsqueeze(-1)) + pos_d.unsqueeze(0)  # [B, 48, D]
+
+        # Explicitly condition on S^d via cross-attention (decouples day/week)
+        attn_out, _ = self.daily_to_weekly_attn(week_tokens, day_tokens, day_tokens)
+        week_tokens = week_tokens + attn_out
+
+        h = self.backbone(week_tokens, t_emb=t_emb, cond=spatial_cond)
+        v = self.out_proj(h).squeeze(-1)  # [B, 168]
+        return v
+
+
+# =============================================================================
+# Level 3: Long-term Residual Flow Matching
+# =============================================================================
+
+class LongTermResidualFM(nn.Module):
+    """
+    Level 3: Long-term Residual Flow Matching.
+
+    Learns to generate fine residuals for the full sequence (672 time steps).
+    Uses Mamba + multi-scale dilated convolutions for efficient long-sequence modeling.
+
+    Explicitly conditioned on peak hour location to force peak generation.
+    """
+
+    def __init__(
+        self,
+        spatial_dim: int = 192,
+        hidden_dim: int = 256,
+        n_layers: int = 6,
+        steps_per_day: int = 24,
+    ):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.hidden_dim = hidden_dim
+        self.steps_per_day = steps_per_day
+        self.week_len = 7 * steps_per_day
+        self.daytype_len = 2 * steps_per_day
+
+        self.time_embed = FourierTimeEmbedding(hidden_dim)
+        
+        # Explicit Peak Position Encoding
+        # Maps 0-23 hours to a hidden vector to serve as a strong condition
+        self.peak_embed = nn.Embedding(24, hidden_dim)
+
+        # Token-wise projection of multi-channel inputs
+        self.in_proj = nn.Linear(4, hidden_dim)
+
+        # Main backbone (Mamba + multi-scale dilated conv) for long sequences
+        self.backbone = HybridLongSequenceBackbone(
+            d_model=hidden_dim,
+            n_layers=n_layers,
+            d_state=128,
+            use_mamba=True,
+            use_dilated_conv=True,
+            # (local, daily, weekly) receptive fields at hourly resolution
+            dilations=[1, 2, 4, 8, 16, 24, 48, 168],
+            cond_dim=spatial_dim,
+            dropout=0.1,
+        )
+        self.out_proj = nn.Linear(hidden_dim, 1)
+
+    def _repeat_to_length(self, pattern: torch.Tensor, target_len: int) -> torch.Tensor:
+        # pattern: [B, P]
+        B, P = pattern.shape
+        reps = (target_len + P - 1) // P
+        tiled = pattern.repeat(1, reps)
+        return tiled[:, :target_len]
+
+    def _repeat_daytype_to_length(self, daytype: torch.Tensor, target_len: int) -> torch.Tensor:
+        """
+        Expand day-type templates (weekday/weekend) to a full 28-day hourly sequence.
+
+        Assumption (consistent with plot_traffic_decomposition*.py): sequence starts on Monday.
+        """
+        B, L = daytype.shape
+        assert L == self.daytype_len, f"Expected daytype_len={self.daytype_len}, got {L}"
+        steps = self.steps_per_day
+        weekday = daytype[:, :steps]
+        weekend = daytype[:, steps:]
+
+        n_days = target_len // steps
+        parts = []
+        for d in range(n_days):
+            dow = d % 7
+            parts.append(weekday if dow < 5 else weekend)
+        seq = torch.cat(parts, dim=1)  # [B, n_days*steps]
+        if seq.shape[1] < target_len:
+            pad = torch.zeros(B, target_len - seq.shape[1], device=seq.device, dtype=seq.dtype)
+            seq = torch.cat([seq, pad], dim=1)
+        return seq[:, :target_len]
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t: torch.Tensor,
+        coarse_signal: torch.Tensor,
+        daily_pattern: torch.Tensor,
+        weekly_trend: torch.Tensor,
+        spatial_cond: torch.Tensor,
+        peak_hour: torch.Tensor,  
+    ) -> torch.Tensor:
+        """
+        Args:
+            x: [B, 672] residual sequence
+            t: [B, 1] time step
+            coarse_signal: [B, 672] periodic component (tiled weekly pattern)
+            daily_pattern: [B, 48] day-type templates
+            weekly_trend: [B, 168] weekly pattern
+            spatial_cond: [B, spatial_dim] spatial context
+            peak_hour: [B] Integer tensor (0-23) indicating explicit peak location
+        Returns:
+            v: [B, 672] velocity field
+        """
+        B, L = x.shape
+        assert coarse_signal.shape == (B, L)
+        assert daily_pattern.shape == (B, self.daytype_len)
+        assert weekly_trend.shape == (B, self.week_len)
+
+        # Fuse Time Embedding with Peak Embedding
+        t_emb = self.time_embed(t)  # [B, D]
+        peak_cond = self.peak_embed(peak_hour)  # [B, D]
+        
+        # Combine: Global time context + "Peak Attention" bias
+        global_cond = t_emb + peak_cond
+
+        pos = sinusoidal_positional_embedding(L, self.hidden_dim, x.device, x.dtype)
+
+        daily_rep = self._repeat_daytype_to_length(daily_pattern, L)  # [B, L]
+        # weekly_trend is weekly pattern here: tile 168 -> 672 (4 weeks)
+        weekly_rep = self._repeat_to_length(weekly_trend, L)  # [B, L]
+        weekly_delta = coarse_signal - daily_rep  # [B, L]
+
+        # Token features: [residual, periodic, repeated_daytype, weekly_delta]
+        feats = torch.stack([x, coarse_signal, daily_rep, weekly_delta], dim=-1)  # [B, L, 4]
+        h = self.in_proj(feats) + pos.unsqueeze(0)
+        
+        # Pass combined global condition
+        h = self.backbone(h, t_emb=global_cond, cond=spatial_cond)
+        
+        v = self.out_proj(h).squeeze(-1)  # [B, L]
+        return v
+
+
+# =============================================================================
+# Complete Hierarchical Flow Matching Model
+# =============================================================================
+
+class HierarchicalFlowMatchingV4(nn.Module):
+    """
+    Complete Hierarchical Flow Matching model with three-level cascaded architecture.
+
+    Level 1: Daily Pattern FM
+    Level 2: Weekly Pattern FM (with daily conditioning)
+    Level 3: Long-term Residual FM (with daily + weekly conditioning + explicit peak)
+    """
+
+    def __init__(
+        self,
+        spatial_dim: int = 192,
+        hidden_dim: int = 256,
+        n_layers_level3: int = 6,
+        steps_per_day: int = 24,
+    ):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.hidden_dim = hidden_dim
+        self.steps_per_day = steps_per_day
+        self.week_len = 7 * steps_per_day
+        self.daytype_len = 2 * steps_per_day
+        # This repo's 672-length traffic is hourly: 28 days = 4 weeks.
+        self.seq_len = 672
+        self.n_weeks = self.seq_len // self.week_len
+
+        # Three-level FM
+        self.level1_fm = DailyPatternFM(spatial_dim, hidden_dim, steps_per_day=steps_per_day)
+        self.level2_fm = WeeklyPatternFM(spatial_dim, hidden_dim, steps_per_day=steps_per_day)
+        self.level3_fm = LongTermResidualFM(
+            spatial_dim, hidden_dim, n_layers_level3, steps_per_day=steps_per_day
+        )
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        t: torch.Tensor,
+        spatial_cond: torch.Tensor,
+        level: int = 1,
+        daily_pattern: Optional[torch.Tensor] = None,
+        weekly_trend: Optional[torch.Tensor] = None,
+        coarse_signal: Optional[torch.Tensor] = None,
+        peak_hour: Optional[torch.Tensor] = None, 
+    ) -> torch.Tensor:
+        """
+        Forward pass for a specific level.
+        """
+        if level == 1:
+            return self.level1_fm(x, t, spatial_cond)
+
+        elif level == 2:
+            assert daily_pattern is not None, "daily_pattern required for level 2"
+            return self.level2_fm(x, t, daily_pattern, spatial_cond)
+
+        elif level == 3:
+            assert daily_pattern is not None, "daily_pattern required for level 3"
+            assert weekly_trend is not None, "weekly_trend required for level 3"
+            assert coarse_signal is not None, "coarse_signal required for level 3"
+            assert peak_hour is not None, "peak_hour required for level 3 (Explicit Peak Conditioning)"
+            return self.level3_fm(x, t, coarse_signal, daily_pattern, weekly_trend, spatial_cond, peak_hour)
+
+        else:
+            raise ValueError(f"Invalid level: {level}")
+
+    # =========================================================================
+    # Generation Methods (ODE Solve)
+    # =========================================================================
+
+    def _unpack_level_conditions(
+        self,
+        spatial_cond: torch.Tensor | Dict[str, torch.Tensor],
+    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        if isinstance(spatial_cond, dict):
+            return (
+                spatial_cond["level1_cond"],
+                spatial_cond["level2_cond"],
+                spatial_cond["level3_cond"],
+            )
+        return spatial_cond, spatial_cond, spatial_cond
+
+    def generate_daily_pattern(
+        self,
+        spatial_cond: torch.Tensor | Dict[str, torch.Tensor],
+        n_steps: int = 50,
+    ) -> torch.Tensor:
+        """
+        Generate day-type templates (Level 1).
+        """
+        spatial_cond_level1, _, _ = self._unpack_level_conditions(spatial_cond)
+        B = spatial_cond_level1.shape[0]
+        device = spatial_cond_level1.device
+
+        x = torch.randn(B, self.daytype_len, device=device)
+        dt = 1.0 / n_steps
+
+        for step in range(n_steps):
+            t = torch.full((B, 1), step / n_steps, device=device)
+            v = self.level1_fm(x, t, spatial_cond_level1)
+            v = torch.clamp(v, -10.0, 10.0)
+            x = x + dt * v
+            x = torch.clamp(x, -10.0, 10.0)
+
+        return x
+
+    def generate_weekly_trend(
+        self,
+        daily_pattern: torch.Tensor,
+        spatial_cond: torch.Tensor | Dict[str, torch.Tensor],
+        n_steps: int = 50,
+    ) -> torch.Tensor:
+        """
+        Generate weekly pattern (Level 2).
+        """
+        _, spatial_cond_level2, _ = self._unpack_level_conditions(spatial_cond)
+        B = spatial_cond_level2.shape[0]
+        device = spatial_cond_level2.device
+
+        x = torch.randn(B, self.week_len, device=device)
+        dt = 1.0 / n_steps
+
+        for step in range(n_steps):
+            t = torch.full((B, 1), step / n_steps, device=device)
+            v = self.level2_fm(x, t, daily_pattern, spatial_cond_level2)
+            v = torch.clamp(v, -10.0, 10.0)
+            x = x + dt * v
+            x = torch.clamp(x, -10.0, 10.0)
+
+        return x
+
+    def generate_residual(
+        self,
+        coarse_signal: torch.Tensor,
+        daily_pattern: torch.Tensor,
+        weekly_trend: torch.Tensor,
+        spatial_cond: torch.Tensor | Dict[str, torch.Tensor],
+        peak_hour: torch.Tensor,  
+        n_steps: int = 50,
+    ) -> torch.Tensor:
+        """
+        Generate fine residual (Level 3).
+        Requires peak_hour for explicit conditioning.
+        """
+        _, _, spatial_cond_level3 = self._unpack_level_conditions(spatial_cond)
+        B = spatial_cond_level3.shape[0]
+        device = spatial_cond_level3.device
+
+        x = 0.1 * torch.randn_like(coarse_signal, device=device)
+        dt = 1.0 / n_steps
+
+        for step in range(n_steps):
+            t = torch.full((B, 1), step / n_steps, device=device)
+            # Pass peak_hour
+            v = self.level3_fm(
+                x, t, coarse_signal, daily_pattern, weekly_trend, spatial_cond_level3, peak_hour
+            )
+            v = torch.clamp(v, -5.0, 5.0)
+            x = x + dt * v
+            x = torch.clamp(x, -5.0, 5.0)
+
+        return x
+
+    def generate_hierarchical(
+        self,
+        spatial_cond: torch.Tensor | Dict[str, torch.Tensor],
+        peak_hour: torch.Tensor, # Required input
+        n_steps_per_level: int = 50,
+    ) -> Tuple[torch.Tensor, Dict]:
+        """
+        Full hierarchical generation.
+        """
+        spatial_cond_level1, spatial_cond_level2, spatial_cond_level3 = self._unpack_level_conditions(
+            spatial_cond
+        )
+        B = spatial_cond_level3.shape[0]
+        device = spatial_cond_level3.device
+
+        # Level 1: Generate day-type templates
+        daily_pattern = self.generate_daily_pattern(spatial_cond_level1, n_steps_per_level)
+        daily_pattern = torch.clamp(daily_pattern, -10.0, 10.0)
+
+        # Level 2: Generate weekly pattern (168 hours)
+        weekly_pattern = self.generate_weekly_trend(
+            daily_pattern, spatial_cond_level2, n_steps_per_level
+        )
+        weekly_pattern = torch.clamp(weekly_pattern, -10.0, 10.0)
+
+        # Construct periodic component for 4 weeks (672 hours)
+        coarse_signal = weekly_pattern.repeat(1, self.n_weeks)  # [B, 672]
+        coarse_signal = torch.clamp(coarse_signal, -10.0, 10.0)
+
+        # Level 3: Generate fine residual
+        # Pass peak_hour to residual generator
+        residual = self.generate_residual(
+            coarse_signal,
+            daily_pattern,
+            weekly_pattern,
+            spatial_cond_level3,
+            peak_hour=peak_hour, 
+            n_steps=n_steps_per_level,
+        )
+        residual = torch.clamp(residual, -5.0, 5.0)
+
+        # Final output
+        generated = coarse_signal + residual
+        
+        # =========================================================================
+        # [MODIFIED] Physical Constraint: Enforce non-negative traffic
+        # Previously was: generated = torch.clamp(generated, -10.0, 10.0)
+        # =========================================================================
+        generated = torch.clamp(generated, min=0.0, max=10.0) 
+
+        intermediates = {
+            'daily_pattern': daily_pattern,
+            'weekly_pattern': weekly_pattern,
+            'coarse_signal': coarse_signal,
+            'residual': residual,
+        }
+
+        return generated, intermediates

index.html

@@ -0,0 +1,147 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Perception Layer - Data Alignment</title>
+    
+    <script src="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.js"></script>
+    <link href="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css" rel="stylesheet" />
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    
+    <link rel="stylesheet" href="style.css">
+</head>
+<body>
+
+    <div id="loading" class="loading-overlay">
+        <div class="spinner"></div>
+        <h2>SYSTEM INITIALIZING</h2>
+        <p>Loading Spatial & Temporal Data...</p>
+    </div>
+
+    <div class="sidebar">
+        <div class="header">
+            <h1>Overall</h1>
+            
+            <div class="search-section">
+                <div class="search-container">
+                    <input type="text" id="search-input" placeholder="Search ID..." autocomplete="off">
+                    <button id="search-btn" class="cyber-btn-small">GO</button>
+                    <button id="clear-search-btn" class="cyber-btn-small" title="Clear Markers">✕</button>
+                </div>
+                
+                <div class="search-mode">
+                    <input type="checkbox" id="keep-markers-check" checked>
+                    <label for="keep-markers-check">Keep Previous Markers</label>
+                </div>
+            </div>
+        </div>
+
+        <div class="card">
+            <h2>📈 Temporal Modality</h2>
+            <div class="chart-container">
+                <canvas id="energyChart"></canvas>
+            </div>
+        </div>
+        
+        <div class="card details-card">
+            <h2>📍 Spatial Metadata</h2>
+            <div class="stat-row">
+                <div><span class="label">Station ID</span> <span id="selected-id" class="value highlight">--</span></div>
+                <div><span class="label">Total Nodes</span> <span id="total-stations" class="value">--</span></div>
+            </div>
+            <div id="station-details" class="details-content">
+                <p class="placeholder-text">Waiting for selection...</p>
+            </div>
+        </div>
+    </div>
+
+    <div id="prediction-panel" class="sidebar-right">
+        <div class="header">
+            <h1>Traffic Prediction</h1>
+            <button id="close-pred-btn" class="cyber-btn-small">✕</button>
+        </div>
+        <div class="details-content">
+            <div class="stat-row" style="margin-bottom: 20px;">
+                <div><span class="label">Target Station ID</span> <span id="pred-station-id" class="value highlight" style="color: #f39c12;">--</span></div>
+            </div>
+            
+            <div class="chart-container" style="height: 250px; position: relative;">
+                <canvas id="predictionChart"></canvas>
+            </div>
+
+            <!-- <div class="legend-box" style="margin-top: 20px; font-size: 0.9em; padding: 10px; background: rgba(0,0,0,0.3); border-radius: 4px;">
+                <div style="display:flex; align-items:center; margin-bottom:8px;">
+                    <span style="display:inline-block; width:12px; height:12px; background:#00cec9; margin-right:10px; border-radius:50%;"></span>
+                    <span>Real Data (Observed)</span>
+                </div>
+                <div style="display:flex; align-items:center;">
+                    <span style="display:inline-block; width:12px; height:12px; background:#f39c12; margin-right:10px; border-radius:50%;"></span>
+                    <span>AI Prediction (Model + POI)</span>
+                </div>
+            </div> -->
+
+            <div id="site-map-container" style="margin-top: 20px; display: none; border-top: 1px solid rgba(243, 156, 18, 0.3); padding-top: 15px;">
+                <h3 style="font-size: 13px; color: #f39c12; margin-bottom: 10px; text-transform: uppercase; letter-spacing: 1px;">
+                    <span class="icon">📍</span> Optimal Site Analysis
+                </h3>
+                
+                <div style="background: rgba(0,0,0,0.5); padding: 10px; border-radius: 6px; border: 1px solid rgba(255,255,255,0.05); display: flex; justify-content: center; align-items: center;">
+                    <img id="site-map-img" src="" alt="LSI Site Map" style="width: 75%; border-radius: 4px; box-shadow: 0 0 10px rgba(0,0,0,0.5); display: block;">
+                </div>
+                
+                <div id="site-explanation" class="cyber-explanation" style="display: none;"></div>
+                
+                <p style="font-size: 0.7em; color: #aaa; margin-top: 8px; line-height: 1.4;">
+                    * Heatmap calculated via spatial windowing.<br>
+                    <span style="color:#2ecc71;">Green = High LSI (Stable)</span> | <span style="color:#e74c3c;">Red = High Volatility</span>
+                </p>
+            </div>
+
+            <p style="font-size: 0.75em; color: #666; margin-top: 20px; line-height: 1.4; border-top: 1px solid #333; padding-top: 10px;">
+                * Powered by <strong>Hierarchical Flow Matching V4</strong>.<br>
+                Utilizes Multi-modal Spatial Embeddings (POI, Satellite, Coordinates) for context-aware traffic forecasting.
+            </p>
+        </div>
+    </div>
+
+    <button id="toggle-left-btn" class="panel-toggle-btn left-toggle">◀</button>
+    <button id="toggle-right-btn" class="panel-toggle-btn right-toggle">▶</button>
+    <div class="main-content">
+        <div class="controls-container">
+            <button id="view-toggle" class="cyber-btn">
+                <span class="icon">👁️</span> View: 3D
+            </button>
+            <button id="data-toggle" class="cyber-btn">
+                <span class="icon">📡</span> Toggle Data
+            </button>
+            
+            <button id="predict-toggle" class="cyber-btn" style="border-color: #f39c12; color: #f39c12;">
+                <span class="icon">🔮</span> Prediction Mode
+            </button>
+
+            <div class="filter-wrapper">
+                <button id="filter-btn" class="cyber-btn">
+                    <span class="icon">🌪️</span> Filter Volatility
+                </button>
+                <div id="filter-menu" class="filter-menu"></div>
+            </div>
+        </div>
+
+        <div class="time-panel">
+            <button id="play-btn" class="cyber-btn play-control">▶</button>
+            <div class="slider-wrapper">
+                <input type="range" id="time-slider" min="0" max="671" value="0" step="1">
+                <div class="slider-ticks">
+                    <span>Day 1</span><span>Day 7</span><span>Day 14</span><span>Day 21</span><span>Day 28</span>
+                </div>
+            </div>
+            <div id="time-display" class="digital-clock" style="min-width: 170px;">Day 01 - 00:00</div>
+        </div>
+
+        <div id="map"></div>
+    </div>
+
+    <script src="script.js"></script>
+</body>
+</html>

multimodal_spatial_encoder_v4.py

@@ -0,0 +1,645 @@
+"""
+Multi-Modal Spatial Context Encoder (V4)
+=========================================
+
+Fuses POI features and satellite imagery into a unified spatial context embedding.
+
+Key components:
+1. POI Encoder: MLP with learnable category importance weights
+2. Satellite Image Encoder: ResNet-18 with multi-scale features
+3. Coordinate Encoder: Fourier features with learnable frequencies
+4. Fusion Strategy: Cross-attention + adaptive gating
+5. Condition Injection: FiLM/AdaGN modulation
+6. [NEW] Auxiliary Head: Peak Hour Classification (Explicit Peak Prediction)
+
+Author: Optimization Team
+Date: 2026-01-21
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import numpy as np
+from typing import Dict, Optional
+
+
+# =============================================================================
+# POI Encoder with Learnable Importance Weights
+# =============================================================================
+
+class POIEncoder(nn.Module):
+    """
+    POI encoder with learnable category importance weights.
+
+    Input: POI count/density vector [B, poi_dim]
+    Output: POI embedding [B, spatial_dim]
+    """
+
+    def __init__(self, poi_dim: int = 20, spatial_dim: int = 192):
+        super().__init__()
+        self.poi_dim = poi_dim
+        self.spatial_dim = spatial_dim
+
+        # Learnable category importance weights
+        self.category_importance = nn.Parameter(torch.ones(poi_dim))
+
+        # Category token embeddings (POI-Enhancer inspired: attention-weighted semantic fusion)
+        self.category_embed = nn.Embedding(poi_dim, spatial_dim)
+
+        # Deep encoder with residual connections
+        self.encoder = nn.Sequential(
+            nn.Linear(poi_dim, 256),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(256, 256),
+            nn.GELU(),
+            nn.LayerNorm(256),
+            nn.Linear(256, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+        # Attention pooling over category tokens
+        self.token_attn = nn.Sequential(
+            nn.Linear(spatial_dim, 128),
+            nn.GELU(),
+            nn.Linear(128, 1),
+        )
+
+        # Gate between MLP vector and token-pooled vector
+        self.fuse_gate = nn.Sequential(
+            nn.Linear(spatial_dim * 2, 1),
+            nn.Sigmoid(),
+        )
+
+    def forward(self, poi_dist: torch.Tensor, return_tokens: bool = False):
+        """
+        Args:
+            poi_dist: [B, poi_dim] POI distribution
+        Returns:
+            features: [B, spatial_dim] POI embedding
+        """
+        # Apply learnable importance weights
+        weights = F.softmax(self.category_importance, dim=0)
+        weighted_poi = poi_dist * weights
+
+        # Log transform for count data (handles skewed distributions)
+        poi_log = torch.log1p(weighted_poi)
+
+        # (1) Global vector via MLP
+        features_mlp = self.encoder(poi_log)
+
+        # (2) Category tokens + attention pooling (attention score-weighted merging)
+        # token_scale: [B, poi_dim, 1]
+        token_scale = poi_log.unsqueeze(-1)
+        # tokens: [B, poi_dim, D]
+        tokens = token_scale * self.category_embed.weight.unsqueeze(0)
+        attn_logits = self.token_attn(tokens).squeeze(-1)  # [B, poi_dim]
+        attn = F.softmax(attn_logits, dim=-1).unsqueeze(-1)  # [B, poi_dim, 1]
+        features_tok = (tokens * attn).sum(dim=1)  # [B, D]
+
+        # Combine (learned trade-off)
+        g = self.fuse_gate(torch.cat([features_mlp, features_tok], dim=-1))  # [B, 1]
+        features = g * features_mlp + (1.0 - g) * features_tok
+
+        if return_tokens:
+            return features, tokens
+        return features
+
+
+# =============================================================================
+# Satellite Image Encoder (ResNet-18 backbone)
+# =============================================================================
+
+class ResidualBlock(nn.Module):
+    """Basic residual block for ResNet."""
+
+    def __init__(self, in_channels: int, out_channels: int, stride: int = 1):
+        super().__init__()
+        self.conv1 = nn.Conv2d(in_channels, out_channels, 3, stride=stride, padding=1)
+        self.bn1 = nn.BatchNorm2d(out_channels)
+        self.relu = nn.ReLU(inplace=True)
+        self.conv2 = nn.Conv2d(out_channels, out_channels, 3, padding=1)
+        self.bn2 = nn.BatchNorm2d(out_channels)
+
+        self.stride = stride
+        if stride != 1 or in_channels != out_channels:
+            self.shortcut = nn.Sequential(
+                nn.Conv2d(in_channels, out_channels, 1, stride=stride),
+                nn.BatchNorm2d(out_channels),
+            )
+        else:
+            self.shortcut = None
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        identity = x
+        out = self.conv1(x)
+        out = self.bn1(out)
+        out = self.relu(out)
+
+        out = self.conv2(out)
+        out = self.bn2(out)
+
+        if self.shortcut is not None:
+            identity = self.shortcut(x)
+
+        out = out + identity
+        out = self.relu(out)
+        return out
+
+
+class SatelliteImageEncoder(nn.Module):
+    """
+    ResNet-18-based satellite image encoder with multi-scale feature extraction.
+
+    Input: Satellite image [B, 3, 64, 64]
+    Output: Image embedding [B, spatial_dim]
+    """
+
+    def __init__(self, spatial_dim: int = 192, n_heads: int = 8, token_layers: int = 2):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+
+        # Initial layer
+        self.conv1 = nn.Sequential(
+            nn.Conv2d(3, 64, 7, stride=2, padding=3),
+            nn.BatchNorm2d(64),
+            nn.ReLU(inplace=True),
+            nn.MaxPool2d(3, stride=2, padding=1),
+        )
+
+        # ResNet blocks
+        self.layer1 = self._make_layer(64, 64, 2, stride=1)
+        self.layer2 = self._make_layer(64, 128, 2, stride=2)
+        self.layer3 = self._make_layer(128, 256, 2, stride=2)
+        self.layer4 = self._make_layer(256, 512, 2, stride=2)
+
+        # Multi-scale feature aggregation
+        self.pool1 = nn.AdaptiveAvgPool2d(1)
+        self.pool2 = nn.AdaptiveAvgPool2d(1)
+        self.pool3 = nn.AdaptiveAvgPool2d(1)
+        self.pool4 = nn.AdaptiveAvgPool2d(1)
+
+        # Learnable scale weights
+        self.scale_weights = nn.Parameter(torch.tensor([1.0, 1.0, 1.0, 1.0]))
+
+        # Final projection
+        self.proj = nn.Sequential(
+            nn.Linear(64 + 128 + 256 + 512, 384),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(384, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+        # Region-level tokens (RemoteCLIP-inspired: patch/region awareness)
+        self.token_proj3 = nn.Linear(256, spatial_dim)
+        self.token_proj4 = nn.Linear(512, spatial_dim)
+        self.img_cls = nn.Parameter(torch.zeros(1, 1, spatial_dim))
+        enc_layer = nn.TransformerEncoderLayer(
+            d_model=spatial_dim,
+            nhead=n_heads,
+            dim_feedforward=spatial_dim * 4,
+            dropout=0.1,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.token_mixer = nn.TransformerEncoder(enc_layer, num_layers=int(token_layers))
+
+    def _make_layer(self, in_channels: int, out_channels: int, blocks: int, stride: int):
+        layers = []
+        layers.append(ResidualBlock(in_channels, out_channels, stride))
+        for _ in range(1, blocks):
+            layers.append(ResidualBlock(out_channels, out_channels, 1))
+        return nn.Sequential(*layers)
+
+    def forward(self, x: torch.Tensor, return_tokens: bool = False):
+        """
+        Args:
+            x: [B, 3, 64, 64] satellite image
+        Returns:
+            features: [B, spatial_dim] image embedding
+        """
+        x = self.conv1(x)  # [B, 64, 16, 16]
+
+        x1 = self.layer1(x)  # [B, 64, 16, 16]
+        x2 = self.layer2(x1)  # [B, 128, 8, 8]
+        x3 = self.layer3(x2)  # [B, 256, 4, 4]
+        x4 = self.layer4(x3)  # [B, 512, 2, 2]
+
+        # Multi-scale pooling
+        f1 = self.pool1(x1).flatten(1)  # [B, 64]
+        f2 = self.pool2(x2).flatten(1)  # [B, 128]
+        f3 = self.pool3(x3).flatten(1)  # [B, 256]
+        f4 = self.pool4(x4).flatten(1)  # [B, 512]
+
+        # Weighted fusion
+        weights = F.softmax(self.scale_weights, dim=0)
+        fused = torch.cat([
+            f1 * weights[0],
+            f2 * weights[1],
+            f3 * weights[2],
+            f4 * weights[3],
+        ], dim=-1)
+
+        # Final projection
+        features = self.proj(fused)
+
+        if not return_tokens:
+            return features
+
+        # Build region tokens from intermediate feature maps (4x4 + 2x2 = 20 tokens)
+        t3 = x3.flatten(2).transpose(1, 2)  # [B, 16, 256]
+        t4 = x4.flatten(2).transpose(1, 2)  # [B, 4, 512]
+        t3 = self.token_proj3(t3)  # [B, 16, D]
+        t4 = self.token_proj4(t4)  # [B, 4, D]
+        tokens = torch.cat([t3, t4], dim=1)  # [B, 20, D]
+
+        # Mix tokens with a tiny Transformer, include a [CLS] token
+        cls = self.img_cls.expand(tokens.shape[0], -1, -1)
+        tokens_with_cls = torch.cat([cls, tokens], dim=1)  # [B, 21, D]
+        tokens_with_cls = self.token_mixer(tokens_with_cls)
+
+        # tokens_with_cls[:, 0] is CLS; keep both CLS and spatial tokens
+        cls_out = tokens_with_cls[:, 0]  # [B, D]
+        spatial_tokens = tokens_with_cls[:, 1:]  # [B, 20, D]
+
+        # Blend CLS with pooled global feature for stability
+        feat = 0.5 * features + 0.5 * cls_out
+        return feat, spatial_tokens
+
+
+# =============================================================================
+# Coordinate Encoder with Learnable Fourier Features
+# =============================================================================
+
+class CoordinateEncoder(nn.Module):
+    """
+    Coordinate encoder with learnable Fourier frequencies.
+
+    Input: Coordinates [B, 2] (latitude, longitude)
+    Output: Coordinate embedding [B, spatial_dim]
+    """
+
+    def __init__(self, coord_dim: int = 2, spatial_dim: int = 192):
+        super().__init__()
+        self.coord_dim = coord_dim
+        self.spatial_dim = spatial_dim
+
+        # Multi-scale learnable Fourier frequencies
+        n_freqs = 64
+        init_freqs = 2 ** torch.linspace(0, 8, n_freqs)
+        self.freqs = nn.Parameter(init_freqs)
+
+        fourier_dim = coord_dim * n_freqs * 2
+
+        # Deep encoder
+        self.encoder = nn.Sequential(
+            nn.Linear(fourier_dim + coord_dim, 512),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(512, 384),
+            nn.GELU(),
+            nn.LayerNorm(384),
+            nn.Linear(384, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+    def forward(self, coords: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            coords: [B, 2] coordinates
+        Returns:
+            features: [B, spatial_dim] coordinate embedding
+        """
+        # Fourier features with learnable frequencies
+        coords_scaled = coords.unsqueeze(-1) * self.freqs  # [B, 2, n_freqs]
+        fourier = torch.cat([
+            torch.sin(coords_scaled * np.pi),
+            torch.cos(coords_scaled * np.pi),
+        ], dim=-1).flatten(-2)  # [B, fourier_dim]
+
+        # Combine with raw coordinates
+        combined = torch.cat([coords, fourier], dim=-1)
+
+        # Encode
+        features = self.encoder(combined)
+
+        return features
+
+
+# =============================================================================
+# Cross-Attention Fusion Module
+# =============================================================================
+
+class CrossAttentionFusion(nn.Module):
+    """
+    Cross-attention fusion for multi-modal conditioning.
+
+    Fuses POI, satellite, and coordinate embeddings via multi-head attention.
+    """
+
+    def __init__(self, spatial_dim: int = 192, n_heads: int = 8):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.n_heads = n_heads
+
+        # Two rounds of cross-attention (vector mode: 3 tokens; token mode: CLS->context)
+        self.cross_attn1 = nn.MultiheadAttention(
+            spatial_dim, num_heads=n_heads, dropout=0.1, batch_first=True
+        )
+        self.cross_attn2 = nn.MultiheadAttention(
+            spatial_dim, num_heads=n_heads, dropout=0.1, batch_first=True
+        )
+
+        # Layer norms
+        self.norm1 = nn.LayerNorm(spatial_dim)
+        self.norm2 = nn.LayerNorm(spatial_dim)
+        self.norm3 = nn.LayerNorm(spatial_dim)
+        self.norm4 = nn.LayerNorm(spatial_dim)
+
+        # Feed-forward networks
+        self.ffn1 = nn.Sequential(
+            nn.Linear(spatial_dim, spatial_dim * 4),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(spatial_dim * 4, spatial_dim),
+        )
+        self.ffn2 = nn.Sequential(
+            nn.Linear(spatial_dim, spatial_dim * 4),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(spatial_dim * 4, spatial_dim),
+        )
+
+        # Adaptive gating for modality importance
+        self.gate = nn.Sequential(
+            nn.Linear(spatial_dim * 3, 256),
+            nn.GELU(),
+            nn.Linear(256, 3),
+            nn.Softmax(dim=-1),
+        )
+
+        # Token-mode: learnable fusion token
+        self.fusion_cls = nn.Parameter(torch.zeros(1, 1, spatial_dim))
+        self.token_out_gate = nn.Sequential(
+            nn.Linear(spatial_dim * 2, 1),
+            nn.Sigmoid(),
+        )
+
+    def forward(
+        self,
+        sat_feat: torch.Tensor,
+        poi_feat: torch.Tensor,
+        coord_feat: torch.Tensor,
+        sat_tokens: Optional[torch.Tensor] = None,
+        poi_tokens: Optional[torch.Tensor] = None,
+        coord_token: Optional[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        """
+        Args:
+            sat_feat: [B, spatial_dim] satellite embedding
+            poi_feat: [B, spatial_dim] POI embedding
+            coord_feat: [B, spatial_dim] coordinate embedding
+        Returns:
+            fused: [B, spatial_dim] fused embedding
+        """
+        # ---------------------------------------------------------------------
+        # (A) Vector mode (backward-compatible): treat each modality as 1 token.
+        # ---------------------------------------------------------------------
+        if sat_tokens is None and poi_tokens is None and coord_token is None:
+            # Stack as sequence [B, 3, D]
+            modalities = torch.stack([sat_feat, poi_feat, coord_feat], dim=1)
+
+            # First round of cross-attention
+            attn_out1, _ = self.cross_attn1(modalities, modalities, modalities)
+            modalities = self.norm1(modalities + attn_out1)
+            ffn_out1 = self.ffn1(modalities)
+            modalities = self.norm2(modalities + ffn_out1)
+
+            # Second round
+            attn_out2, _ = self.cross_attn2(modalities, modalities, modalities)
+            modalities = self.norm3(modalities + attn_out2)
+            ffn_out2 = self.ffn2(modalities)
+            modalities = self.norm4(modalities + ffn_out2)
+
+            # Unpack
+            sat_out, poi_out, coord_out = modalities.unbind(dim=1)
+
+            # Adaptive gating
+            concat = torch.cat([sat_out, poi_out, coord_out], dim=-1)
+            weights = self.gate(concat)  # [B, 3]
+
+            # Weighted fusion
+            fused = (
+                weights[:, 0:1] * sat_out +
+                weights[:, 1:2] * poi_out +
+                weights[:, 2:3] * coord_out
+            )
+
+            return fused
+
+        # ---------------------------------------------------------------------
+        # (B) Token mode: CLS attends over (sat tokens + poi tokens + coord token).
+        # RemoteCLIP-inspired region tokens + POI-Enhancer-inspired semantic tokens.
+        # ---------------------------------------------------------------------
+        B = sat_feat.shape[0]
+        context = []
+        if sat_tokens is not None:
+            context.append(sat_tokens)
+        else:
+            context.append(sat_feat.unsqueeze(1))
+
+        if poi_tokens is not None:
+            context.append(poi_tokens)
+        else:
+            context.append(poi_feat.unsqueeze(1))
+
+        if coord_token is not None:
+            context.append(coord_token.unsqueeze(1))
+        else:
+            context.append(coord_feat.unsqueeze(1))
+
+        context_tokens = torch.cat(context, dim=1)  # [B, L, D]
+        cls = self.fusion_cls.expand(B, -1, -1)  # [B, 1, D]
+
+        # Two rounds of CLS->context attention + FFN (Transformer-like)
+        attn1, _ = self.cross_attn1(cls, context_tokens, context_tokens)
+        cls = self.norm1(cls + attn1)
+        cls = self.norm2(cls + self.ffn1(cls))
+
+        attn2, _ = self.cross_attn2(cls, context_tokens, context_tokens)
+        cls = self.norm3(cls + attn2)
+        cls = self.norm4(cls + self.ffn2(cls))
+
+        cls_vec = cls.squeeze(1)  # [B, D]
+
+        # Keep the original adaptive gating as a global shortcut, then learn to mix.
+        concat = torch.cat([sat_feat, poi_feat, coord_feat], dim=-1)
+        weights = self.gate(concat)
+        gated = (
+            weights[:, 0:1] * sat_feat +
+            weights[:, 1:2] * poi_feat +
+            weights[:, 2:3] * coord_feat
+        )
+        mix = self.token_out_gate(torch.cat([cls_vec, gated], dim=-1))  # [B, 1]
+        fused = mix * cls_vec + (1.0 - mix) * gated
+        return fused
+
+
+# =============================================================================
+# Multi-Scale Condition Generator
+# =============================================================================
+
+class MultiScaleConditionGenerator(nn.Module):
+    """
+    Generate stage-specific multi-scale conditions.
+
+    Produces different condition embeddings for each hierarchical level.
+    """
+
+    def __init__(self, spatial_dim: int = 192):
+        super().__init__()
+
+        # Level 1 (daily): global patterns
+        self.level1_proj = nn.Sequential(
+            nn.Linear(spatial_dim, 256),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(256, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+        # Level 2 (weekly): periodic structure
+        self.level2_proj = nn.Sequential(
+            nn.Linear(spatial_dim, 256),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(256, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+        # Level 3 (residual): fine details
+        self.level3_proj = nn.Sequential(
+            nn.Linear(spatial_dim, 384),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(384, spatial_dim),
+            nn.LayerNorm(spatial_dim),
+        )
+
+    def forward(self, base_condition: torch.Tensor) -> Dict[str, torch.Tensor]:
+        """Generate stage-specific conditions."""
+        return {
+            'level1_cond': self.level1_proj(base_condition),
+            'level2_cond': self.level2_proj(base_condition),
+            'level3_cond': self.level3_proj(base_condition),
+        }
+
+
+# =============================================================================
+# Complete Multi-Modal Spatial Encoder
+# =============================================================================
+
+class MultiModalSpatialEncoderV4(nn.Module):
+    """
+    Complete multi-modal spatial encoder combining:
+    - POI features
+    - Satellite imagery
+    - Geographic coordinates
+    - Cross-attention fusion
+    - Multi-scale condition generation
+    - [NEW] Auxiliary Peak Hour Classification
+    """
+
+    def __init__(self, spatial_dim: int = 192, poi_dim: int = 20):
+        super().__init__()
+        self.spatial_dim = spatial_dim
+        self.poi_dim = poi_dim
+
+        # Individual encoders
+        self.poi_encoder = POIEncoder(poi_dim, spatial_dim)
+        self.satellite_encoder = SatelliteImageEncoder(spatial_dim)
+        self.coord_encoder = CoordinateEncoder(2, spatial_dim)
+
+        # Multi-modal fusion
+        self.fusion = CrossAttentionFusion(spatial_dim, n_heads=8)
+
+        # Multi-scale condition generation
+        self.multiscale_generator = MultiScaleConditionGenerator(spatial_dim)
+        
+        # [NEW] Auxiliary Head: Peak Hour Prediction
+        # Predicts which hour (0-23) has the maximum traffic
+        self.peak_hour_classifier = nn.Sequential(
+            nn.Linear(spatial_dim, 128),
+            nn.GELU(),
+            nn.Dropout(0.1),
+            nn.Linear(128, 24)  # 24 hours classification
+        )
+
+    def forward(self, batch: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
+        """
+        Args:
+            batch: dict with keys:
+                - 'satellite_img': [B, 3, 64, 64]
+                - 'poi_dist': [B, poi_dim]
+                - 'coords': [B, 2]
+        Returns:
+            outputs: dict with conditions and predicted peak logits
+        """
+        # Encode each modality (token-aware for stronger multi-modal fusion)
+        sat_feat, sat_tokens = self.satellite_encoder(batch['satellite_img'], return_tokens=True)
+        poi_feat, poi_tokens = self.poi_encoder(batch['poi_dist'], return_tokens=True)
+        coord_feat = self.coord_encoder(batch['coords'])
+
+        # Fuse modalities (CLS attends to region tokens + semantic tokens)
+        base_condition = self.fusion(
+            sat_feat,
+            poi_feat,
+            coord_feat,
+            sat_tokens=sat_tokens,
+            poi_tokens=poi_tokens,
+            coord_token=coord_feat,
+        )
+
+        # Generate multi-scale conditions
+        stage_conditions = self.multiscale_generator(base_condition)
+        
+        # [NEW] Predict peak hour
+        pred_peak_logits = self.peak_hour_classifier(base_condition)
+
+        outputs = {
+            'base_condition': base_condition,
+            'pred_peak_logits': pred_peak_logits, # Auxiliary output
+            **stage_conditions,
+        }
+
+        return outputs
+
+
+if __name__ == "__main__":
+    # Test the encoder
+    B = 4
+    spatial_dim = 192
+    poi_dim = 20
+
+    encoder = MultiModalSpatialEncoderV4(spatial_dim, poi_dim)
+
+    # Create dummy batch
+    batch = {
+        'satellite_img': torch.randn(B, 3, 64, 64),
+        'poi_dist': torch.randn(B, poi_dim),
+        'coords': torch.randn(B, 2),
+    }
+
+    # Forward pass
+    outputs = encoder(batch)
+
+    print("Multi-Modal Spatial Encoder V4 Test:")
+    print(f"  Base condition shape: {outputs['base_condition'].shape}")
+    print(f"  Peak Logits shape: {outputs['pred_peak_logits'].shape}")
+    print(f"  Level 1 condition shape: {outputs['level1_cond'].shape}")
+    print(f"  Level 2 condition shape: {outputs['level2_cond'].shape}")
+    print(f"  Level 3 condition shape: {outputs['level3_cond'].shape}")
+
+    print("\nEncoder test passed!")

prediction_backend.py

@@ -0,0 +1,359 @@
+import os
+import torch
+import math
+import numpy as np
+import requests
+import random
+import base64
+import matplotlib
+matplotlib.use('Agg') 
+import matplotlib.pyplot as plt
+from matplotlib.backends.backend_agg import FigureCanvasAgg
+from io import BytesIO
+from PIL import Image
+
+# Import V4 Model System 
+from hierarchical_flow_matching_training_v4 import HierarchicalFlowMatchingSystemV4
+
+# =============================================================================
+# Config
+# =============================================================================
+MAPBOX_ACCESS_TOKEN = "pk.eyJ1IjoieXlhaXl5IiwiYSI6ImNtaTVpMTVlaTJmdzMybW9zcmFieGxpdHUifQ.181d6E5fzLw1CEZMEPU53Q" 
+MAPBOX_ZOOM = 15  
+FETCH_SIZE = 256  
+IMAGE_SIZE = 64   
+SEED = 42
+
+SPATIAL_DIM = 192
+HIDDEN_DIM = 256
+POI_DIM = 20
+N_LAYERS_LEVEL3 = 6
+N_STEPS = 50      
+
+
+class MapboxSatelliteFetcher:
+    """
+    Dynamically fetches satellite imagery, strictly aligning with 
+    the image preprocessing logic used during training.
+    """
+    def __init__(self, access_token=MAPBOX_ACCESS_TOKEN, zoom=MAPBOX_ZOOM, fetch_size=FETCH_SIZE, target_size=IMAGE_SIZE):
+        self.access_token = access_token
+        self.zoom = zoom
+        self.fetch_size = fetch_size
+        self.target_size = target_size
+
+    def fetch(self, lon, lat, station_id=None, return_pil=False): 
+        """ Fetches static satellite map centered at [lon, lat] """
+        url = f"https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/{lon},{lat},{self.zoom},0,0/{self.fetch_size}x{self.fetch_size}?access_token={self.access_token}"
+        try:
+            response = requests.get(url, timeout=10)
+            response.raise_for_status()
+            
+            img = Image.open(BytesIO(response.content)).convert("RGB")
+            original_pil = img.copy() # Store high-res original for micro-grid slicing
+            
+            # Resize to model input size (64x64)
+            img_resized = img.resize((self.target_size, self.target_size), Image.BILINEAR)
+            arr = np.asarray(img_resized, dtype=np.float32) / 255.0
+            
+            # Convert HWC to CHW format
+            chw = arr.transpose(2, 0, 1)
+            tensor_np = np.clip(chw, 0.0, 1.0).astype(np.float32, copy=False)
+            
+            if return_pil:
+                return tensor_np, original_pil
+            return tensor_np
+            
+        except Exception as e:
+            print(f"[Mapbox Fetcher Error] Station {station_id}: {e}")
+            fallback_np = np.zeros((3, self.target_size, self.target_size), dtype=np.float32)
+            if return_pil:
+                return fallback_np, Image.new('RGB', (self.fetch_size, self.fetch_size), color='black')
+            return fallback_np
+
+
+class TrafficPredictor:
+    """Traffic generation model predictor and site selection analyzer"""
+    def __init__(self, model_path, spatial_path, traffic_path, local_sat_dir="real_spatial_data/satellite_png", device=None):
+        self.device = device if device else torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+        self.local_sat_dir = local_sat_dir
+        
+        # Load spatial features cache
+        if os.path.exists(spatial_path):
+            self.data_cache = np.load(spatial_path, allow_pickle=True)
+        else:
+            raise FileNotFoundError(f"Spatial path {spatial_path} not found!")
+
+        # Load traffic records for validation comparison
+        if os.path.exists(traffic_path):
+            self.traffic_data = np.load(traffic_path, allow_pickle=True)['bs_record']
+        else:
+            self.traffic_data = None
+
+        # ==========================================
+        # Strictly simulate Dataset length truncation to ensure 
+        # normalization extrema are 100% aligned with training.
+        # ==========================================
+        n_traffic = len(self.traffic_data) if self.traffic_data is not None else float('inf')
+        n_poi = len(self.data_cache['poi_distributions'])
+        n_coords = len(self.data_cache['coordinates'])
+        self.n_valid = min(n_traffic, n_poi, n_coords)
+
+        # Calculate coordinate bounds for normalization
+        raw_coords_valid = self.data_cache['coordinates'][:self.n_valid].astype(np.float32)
+        self.coord_min = raw_coords_valid.min(axis=0)
+        self.coord_max = raw_coords_valid.max(axis=0)
+
+        self.satellite_fetcher = MapboxSatelliteFetcher()
+        self.model = self._load_model(model_path)
+
+    def _load_model(self, model_path):
+        print(f"Loading V4 Model on {self.device}...")
+        model = HierarchicalFlowMatchingSystemV4(
+            spatial_dim=SPATIAL_DIM, 
+            hidden_dim=HIDDEN_DIM, 
+            poi_dim=POI_DIM, 
+            n_layers_level3=N_LAYERS_LEVEL3
+        ).to(self.device)
+
+        if os.path.exists(model_path):
+            ckpt = torch.load(model_path, map_location=self.device, weights_only=False)
+            state_dict = ckpt['model_state_dict'] if 'model_state_dict' in ckpt else ckpt
+            model.load_state_dict(state_dict)
+            print(f"Checkpoint loaded successfully from {model_path}.")
+        else:
+            raise FileNotFoundError(f"Model checkpoint not found at {model_path}")
+        
+        model.eval()
+        return model
+
+    def predict(self, idx, use_local_img_for_debug=False):
+        """Generates traffic predictions and performs LSI spatial analysis"""
+        try:
+            torch.manual_seed(SEED)
+            idx = int(idx)
+
+            # 1. Process POI distributions
+            raw_poi = self.data_cache['poi_distributions'][idx].astype(np.float32).copy()
+            raw_poi = np.clip(raw_poi, 0.0, None)
+            poi_sum = float(raw_poi.sum())
+            if poi_sum > 1e-8:
+                raw_poi = raw_poi / poi_sum
+            else:
+                raw_poi = np.zeros_like(raw_poi)
+            poi_tensor = torch.from_numpy(raw_poi).unsqueeze(0).to(self.device)
+
+            # 2. Process Geographical Coordinates
+            raw_loc = self.data_cache['coordinates'][idx].astype(np.float32)
+            lon, lat = raw_loc[0], raw_loc[1] 
+            
+            # Fetch Satellite Image (Local Debug vs. Remote API)
+            if use_local_img_for_debug and os.path.exists(f"{self.local_sat_dir}/{idx}.png"):
+                img = Image.open(f"{self.local_sat_dir}/{idx}.png").convert("RGB")
+                original_pil = img.copy()
+            else:
+                _, original_pil = self.satellite_fetcher.fetch(lon, lat, station_id=str(idx), return_pil=True)
+
+            # 3. LSI Heatmap Generation (Location Stability Index)
+            lsi_grid, best_idx, best_traffic = self.generate_lsi_heatmap(original_pil, lat, lon, poi_tensor, grid_size=3)
+            site_map_b64 = self.create_site_map_base64(original_pil, lsi_grid, best_idx)
+
+            # 4. Map Projections: Convert grid indices back to physical Lat/Lon
+            grid_size = 3
+            best_row, best_col = best_idx
+            
+            # Calculate spans based on Web Mercator projection at specific zoom
+            lon_span = 360.0 / (2 ** MAPBOX_ZOOM)
+            lat_span = lon_span * math.cos(math.radians(lat))
+            step_lon = lon_span / grid_size
+            step_lat = lat_span / grid_size
+
+            # Offset from base center
+            best_lat = lat - (best_row - grid_size // 2) * step_lat
+            best_lon = lon + (best_col - grid_size // 2) * step_lon
+            best_loc = [float(best_lon), float(best_lat)]
+
+            # 5. Multidimensional NLG (Natural Language Generation) Engine
+            best_lsi_value = float(lsi_grid[best_idx])
+            avg_lsi_value = float(np.mean(lsi_grid))
+            min_lsi_value = float(np.min(lsi_grid))
+            
+            # Core Performance Metrics
+            improvement_avg = ((best_lsi_value - avg_lsi_value) / avg_lsi_value) * 100 if avg_lsi_value > 0 else 0
+            spatial_contrast = ((best_lsi_value - min_lsi_value) / min_lsi_value) * 100 if min_lsi_value > 0 else 0
+
+            # Feature A: POI Semantic Mapping
+            poi_idx = int(torch.argmax(poi_tensor[0]))
+            poi_categories = [
+                "Commercial/Retail", "Residential Complex", "Transit Hub", 
+                "Corporate/Office", "Public/Recreational", "Industrial Zone", 
+                "Mixed-Use Urban", "Educational/Campus"
+            ]
+            dominant_poi = poi_categories[poi_idx % len(poi_categories)]
+
+            # Feature B: Temporal Tide Analysis (Extract daily peak from 672-hour sequence)
+            daily_pattern = best_traffic.reshape(-1, 24).mean(axis=0)
+            peak_hour = int(np.argmax(daily_pattern))
+            
+            if 7 <= peak_hour <= 10: 
+                peak_type = "Morning Rush (07:00-10:00)"
+            elif 16 <= peak_hour <= 19: 
+                peak_type = "Evening Rush (16:00-19:00)"
+            elif 11 <= peak_hour <= 15: 
+                peak_type = "Midday Active (11:00-15:00)"
+            else: 
+                peak_type = "Night/Off-peak Active"
+
+            # Load description based on average volume
+            avg_load = float(np.mean(best_traffic))
+            if avg_load > 6.0: load_desc = "High-Capacity"
+            elif avg_load > 3.0: load_desc = "Moderate-Load"
+            else: load_desc = "Baseline/Sparse"
+
+            # Dynamic Text Assembly (4-Stage Structure)
+            # Stage 1: Spatial Environment Diagnosis
+            if spatial_contrast > 40:
+                p1 = f"Spatial scan detects a highly heterogeneous {dominant_poi} sector with steep traffic gradients. "
+            else:
+                p1 = f"Spatial scan indicates a relatively uniform {dominant_poi} matrix. "
+
+            # Stage 2: Temporal Characteristics
+            p2 = f"Flow Matching model projects a {load_desc} demand curve, heavily anchored by a {peak_type} signature. "
+
+            # Stage 3: Decision Output
+            p3 = f"Micro-grid ({best_row}, {best_col}) is isolated as the topological optimum, yielding a peak Location Stability Index (LSI) of {best_lsi_value:.2f}. "
+
+            # Stage 4: Business Value Assessment
+            if improvement_avg > 15:
+                p4 = f"Deploying infrastructure here intercepts peak volatility, providing a {improvement_avg:.1f}% structural stability gain over the regional average."
+            else:
+                p4 = f"This precise coordinate offers a marginal yet critical {improvement_avg:.1f}% variance reduction, ensuring optimal load-balancing."
+
+            explanation_text = p1 + p2 + p3 + p4
+            # ===============================================
+
+            # Finalize output sequence
+            gen_seq_real = np.clip(best_traffic, 0.0, 10.0)
+            real_seq = self.traffic_data[idx].tolist() if self.traffic_data is not None else []
+
+            return {
+                "station_id": idx,
+                "prediction": gen_seq_real.tolist(),
+                "real": real_seq,
+                "site_map_b64": site_map_b64, 
+                "best_loc": best_loc, 
+                "explanation": explanation_text,
+                "status": "success"
+            }
+
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
+            return {"error": str(e), "status": "failed"}
+        
+    @torch.no_grad()
+    def generate_lsi_heatmap(self, img_pil, base_lat, base_lon, poi_tensor, grid_size=3):
+        w, h = img_pil.size
+        patch_w, patch_h = w // grid_size, h // grid_size
+        
+        patches = []
+        coords = []
+        
+        # Calculate precise Lat/Lon spans for 256x256 image area
+        lon_span = 360.0 / (2 ** MAPBOX_ZOOM)
+        lat_span = lon_span * math.cos(math.radians(base_lat))
+        step_lon = lon_span / grid_size
+        step_lat = lat_span / grid_size
+        
+        for i in range(grid_size):
+            for j in range(grid_size):
+                # Slice and resize patches for model
+                box = (j * patch_w, i * patch_h, (j+1) * patch_w, (i+1) * patch_h)
+                patch = img_pil.crop(box).resize((IMAGE_SIZE, IMAGE_SIZE), Image.BILINEAR).convert("RGB")
+                arr = np.array(patch).transpose(2,0,1) / 255.0
+                patches.append(torch.tensor(arr, dtype=torch.float32))
+                
+                # Normalize coordinates for the model
+                offset_lat = base_lat - (i - grid_size//2) * step_lat
+                offset_lon = base_lon + (j - grid_size//2) * step_lon
+                raw_coord = np.array([offset_lon, offset_lat], dtype=np.float32)
+                norm_coord = (raw_coord - self.coord_min) / (self.coord_max - self.coord_min + 1e-8)
+                coords.append(torch.tensor(norm_coord, dtype=torch.float32))
+
+        batch_size = grid_size ** 2
+        # Assemble GPU Batch
+        batch_gpu = {
+            'satellite_img': torch.stack(patches).to(self.device),
+            'poi_dist': poi_tensor.repeat(batch_size, 1),
+            'coords': torch.stack(coords).to(self.device),
+            'traffic_seq': torch.zeros(batch_size, 672, dtype=torch.float32).to(self.device) 
+        }
+        
+        # Batch Inference (Computes 9 regions simultaneously)
+        output = self.model(batch_gpu, mode='generate', loss_cfg={'n_steps_generate': N_STEPS})
+        outputs = output['generated'].cpu().numpy() # [9, 672]
+        
+        ## LSI Calculation: 1 / (std + epsilon)
+        # Higher LSI means lower variance (more stable traffic)
+        stds = outputs.std(axis=1)
+        lsis = 1.0 / (stds + 1e-6)
+        lsi_grid = lsis.reshape(grid_size, grid_size)
+        
+        # Find the most stable coordinate
+        best_idx = np.unravel_index(np.argmax(lsi_grid), lsi_grid.shape)
+        best_traffic = outputs[best_idx[0] * grid_size + best_idx[1]]
+        
+        return lsi_grid, best_idx, best_traffic
+
+
+    def create_site_map_base64(self, img_pil, lsi_grid, best_idx):
+        """Generates heatmap overlay visualization and encodes to Base64"""
+        img_arr = np.array(img_pil)
+        h, w, _ = img_arr.shape
+        grid_h, grid_w = lsi_grid.shape
+        
+        fig, ax = plt.subplots(figsize=(4, 4), dpi=120)
+        
+        # Overlay heatmap on satellite image
+        ax.imshow(img_arr)
+        im = ax.imshow(lsi_grid, cmap='RdYlGn', alpha=0.45, extent=[0, w, h, 0], interpolation='bicubic')
+        
+        cell_w, cell_h = w / grid_w, h / grid_h
+        best_row, best_col = best_idx
+        center_x = best_col * cell_w + cell_w / 2
+        center_y = best_row * cell_h + cell_h / 2
+        
+        # Draw target star and LSI indicator
+        ax.plot(center_x, center_y, marker='*', color='red', markersize=20, markeredgecolor='white', markeredgewidth=1.5)
+        best_lsi = lsi_grid[best_idx]
+        ax.annotate(f"LSI: {best_lsi:.2f}", xy=(center_x, center_y), xytext=(10, 10),
+                    textcoords='offset points', color='white', fontweight='bold',
+                    bbox=dict(boxstyle="round,pad=0.3", facecolor="red", alpha=0.8, edgecolor="white"))
+        
+        ax.axis('off')
+        plt.tight_layout()
+        
+        # Convert to Base64 for API transmission
+        buf = BytesIO()
+        fig.savefig(buf, format="png", bbox_inches='tight', transparent=True)
+        plt.close(fig)
+        return base64.b64encode(buf.getvalue()).decode("utf-8")
+
+if __name__ == "__main__":
+    MODEL_PATH = "best_corr_model.pt"
+    SPATIAL_PATH = "data/spatial_features.npz"
+    TRAFFIC_PATH = "data/bs_record_energy_normalized_sampled.npz"
+
+    predictor = TrafficPredictor(
+        model_path=MODEL_PATH,
+        spatial_path=SPATIAL_PATH,
+        traffic_path=TRAFFIC_PATH
+    )
+
+    test_id = 277
+    result = predictor.predict(test_id, use_local_img_for_debug=False)
+    
+    if result.get("status") == "success":
+        print(f"Prediction successful for Station {test_id}!")
+    else:
+        print(f"Prediction failed: {result.get('error')}")

requirements.txt

@@ -0,0 +1,8 @@
+Flask==3.0.0
+flask-cors==4.0.0
+numpy==1.26.4
+Pillow==10.2.0
+requests==2.31.0
+matplotlib==3.8.2
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.1.2+cpu

script.js

@@ -0,0 +1,954 @@
+// ==========================================
+// 1. Config (Focused on Shanghai)
+// ==========================================
+const CONFIG = {
+    MAPBOX_TOKEN: 'pk.eyJ1IjoieXlhaXl5IiwiYSI6ImNtaTVpMTVlaTJmdzMybW9zcmFieGxpdHUifQ.181d6E5fzLw1CEZMEPU53Q',
+    // API_BASE: 'http://127.0.0.1:5000/api', // Local
+    API_BASE: '/api',  // Online
+    
+    // Shanghai City Center
+    DEFAULT_CENTER: [121.4737, 31.2304], 
+    DEFAULT_ZOOM: 10.5,
+
+    // Shanghai Coordinate Bounds [Southwest, Northeast]
+    SHANGHAI_BOUNDS: [
+        [120.80, 30.60], // Southwest
+        [122.50, 31.90]  // Northeast
+    ]
+};
+
+// ==========================================
+// 2. Globals
+// ==========================================
+let chartInstance = null;
+let predictionChartInstance = null; 
+let currentMarker = null;
+let mapInstance = null;
+let globalStationData = [];
+let animationFrameId = null;
+let isPredictionMode = false; 
+let predictionMarker = null; 
+let optimalMarker = null;     
+
+// ==========================================
+// 3. API Logic
+// ==========================================
+async function fetchLocations() {
+    console.log("Requesting backend data...");
+    const res = await fetch(`${CONFIG.API_BASE}/stations/locations`);
+    if (!res.ok) throw new Error(`API Error: ${res.status}`);
+    return await res.json();
+}
+
+async function fetchStationDetail(id) {
+    try {
+        const res = await fetch(`${CONFIG.API_BASE}/stations/detail/${id}`);
+        return await res.json();
+    } catch (e) {
+        console.error("Fetch Detail Error:", e);
+        return null;
+    }
+}
+
+// Fetch AI Prediction Data
+async function fetchPrediction(id) {
+    try {
+        const res = await fetch(`${CONFIG.API_BASE}/predict/${id}?t=${Date.now()}`);
+        const data = await res.json();
+        if (data.error) throw new Error(data.error);
+        return data;
+    } catch (e) {
+        console.error("Prediction API Error:", e);
+        alert("Prediction failed: " + e.message);
+        return null;
+    }
+}
+
+function loadSatellitePatch(lng, lat) {
+    // Logic for loading static satellite imagery patch
+    const img = document.getElementById('satellite-patch');
+    const placeholder = document.getElementById('sat-placeholder');
+    if(!img) return;
+    
+    img.style.display = 'none'; 
+    placeholder.style.display = 'flex'; 
+    placeholder.innerHTML = '<p>Loading...</p>';
+    
+    img.src = `https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/${lng},${lat},16,0,0/320x200?access_token=${CONFIG.MAPBOX_TOKEN}`;
+    img.onload = () => { img.style.display = 'block'; placeholder.style.display = 'none'; };
+}
+
+// ==========================================
+// 4. Chart Logic (Normal & Prediction)
+// ==========================================
+function renderChart(recordData) {
+    const ctx = document.getElementById('energyChart').getContext('2d');
+    if (chartInstance) chartInstance.destroy();
+
+    chartInstance = new Chart(ctx, {
+        type: 'line',
+        data: { 
+            labels: recordData.map((_, i) => i), 
+            datasets: [
+                { 
+                    label: 'Traffic', data: recordData, 
+                    borderColor: '#00cec9', backgroundColor: 'rgba(0, 206, 201, 0.1)', 
+                    borderWidth: 1.5, fill: true, pointRadius: 0, tension: 0.3 
+                },
+                { 
+                    label: 'Current', data: [], type: 'scatter', 
+                    pointRadius: 6, pointBackgroundColor: '#ffffff', 
+                    pointBorderColor: '#e84393', pointBorderWidth: 3 
+                }
+            ] 
+        },
+        options: { 
+            responsive: true, maintainAspectRatio: false, animation: false,
+            plugins: { legend: { display: false } }, 
+            scales: { x: { display: false }, y: { grid: { color: 'rgba(255,255,255,0.05)' }, ticks: { color: '#64748b', font: {size: 10} } } } 
+        }
+    });
+}
+
+function updateChartCursor(timeIndex) {
+    if (chartInstance && chartInstance.data.datasets[0].data.length > timeIndex) {
+        const yValue = chartInstance.data.datasets[0].data[timeIndex];
+        chartInstance.data.datasets[1].data = [{x: timeIndex, y: yValue}];
+        chartInstance.update('none');
+    }
+}
+
+// Render AI Prediction Comparison Chart
+function renderPredictionChart(realData, predData) {
+    const canvas = document.getElementById('predictionChart');
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    
+    if (predictionChartInstance) {
+        predictionChartInstance.destroy();
+    }
+
+    // Generate X-axis labels (e.g., H0, H1...)
+    const labels = realData.map((_, i) => `H${i}`);
+
+    predictionChartInstance = new Chart(ctx, {
+        type: 'line',
+        data: {
+            labels: labels,
+            datasets: [
+                {
+                    label: 'Real Traffic',
+                    data: realData,
+                    borderColor: 'rgba(0, 206, 201, 0.8)', // Cyan
+                    backgroundColor: 'rgba(0, 206, 201, 0.1)',
+                    borderWidth: 1.5,
+                    pointRadius: 0,
+                    fill: true,
+                    tension: 0.3
+                },
+                {
+                    label: 'AI Prediction',
+                    data: predData,
+                    borderColor: '#f39c12', // Orange
+                    backgroundColor: 'transparent',
+                    borderWidth: 2,
+                    borderDash: [5, 5], // Dashed line effect
+                    pointRadius: 0,
+                    fill: false,
+                    tension: 0.3 
+                }
+            ]
+        },
+        options: {
+            responsive: true,
+            maintainAspectRatio: false,
+            interaction: {
+                mode: 'index',
+                intersect: false, // Tooltip shows both values simultaneously
+            },
+            plugins: {
+                legend: { 
+                    display: true, 
+                    labels: { color: '#e0e0e0', font: { size: 10 } }
+                }
+            },
+            scales: {
+                x: { 
+                    display: true, 
+                    grid: { color: 'rgba(255,255,255,0.05)' },
+                    ticks: { color: '#64748b', font: {size: 9}, maxTicksLimit: 14 } 
+                },
+                y: {
+                    grid: { color: 'rgba(255,255,255,0.1)' },
+                    ticks: { color: '#888', font: {size: 10} },
+                    beginAtZero: true
+                }
+            }
+        }
+    });
+}
+
+// ==========================================
+// 5. Map Manager 
+// ==========================================
+function initMap() {
+    mapboxgl.accessToken = CONFIG.MAPBOX_TOKEN;
+    mapInstance = new mapboxgl.Map({
+        container: 'map',
+        style: 'mapbox://styles/mapbox/satellite-streets-v12',
+        center: CONFIG.DEFAULT_CENTER,
+        zoom: CONFIG.DEFAULT_ZOOM,
+        pitch: 60, 
+        bearing: -15, 
+        antialias: true,
+        maxBounds: CONFIG.SHANGHAI_BOUNDS, 
+        minZoom: 9 
+    });
+    mapInstance.addControl(new mapboxgl.NavigationControl(), 'top-right');
+    return mapInstance;
+}
+
+function setupMapEnvironment(map) {
+    map.addSource('mapbox-dem', { 
+        'type': 'raster-dem', 
+        'url': 'mapbox://mapbox.mapbox-terrain-dem-v1', 
+        'tileSize': 512, 
+        'maxzoom': 14 });
+        
+    map.setTerrain({ 'source': 'mapbox-dem', 
+        'exaggeration': 1.5 });
+    
+    map.addLayer({ 
+        'id': 'sky', 
+        'type': 'sky', 
+        'paint': { 'sky-type': 'atmosphere', 'sky-atmosphere-sun': [0.0, 0.0], 'sky-atmosphere-sun-intensity': 15 } 
+    });
+    
+    if (map.setFog) {
+        map.setFog({ 'range': [0.5, 10], 
+            'color': '#240b36', 
+            'horizon-blend': 0.1, 
+            'high-color': '#0f172a', 
+            'space-color': '#000000', 
+            'star-intensity': 0.6 });
+    }
+
+    const labelLayerId = map.getStyle().layers.find(l => l.type === 'symbol' && l.layout['text-field']).id;
+    if (!map.getLayer('3d-buildings')) {
+        map.addLayer({
+            'id': '3d-buildings', 'source': 'composite', 
+            'source-layer': 'building', 'filter': ['==', 'extrude', 'true'], 
+            'type': 'fill-extrusion', 'minzoom': 11,
+            'paint': {
+                'fill-extrusion-color': ['interpolate', ['linear'], ['get', 'height'], 0, '#0f0c29', 30, '#1e2a4a', 200, '#4b6cb7'],
+                'fill-extrusion-height': ['get', 'height'], 'fill-extrusion-base': ['get', 'min_height'], 'fill-extrusion-opacity': 0.6
+            }
+        }, labelLayerId);
+    }
+}
+
+function updateGeoJSONData(map, stations, mode = 'avg', timeIndex = 0) {
+    const pointFeatures = [];
+    const polygonFeatures = [];
+    const r = 0.00025; // Marker radius
+
+    stations.forEach(s => {
+        const lng = s.loc[0], lat = s.loc[1];
+        let valH = (mode === 'avg') ? (s.val_h || 0) : ((s.vals && s.vals[timeIndex]) !== undefined ? s.vals[timeIndex] : 0);
+        let valC = (s.val_c !== undefined) ? s.val_c : 0;
+        
+        const props = { id: s.id, load_avg: valH, load_std: valC };
+        
+        pointFeatures.push({ type: 'Feature', geometry: { 
+            type: 'Point', coordinates: [lng, lat] }, properties: props });
+        polygonFeatures.push({ type: 'Feature', geometry: { 
+            type: 'Polygon', coordinates: [[ [lng-r, lat-r], [lng+r, lat-r], [lng+r, lat+r], [lng-r, lat+r], [lng-r, lat-r] ]] }, properties: props });
+    });
+
+    if (map.getSource('stations-points')) {
+        map.getSource('stations-points').setData({ 
+            type: 'FeatureCollection', 
+            features: pointFeatures });
+
+        map.getSource('stations-polygons').setData({ 
+            type: 'FeatureCollection', 
+            features: polygonFeatures });
+    }
+    return { points: { type: 'FeatureCollection', features: pointFeatures }, polys: { type: 'FeatureCollection', features: polygonFeatures } };
+}
+
+function addStationLayers(map, geoData, statsLoad, statsColor) {
+    map.addSource('stations-points', { type: 'geojson', data: geoData.points });
+    map.addSource('stations-polygons', { type: 'geojson', data: geoData.polys });
+
+    map.addLayer({
+        id: 'stations-heatmap', type: 'heatmap', source: 'stations-points', maxzoom: 14,
+        paint: {
+            'heatmap-weight': ['interpolate', ['linear'], ['get', 'load_avg'], statsLoad.min, 0, statsLoad.max, 1],
+            'heatmap-intensity': ['interpolate', ['linear'], ['zoom'], 0, 1, 13, 3],
+            'heatmap-color': ['interpolate', ['linear'], ['heatmap-density'], 0, 'rgba(0,0,0,0)', 0.2, '#0984e3', 0.4, '#00cec9', 0.6, '#a29bfe', 0.8, '#fd79a8', 1, '#ffffff'],
+            'heatmap-radius': ['interpolate', ['linear'], ['zoom'], 0, 2, 13, 25],
+            'heatmap-opacity': ['interpolate', ['linear'], ['zoom'], 12, 1, 14, 0]
+        }
+    });
+
+    map.addLayer({
+        id: 'stations-2d-dots', type: 'circle', source: 'stations-points', minzoom: 12,
+        paint: {
+            'circle-radius': 3,
+            'circle-color': ['step', ['get', 'load_std'], '#1e1e2e', statsColor.t1, '#0984e3', statsColor.t2, '#00cec9', statsColor.t3, '#fd79a8', statsColor.t4, '#e84393'],
+            'circle-stroke-width': 1, 'circle-stroke-color': '#fff', 'circle-opacity': 0.8
+        }
+    });
+
+    map.addLayer({
+        id: 'stations-3d-pillars', type: 'fill-extrusion', source: 'stations-polygons', minzoom: 12,
+        paint: {
+            'fill-extrusion-color': ['step', ['get', 'load_std'], '#1e1e2e', statsColor.t1, '#0984e3', statsColor.t2, '#00cec9', statsColor.t3, '#fd79a8', statsColor.t4, '#e84393'],
+            'fill-extrusion-height': ['interpolate', ['linear'], ['get', 'load_avg'], 0, 0, statsLoad.min, 5, statsLoad.max, 300],
+            'fill-extrusion-opacity': 0.7
+        }
+    });
+
+    map.addLayer({ id: 'stations-hitbox', type: 'circle', source: 'stations-points', 
+        paint: { 'circle-radius': 10, 'circle-color': 'transparent', 'circle-opacity': 0 } });
+}
+
+// ==========================================
+// 6. Map Interactions 
+// ==========================================
+function setupInteraction(map) {
+    const popup = new mapboxgl.Popup({ closeButton: false, closeOnClick: false, className: 'cyber-popup' });
+
+    map.on('mouseenter', 'stations-hitbox', (e) => {
+        map.getCanvas().style.cursor = 'pointer';
+        if (isPredictionMode) return; 
+
+        const props = e.features[0].properties;
+        const coordinates = e.features[0].geometry.coordinates.slice();
+        
+        while (Math.abs(e.lngLat.lng - coordinates[0]) > 180) { coordinates[0] += e.lngLat.lng > coordinates[0] ? 360 : -360; }
+        
+        popup.setLngLat(coordinates)
+            .setHTML(`
+                <div style="font-weight:bold; color:#fff; border-bottom:1px solid #444; padding-bottom:2px; margin-bottom:2px;">Station ${props.id}</div>
+                <div style="color:#00cec9;">Load: <span style="color:#fff;">${props.load_avg.toFixed(2)}</span></div>
+                <div style="color:#fd79a8;">Stability: <span style="color:#fff;">${props.load_std.toFixed(4)}</span></div>
+            `).addTo(map);
+    });
+
+    map.on('mouseleave', 'stations-hitbox', () => { 
+        if (!isPredictionMode) map.getCanvas().style.cursor = ''; 
+        popup.remove(); 
+    });
+
+    // Core Interaction Logic
+    map.on('click', 'stations-hitbox', async (e) => {
+        const coordinates = e.features[0].geometry.coordinates.slice();
+        const id = e.features[0].properties.id;
+
+        // 1. Prediction Mode Logic
+        if (isPredictionMode) {
+            const predPanel = document.getElementById('prediction-panel');
+            const predIdDisplay = document.getElementById('pred-station-id');
+            const siteMapContainer = document.getElementById('site-map-container');
+            const siteMapImg = document.getElementById('site-map-img');
+            
+            predPanel.classList.add('active');
+
+            const rightBtn = document.getElementById('toggle-right-btn');
+            if (rightBtn) rightBtn.classList.add('active');
+
+            predIdDisplay.innerText = `${id} (Calculating...)`; 
+            
+            // Clear previous optimal site marker when a new station is clicked
+            if (optimalMarker) {
+                optimalMarker.remove();
+                optimalMarker = null;
+            }
+
+            // Drop orange selection pin and draw 3x3 grid
+            if (!predictionMarker) {
+                predictionMarker = new mapboxgl.Marker({ color: '#f39c12' })
+                    .setLngLat(coordinates).addTo(map);
+            } else {
+                predictionMarker.setLngLat(coordinates);
+            }
+            updatePredictionGrid(map, coordinates[0], coordinates[1]);
+
+            if (siteMapContainer) siteMapContainer.style.display = 'none';
+            if (siteMapImg) siteMapImg.src = '';
+            
+            if(predictionChartInstance) {
+                predictionChartInstance.destroy();
+                predictionChartInstance = null;
+            }
+            
+            // Call Prediction API
+            const result = await fetchPrediction(id);
+            if(result && result.status === "success") {
+                predIdDisplay.innerText = id; 
+                renderPredictionChart(result.real, result.prediction);
+                
+                // Render returned Base64 site heatmap and mark optimal location
+                if (result.site_map_b64 && siteMapContainer && siteMapImg) {
+                    siteMapImg.src = `data:image/png;base64,${result.site_map_b64}`;
+                    siteMapContainer.style.display = 'block'; 
+                    
+                    // Typewriter Effect for AI Explanation
+                    const explanationBox = document.getElementById('site-explanation');
+                    if (explanationBox && result.explanation) {
+                        explanationBox.style.display = 'block';
+                        
+                        // Reset content and add blinking cursor
+                        explanationBox.innerHTML = `<strong>> SYSTEM LOG: AI DECISION</strong><br><span id="typewriter-text"></span><span class="cursor" style="animation: blink 1s step-end infinite;">_</span>`;
+                        
+                        const textTarget = document.getElementById('typewriter-text');
+                        const fullText = result.explanation;
+                        let charIndex = 0;
+                        
+                        function typeWriter() {
+                            if (charIndex < fullText.length) {
+                                textTarget.innerHTML += fullText.charAt(charIndex);
+                                charIndex++;
+                                // Randomize typing speed for realistic terminal feel
+                                setTimeout(typeWriter, Math.random() * 20 + 10);
+                            }
+                        }
+                        typeWriter();
+                    }
+
+                    // Mark green optimal Pin on physical map coordinates
+                    if (result.best_loc) {
+                        
+                        // Remove orange marker to avoid overlap
+                        if (predictionMarker) {
+                            predictionMarker.remove();
+                            predictionMarker = null; 
+                        }
+
+                        // Create custom "Green Pulse" DOM element defined in CSS
+                        const customPin = document.createElement('div');
+                        customPin.className = 'optimal-pulse-pin';
+
+                        optimalMarker = new mapboxgl.Marker(customPin) 
+                            .setLngLat(result.best_loc)
+                            .setPopup(new mapboxgl.Popup({ offset: 25, closeButton: false, className: 'cyber-popup' })
+                            .setHTML('<div style="color:#2ecc71; font-weight:bold; font-size:14px;">🌟 Best LSI Site</div>'))
+                            .addTo(map);
+                            
+                        optimalMarker.togglePopup();
+
+                        // Smoothly fly to the optimal site location
+                        map.flyTo({
+                            center: result.best_loc,
+                            zoom: 16.5,
+                            speed: 1.2
+                        });
+                    }
+                }
+            } else {
+                predIdDisplay.innerText = `${id} (Failed)`;
+            }
+            return; 
+        }
+
+        // 2. Standard Detail Mode Logic
+        if (currentMarker) currentMarker.remove();
+        currentMarker = new mapboxgl.Marker().setLngLat(coordinates).addTo(map);
+        
+        const pitch = map.getPitch();
+        map.flyTo({ center: coordinates, zoom: 15, pitch: pitch > 10 ? 60 : 0, speed: 1.5 });
+        
+        document.getElementById('selected-id').innerText = id;
+
+        try {
+            document.getElementById('station-details').innerHTML = '<p class="placeholder-text">Loading details...</p>';
+            
+            const detailData = await fetchStationDetail(id);
+            if (detailData) {
+                const stats = detailData.stats || {avg:0, std:0};
+                
+                document.getElementById('station-details').innerHTML = 
+                    `<div style="margin-top:10px;">
+                        <p><strong>Longitude:</strong> ${detailData.loc[0].toFixed(4)}</p>
+                        <p><strong>Latitude:</strong> ${detailData.loc[1].toFixed(4)}</p>
+                        <hr style="border:0; border-top:1px solid #444; margin:5px 0;">
+                        <p><strong>Avg Load:</strong> <span style="color:#00cec9">${stats.avg.toFixed(4)}</span></p>
+                        <p><strong>Stability:</strong> <span style="color:#fd79a8">${stats.std.toFixed(4)}</span></p>
+                    </div>`;
+                
+                if (detailData.bs_record) {
+                    renderChart(detailData.bs_record);
+                }
+            }
+        } catch (err) {
+            console.error("Failed to fetch clicked station details:", err);
+            document.getElementById('station-details').innerHTML = '<p style="color:red">Error loading data</p>';
+        }
+    });
+}
+
+// Prediction Mode State Control
+function setupPredictionMode(map) {
+    const predictBtn = document.getElementById('predict-toggle');
+    const predPanel = document.getElementById('prediction-panel');
+    const closePredBtn = document.getElementById('close-pred-btn');
+
+    if (!predictBtn) return;
+
+    predictBtn.addEventListener('click', () => {
+        // Enforce 2D view check for prediction mode
+        const pitch = map.getPitch();
+        if (pitch > 10) {
+            alert("Prediction Mode is only available in 2D View. Please switch to 2D first.");
+            return;
+        }
+
+        isPredictionMode = !isPredictionMode;
+        
+        if (isPredictionMode) {
+            predictBtn.classList.add('predict-on');
+            predictBtn.innerHTML = '<span class="icon">🔮</span> Mode: ON';
+            map.getCanvas().style.cursor = 'crosshair';
+        } else {
+            predictBtn.classList.remove('predict-on');
+            predictBtn.innerHTML = '<span class="icon">🔮</span> Prediction Mode';
+            map.getCanvas().style.cursor = '';
+            predPanel.classList.remove('active');
+
+            // Reset UI state when exiting prediction
+            predPanel.classList.remove('collapsed');
+            const rightBtn = document.getElementById('toggle-right-btn');
+            if(rightBtn) {
+                rightBtn.innerText = '▶';
+                rightBtn.classList.remove('active'); 
+                rightBtn.classList.remove('collapsed');
+            }
+
+            // Clear markers and grids
+            clearPredictionExtras(map);
+        }
+    });
+
+    if (closePredBtn) {
+        closePredBtn.addEventListener('click', () => {
+            predPanel.classList.remove('active');
+            const rightBtn = document.getElementById('toggle-right-btn');
+            if (rightBtn) rightBtn.classList.remove('active');
+            predictBtn.click(); // Trigger toggle to clean up state
+        });
+    }
+}
+
+// === 新增：绘制 AI 模型的 3x3 空间感知网格 ===
+// function updatePredictionGrid(map, centerLng, centerLat) {
+//     const features = [];
+//     const step = 0.002; // 与后端 Python 的 offset = 0.002 对齐
+//     const gridSize = 3;
+//     const offset = Math.floor(gridSize / 2);
+
+//     for (let i = 0; i < gridSize; i++) {
+//         for (let j = 0; j < gridSize; j++) {
+//             // 精确还原 Python 中切片的中心坐标
+//             const cLng = centerLng + (j - offset) * step;
+//             const cLat = centerLat - (i - offset) * step;
+//             const w = step / 2;
+
+//             features.push({
+//                 'type': 'Feature',
+//                 'geometry': {
+//                     'type': 'Polygon',
+//                     'coordinates': [[
+//                         [cLng - w, cLat - w], [cLng + w, cLat - w],
+//                         [cLng + w, cLat + w], [cLng - w, cLat + w],
+//                         [cLng - w, cLat - w]
+//                     ]]
+//                 }
+//             });
+//         }
+//     }
+
+//     const geojson = { 'type': 'FeatureCollection', 'features': features };
+
+//     if (map.getSource('pred-grid-source')) {
+//         map.getSource('pred-grid-source').setData(geojson);
+//     } else {
+//         map.addSource('pred-grid-source', { type: 'geojson', data: geojson });
+//         map.addLayer({
+//             'id': 'pred-grid-fill', 'type': 'fill', 'source': 'pred-grid-source',
+//             'paint': { 'fill-color': '#f39c12', 'fill-opacity': 0.1 }
+//         });
+//         map.addLayer({
+//             'id': 'pred-grid-line', 'type': 'line', 'source': 'pred-grid-source',
+//             'paint': { 'line-color': '#f39c12', 'line-width': 2, 'line-dasharray': [2, 2] }
+//         });
+//     }
+// }
+
+// Dynamic 3x3 grid matching the 256px satellite patch bounds
+function updatePredictionGrid(map, centerLng, centerLat) {
+    const features = [];
+    const gridSize = 3;
+    const offset = Math.floor(gridSize / 2);
+
+    // Precise Web Mercator projection span calculation at Zoom 15
+    const zoom = 15; 
+    
+    // Total Longitude span for 256 pixels at this zoom
+    const lonSpan = 360 / Math.pow(2, zoom); 
+    // Latitude span (scaled by local latitude)
+    const latSpan = lonSpan * Math.cos(centerLat * Math.PI / 180);
+
+    // Actual step sizes for 3x3 division
+    const stepLon = lonSpan / gridSize;
+    const stepLat = latSpan / gridSize;
+
+    for (let i = 0; i < gridSize; i++) {
+        for (let j = 0; j < gridSize; j++) {
+            // Center point of each micro-grid cell
+            const cLng = centerLng + (j - offset) * stepLon;
+            const cLat = centerLat - (i - offset) * stepLat;
+
+            const wLon = stepLon / 2;
+            const wLat = stepLat / 2;
+
+            features.push({
+                'type': 'Feature',
+                'geometry': {
+                    'type': 'Polygon',
+                    'coordinates': [[
+                        [cLng - wLon, cLat - wLat], [cLng + wLon, cLat - wLat],
+                        [cLng + wLon, cLat + wLat], [cLng - wLon, cLat + wLat],
+                        [cLng - wLon, cLat - wLat]
+                    ]]
+                }
+            });
+        }
+    }
+
+    const geojson = { 'type': 'FeatureCollection', 'features': features };
+
+    if (map.getSource('pred-grid-source')) {
+        map.getSource('pred-grid-source').setData(geojson);
+    } else {
+        map.addSource('pred-grid-source', { type: 'geojson', data: geojson });
+        map.addLayer({
+            'id': 'pred-grid-fill', 'type': 'fill', 'source': 'pred-grid-source',
+            'paint': { 'fill-color': '#f39c12', 'fill-opacity': 0.1 }
+        });
+        map.addLayer({
+            'id': 'pred-grid-line', 'type': 'line', 'source': 'pred-grid-source',
+            'paint': { 'line-color': '#f39c12', 'line-width': 2, 'line-dasharray': [2, 2] }
+        });
+    }
+}
+
+// Cleanup prediction visual elements
+function clearPredictionExtras(map) {
+    if (predictionMarker) { predictionMarker.remove(); predictionMarker = null; }
+    if (optimalMarker) { optimalMarker.remove(); optimalMarker = null; } // ====== 新增：清理绿色点 ======
+    if (map.getSource('pred-grid-source')) {
+        map.getSource('pred-grid-source').setData({ type: 'FeatureCollection', features: [] });
+    }
+}
+
+// ==========================================
+// 7. Timeline Logic
+// ==========================================
+function setupTimeLapse(map, globalData) {
+    const playBtn = document.getElementById('play-btn');
+    const slider = document.getElementById('time-slider');
+    const display = document.getElementById('time-display');
+    if (!playBtn || !slider) return;
+
+    const totalHours = (globalData.length > 0 && globalData[0].vals) ? globalData[0].vals.length : 672;
+    slider.max = totalHours - 1;
+    let isPlaying = false;
+    let speed = 100;
+
+    const updateTime = (val) => {
+        const day = Math.floor(val / 24) + 1;
+        const hour = val % 24;
+        display.innerText = `Day ${day.toString().padStart(2, '0')} - ${hour.toString().padStart(2, '0')}:00`;
+        
+        updateGeoJSONData(map, globalData, 'time', val);
+        updateChartCursor(val);
+    };
+
+    const play = () => {
+        let val = parseInt(slider.value);
+        val = (val + 1) % totalHours; 
+        slider.value = val;
+        updateTime(val);
+        if (isPlaying) animationFrameId = setTimeout(() => requestAnimationFrame(play), speed); 
+    };
+
+    playBtn.onclick = () => {
+        isPlaying = !isPlaying;
+        playBtn.innerText = isPlaying ? '⏸' : '▶';
+        if (isPlaying) play(); else clearTimeout(animationFrameId);
+    };
+
+    slider.oninput = (e) => {
+        isPlaying = false; 
+        if(animationFrameId) clearTimeout(animationFrameId);
+        playBtn.innerText = '▶';
+        updateTime(parseInt(e.target.value));
+    };
+}
+
+// ==========================================
+// 8. UI Controls
+// ==========================================
+function setupModeToggle(map) {
+    const btn = document.getElementById('view-toggle');
+    const timePanel = document.querySelector('.time-panel');
+    let is3D = true;
+
+    if (!btn) return;
+
+    btn.onclick = () => {
+        // Prevent switching to 3D mode if Prediction Mode is active
+        if (isPredictionMode) {
+            alert("Please exit Prediction Mode before switching to 3D.");
+            return;
+        }
+
+        is3D = !is3D;
+        if (is3D) {
+            // Switch to 3D View: Show pillars and tilt camera
+            if(map.getLayer('stations-3d-pillars')) map.setLayoutProperty('stations-3d-pillars', 'visibility', 'visible');
+            map.easeTo({ pitch: 60, bearing: -15 });
+            btn.innerHTML = '<span class="icon">👁️</span> View: 3D';
+            if (timePanel) {
+                timePanel.style.display = 'flex';
+                setTimeout(() => { timePanel.style.opacity = '1'; }, 10);
+            }
+        } else {
+            // Switch to 2D View: Hide pillars and reset camera pitch
+            if(map.getLayer('stations-3d-pillars')) map.setLayoutProperty('stations-3d-pillars', 'visibility', 'none');
+            map.easeTo({ pitch: 0, bearing: 0 });
+            btn.innerHTML = '<span class="icon">🗺️</span> View: 2D';
+            if (timePanel) {
+                timePanel.style.display = 'none';
+                timePanel.style.opacity = '0';
+            }
+            // Stop timelapse playback when entering 2D mode
+            const playBtn = document.getElementById('play-btn');
+            if (playBtn && playBtn.innerText === '⏸') playBtn.click();
+        }
+    };
+}
+
+function setupDataToggle(map) {
+    const btn = document.getElementById('data-toggle');
+    const layers = ['stations-3d-pillars', 'stations-2d-dots', 'stations-heatmap', 'stations-hitbox'];
+    let isVisible = true;
+    if(btn) btn.onclick = () => {
+        isVisible = !isVisible;
+        const val = isVisible ? 'visible' : 'none';
+        layers.forEach(id => { if(map.getLayer(id)) map.setLayoutProperty(id, 'visibility', val); });
+        btn.innerHTML = isVisible ? '<span class="icon">📡</span> Toggle Data' : '<span class="icon">🚫</span> Toggle Data';
+        btn.style.opacity = isVisible ? '1' : '0.6';
+    };
+}
+
+function setupFilterMenu(map, statsColor) {
+    const btn = document.getElementById('filter-btn');
+    const menu = document.getElementById('filter-menu');
+    if (!btn || !menu) return;
+
+    // Define stability levels based on Standard Deviation thresholds
+    const levels = [
+        { label: "Level 5: Highly Unstable", color: "#e84393", filter: ['>=', 'load_std', statsColor.t4] },
+        { label: "Level 4: Volatile",        color: "#fd79a8", filter: ['all', ['>=', 'load_std', statsColor.t3], ['<', 'load_std', statsColor.t4]] },
+        { label: "Level 3: Normal",          color: "#00cec9", filter: ['all', ['>=', 'load_std', statsColor.t2], ['<', 'load_std', statsColor.t3]] },
+        { label: "Level 2: Stable",          color: "#0984e3", filter: ['all', ['>=', 'load_std', statsColor.t1], ['<', 'load_std', statsColor.t2]] },
+        { label: "Level 1: Highly Stable",   color: "#1e1e2e", filter: ['<', 'load_std', statsColor.t1] }
+    ];
+
+    menu.innerHTML = ''; 
+    levels.forEach((lvl) => {
+        const item = document.createElement('div');
+        item.className = 'filter-item';
+        item.innerHTML = `<div class="color-box" style="background:${lvl.color}; box-shadow: 0 0 5px ${lvl.color};"></div><span>${lvl.label}</span>`;
+        item.onclick = (e) => {
+            e.stopPropagation(); 
+            if (item.classList.contains('selected')) {
+                item.classList.remove('selected'); 
+                applyFilter(map, null); 
+            } else {
+                document.querySelectorAll('.filter-item').forEach(el => el.classList.remove('selected'));
+                item.classList.add('selected'); 
+                applyFilter(map, lvl.filter);
+            }
+        };
+        menu.appendChild(item);
+    });
+
+    // Toggle menu visibility
+    btn.onclick = (e) => { e.stopPropagation(); menu.classList.toggle('active'); };
+    document.addEventListener('click', (e) => { if (!menu.contains(e.target) && !btn.contains(e.target)) menu.classList.remove('active'); });
+}
+
+function applyFilter(map, filterExpression) {
+    const targetLayers = ['stations-3d-pillars', 'stations-2d-dots', 'stations-heatmap', 'stations-hitbox'];
+    targetLayers.forEach(layerId => { if (map.getLayer(layerId)) map.setFilter(layerId, filterExpression); });
+}
+
+function setupSearch(map, globalData) {
+    const input = document.getElementById('search-input');
+    const btn = document.getElementById('search-btn');
+    const clearBtn = document.getElementById('clear-search-btn');
+    const keepCheck = document.getElementById('keep-markers-check');
+
+    if (!input || !btn) return;
+
+    let searchMarkers = [];
+
+    const clearAllMarkers = () => {
+        searchMarkers.forEach(marker => marker.remove());
+        searchMarkers = [];
+    };
+
+    const performSearch = async () => {
+        const queryId = input.value.trim();
+        if (!queryId) return;
+
+        const target = globalData.find(s => String(s.id) === String(queryId));
+
+        if (target) {
+            if (!keepCheck.checked) {
+                clearAllMarkers();
+            }
+
+            // Fly to searched station and switch to high-detail view
+            map.flyTo({
+                center: target.loc,
+                zoom: 16,
+                pitch: 60,
+                essential: true
+            });
+
+            document.getElementById('selected-id').innerText = target.id;
+            try {
+                const detailData = await fetchStationDetail(target.id);
+                if (detailData) {
+                    const stats = detailData.stats || {avg:0, std:0};
+                    document.getElementById('station-details').innerHTML = 
+                        `<div style="margin-top:10px;">
+                            <p><strong>Longitude:</strong> ${detailData.loc[0].toFixed(4)}</p>
+                            <p><strong>Latitude:</strong> ${detailData.loc[1].toFixed(4)}</p>
+                            <hr style="border:0; border-top:1px solid #444; margin:5px 0;">
+                            <p><strong>Avg Load:</strong> <span style="color:#00cec9">${stats.avg.toFixed(4)}</span></p>
+                            <p><strong>Stability:</strong> <span style="color:#fd79a8">${stats.std.toFixed(4)}</span></p>
+                        </div>`;
+                    
+                    if (detailData.bs_record) renderChart(detailData.bs_record);
+                }
+            } catch (e) {
+                console.error("Fetch details failed", e);
+            }
+
+            // Create red highlight marker for searched target
+            const marker = new mapboxgl.Marker({ color: '#ff0000', scale: 0.8 })
+                .setLngLat(target.loc)
+                .setPopup(new mapboxgl.Popup({ offset: 25 }).setText(`Station ID: ${target.id}`)) 
+                .addTo(map);
+            
+            searchMarkers.push(marker);
+
+        } else {
+            alert("Station ID not found!");
+        }
+    };
+
+    btn.onclick = performSearch;
+    
+    input.addEventListener('keypress', (e) => {
+        if (e.key === 'Enter') performSearch();
+    });
+
+    if (clearBtn) {
+        clearBtn.onclick = () => {
+            clearAllMarkers();
+            input.value = '';
+        };
+    }
+}
+
+// Sidebar & Panel Toggle Logic
+function setupPanelToggles(map) {
+    const leftSidebar = document.querySelector('.sidebar');
+    const leftToggleBtn = document.getElementById('toggle-left-btn');
+    
+    if (leftToggleBtn && leftSidebar) {
+        leftToggleBtn.addEventListener('click', () => {
+            leftSidebar.classList.toggle('collapsed');
+            leftToggleBtn.classList.toggle('collapsed'); 
+            leftToggleBtn.innerText = leftSidebar.classList.contains('collapsed') ? '▶' : '◀';
+            setTimeout(() => map.resize(), 300);
+        });
+    }
+
+    const rightSidebar = document.getElementById('prediction-panel');
+    const rightToggleBtn = document.getElementById('toggle-right-btn');
+    
+    if (rightToggleBtn && rightSidebar) {
+        rightToggleBtn.addEventListener('click', () => {
+            rightSidebar.classList.toggle('collapsed');
+            rightToggleBtn.classList.toggle('collapsed'); 
+            rightToggleBtn.innerText = rightSidebar.classList.contains('collapsed') ? '◀' : '▶';
+            setTimeout(() => map.resize(), 300);
+        });
+    }
+}
+
+// ==========================================
+// 9. Main Entry Point
+// ==========================================
+window.onload = async () => {
+    const map = initMap();
+    
+    map.on('load', async () => {
+        setupMapEnvironment(map);
+        
+        try {
+            // Load initial station metadata
+            const data = await fetchLocations();
+            globalStationData = data.stations;
+            document.getElementById('total-stations').innerText = globalStationData.length;
+
+            // Initialize Map Layers with empty data initially
+            addStationLayers(map, 
+                             {points: {type:'FeatureCollection', features:[]}, polys: {type:'FeatureCollection', features:[]} }, 
+                             data.stats_height, data.stats_color);
+            
+            // Immediately load data for T=0 (initial state)
+            updateGeoJSONData(map, globalStationData, 'time', 0);
+            updateChartCursor(0);
+
+            // Start Time Lapse
+            setupTimeLapse(map, globalStationData);
+            
+            // Bind Interactions
+            setupPredictionMode(map);   // Initialize AI Prediction events
+            setupInteraction(map);      // Initialize standard map clicks/popups
+            setupModeToggle(map);       // 2D/3D View switch
+            setupDataToggle(map);       // Layer visibility switch
+            setupFilterMenu(map, data.stats_color); // Load-stability filters
+            setupSearch(map, globalStationData);    // Search bar logic
+
+            // Initialize sidebar collapse/expand controls
+            setupPanelToggles(map);
+
+            // Remove Loading Screen
+            document.getElementById('loading').style.display = 'none';
+        } catch (e) {
+            console.error(e);
+            alert('System Initialization Failed. Check Console.');
+            document.getElementById('loading').innerHTML = '<h2>Error Loading Data</h2>';
+        }
+    });
+};

server.py

@@ -0,0 +1,269 @@
+import os
+import json
+import numpy as np
+import math
+from flask import Flask, jsonify, send_from_directory, request
+from flask_cors import CORS
+
+# Import the custom prediction backend module
+try:
+    from prediction_backend import TrafficPredictor
+except ImportError:
+    print("Warning: prediction_backend.py not found. Prediction features will be disabled.")
+    TrafficPredictor = None
+except Exception as e:
+    print(f"Warning: Failed to import prediction_backend: {e}")
+    TrafficPredictor = None
+
+# ==========================================
+# Flask Server 
+# ==========================================
+app = Flask(__name__, static_folder='.')
+CORS(app)
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+# Data directory path
+DATA_DIR = os.path.abspath(os.path.join(BASE_DIR, 'data')) 
+
+# File path configurations
+JSON_PATH = os.path.join(DATA_DIR, 'base2info.json')
+TRAFFIC_PATH = os.path.join(DATA_DIR, 'bs_record_energy_normalized_sampled.npz')
+SPATIAL_PATH = os.path.join(DATA_DIR, 'spatial_features.npz')
+MODEL_PATH = os.path.join(BASE_DIR, 'best_corr_model.pt') 
+
+# ==========================================
+# Utility Functions
+# ==========================================
+def calculate_std_dev(records, avg):
+    """Calculates standard deviation for a given set of records and their average."""
+    if not records or len(records) < 2:
+        return 0
+    variance = sum((x - avg) ** 2 for x in records) / len(records)
+    return math.sqrt(variance)
+
+def calculate_stats(data_list):
+    """Calculate global statistics for frontend normalization"""
+    print("Calculating statistical distribution (Avg & Std)...")
+    avgs = [] 
+    stds = [] 
+    
+    for item in data_list:
+        records = item.get('bs_record', [])
+        if records:
+            avg = sum(records) / len(records)
+            std = calculate_std_dev(records, avg)
+        else:
+            avg = 0
+            std = 0
+        avgs.append(avg)
+        stds.append(std)
+    
+    def get_percentiles(values):
+        """Calculates percentiles to create data brackets for visualization."""
+        values.sort()
+        n = len(values)
+        if n == 0: return {k:0 for k in ['min','max','t1','t2','t3','t4']}
+        return {
+            "min": values[0],
+            "max": values[-1],
+            "t1": values[int(n * 0.2)],
+            "t2": values[int(n * 0.4)],
+            "t3": values[int(n * 0.6)],
+            "t4": values[int(n * 0.8)]
+        }
+
+    stats_h = get_percentiles(avgs) # Statistics for pillar heights
+    stats_c = get_percentiles(stds) # Statistics for pillar colors (stability)
+    return stats_h, stats_c
+
+def _convert_numpy_type(val):
+    if isinstance(val, np.ndarray): return val.tolist()
+    elif isinstance(val, (np.integer, np.int64, np.int32, np.int16)): return int(val)
+    elif isinstance(val, (np.floating, np.float64, np.float32)): return float(val)
+    elif isinstance(val, bytes): return val.decode('utf-8')
+    else: return val
+
+def load_and_process_data(json_path, npz_path):
+    print(f"[DataLoader] Loading basic data...")
+    print(f"   - JSON: {json_path}")
+    print(f"   - Traffic NPZ : {npz_path}")
+
+    if not os.path.exists(json_path) or not os.path.exists(npz_path):
+        print("[DataLoader] Error: Input files not found.")
+        return []
+
+    try:
+        npz_data = np.load(npz_path)
+        with open(json_path, 'r', encoding='utf-8') as f:
+            json_map = json.load(f)
+    except Exception as e:
+        print(f"[DataLoader] Read error: {e}")
+        return []
+
+    # Handle binary strings if present in NPZ
+    raw_bs_ids = npz_data['bs_id']
+    bs_ids = [x.decode('utf-8') if isinstance(x, bytes) else str(x) for x in raw_bs_ids]
+    num_stations = len(bs_ids)
+    
+    # Identify available time-series attributes in NPZ
+    station_attributes = []
+    for key in npz_data.files:
+        if key == 'bs_id': continue
+        if npz_data[key].shape[0] == num_stations:
+            station_attributes.append(key)
+    
+    merged_data = []
+    match_count = 0
+
+    for i in range(num_stations):
+        current_id = bs_ids[i]
+        json_key = f"Base_{current_id}" 
+
+        if json_key in json_map:
+            match_count += 1
+            entry = {
+                "id": current_id,
+                "npz_index": i, # Store original index for prediction lookups
+                "loc": json_map[json_key]["loc"]
+            }
+            for attr in station_attributes:
+                val = npz_data[attr][i]
+                entry[attr] = _convert_numpy_type(val)
+            merged_data.append(entry)
+
+    print(f"[DataLoader] Merge complete! Matched: {match_count}/{num_stations}")
+    return merged_data
+
+# ==========================================
+# Initialization Sequence
+# ==========================================
+
+print("Server Initializing...")
+
+# 1. Load basic station data for frontend display
+ALL_DATA = load_and_process_data(JSON_PATH, TRAFFIC_PATH)
+
+STATS_HEIGHT = {} 
+STATS_COLOR = {}  
+
+if ALL_DATA:
+    STATS_HEIGHT, STATS_COLOR = calculate_stats(ALL_DATA)
+else:
+    print("⚠️ CRITICAL WARNING: Data list is empty!")
+
+# 2. Initialize AI Predictor with Spatial Features
+predictor = None
+if TrafficPredictor:
+    try:
+        print(f"[AI] Initializing Predictor with model: {MODEL_PATH}")
+        # Initialize the predictor using the model and spatial feature files
+        predictor = TrafficPredictor(
+            model_path=MODEL_PATH, 
+            spatial_path=SPATIAL_PATH, 
+            traffic_path=TRAFFIC_PATH
+        )
+        print("[AI] Predictor loaded successfully.")
+    except Exception as e:
+        print(f"[AI] Failed to load predictor: {e}")
+
+# ==========================================
+# API Routes
+# ==========================================
+
+@app.route('/')
+def index():
+    """Serves the main dashboard page."""
+    return send_from_directory('.', 'index.html')
+
+@app.route('/<path:path>')
+def serve_static(path):
+    """Serves static assets (JS, CSS, Images)."""
+    return send_from_directory('.', path)
+
+@app.route('/api/stations/locations')
+def get_station_locations():
+    """Returns a lightweight list of station coordinates and statistical summaries."""
+    lightweight_data = []
+    for item in ALL_DATA:
+        records = item.get('bs_record', [])
+        if records:
+            avg = sum(records) / len(records)
+            std = calculate_std_dev(records, avg)
+        else:
+            avg = 0
+            std = 0
+            
+        lightweight_data.append({
+            "id": item['id'],
+            "loc": item['loc'],
+            "val_h": avg,
+            "val_c": std,
+            "vals": records 
+        })
+    
+    return jsonify({
+        "stats_height": STATS_HEIGHT,
+        "stats_color": STATS_COLOR,
+        "stations": lightweight_data
+    })
+
+@app.route('/api/stations/detail/<station_id>')
+def get_station_detail(station_id):
+    """Returns detailed metadata and stats for a specific station."""
+    for item in ALL_DATA:
+        if str(item['id']) == str(station_id):
+            records = item.get('bs_record', [])
+            avg = sum(records)/len(records) if records else 0
+            std = calculate_std_dev(records, avg)
+            
+            response = item.copy()
+            response['stats'] = {"avg": avg, "std": std}
+            return jsonify(response)
+            
+    return jsonify({"error": "Station not found"}), 404
+
+@app.route('/api/predict/<station_id>')
+def predict_traffic(station_id):
+    """Triggers the ML model to predict future traffic for a specific station."""
+    if not predictor:
+        return jsonify({"error": "Prediction service not available"}), 503
+    
+    try:
+        target_idx = -1
+        
+        # Map Station ID to its internal index in the NPZ file
+        for item in ALL_DATA:
+            if str(item['id']) == str(station_id):
+                target_idx = item.get('npz_index', -1)
+                break
+        
+        if target_idx == -1:
+            # Fallback: Check if the ID provided is directly a numerical index
+            if str(station_id).isdigit():
+                target_idx = int(station_id)
+            else:
+                return jsonify({"error": "Station ID not found in mapping"}), 404
+
+        # Execute prediction through the ML backend
+        result = predictor.predict(target_idx)
+        
+        if "error" in result:
+            return jsonify(result), 500
+            
+        return jsonify(result)
+
+    except Exception as e:
+        print(f"Prediction Error: {e}")
+        return jsonify({"error": str(e)}), 500
+
+# Local development server
+# if __name__ == '__main__':
+#     print(f"Monitoring Data Directory: {DATA_DIR}")
+#     print("Server running on http://127.0.0.1:5000")
+#     app.run(debug=True, port=5000)
+
+# FOR ONLINE
+if __name__ == '__main__':
+    print(f"Monitoring Data Directory: {DATA_DIR}")
+    print("Server running on port 7860...")
+    app.run(host='0.0.0.0', port=7860)  # <--- 就改这一行！取消 debug=True，改 host 和 port

style.css

@@ -0,0 +1,617 @@
+/* =========================================
+   1. Base Reset & Layout
+   ========================================= */
+   * {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+    /* Clean sans-serif stack for readability in high-tech interfaces */
+    font-family: 'Segoe UI', 'Roboto', Helvetica, Arial, sans-serif;
+}
+
+body {
+    background: #0f0c29; /* Deep space navy */
+    color: #e0e0e0;
+    height: 100vh;
+    overflow: hidden; /* Prevents browser scrollbars during panel transitions */
+    display: flex;  /* Sidebars and main content align horizontally */
+}
+
+/* =========================================
+   2. Loading Overlay
+   ========================================= */
+.loading-overlay {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: #0f0c29;
+    z-index: 9999;  /* Ensure it stays above map and sidebars */
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    transition: opacity 0.8s ease-out;
+}
+
+.spinner {
+    width: 50px;
+    height: 50px;
+    border: 3px solid rgba(0, 206, 201, 0.1);
+    border-top: 3px solid #00cec9;  /* Neon teal accent */
+    border-radius: 50%;
+    animation: spin 1s infinite cubic-bezier(0.55, 0.15, 0.45, 0.85);
+    margin-bottom: 20px;
+}
+
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+
+/* =========================================
+   3. Left Sidebar (Main Controls)
+   ========================================= */
+.sidebar {
+    width: 380px;
+    background: rgba(15, 23, 42, 0.85); 
+    backdrop-filter: blur(20px) saturate(180%);
+    /* Glassmorphism: blur effect creates depth against the map */
+    -webkit-backdrop-filter: blur(20px) saturate(180%);
+    padding: 25px;
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+    box-shadow: 10px 0 30px rgba(0,0,0,0.5);
+    z-index: 10;
+    border-right: 1px solid rgba(255,255,255,0.05);
+    overflow-y: auto;
+}
+
+.header h1 { 
+    font-size: 24px; 
+    font-weight: 300; 
+    letter-spacing: 1px; 
+    /* Gradient text for futuristic branding */
+    background: linear-gradient(to right, #00cec9, #a29bfe); 
+    -webkit-background-clip: text; 
+    -webkit-text-fill-color: transparent; 
+}
+
+/* Search Section in Left Sidebar */
+.search-section {
+    margin-top: 15px;
+    margin-bottom: 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.search-container {
+    display: flex;
+    gap: 8px;
+}
+
+#search-input {
+    flex: 1;
+    background: rgba(15, 23, 42, 0.6);
+    border: 1px solid rgba(0, 206, 201, 0.4);
+    color: #fff;
+    padding: 6px 10px;
+    border-radius: 4px;
+    outline: none;
+    font-family: 'Courier New', monospace;  /* "Code" feel for data input */
+    font-size: 14px;
+}
+
+#search-input:focus { 
+    border-color: #00cec9; 
+    box-shadow: 0 0 8px rgba(0, 206, 201, 0.2); 
+}
+
+.search-mode {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 11px;
+    color: #94a3b8;
+    padding-left: 2px;
+}
+
+.search-mode input { cursor: pointer; accent-color: #00cec9; }
+.search-mode label { cursor: pointer; }
+
+/* Small Utility Buttons */
+.cyber-btn-small {
+    background: rgba(0, 206, 201, 0.1);
+    color: #00cec9;
+    border: 1px solid #00cec9;
+    padding: 0 12px;
+    border-radius: 4px;
+    cursor: pointer;
+    font-weight: bold;
+    transition: all 0.2s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.cyber-btn-small:hover { 
+    background: #00cec9; 
+    color: #000; 
+}
+
+#clear-search-btn {
+    border-color: #fd79a8;
+    color: #fd79a8;
+    background: rgba(253, 121, 168, 0.1);
+}
+
+#clear-search-btn:hover { 
+    background: #fd79a8; 
+    color: #fff; 
+}
+
+/* Cards & Charts */
+.card { 
+    background: rgba(255, 255, 255, 0.03); 
+    padding: 20px; 
+    border-radius: 12px; 
+    border: 1px solid rgba(255,255,255,0.02);
+    transition: transform 0.2s, background 0.2s;
+}
+
+.card:hover { 
+    background: rgba(255, 255, 255, 0.05); 
+    border-color: rgba(0, 206, 201, 0.2); 
+}
+
+.card h2 { 
+    font-size: 12px; 
+    color: #94a3b8; 
+    margin-bottom: 15px; 
+    border-bottom: 1px solid rgba(255,255,255,0.05); 
+    padding-bottom: 8px; 
+    text-transform: uppercase; 
+    font-weight: 600; 
+}
+
+.chart-container { 
+    height: 140px; 
+    width: 100%; 
+    position: relative;
+}
+
+.stat-row { 
+    display: flex; 
+    justify-content: space-between; 
+    margin-bottom: 5px; 
+}
+
+.value { 
+    font-size: 18px; 
+    font-weight: 500; 
+    color: #f1f5f9; 
+    font-family: 'Courier New', monospace; 
+}
+
+.value.highlight { color: #00cec9; }
+
+.details-content p { 
+    font-size: 13px; 
+    line-height: 1.8; 
+    color: #cbd5e1; 
+}
+
+/* =========================================
+   4. Main Content & Map Area
+   ========================================= */
+.main-content { 
+    flex: 1; 
+    height: 100%; 
+    position: relative; 
+    overflow: hidden; 
+}
+
+#map { width: 100%; height: 100%; }
+
+/* Mapbox Popup Overrides */
+.mapboxgl-popup-content { 
+    background: rgba(15, 23, 42, 0.95) !important; 
+    border: 1px solid rgba(0, 206, 201, 0.5); 
+    box-shadow: 0 0 15px rgba(0, 206, 201, 0.2); 
+    padding: 8px 12px !important; 
+    border-radius: 6px !important; 
+    color: #e0e0e0; 
+    min-width: 120px; 
+}
+.mapboxgl-popup-tip { 
+    border-top-color: rgba(0, 206, 201, 0.5) !important; 
+    margin-bottom: -1px; 
+}
+
+/* =========================================
+   5. Top-Left Controls
+   ========================================= */
+.controls-container { 
+    position: absolute; 
+    top: 20px; 
+    left: 20px; 
+    z-index: 100; 
+    display: flex; 
+    gap: 10px; 
+}
+
+.cyber-btn { 
+    background: rgba(15, 23, 42, 0.9); 
+    color: #00cec9; 
+    border: 1px solid #00cec9; 
+    padding: 10px 20px; 
+    font-size: 14px; 
+    font-weight: 600; 
+    border-radius: 4px; 
+    cursor: pointer; 
+    box-shadow: 0 0 10px rgba(0, 206, 201, 0.2); 
+    transition: all 0.3s ease; 
+    display: flex; 
+    align-items: center; 
+    gap: 8px;
+    text-transform: uppercase; 
+    letter-spacing: 1px; 
+    white-space: nowrap; 
+}
+
+.cyber-btn:hover { 
+    background: rgba(0, 206, 201, 0.15); 
+    box-shadow: 0 0 20px rgba(0, 206, 201, 0.4); 
+    transform: translateY(-1px); 
+}
+
+/* Filter Menu */
+.filter-wrapper { position: relative; display: inline-block; }
+
+.filter-menu { 
+    position: absolute; 
+    top: 50px; 
+    left: 0; 
+    width: 170px; 
+    background: rgba(15, 23, 42, 0.95); 
+    border: 1px solid #00cec9; 
+    border-radius: 4px; 
+    padding: 8px; 
+    display: flex; 
+    flex-direction: column; 
+    gap: 6px; 
+    opacity: 0; 
+    visibility: hidden; 
+    transform: translateY(-10px); 
+    transition: all 0.3s ease; 
+    box-shadow: 0 5px 20px rgba(0,0,0,0.5); 
+}
+
+.filter-menu.active { 
+    opacity: 1; 
+    visibility: visible; 
+    transform: translateY(0); 
+}
+
+.filter-item { 
+    display: flex; 
+    align-items: center; 
+    gap: 10px; 
+    padding: 8px 10px; 
+    border-radius: 4px; 
+    cursor: pointer; 
+    transition: background 0.2s; 
+    font-size: 12px; 
+    color: #ccc; 
+    border: 1px solid transparent; 
+}
+
+.filter-item:hover { background: rgba(255, 255, 255, 0.1); }
+
+.filter-item.selected { 
+    background: rgba(0, 206, 201, 0.2); 
+    border-color: rgba(0, 206, 201, 0.5); 
+    color: #fff; font-weight: bold; 
+}
+
+.color-box { width: 12px; height: 12px; border-radius: 2px; }
+
+/* =========================================
+   6. Bottom Time Panel
+   ========================================= */
+.time-panel { 
+    position: absolute; 
+    bottom: 40px; 
+    left: 50%; 
+    transform: translateX(-50%); 
+    width: 60%; 
+    min-width: 500px; 
+    height: 70px; 
+    background: rgba(15, 23, 42, 0.9); 
+    border: 1px solid #00cec9; 
+    box-shadow: 0 0 20px rgba(0, 206, 201, 0.15), inset 0 0 50px rgba(0,0,0,0.6); 
+    backdrop-filter: blur(10px); 
+    border-radius: 50px; 
+    z-index: 100; 
+    display: flex; 
+    align-items: center; 
+    padding: 0 25px; 
+    gap: 20px; 
+}
+
+.play-control { 
+    min-width: 45px; 
+    height: 45px; 
+    border-radius: 50%; 
+    justify-content: center; 
+    padding: 0; 
+    font-size: 18px; 
+    border-width: 2px; 
+}
+
+.digital-clock { 
+    font-family: 'Courier New', monospace; 
+    font-size: 20px; 
+    font-weight: bold; 
+    color: #00cec9; 
+    text-shadow: 0 0 8px rgba(0, 206, 201, 0.8); 
+    background: rgba(0, 0, 0, 0.4); 
+    padding: 5px 12px; 
+    border-radius: 6px; 
+    border: 1px solid rgba(0, 206, 201, 0.2); 
+    min-width: 80px; 
+    text-align: center; 
+}
+
+.slider-wrapper { 
+    flex: 1; 
+    display: flex; 
+    flex-direction: column; 
+    justify-content: center; 
+    position: relative; 
+    margin-top: -2px; 
+}
+
+.slider-ticks { 
+    display: flex; 
+    justify-content: space-between; 
+    margin-top: 8px; 
+    font-size: 10px; 
+    color: #64748b; 
+    font-family: monospace; 
+    padding: 0 2px; 
+}
+
+#time-slider { 
+    -webkit-appearance: none; 
+    width: 100%; 
+    height: 4px; 
+    background: rgba(255, 255, 255, 0.1); 
+    border-radius: 2px; 
+    outline: none; 
+    cursor: pointer; 
+    transition: background 0.3s; 
+}
+
+#time-slider:hover { background: rgba(255, 255, 255, 0.2); }
+
+#time-slider::-webkit-slider-thumb { 
+    -webkit-appearance: none; 
+    width: 22px; 
+    height: 22px; 
+    border-radius: 50%; 
+    background: #0f172a; 
+    border: 2px solid #00cec9; 
+    box-shadow: 0 0 10px #00cec9; 
+    margin-top: 0px; 
+    transition: transform 0.1s; 
+}
+
+#time-slider::-webkit-slider-thumb:hover { 
+    transform: scale(1.2); 
+    background: #00cec9; 
+}
+
+/* =========================================
+   7. Right Sidebar (Prediction Mode)
+   ========================================= */
+/* Container for the sliding panel */
+.sidebar-right {
+    position: fixed;
+    top: 0;
+    right: -450px; /* Hidden by default */
+    width: 400px;
+    height: 100vh;
+    background: rgba(10, 10, 30, 0.95);
+    border-left: 1px solid #f39c12; 
+    backdrop-filter: blur(10px);
+    transition: right 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    z-index: 1000;
+    padding: 25px;
+    color: #fff;
+    box-shadow: -10px 0 30px rgba(0,0,0,0.5);
+    display: flex;
+    flex-direction: column; 
+    overflow-y: auto; 
+}
+/* Active state (Slid in) */
+.sidebar-right.active {
+    right: 0;
+}
+
+/* Custom Cyber-Scrollbar for Prediction Sidebar */
+.sidebar-right::-webkit-scrollbar {
+    width: 6px;
+}
+.sidebar-right::-webkit-scrollbar-track {
+    background: rgba(0, 0, 0, 0.3);
+}
+.sidebar-right::-webkit-scrollbar-thumb {
+    background: #f39c12;
+    border-radius: 3px;
+}
+.sidebar-right::-webkit-scrollbar-thumb:hover {
+    background: #e67e22;
+}
+
+/* Header within right sidebar */
+.sidebar-right .header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    border-bottom: 1px solid rgba(243, 156, 18, 0.3);
+    padding-bottom: 15px;
+    margin-bottom: 20px;
+}
+
+.sidebar-right h1 {
+    font-size: 20px;
+    background: linear-gradient(to right, #f39c12, #f1c40f);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+}
+
+/* Close button for right sidebar */
+#close-pred-btn {
+    border-color: #666;
+    color: #aaa;
+    background: transparent;
+}
+#close-pred-btn:hover {
+    border-color: #fff;
+    color: #fff;
+    background: rgba(255,255,255,0.1);
+}
+
+/* Prediction specific button states */
+#predict-toggle.predict-on {
+    background: rgba(243, 156, 18, 0.2);
+    box-shadow: 0 0 20px rgba(243, 156, 18, 0.4);
+    border-color: #f39c12;
+    color: #f39c12;
+}
+
+/* Legend items in prediction panel */
+.legend-box {
+    margin-top: auto; /* Push to bottom if needed, or just normal flow */
+    border: 1px solid rgba(255,255,255,0.1);
+}
+
+.dot { 
+    width: 10px; 
+    height: 10px; 
+    display: inline-block; 
+    border-radius: 50%; 
+    margin-right: 8px; 
+}
+
+
+/* =========================================
+   8. Map Custom Pins & AI Log Visuals
+   ========================================= */
+   .optimal-pulse-pin {
+    width: 20px;
+    height: 20px;
+    background-color: #2ecc71;
+    border-radius: 50%;
+    border: 3px solid #ffffff;
+    box-shadow: 0 0 15px #2ecc71, 0 0 30px #2ecc71;
+    animation: optimal-pulse 1.5s infinite cubic-bezier(0.66, 0, 0, 1);
+    cursor: pointer;
+}
+
+@keyframes optimal-pulse {
+    to {
+        box-shadow: 0 0 0 20px rgba(46, 204, 113, 0);
+        background-color: rgba(46, 204, 113, 0.8);
+    }
+}
+
+.cyber-explanation {
+    margin-top: 12px;
+    padding: 12px;
+    background: rgba(0, 206, 201, 0.05);
+    border-left: 3px solid #00cec9;
+    border-radius: 0 4px 4px 0;
+    font-size: 11px;
+    color: #a29bfe;
+    font-family: 'Courier New', Courier, monospace;
+    line-height: 1.6;
+    box-shadow: inset 0 0 10px rgba(0, 206, 201, 0.05);
+}
+
+.cyber-explanation strong {
+    color: #00cec9;
+    font-weight: bold;
+}
+
+/* =========================================
+   9. Panel Toggle Buttons & Navigation UI
+   ========================================= */
+.sidebar {
+    transition: margin-left 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    position: relative;
+}
+.sidebar.collapsed {
+    margin-left: -380px; 
+}
+.sidebar-right.active.collapsed {
+    right: -400px; 
+}
+
+/* Sticky toggle buttons on panel edges */
+.panel-toggle-btn {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 22px;
+    height: 60px;
+    background: rgba(15, 23, 42, 0.9);
+    border: 1px solid #00cec9;
+    color: #00cec9;
+    cursor: pointer;
+    z-index: 1000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 10px;
+    box-shadow: 0 0 10px rgba(0, 206, 201, 0.2);
+    backdrop-filter: blur(5px);
+    transition: all 0.2s ease;
+    outline: none;
+}
+
+.panel-toggle-btn:hover {
+    background: #00cec9;
+    color: #000;
+    box-shadow: 0 0 15px rgba(0, 206, 201, 0.5);
+}
+
+/* Positioning logic for sidebars toggles */
+.left-toggle {
+    left: 380px; /* Aligned with sidebar width */
+    border-left: none;
+    border-radius: 0 6px 6px 0;
+    transition: left 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+.left-toggle.collapsed {
+    left: 0; 
+}
+
+.right-toggle {
+    right: -22px; /* Starts hidden */
+    border-right: none;
+    border-radius: 6px 0 0 6px;
+    transition: right 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+.right-toggle.active {
+    right: 400px; 
+}
+.right-toggle.collapsed {
+    right: 0; 
+}