1. 项目概述从零开始驾驭海浪模拟的利器最近在折腾一个海洋数值模拟相关的项目需要用到海浪谱模型WaveWatch III通常简称为WW3自然就成了绕不开的工具。这可不是一个能一键安装的桌面软件而是一个由NOAA等机构维护的、用于模拟全球或区域尺度海浪的Fortran数值模型。网上能找到的官方文档和零散的安装指南不少但要么过于简略跳过了关键细节要么环境老旧已经不适用。我花了几天时间在Linux系统上从源码编译、配置到成功运行测试案例踩了不少坑也总结出一套相对稳定可靠的流程。这篇笔记就详细记录下整个过程特别是那些官方手册里没明说、但实际操作中一定会遇到的“坎儿”目标是让你能避开我走过的弯路顺利地把WW3环境搭起来并跑通第一个例子。无论你是海洋学、气象学的研究生还是从事海岸工程、航运预报的工程师只要需要用到海浪数值模拟WW3很可能就是你的核心工具之一。它的输出如有效波高、谱峰周期、波浪传播方向等是许多后续分析和应用的基础。因此一个稳定、编译正确的WW3环境是第一步也是最关键的一步。整个过程会涉及到Linux基础操作、编译器选择、环境变量配置、NetCDF库的依赖处理以及MPI并行环境的搭建如果你想发挥多核计算能力的话我会一步步拆开讲清楚。2. 环境准备与核心依赖解析在动手下载WW3源码之前我们必须先把它的“家”给准备好。这个“家”主要指的就是编译器和一系列科学计算必需的库。WW3是用Fortran 90写的所以一个现代的Fortran编译器是必需品。同时它高度依赖NetCDF库来读写输入输出文件这也是最容易出问题的地方。2.1 编译器与基础工具链选择首先选择一个合适的Fortran编译器。常见的有GNU的gfortran、Intel的ifort和PGI的pgfortran。对于大多数用户尤其是刚开始接触和在学术环境下的我强烈推荐使用gfortran。原因很简单它是开源的、免费且与大多数Linux发行版集成良好。Intel编译器虽然理论上可能生成更优化的代码但其安装和许可更复杂对于入门和测试来说gfortran的简便性和稳定性优势明显。在Ubuntu或Debian系的系统上安装基础开发工具和gfortran非常直接sudo apt update sudo apt install build-essential gfortran m4这里build-essential包含了make、gcc等核心工具m4是一个宏处理器WW3的编译脚本会用到它。如果你用的是CentOS、RHEL或Fedora对应的命令可能是sudo yum groupinstall Development Tools和sudo yum install gcc-gfortran m4。注意请务必确认你的gfortran版本。太旧的版本如早于7.x可能不支持某些Fortran 2003/2008特性导致编译失败。可以通过gfortran --version查看。我使用的是gfortran 11.3.0整个过程很顺利。2.2 NetCDF库的依赖最关键的“一道坎”这是整个安装过程中最具挑战性的一环。WW3需要NetCDF库而且它同时需要NetCDF的C接口和Fortran接口。更关键的是这些库必须由同一个编译器套件即你用来编译WW3的gfortran和对应的gcc编译而来。直接使用系统包管理器安装的NetCDF例如sudo apt install libnetcdf-dev libnetcdff-dev很可能是因为它们是用系统默认的编译器编译的与你的gfortran环境不兼容在链接WW3时会遭遇令人头疼的“未定义引用”错误。最可靠的方法是手动编译安装NetCDF库及其依赖。这听起来复杂但按顺序来并不难。NetCDF库依赖于HDF5和zlib等库。我们需要按顺序编译zlib - HDF5 - NetCDF-C - NetCDF-Fortran。假设我们将所有库安装到/opt/ww3_libs目录下你可以选择其他有写入权限的目录。首先创建安装目录并下载源码包export WW3_LIBS/opt/ww3_libs mkdir -p $WW3_LIBS/src $WW3_LIBS cd $WW3_LIBS/src # 下载源码 (版本号可去官网更新为最新稳定版) wget https://zlib.net/zlib-1.2.13.tar.gz wget https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.14/hdf5-1.14.3/src/hdf5-1.14.3.tar.gz wget https://github.com/Unidata/netcdf-c/archive/refs/tags/v4.9.2.tar.gz -O netcdf-c-4.9.2.tar.gz wget https://github.com/Unidata/netcdf-fortran/archive/refs/tags/v4.6.1.tar.gz -O netcdf-fortran-4.6.1.tar.gz接下来是编译安装。核心原则每一步的CCC编译器和FCFortran编译器环境变量都要指向我们选定的gcc和gfortran并且--prefix指定安装路径。编译安装zlibtar -xzf zlib-1.2.13.tar.gz cd zlib-1.2.13 ./configure --prefix$WW3_LIBS make make check # 可选运行测试 sudo make install # 如果需要安装到系统目录如/usr/local则需要sudo cd ..编译安装HDF5tar -xzf hdf5-1.14.3.tar.gz cd hdf5-1.14.3 # 这里必须设置CC为gcc并指定zlib路径 CCgcc ./configure --prefix$WW3_LIBS --with-zlib$WW3_LIBS --enable-hl --enable-fortran make -j4 # 使用4个核心并行编译加快速度 make check sudo make install cd ..注意--enable-fortran是必须的因为NetCDF-Fortran依赖HDF5的Fortran接口。编译安装NetCDF-Ctar -xzf netcdf-c-4.9.2.tar.gz cd netcdf-c-4.9.2 # 设置CPPFLAGS和LDFLAGS来告诉编译器HDF5和zlib的位置 CPPFLAGS-I$WW3_LIBS/include LDFLAGS-L$WW3_LIBS/lib CCgcc ./configure --prefix$WW3_LIBS --disable-dap make -j4 make check sudo make install cd ..编译安装NetCDF-Fortrantar -xzf netcdf-fortran-4.6.1.tar.gz cd netcdf-fortran-4.6.1 # 关键步骤必须导出NetCDF-C的路径并指定Fortran编译器 export LD_LIBRARY_PATH$WW3_LIBS/lib:$LD_LIBRARY_PATH CPPFLAGS-I$WW3_LIBS/include LDFLAGS-L$WW3_LIBS/lib FCgfortran ./configure --prefix$WW3_LIBS make -j4 make check sudo make install cd ..完成后可以测试一下Fortran接口是否正常nf-config --flibs和nc-config --libs应该能正确输出库链接信息。2.3 MPI并行环境准备可选但推荐WW3支持MPI并行计算以加速大规模模拟。如果你有多核CPU或要在集群上运行建议安装。常用的实现是OpenMPI或MPICH。同样建议用系统包管理器安装与编译器兼容的版本。# Ubuntu/Debian sudo apt install openmpi-bin libopenmpi-dev # CentOS/RHEL sudo yum install openmpi openmpi-devel安装后可以通过mpifort --version来确认MPI的Fortran包装器是否调用了我们指定的gfortran。3. 获取源码与编译配置实战当所有依赖库就位后我们就可以请出“主角”了。WW3的源代码托管在GitHub上这使得获取和更新代码变得非常方便。3.1 克隆代码仓库与结构初探打开终端找一个你打算存放项目的目录执行git clone https://github.com/NOAA-EMC/WW3.git cd WW3克隆完成后你会看到一个结构清晰的目录树。几个关键目录你需要了解model/WW3核心模型的源代码所在地。work/这是你主要的工作目录。里面存放了各种测试案例、编译脚本和用于生成可执行文件的链接文件。regtests/包含了大量的回归测试用例用于验证编译是否正确以及模型功能是否正常。我们后续的测试就在这里进行。bin/编译成功后生成的可执行文件会放在这里或者你指定的位置。3.2 编译配置文件的定制与解读WW3的编译系统并不使用常见的CMake或autotools而是采用了一套基于make和模板文件的机制其核心配置文件是work/ww3_makefile。我们需要根据我们的环境来修改它。首先我们复制一个模板过来cd work cp ../bin/makefile/makefile.gfortran ww3_makefile这里我们选择了gfortran的模板。如果你用Intel编译器就复制makefile.intel。现在用文本编辑器如vim或nano打开ww3_makefile。我们需要关注以下几个关键变量SHELL保持/bin/bash即可。LN链接命令保持ln -sf。CPPC预处理器用于处理Fortran代码中的预处理指令。保持/lib/cpp -P -traditional。如果系统没有/lib/cpp可能需要安装cpp包或修改为/usr/bin/cpp。COMP编译类型。对于测试我们选择single单精度即可它比double双精度运行更快且对于功能测试足够。所以设置COMP single。CC,FC,MPICC,MPIFC这些是编译器的设置。由于我们只用gfortran和可能用到的OpenMPI通常模板已经设置好了如FC gfortran。检查确保MPIFC mpif90。最关键的库路径和链接标志。这是将我们之前编译的NetCDF库告诉编译器的步骤。你需要找到类似以下的行并进行修改# 示例你的路径可能不同 INC4 -I/opt/ww3_libs/include LIB4 -L/opt/ww3_libs/lib -lnetcdff -lnetcdf -lhdf5_hl -lhdf5 -lz -lmINC4是包含头文件的路径LIB4是链接库的路径和库列表。顺序很重要必须按照依赖关系从最上层netcdff到最底层zlib排列。-lm是数学库。DMY日期函数。保持DMY 空通常可以。修改保存后这个ww3_makefile就成为了你当前工作环境的编译蓝图。3.3 执行编译与生成可执行文件配置好后编译过程本身反而很简单。在work/目录下执行make clean # 清理之前的编译结果如果是第一次可跳过 make all # 编译所有组件make all命令会根据ww3_makefile中的配置编译生成一系列可执行文件例如ww3_grid网格生成器、ww3_prnc输入数据预处理、ww3_shel主集成程序等。如果一切顺利你会在work/目录下看到这些可执行文件或者它们被链接到了../bin/目录下。实操心得编译过程可能会输出很多警告warning只要没有错误error导致中断通常可以忽略。如果遇到“未找到 -lnetcdff”或“无法识别 -lhdf5_hl”之类的错误请回头仔细检查LIB4和INC4的路径是否正确以及库文件是否确实存在于那些目录中可以用ls /opt/ww3_libs/lib/查看。最常见的错误就是NetCDF库的路径或版本不匹配。4. 运行测试案例验证安装成功的“试金石”编译成功只意味着代码被转换成了机器指令但模型逻辑是否正确、输入输出是否正常需要通过运行测试案例来验证。WW3贴心地提供了regtests目录里面包含了从简单到复杂的各种测试。4.1 测试案例结构与运行脚本剖析我们找一个最简单的案例开始比如regtests/ww3_tp2.1这是一个双网格点测试计算量极小几秒钟就跑完。进入该目录cd ../regtests/ww3_tp2.1 ls你会看到一些.inp文件输入配置文件、wind.nc之类的输入数据文件以及一个关键的脚本run_test。这个脚本自动化了整个测试流程。在运行前我们最好先看一下这个脚本的内容了解它做了什么cat run_test脚本内容通常包括链接必要的输入文件到工作目录、运行ww3_grid生成mod_def网格文件、运行ww3_prnc处理强迫场数据、运行ww3_shel进行模式积分、最后运行ww3_ounf等程序进行后处理输出。它是一系列标准操作流程的封装。4.2 执行测试与结果验证要运行测试通常只需要./run_test或者如果脚本没有执行权限先chmod x run_test。脚本开始运行后会在终端输出大量信息显示各个组件正在执行。如果一切正常最终你会看到脚本成功完成的提示并生成一系列输出文件如out_grd.ww3网格信息、out_pnt.ww3点输出以及NetCDF格式的结果文件。如何判断测试是否真的成功看脚本退出状态在终端中命令执行完毕后输入echo $?。如果返回0表示脚本正常退出。看输出文件检查是否有预期的输出文件生成并且文件大小不为零。看日志与错误信息脚本运行过程中不应有FORTRAN STOP或ERROR等导致程序异常终止的信息。警告信息可能有一些需要根据内容判断是否影响结果。结果合理性检查进阶对于ww3_tp2.1这种标准测试其结果应该是可预期的。你可以快速用ncdump -h查看一下生成的NetCDF文件头确认其中包含如hs有效波高等变量。4.3 测试过程中常见问题精讲即使编译通过了运行测试时也可能遇到问题。这里列举几个我遇到的典型情况“Cannot open netCDF file” 或 “NetCDF: Not a valid data type”问题根源这几乎100%是NetCDF库版本不匹配或链接错误造成的。可能是你编译WW3时链接的NetCDF库版本与系统环境变量LD_LIBRARY_PATH指向的运行时库版本不一致。解决方案确保你的LD_LIBRARY_PATH包含了自定义安装的NetCDF库路径并且在运行测试前将其导出。export LD_LIBRARY_PATH/opt/ww3_libs/lib:$LD_LIBRARY_PATH ./run_test为了避免每次都要设置可以将这行命令添加到你的shell配置文件如~/.bashrc中。脚本执行到一半报错退出提示某个“.inp”文件找不到问题根源run_test脚本内部通过软链接来获取输入文件。如果WW3的目录结构被移动或者你在错误的位置执行脚本链接就会失效。解决方案确保你在测试案例的目录下例如regtests/ww3_tp2.1执行脚本并且WW3的主目录结构完整。不要随意移动regtests目录。运行ww3_shel时卡住或非常慢问题根源如果你运行的不是最简单的测试案例如ww3_tp2.1而是像ww3_ts1全球测试这样的案例计算量会大很多。默认可能是串行运行。解决方案检查测试案例目录下是否有run_test.mpi脚本。如果有说明该测试支持并行。你需要确保MPI已正确安装然后使用mpirun来运行例如mpirun -np 4 ./run_test.mpi使用4个进程。这能极大缩短计算时间。生成的结果文件内容全是填充值如-999.9问题根源可能是强迫场数据风场、流场没有正确链接或处理或者时间范围设置有问题导致模型实际没有接收到有效的驱动数据。解决方案仔细检查run_test脚本中关于ww3_prnc强迫场预处理的部分确认输入的风场文件如wind.nc被正确链接且其时间覆盖了模拟时段。可以手动执行ww3_prnc命令看看是否有错误输出。5. 从测试到应用搭建自定义模拟工作流成功运行官方测试案例标志着你的WW3安装基本正确。但这只是开始我们的最终目标是为了自己的研究区域或工程问题运行模拟。这就需要我们建立自己的工作流。5.1 工作目录的标准化管理我强烈建议不要直接在regtests或work目录下进行你的个人项目。最好的做法是创建一个独立的工作目录例如~/my_ww3_project并在此目录下建立清晰的子文件夹结构my_ww3_project/ ├── bin/ # 链接或复制WW3的可执行文件到此 ├── grid/ # 存放网格生成相关文件 (.inp, 岸线数据等) ├── forc/ # 存放强迫场数据 (风场.nc, 流场.nc等) ├── inp/ # 存放各种.inp配置文件 ├── out/ # 存放模型输出结果 ├── log/ # 存放运行日志 └── scripts/ # 存放自己写的运行脚本将编译好的可执行文件从WW3/work/链接到你的bin/目录ln -s /path/to/WW3/work/ww3_* ~/my_ww3_project/bin/。5.2 核心输入文件准备详解一个完整的WW3模拟需要准备三个核心输入文件它们通过.inp文件进行配置网格文件生成 (ww3_grid.inp)这是基础。你需要定义模拟区域的网格经纬度或笛卡尔坐标、水深、岸线掩码等。最复杂的是准备水深数据文件和岸线数据文件。你可以从ETOPO、GEBCO等全球地形数据集获取水深并使用GSHHS等岸线数据集。ww_grid.inp中需要指定这些文件的格式和路径。运行ww3_grid后会生成一个二进制的mod_def.ww3文件供后续步骤使用。强迫场预处理 (ww3_prnc.inp)海浪需要风来驱动可能还需要水流场。你需要准备NetCDF格式的风场U10, V10等数据。ww3_prnc.inp文件用于告诉模型如何从你的NetCDF文件中读取变量、时间和空间信息。运行ww3_prnc会生成wind.ww3这样的二进制强迫场文件。主程序集成 (ww3_shel.inp)这是主控文件。在这里你设置模拟的起止时间、时间步长、输出频率、输出类型谱、参数、重启文件等、物理参数化方案源函数项风输入、白冠耗散、非线性波波相互作用等。你需要指定前面生成的mod_def.ww3和强迫场文件。5.3 编写自动化运行脚本手动依次执行三个步骤容易出错。编写一个Shell脚本来自动化这个过程是专业做法。一个极简的脚本框架如下#!/bin/bash # run_my_simulation.sh # 1. 设置环境变量 export LD_LIBRARY_PATH/opt/ww3_libs/lib:$LD_LIBRARY_PATH # 2. 生成网格 echo Step 1: Running ww3_grid... ./bin/ww3_grid log/grid.log 21 if [ $? -ne 0 ]; then echo Grid generation failed!; exit 1; fi # 3. 预处理强迫场 echo Step 2: Running ww3_prnc... ./bin/ww3_prnc log/prnc.log 21 if [ $? -ne 0 ]; then echo Forcing preprocessing failed!; exit 1; fi # 4. 运行主模型 echo Step 3: Running ww3_shel... # 如果是并行运行使用 mpirun -np N ./bin/ww3_shel ./bin/ww3_shel log/shel.log 21 if [ $? -ne 0 ]; then echo Model run failed!; exit 1; fi echo All steps completed successfully!这个脚本包含了基本的错误检查通过$?判断上一条命令的退出状态并将每个组件的输出重定向到日志文件便于事后排查。5.4 结果后处理与可视化初步WW3默认的输出是二进制或NetCDF格式。对于NetCDF输出你可以使用多种工具进行后处理Python使用xarray和netCDF4库读取数据用matplotlib或cartopy进行绘图。这是目前最灵活、最主流的方式。NCL在气象海洋领域传统深厚绘图功能强大但已停止维护。MATLAB也有相应的NetCDF读写工具包。一个简单的Python脚本用于读取并绘制有效波高场示例import xarray as xr import matplotlib.pyplot as plt import cartopy.crs as ccrs # 打开WW3输出的NetCDF文件 ds xr.open_dataset(out/ww3.201210.nc) # 假设变量名是hs选择第一个时间步 hs ds[hs].isel(time0) # 创建地图投影 fig plt.figure(figsize(12, 8)) ax plt.axes(projectionccrs.PlateCarree()) ax.coastlines(resolution10m) # 绘制填色图 plot hs.plot(axax, transformccrs.PlateCarree(), cmapjet, add_colorbarTrue, cbar_kwargs{label: Significant Wave Height (m)}) ax.set_title(WW3 Model Output - Hs) plt.show()从编译安装到运行测试再到建立自己的项目工作流这个过程确实涉及不少细节。最大的挑战往往不在WW3本身而在其依赖环境的搭建尤其是NetCDF库的手动编译。一旦跨过这道坎后面按照手册和示例操作就会顺畅很多。建议在开始自己的科学模拟前多花时间研究几个不同的regtests案例理解各种.inp文件的配置项含义这比直接啃理论手册要直观有效得多。