WRF-Hydro水文模型编译运行实操与避坑指南

WRF-Hydro是在WRF陆面过程框架基础上发展的新一代分布式水文模型，核心目标是模拟大气与水文过程之间的耦合互动。模型采用Fortran 90编写，具备高空间分辨率、较全面的物理过程刻画、与气象模式耦合、分布式模拟架构、动态适应性强及支持数据同化等优势，广泛应用于洪水预报、水资源管理、生态水文研究、气候变化影响评估与水电工程规划等场景。适用范围：Linux环境、Fortran编译链可用；Windows用户可通过虚拟机搭建隔离环境。 然而模型落地涉及数据制备、代码编译、系统操作等多环节，对初学者存在一定门槛。本文围绕平台搭建、源码编译与离线运行三个层面，提供可直接执行的技术参考。

一、模型功能定位与运行流程概览

WRF-Hydro采用模块化设计，大致可划分为四大模块：陆面过程模块负责下渗、蒸散发、土壤水分等垂向水量与能量交换；地表汇流模块基于栅格地形进行坡面汇流演算；河道汇流模块处理河网洪水演进；数据同化与输出模块统一管理NetCDF格式结果。各模块既可独立运行，也可通过耦合接口与气象模式联动。

一次完整模拟通常包含以下阶段：①准备静态地理数据与气象强迫数据；②配置模型控制文件与参数表；③编译生成可执行程序；④执行离线或耦合运行；⑤对NetCDF输出进行后处理与可视化。理解此流程有助于排错时快速定位问题环节。

二、运行平台与依赖库准备

2.1 怎么选编译器与外部链接库

Intel方案（推荐追求性能）： 使用Intel OneAPI或旧版Intel Parallel Studio，核心命令为ifort（Fortran）与mpiicc（C）。

免费替代方案： gfortran（GNU Fortran）+ OpenMPI，适合预算有限或学术环境，编译命令为mpif90与mpicc。

外部链接库方面，NetCDF是输入输出事实标准，需同时安装C与Fortran接口版本。建议版本约束：NetCDF-C ≥ 4.6、NetCDF-Fortran ≥ 4.5、HDF5 ≥ 1.10、zlib ≥ 1.2。 安装顺序务必为：先编译zlib → 再编译HDF5 → 最后编译NetCDF，否则极易因链接顺序导致兼容错误。并行运行还需MPI库（Intel MPI或OpenMPI），部分模块可能依赖HDF5底层支持。

2.2 Linux基础环境搭建

模型官方支持Linux。若无独立服务器，可在Windows主机上通过VMware或VirtualBox安装Ubuntu 20.04/22.04或CentOS 7/8。安装时建议为虚拟机分配≥50 GB磁盘空间与≥8 GB内存，因为静态地理数据与模拟输出占用较大存储。重要提醒：定期对虚拟机做快照备份，避免编译中断或误操作导致数据丢失。 系统就绪后，配置网络、软件源与基础开发工具链（build-essential或Development Tools）。

2.3 编译环境与后处理环境配置

以Intel为例，安装后在~/.bashrc中添加：

source /opt/intel/oneapi/setvars.sh
export PATH=/opt/intel/oneapi/mpi/latest/bin:$PATH
export LD_LIBRARY_PATH=/opt/netcdf/lib:$LD_LIBRARY_PATH

使用apt安装依赖库示例：

sudo apt-get install -y libnetcdf-dev libnetcdff-dev libhdf5-dev zlib1g-dev openmpi-bin libopenmpi-dev

验证Fortran接口是否正常：编译一个读取NetCDF的小程序，确认无链接报错。

后处理方面，建议创建独立Python环境：

conda create -n wrfhydro python=3.10
conda activate wrfhydro
pip install xarray numpy netCDF4 matplotlib jupyter

借助xarray可方便读取多维NetCDF变量，结合Jupyter实现交互式可视化。

三、源码结构与编译实践

3.1 关键配置文件与编译步骤

WRF-Hydro源码根目录下包含核心物理模块、驱动层与编译框架。编译前需修改hydro.configure（或类似名称的模板脚本），指定编译器类型、NetCDF路径与并行选项。典型编译流程如下：

1. 设置环境变量（见2.3节示例）；
2. 选择配置模板：cp hydro.configure.example hydro.configure并编辑；
3. 执行配置脚本：./hydro.configure；
4. 执行编译命令：make -j 4（串行用make，并行指定核心数）；
5. 检查可执行文件：确认wrf_hydro.exe（或wrf_hydro_offline）生成且可运行。

每一步都应确认返回状态，避免错误被后续步骤掩盖。建议保留完整编译日志。

3.2 常见错误排查对照表

错误现象	可能原因	处置步骤
链接错误（undefined reference）	库路径未设置或版本不匹配	检查LD_LIBRARY_PATH，确认NetCDF/HDF5版本≥要求
段错误（Segmentation fault）	编译器版本与源码要求不一致	核对ifort/gfortran版本，尝试降低优化等级-O1
模块缺失（No such file）	编译顺序或依赖模块未就绪	清理后make clean重新编译，确认模块依赖关系
权限拒绝	文件无执行权限	chmod +x wrf_hydro.exe

四、初步运行与输入输出处理

模型运行依赖三类输入：静态地理数据（地形、土地利用、土壤类型，可从UCAR或官方示例页面下载）、气象强迫数据（降水、温度等）、控制文件与参数表。初次运行建议使用官方示例区域文件，以最小配置验证环境。运行时需重点关注控制文件中的起止时间、区域范围与输出频率，确保与输入数据匹配。

输出以NetCDF格式保存，包含径流、土壤水分、蒸散发等变量。最小后处理代码示例：

import xarray as xr, matplotlib.pyplot as plt
ds = xr.open_dataset('wrfhydro_output.nc')
ds['SFCRNOFF'].isel(time=0).plot(cmap='Blues')
plt.title('Surface Runoff')
plt.show()

也可使用ncview wrfhydro_output.nc快速浏览。建议在初步运行阶段就建立规范的后处理脚本。

五、典型案例实践

案例1：示例文件径流模拟
使用官方示例区域，设置时间步长60 s、总模拟时长24 h、输出频率每小时。运行后绘制流量过程线，检查洪峰时间与量级是否合理，建立对模型行为的直观认识。

案例2：冷启动与热启动
冷启动从初始状态（通常为零或气候态）开始积分；热启动读取已有状态文件（如RESTART.nc）继续运行。实践建议：先冷启动配合12–24 h预热期使土壤湿度趋于平衡，再以热启动开展正式模拟，减少初始条件对结果的影响。

案例3：替换高质量降水资料
将默认降水替换为站点观测或再分析数据时，需注意：①时间分辨率统一（如逐小时）；②空间插值到模型栅格；③单位一致性（mm/h）。替换后对比径流过程线，评估降水输入对洪水响应的影响，此环节对洪水预报应用尤为关键。

六、小结

WRF-Hydro工程落地涵盖环境搭建、依赖库配置、源码编译、数据制备与结果分析等环节。本文补充了具体配置文件名、版本约束、安装命令与排错对照表，强调了依赖库安装顺序与后处理脚本规范化。掌握本流程后，读者可进一步探索模型与WRF气象模式的耦合运行及参数率定等进阶主题，为流域水文模拟与洪水预报提供坚实技术支撑。