1. 項目概述從零開始駕馭海浪模擬的利器最近在折騰一個海洋數(shù)值模擬相關(guān)的項目需要用到海浪譜模型WaveWatch III通常簡稱為WW3自然就成了繞不開的工具。這可不是一個能一鍵安裝的桌面軟件而是一個由NOAA等機構(gòu)維護的、用于模擬全球或區(qū)域尺度海浪的Fortran數(shù)值模型。網(wǎng)上能找到的官方文檔和零散的安裝指南不少但要么過于簡略跳過了關(guān)鍵細節(jié)要么環(huán)境老舊已經(jīng)不適用。我花了幾天時間在Linux系統(tǒng)上從源碼編譯、配置到成功運行測試案例踩了不少坑也總結(jié)出一套相對穩(wěn)定可靠的流程。這篇筆記就詳細記錄下整個過程特別是那些官方手冊里沒明說、但實際操作中一定會遇到的“坎兒”目標是讓你能避開我走過的彎路順利地把WW3環(huán)境搭起來并跑通第一個例子。無論你是海洋學、氣象學的研究生還是從事海岸工程、航運預報的工程師只要需要用到海浪數(shù)值模擬WW3很可能就是你的核心工具之一。它的輸出如有效波高、譜峰周期、波浪傳播方向等是許多后續(xù)分析和應用的基礎(chǔ)。因此一個穩(wěn)定、編譯正確的WW3環(huán)境是第一步也是最關(guān)鍵的一步。整個過程會涉及到Linux基礎(chǔ)操作、編譯器選擇、環(huán)境變量配置、NetCDF庫的依賴處理以及MPI并行環(huán)境的搭建如果你想發(fā)揮多核計算能力的話我會一步步拆開講清楚。2. 環(huán)境準備與核心依賴解析在動手下載WW3源碼之前我們必須先把它的“家”給準備好。這個“家”主要指的就是編譯器和一系列科學計算必需的庫。WW3是用Fortran 90寫的所以一個現(xiàn)代的Fortran編譯器是必需品。同時它高度依賴NetCDF庫來讀寫輸入輸出文件這也是最容易出問題的地方。2.1 編譯器與基礎(chǔ)工具鏈選擇首先選擇一個合適的Fortran編譯器。常見的有GNU的gfortran、Intel的ifort和PGI的pgfortran。對于大多數(shù)用戶尤其是剛開始接觸和在學術(shù)環(huán)境下的我強烈推薦使用gfortran。原因很簡單它是開源的、免費且與大多數(shù)Linux發(fā)行版集成良好。Intel編譯器雖然理論上可能生成更優(yōu)化的代碼但其安裝和許可更復雜對于入門和測試來說gfortran的簡便性和穩(wěn)定性優(yōu)勢明顯。在Ubuntu或Debian系的系統(tǒng)上安裝基礎(chǔ)開發(fā)工具和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庫的依賴最關(guān)鍵的“一道坎”這是整個安裝過程中最具挑戰(zhàn)性的一環(huán)。WW3需要NetCDF庫而且它同時需要NetCDF的C接口和Fortran接口。更關(guān)鍵的是這些庫必須由同一個編譯器套件即你用來編譯WW3的gfortran和對應的gcc編譯而來。直接使用系統(tǒng)包管理器安裝的NetCDF例如sudo apt install libnetcdf-dev libnetcdff-dev很可能是因為它們是用系統(tǒng)默認的編譯器編譯的與你的gfortran環(huán)境不兼容在鏈接WW3時會遭遇令人頭疼的“未定義引用”錯誤。最可靠的方法是手動編譯安裝NetCDF庫及其依賴。這聽起來復雜但按順序來并不難。NetCDF庫依賴于HDF5和zlib等庫。我們需要按順序編譯zlib - HDF5 - NetCDF-C - NetCDF-Fortran。假設我們將所有庫安裝到/opt/ww3_libs目錄下你可以選擇其他有寫入權(quán)限的目錄。首先創(chuàng)建安裝目錄并下載源碼包export WW3_LIBS/opt/ww3_libs mkdir -p $WW3_LIBS/src $WW3_LIBS cd $WW3_LIBS/src # 下載源碼 (版本號可去官網(wǎng)更新為最新穩(wěn)定版) 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編譯器環(huán)境變量都要指向我們選定的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 # 如果需要安裝到系統(tǒng)目錄如/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 # 關(guān)鍵步驟必須導出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并行環(huán)境準備可選但推薦WW3支持MPI并行計算以加速大規(guī)模模擬。如果你有多核CPU或要在集群上運行建議安裝。常用的實現(xiàn)是OpenMPI或MPICH。同樣建議用系統(tǒng)包管理器安裝與編譯器兼容的版本。# Ubuntu/Debian sudo apt install openmpi-bin libopenmpi-dev # CentOS/RHEL sudo yum install openmpi openmpi-devel安裝后可以通過mpifort --version來確認MPI的Fortran包裝器是否調(diào)用了我們指定的gfortran。3. 獲取源碼與編譯配置實戰(zhàn)當所有依賴庫就位后我們就可以請出“主角”了。WW3的源代碼托管在GitHub上這使得獲取和更新代碼變得非常方便。3.1 克隆代碼倉庫與結(jié)構(gòu)初探打開終端找一個你打算存放項目的目錄執(zhí)行g(shù)it clone https://github.com/NOAA-EMC/WW3.git cd WW3克隆完成后你會看到一個結(jié)構(gòu)清晰的目錄樹。幾個關(guān)鍵目錄你需要了解model/WW3核心模型的源代碼所在地。work/這是你主要的工作目錄。里面存放了各種測試案例、編譯腳本和用于生成可執(zhí)行文件的鏈接文件。regtests/包含了大量的回歸測試用例用于驗證編譯是否正確以及模型功能是否正常。我們后續(xù)的測試就在這里進行。bin/編譯成功后生成的可執(zhí)行文件會放在這里或者你指定的位置。3.2 編譯配置文件的定制與解讀WW3的編譯系統(tǒng)并不使用常見的CMake或autotools而是采用了一套基于make和模板文件的機制其核心配置文件是work/ww3_makefile。我們需要根據(jù)我們的環(huán)境來修改它。首先我們復制一個模板過來cd work cp ../bin/makefile/makefile.gfortran ww3_makefile這里我們選擇了gfortran的模板。如果你用Intel編譯器就復制makefile.intel?，F(xiàn)在用文本編輯器如vim或nano打開ww3_makefile。我們需要關(guān)注以下幾個關(guān)鍵變量SHELL保持/bin/bash即可。LN鏈接命令保持ln -sf。CPPC預處理器用于處理Fortran代碼中的預處理指令。保持/lib/cpp -P -traditional。如果系統(tǒng)沒有/lib/cpp可能需要安裝cpp包或修改為/usr/bin/cpp。COMP編譯類型。對于測試我們選擇single單精度即可它比double雙精度運行更快且對于功能測試足夠。所以設置COMP single。CC,FC,MPICC,MPIFC這些是編譯器的設置。由于我們只用gfortran和可能用到的OpenMPI通常模板已經(jīng)設置好了如FC gfortran。檢查確保MPIFC mpif90。最關(guān)鍵的庫路徑和鏈接標志。這是將我們之前編譯的NetCDF庫告訴編譯器的步驟。你需要找到類似以下的行并進行修改# 示例你的路徑可能不同 INC4 -I/opt/ww3_libs/include LIB4 -L/opt/ww3_libs/lib -lnetcdff -lnetcdf -lhdf5_hl -lhdf5 -lz -lmINC4是包含頭文件的路徑LIB4是鏈接庫的路徑和庫列表。順序很重要必須按照依賴關(guān)系從最上層netcdff到最底層zlib排列。-lm是數(shù)學庫。DMY日期函數(shù)。保持DMY 空通常可以。修改保存后這個ww3_makefile就成為了你當前工作環(huán)境的編譯藍圖。3.3 執(zhí)行編譯與生成可執(zhí)行文件配置好后編譯過程本身反而很簡單。在work/目錄下執(zhí)行make clean # 清理之前的編譯結(jié)果如果是第一次可跳過 make all # 編譯所有組件make all命令會根據(jù)ww3_makefile中的配置編譯生成一系列可執(zhí)行文件例如ww3_grid網(wǎng)格生成器、ww3_prnc輸入數(shù)據(jù)預處理、ww3_shel主集成程序等。如果一切順利你會在work/目錄下看到這些可執(zhí)行文件或者它們被鏈接到了../bin/目錄下。實操心得編譯過程可能會輸出很多警告warning只要沒有錯誤error導致中斷通常可以忽略。如果遇到“未找到 -lnetcdff”或“無法識別 -lhdf5_hl”之類的錯誤請回頭仔細檢查LIB4和INC4的路徑是否正確以及庫文件是否確實存在于那些目錄中可以用ls /opt/ww3_libs/lib/查看。最常見的錯誤就是NetCDF庫的路徑或版本不匹配。4. 運行測試案例驗證安裝成功的“試金石”編譯成功只意味著代碼被轉(zhuǎn)換成了機器指令但模型邏輯是否正確、輸入輸出是否正常需要通過運行測試案例來驗證。WW3貼心地提供了regtests目錄里面包含了從簡單到復雜的各種測試。4.1 測試案例結(jié)構(gòu)與運行腳本剖析我們找一個最簡單的案例開始比如regtests/ww3_tp2.1這是一個雙網(wǎng)格點測試計算量極小幾秒鐘就跑完。進入該目錄cd ../regtests/ww3_tp2.1 ls你會看到一些.inp文件輸入配置文件、wind.nc之類的輸入數(shù)據(jù)文件以及一個關(guān)鍵的腳本run_test。這個腳本自動化了整個測試流程。在運行前我們最好先看一下這個腳本的內(nèi)容了解它做了什么cat run_test腳本內(nèi)容通常包括鏈接必要的輸入文件到工作目錄、運行ww3_grid生成mod_def網(wǎng)格文件、運行ww3_prnc處理強迫場數(shù)據(jù)、運行ww3_shel進行模式積分、最后運行ww3_ounf等程序進行后處理輸出。它是一系列標準操作流程的封裝。4.2 執(zhí)行測試與結(jié)果驗證要運行測試通常只需要./run_test或者如果腳本沒有執(zhí)行權(quán)限先chmod x run_test。腳本開始運行后會在終端輸出大量信息顯示各個組件正在執(zhí)行。如果一切正常最終你會看到腳本成功完成的提示并生成一系列輸出文件如out_grd.ww3網(wǎng)格信息、out_pnt.ww3點輸出以及NetCDF格式的結(jié)果文件。如何判斷測試是否真的成功看腳本退出狀態(tài)在終端中命令執(zhí)行完畢后輸入echo $?。如果返回0表示腳本正常退出?？摧敵鑫募z查是否有預期的輸出文件生成并且文件大小不為零。看日志與錯誤信息腳本運行過程中不應有FORTRAN STOP或ERROR等導致程序異常終止的信息。警告信息可能有一些需要根據(jù)內(nèi)容判斷是否影響結(jié)果。結(jié)果合理性檢查進階對于ww3_tp2.1這種標準測試其結(jié)果應該是可預期的。你可以快速用ncdump -h查看一下生成的NetCDF文件頭確認其中包含如hs有效波高等變量。4.3 測試過程中常見問題精講即使編譯通過了運行測試時也可能遇到問題。這里列舉幾個我遇到的典型情況“Cannot open netCDF file” 或 “NetCDF: Not a valid data type”問題根源這幾乎100%是NetCDF庫版本不匹配或鏈接錯誤造成的?？赡苁悄憔幾gWW3時鏈接的NetCDF庫版本與系統(tǒng)環(huán)境變量LD_LIBRARY_PATH指向的運行時庫版本不一致。解決方案確保你的LD_LIBRARY_PATH包含了自定義安裝的NetCDF庫路徑并且在運行測試前將其導出。export LD_LIBRARY_PATH/opt/ww3_libs/lib:$LD_LIBRARY_PATH ./run_test為了避免每次都要設置可以將這行命令添加到你的shell配置文件如~/.bashrc中。腳本執(zhí)行到一半報錯退出提示某個“.inp”文件找不到問題根源run_test腳本內(nèi)部通過軟鏈接來獲取輸入文件。如果WW3的目錄結(jié)構(gòu)被移動或者你在錯誤的位置執(zhí)行腳本鏈接就會失效。解決方案確保你在測試案例的目錄下例如regtests/ww3_tp2.1執(zhí)行腳本并且WW3的主目錄結(jié)構(gòu)完整。不要隨意移動regtests目錄。運行ww3_shel時卡住或非常慢問題根源如果你運行的不是最簡單的測試案例如ww3_tp2.1而是像ww3_ts1全球測試這樣的案例計算量會大很多。默認可能是串行運行。解決方案檢查測試案例目錄下是否有run_test.mpi腳本。如果有說明該測試支持并行。你需要確保MPI已正確安裝然后使用mpirun來運行例如mpirun -np 4 ./run_test.mpi使用4個進程。這能極大縮短計算時間。生成的結(jié)果文件內(nèi)容全是填充值如-999.9問題根源可能是強迫場數(shù)據(jù)風場、流場沒有正確鏈接或處理或者時間范圍設置有問題導致模型實際沒有接收到有效的驅(qū)動數(shù)據(jù)。解決方案仔細檢查run_test腳本中關(guān)于ww3_prnc強迫場預處理的部分確認輸入的風場文件如wind.nc被正確鏈接且其時間覆蓋了模擬時段。可以手動執(zhí)行ww3_prnc命令看看是否有錯誤輸出。5. 從測試到應用搭建自定義模擬工作流成功運行官方測試案例標志著你的WW3安裝基本正確。但這只是開始我們的最終目標是為了自己的研究區(qū)域或工程問題運行模擬。這就需要我們建立自己的工作流。5.1 工作目錄的標準化管理我強烈建議不要直接在regtests或work目錄下進行你的個人項目。最好的做法是創(chuàng)建一個獨立的工作目錄例如~/my_ww3_project并在此目錄下建立清晰的子文件夾結(jié)構(gòu)my_ww3_project/ ├── bin/ # 鏈接或復制WW3的可執(zhí)行文件到此 ├── grid/ # 存放網(wǎng)格生成相關(guān)文件 (.inp, 岸線數(shù)據(jù)等) ├── forc/ # 存放強迫場數(shù)據(jù) (風場.nc, 流場.nc等) ├── inp/ # 存放各種.inp配置文件 ├── out/ # 存放模型輸出結(jié)果 ├── log/ # 存放運行日志 └── scripts/ # 存放自己寫的運行腳本將編譯好的可執(zhí)行文件從WW3/work/鏈接到你的bin/目錄ln -s /path/to/WW3/work/ww3_* ~/my_ww3_project/bin/。5.2 核心輸入文件準備詳解一個完整的WW3模擬需要準備三個核心輸入文件它們通過.inp文件進行配置網(wǎng)格文件生成 (ww3_grid.inp)這是基礎(chǔ)。你需要定義模擬區(qū)域的網(wǎng)格經(jīng)緯度或笛卡爾坐標、水深、岸線掩碼等。最復雜的是準備水深數(shù)據(jù)文件和岸線數(shù)據(jù)文件。你可以從ETOPO、GEBCO等全球地形數(shù)據(jù)集獲取水深并使用GSHHS等岸線數(shù)據(jù)集。ww_grid.inp中需要指定這些文件的格式和路徑。運行ww3_grid后會生成一個二進制的mod_def.ww3文件供后續(xù)步驟使用。強迫場預處理 (ww3_prnc.inp)海浪需要風來驅(qū)動可能還需要水流場。你需要準備NetCDF格式的風場U10, V10等數(shù)據(jù)。ww3_prnc.inp文件用于告訴模型如何從你的NetCDF文件中讀取變量、時間和空間信息。運行ww3_prnc會生成wind.ww3這樣的二進制強迫場文件。主程序集成 (ww3_shel.inp)這是主控文件。在這里你設置模擬的起止時間、時間步長、輸出頻率、輸出類型譜、參數(shù)、重啟文件等、物理參數(shù)化方案源函數(shù)項風輸入、白冠耗散、非線性波波相互作用等。你需要指定前面生成的mod_def.ww3和強迫場文件。5.3 編寫自動化運行腳本手動依次執(zhí)行三個步驟容易出錯。編寫一個Shell腳本來自動化這個過程是專業(yè)做法。一個極簡的腳本框架如下#!/bin/bash # run_my_simulation.sh # 1. 設置環(huán)境變量 export LD_LIBRARY_PATH/opt/ww3_libs/lib:$LD_LIBRARY_PATH # 2. 生成網(wǎng)格 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!這個腳本包含了基本的錯誤檢查通過$?判斷上一條命令的退出狀態(tài)并將每個組件的輸出重定向到日志文件便于事后排查。5.4 結(jié)果后處理與可視化初步WW3默認的輸出是二進制或NetCDF格式。對于NetCDF輸出你可以使用多種工具進行后處理Python使用xarray和netCDF4庫讀取數(shù)據(jù)用matplotlib或cartopy進行繪圖。這是目前最靈活、最主流的方式。NCL在氣象海洋領(lǐng)域傳統(tǒng)深厚繪圖功能強大但已停止維護。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) # 創(chuàng)建地圖投影 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()從編譯安裝到運行測試再到建立自己的項目工作流這個過程確實涉及不少細節(jié)。最大的挑戰(zhàn)往往不在WW3本身而在其依賴環(huán)境的搭建尤其是NetCDF庫的手動編譯。一旦跨過這道坎后面按照手冊和示例操作就會順暢很多。建議在開始自己的科學模擬前多花時間研究幾個不同的regtests案例理解各種.inp文件的配置項含義這比直接啃理論手冊要直觀有效得多。