HarmonicFormer: Cross-Phase Harmonic Modeling for Efficient Long-Term Water Quality Forecasting

Water quality time series exhibit multi-scale periodicities, including daily and weekly cycles, driven by solar radiation, tidal forcing, and seasonal variation. Existing deep learning methods typically rely on patch-based attention or adaptive period decomposition, which suffer from parameter redundancy and high computational cost while failing to explicitly align with physical periodicities. To address this challenge, we propose HarmonicFormer, which restructures sequences into phase-period matrices, explicitly injects multi-scale periodic priors via harmonic temporal encoding, and achieves linear-complexity interactions through a lightweight cross-phase routing mechanism. Evaluated on hourly data from 37 monitoring stations in the Pearl River Basin (2020–2026) across nine water quality parameters and six forecast horizons, HarmonicFormer achieves the lowest average MSE of 0.3809 and MAE of 0.3753 over 54 experimental configurations, while maintaining high training efficiency and significantly reducing long-term error accumulation. Ablation studies confirm the effectiveness of harmonic encoding, reversible instance normalization, and key hyperparameters. This work offers an efficient and reliable explicit-periodicity modeling approach for water quality forecasting in the Pearl River Basin. Although the model currently adopts a fixed period length, future work can further enhance its generalization capability by introducing adaptive period discovery mechanisms.