1. 项目概述为什么要在Linux下折腾Telemac-Mascaret如果你正在读这篇文章大概率是和我一样被一个叫Telemac-Mascaret的水动力模拟系统给“缠”上了。这玩意儿在水利、海洋、环境工程领域是个响当当的角色能模拟从河流、河口到近海的复杂水流、泥沙输运和水质变化。但它的官方安装包尤其是那动辄几个G的预编译版本用起来总感觉隔靴搔痒——要么环境依赖对不上要么想改点底层代码无从下手。所以源码编译就成了我们这些想真正“掌控”它的人的必经之路。选择在Linux下进行编译几乎是唯一明智的选择。这倒不是对Windows有偏见而是这类大型科学计算软件的血脉里就流淌着Unix的基因。从高效的并行计算支持MPI、到复杂的库依赖管理NetCDF, HDF5, METIS再到编译工具链gfortran, gcc的成熟度Linux环境提供了最原生、最稳定的土壤。你在Windows上可能折腾一星期都搞不定的库链接错误在Linux下往往几行apt-get或yum命令就能迎刃而解。更别提后续的高性能计算集群部署几乎清一色是Linux的天下。因此这篇记录就是我趟过源码编译这条河后留下的最详细的一份“过河指南”目标是把所有隐藏的暗礁和漩涡都给你标出来。2. 编译环境准备打造坚实的基石编译Telemac-Mascaret不是简单的./configure make它更像是在搭建一个精密仪器的工作台。工作台不稳后面的一切都是空中楼阁。2.1 系统与基础工具选择首先选一个你熟悉的Linux发行版。Ubuntu系列20.04 LTS, 22.04 LTS和CentOS/Rocky Linux系列7, 8是社区支持最广的。我个人更推荐Ubuntu因为其软件源丰富解决依赖问题相对轻松。如果你身处科研机构服务器可能是CentOS系那本文的步骤你也完全适用只是包管理命令从apt换为yum或dnf。接下来是基础编译工具这是无论如何都绕不开的第一步# Ubuntu/Debian sudo apt update sudo apt install -y build-essential gfortran gcc g cmake git wget curl autoconf automake libtool # CentOS/Rocky Linux sudo yum groupinstall -y Development Tools sudo yum install -y gcc-gfortran gcc-c cmake git wget curl autoconf automake libtool这里有个关键点务必确认gfortran的版本。Telemac-Mascaret的源码主要是Fortran夹杂部分C对Fortran编译器版本有要求。太老的版本如gfortran-7可能缺少某些特性太新的版本如gfortran-13有时会有兼容性警告虽通常不影响编译但看着烦。经过多次测试gfortran-9 到 gfortran-11是一个比较稳妥的区间。安装后可以用gfortran --version查看。2.2 核心依赖库的安装与避坑Telemac-Mascaret依赖一批第三方科学计算库它们是功能实现的基础。我们必须源码编译其中一部分以确保版本和配置的绝对可控。1. MPI库并行计算的发动机没有MPI你就无法利用多核CPU或计算集群。我们选用应用最广的OpenMPI。wget https://download.open-mpi.org/release/open-mpi/v4.1/openmpi-4.1.5.tar.gz tar -zxvf openmpi-4.1.5.tar.gz cd openmpi-4.1.5 ./configure --prefix/opt/openmpi-4.1.5 CCgcc CXXg FCgfortran make -j$(nproc) # 使用所有CPU核心加速编译 sudo make install注意--prefix参数指定了安装目录。我强烈建议将其安装到/opt或/usr/local下的自定义路径而不是默认的/usr。这样便于多版本管理卸载时也干净利落直接删除整个目录即可。编译完成后将以下内容添加到你的~/.bashrc文件中export PATH/opt/openmpi-4.1.5/bin:$PATH export LD_LIBRARY_PATH/opt/openmpi-4.1.5/lib:$LD_LIBRARY_PATH export MANPATH/opt/openmpi-4.1.5/share/man:$MANPATH执行source ~/.bashrc后用mpifort --version和mpirun --version验证安装。2. HDF5和NetCDF库数据存储的基石HDF5是底层数据格式NetCDF依赖HDF5是地球科学领域的事实标准数据接口。必须先装HDF5再装NetCDF且两者都需要启用并行IO即与MPI集成以支持高性能并行数据读写。# 编译安装并行版HDF5 wget https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.14/hdf5-1.14.3/src/hdf5-1.14.3.tar.gz tar -zxvf hdf5-1.14.3.tar.gz cd hdf5-1.14.3 ./configure --prefix/opt/hdf5-1.14.3-parallel --enable-parallel --enable-fortran CCmpicc CXXmpicxx FCmpifort make -j$(nproc) sudo make install # 编译安装并行版NetCDFC库 wget https://github.com/Unidata/netcdf-c/archive/refs/tags/v4.9.2.tar.gz -O netcdf-c-4.9.2.tar.gz tar -zxvf netcdf-c-4.9.2.tar.gz cd netcdf-c-4.9.2 CPPFLAGS-I/opt/hdf5-1.14.3-parallel/include LDFLAGS-L/opt/hdf5-1.14.3-parallel/lib ./configure --prefix/opt/netcdf-c-4.9.2-parallel --enable-parallel-tests --disable-dap make -j$(nproc) sudo make install # 编译安装NetCDF Fortran接口 wget https://github.com/Unidata/netcdf-fortran/archive/refs/tags/v4.6.1.tar.gz -O netcdf-fortran-4.6.1.tar.gz tar -zxvf netcdf-fortran-4.6.1.tar.gz cd netcdf-fortran-4.6.1 CPPFLAGS-I/opt/netcdf-c-4.9.2-parallel/include -I/opt/hdf5-1.14.3-parallel/include LDFLAGS-L/opt/netcdf-c-4.9.2-parallel/lib -L/opt/hdf5-1.14.3-parallel/lib ./configure --prefix/opt/netcdf-fortran-4.6.1-parallel make -j$(nproc) sudo make install实操心得这是最容易出错的一环。configure阶段的错误提示往往晦涩难懂。最关键的是确保环境变量CPPFLAGS和LDFLAGS正确指向了依赖库的头文件和库文件路径。如果遇到“找不到hdf5.h”或“undefined reference to H5Fopen”这类错误十有八九是这两个变量没设对。编译完记得同样将安装路径的bin和lib目录加入环境变量。3. METIS/ParMETIS网格分区利器对于大规模并行计算需要将计算网格划分成多个子区域分配给不同进程。METIS串行和ParMETIS并行就是干这个的。# 安装METIS wget http://glaros.dtc.umn.edu/gkhome/fetch/sw/metis/metis-5.1.0.tar.gz tar -zxvf metis-5.1.0.tar.gz cd metis-5.1.0 make config prefix/opt/metis-5.1.0 make -j$(nproc) sudo make install # 安装ParMETIS (需要MPI) wget http://glaros.dtc.umn.edu/gkhome/fetch/sw/parmetis/parmetis-4.0.3.tar.gz tar -zxvf parmetis-4.0.3.tar.gz cd parmetis-4.0.3 make config prefix/opt/parmetis-4.0.3 make -j$(nproc) sudo make install将它们的lib目录路径加入LD_LIBRARY_PATH。2.3 Python与辅助工具新版本的Telemac配置和前后处理大量使用Python。我们需要一个独立的Python环境如conda或venv避免污染系统Python。# 使用Miniconda创建独立环境 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3 source ~/miniconda3/bin/activate conda create -n telemac python3.9 numpy scipy matplotlib pandas jupyter conda activate telemac pip install pyqt5 # 部分GUI工具需要这个telemac环境将用于后续的配置和脚本运行。3. 源码获取与配置系统解析环境准备好后我们开始处理主角——Telemac-Mascaret源码。3.1 获取源码的两种途径途径一从官方Git仓库克隆推荐这是获取最新代码和参与社区贡献的方式。你需要先注册一个账号。git clone https://gitlab.com/telemac-mascaret/telemac-mascaret.git cd telemac-mascaret # 查看所有版本标签选择一个稳定版例如v8p4r1 git tag -l | grep v8p git checkout v8p4r1途径二下载发布版压缩包在官方网站或Git仓库的Release页面可以找到打包好的稳定版源码如telemac-mascaret-v8p4r1.tar.gz。这种方式下载的代码不需要git历史更干净。3.2 理解目录结构与配置系统解压或克隆后你会看到一个庞大的目录树。核心结构如下telemac-mascaret/ ├── configs/ # 不同系统和编译器的配置文件模板 ├── sources/ # 所有模块的Fortran/C源码 │ ├── telemac2d/ # 二维水动力模块 │ ├── telemac3d/ # 三维水动力模块 │ ├── artemis/ # 波浪模块 │ └── ... # 其他模块泥沙、水质等 ├── scripts/ # Python配置和运行脚本 └── examples/ # 各模块的测试算例它的编译不是传统的CMake或Autotools而是一套自研的、基于Python和make的配置系统。核心配置文件是根目录下的configurePython脚本和configs/下的系统模板文件如config-pc-linux-gfortran-mpi.cfg。我们的任务就是根据我们刚才精心准备的编译环境自定义路径的MPI、HDF5、NetCDF等修改或创建一个属于自己的配置文件告诉编译系统去哪里找这些库用什么编译器。3.3 创建并定制专属配置文件进入configs/目录找一个最接近你环境的模板复制并修改。例如复制LinuxgfortranMPI的模板cd telemac-mascaret cp configs/systel-pc-linux-gfortran-mpi.cfg myconfig.cfg然后用文本编辑器如vim或nano仔细编辑myconfig.cfg。以下是几个最关键的配置段及其解释[build] # 使用的编程语言和编译器 languages fortran c fortran_compiler mpifort # 使用MPI封装的Fortran编译器 c_compiler mpicc # 使用MPI封装的C编译器 cpp_compiler mpicxx # 编译和链接标志优化等级O2是平衡性能与稳定性的好选择 fflags_opt -O2 -fPIC -ffree-line-length-none cflags_opt -O2 -fPIC ldflags -fPIC [api] # 启用并行和关键库支持 enable_mpi yes enable_parallel_io yes # 启用并行IO必须与HDF5/NetCDF的并行编译匹配 enable_hdf5 yes enable_netcdf yes enable_metis yes [paths] # 这是核心指定我们之前编译安装的库的路径 mpi_dir /opt/openmpi-4.1.5 hdf5_dir /opt/hdf5-1.14.3-parallel netcdf_dir /opt/netcdf-c-4.9.2-parallel netcdff_dir /opt/netcdf-fortran-4.6.1-parallel metis_dir /opt/metis-5.1.0 parmetis_dir /opt/parmetis-4.0.3注意事项ffree-line-length-none这个选项对gfortran至关重要因为Telemac源码中有很多超长的Fortran代码行没有这个选项编译会报错。-fPIC位置无关代码对于生成共享库是必要的。4. 编译、安装与验证全流程配置完成后就进入了最激动人心也最可能出错的编译环节。4.1 执行配置与编译首先运行配置脚本并指定你的配置文件# 确保在telemac-mascaret根目录下且conda的telemac环境已激活 python ./configure --config-filemyconfig.cfg如果配置成功脚本会生成必要的Makefile和路径设置文件。如果失败它会明确告诉你哪个库没找到或哪个检查没通过。请根据错误信息回头检查myconfig.cfg中的路径是否正确以及对应的库是否真的安装成功并加入了环境变量。配置成功后开始编译全部模块make all -j$(nproc)-j$(nproc)代表使用你电脑所有的CPU核心进行并行编译能极大缩短时间。这个过程视机器性能可能需要30分钟到数小时。4.2 安装与环境变量最终设置编译成功后并非像普通软件那样make install到系统目录。Telemac的“安装”更像是构建完成。我们需要设置一系列环境变量来告诉系统如何找到这些新编译好的可执行文件和库。创建一个设置脚本例如set_telemac_env.sh#!/bin/bash # 设置Telemac根目录 export TELEMAC_ROOT/path/to/your/telemac-mascaret # 将编译好的可执行文件目录加入PATH export PATH$TELEMAC_ROOT/builds/linux-gfortran-mpi/bin:$PATH # 将模块和库文件目录加入相关路径 export PYTHONPATH$TELEMAC_ROOT/scripts/python3:$PYTHONPATH export LD_LIBRARY_PATH$TELEMAC_ROOT/builds/linux-gfortran-mpi/lib:$LD_LIBRARY_PATH # 同时确保之前安装的第三方库路径也在LD_LIBRARY_PATH中 export LD_LIBRARY_PATH/opt/openmpi-4.1.5/lib:/opt/hdf5-1.14.3-parallel/lib:/opt/netcdf-c-4.9.2-parallel/lib:/opt/netcdf-fortran-4.6.1-parallel/lib:/opt/metis-5.1.0/lib:$LD_LIBRARY_PATH # 激活conda环境如果使用 conda activate telemac每次需要使用Telemac前执行source set_telemac_env.sh即可。4.3 运行测试算例验证安装最可靠的验证方法就是跑一个自带的例子。我们以二维水动力模块telemac2d为例# 进入算例目录 cd $TELEMAC_ROOT/examples/telemac2d/bump # 使用Telemac提供的运行脚本执行算例 telemac2d.py bump.cas这个bump算例是一个经典的二维明渠流动测试计算量小几分钟内就能完成。观察终端输出如果没有“ERROR”字样的报错并且最终生成了结果文件如bump.slf,bump.cli就说明从编译到运行的整个链条全部打通了你可以用ParaView或Telemac自带的rubens后处理工具打开bump.slf文件查看模拟出的水流场这会给你带来巨大的成就感。5. 常见编译与运行问题深度排查即使按照指南你也可能遇到问题。下面是我踩过坑后总结的“排错手册”。5.1 编译阶段经典错误错误1:mpifort: command not found现象配置或编译一开始就报错。原因MPI环境变量未正确加载或mpifort未安装。解决执行which mpifort确认。如果找不到回到2.2节确保OpenMPI安装路径的bin已加入PATH并执行了source ~/.bashrc。错误2:H5Fopen或nc_open等未定义引用现象链接阶段linking报出一大串undefined reference to ...错误。原因这是最典型的库链接顺序问题。编译器在链接时需要找到这些函数的具体实现它们位于HDF5和NetCDF的库文件中。如果链接顺序不对或者库路径没指定就会报错。解决首先确认myconfig.cfg中[paths]章节的路径绝对正确。检查环境变量LD_LIBRARY_PATH是否包含了所有第三方库的lib目录。可以用echo $LD_LIBRARY_PATH查看。有时需要显式指定库文件。可以尝试编辑Telemac源码中configs/目录下对应你系统模板的Makefile在链接标志LIBS中手动添加-lhdf5_fortran -lhdf5 -lnetcdff -lnetcdf等并确保它们的顺序符合依赖关系被依赖的库放在后面。错误3: Fortran代码行过长错误现象编译具体源文件时报错Line truncated或Statement too long。原因gfortran默认的代码行长度限制不够。解决确保在myconfig.cfg的fflags_opt中已经添加了-ffree-line-length-none选项。5.2 运行阶段典型问题问题1: 运行时找不到共享库.so文件现象运行telemac2d.py时报错error while loading shared libraries: lib...so: cannot open shared object file。原因系统动态链接器找不到Telemac自己编译的或第三方依赖的共享库。解决这再次强调了环境变量LD_LIBRARY_PATH的重要性。确保它包含了Telemac编译输出目录下的lib文件夹如$TELEMAC_ROOT/builds/linux-gfortran-mpi/lib。所有第三方库的lib文件夹如OpenMPI, HDF5, NetCDF的路径。 执行ldd $(which telemac2d)可以查看可执行文件依赖的库及其找到的位置是诊断此问题的利器。问题2: MPI运行时错误现象使用多进程运行如mpirun -n 4 telemac2d.py ...时失败提示权限错误或无法启动进程。原因OpenMPI需要无密码SSH互信才能在多台机器或同一台机器的多个进程间通信。即使是单机多进程有时也需要设置。解决为当前用户配置本地SSH无密码登录ssh-keygen -t rsa # 一直回车 cat ~/.ssh/id_rsa.pub ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys然后尝试运行mpirun -n 2 hostname应该能正确输出两次主机名。问题3: 并行计算结果与串行不一致现象使用不同进程数计算同一个算例结果有微小差异。原因这是浮点数并行计算的固有特性。由于网格分区、进程间求和的顺序不同会导致浮点数运算的舍入误差round-off error累积方式不同。只要差异在1e-10或1e-12量级就属于正常现象并非程序错误。解决无需解决这是科学计算并行化的普遍现象。在分析结果时关注物理量的整体趋势和量级而非小数点后十几位。6. 核心模块使用初探与性能调优安装成功只是开始用它高效地解决问题才是目的。6.1 各模块简介与用例选择Telemac-Mascaret是一个模块化系统常用模块包括TELEMAC-2D/3D核心水动力模块分别用于二维深度平均和三维自由表面流动模拟。适用于河流洪水、河口潮汐、水库流动等。ARTEMIS波浪传播模拟模块基于缓坡方程用于港口震荡、波浪折射绕射分析。TOMAWAC第三代波浪谱模型用于近岸区域波浪生成和传播。GAIA泥沙输运模块可与2D/3D耦合模拟河床演变。WAQTEL水质生态模块模拟温度、溶解氧、营养盐等。选择哪个模块取决于你的物理问题。新手建议从examples里的telemac2d/bump或telemac3d/lock-exchange开始理解从网格、边界条件、参数设置到运行、后处理的完整流程。6.2 关键配置文件解析一个Telemac算例的核心是一个后缀为.cas的文本配置文件旧版可能是.dat。它控制了模拟的所有参数。理解几个关键段落至关重要/ 这是一个注释行 FORTRAN FILE bump.f ! 定义几何边界的Fortran文件 GEOMETRY FILE bump.slf ! 网格文件SELAFIN格式 ... / 数值参数部分 NUMBER OF TIME STEPS 1000 TIME STEP 0.1 ... / 物理参数部分 GRAVITY ACCELERATION 9.81 FRICTION COEFFICIENT 0.02 ... / 边界条件部分 BOUNDARY CONDITIONS FILE bump.cli实操心得修改算例时最稳妥的方法是复制一份examples中的案例在其基础上修改。直接修改原文件一旦出错很难回溯。另外.cas文件对格式如空格、换行不敏感但关键词必须拼写正确。错误的关键词会被忽略可能导致运行时出现意想不到的默认行为。6.3 并行计算性能调优建议在集群上运行大规模模拟时性能是关键。网格分区数量使用partel工具编译后生成将网格分区分区数通常等于或略大于你使用的MPI进程数。分区质量对负载均衡和通信开销影响巨大METIS/ParMETIS就是用于生成高质量分区的。MPI进程与OpenMP线程混合并行较新版本的Telemac支持混合并行。你可以用较少的MPI进程每个进程占用一个计算节点或一个CPU插槽处理粗粒度网格分区在每个MPI进程内使用OpenMP线程通过设置环境变量OMP_NUM_THREADS进行细粒度的循环并行。这需要编译器支持OpenMP并在配置时启用。IO优化对于输出频繁的大规模计算将结果输出到并行NetCDF或并行HDF5格式比传统的SELAFIN格式效率高得多。这需要在.cas文件中设置RESULTS FILE FORMAT NCDF或HDF5并确保编译时启用了对应支持。编译器优化标志在myconfig.cfg中可以尝试更激进的优化选项如将-O2改为-O3或添加针对特定CPU架构的优化标志如-marchnative。但这可能会牺牲部分代码稳定性建议在测试算例上充分验证后再用于生产计算。编译和运行Telemac-Mascaret的过程就像在组装一台高性能赛车。每一步的严谨——从选择零件库、拧紧螺丝配置到调试发动机编译、试跑赛道测试——都决定了最终它能否稳定、高速地带你抵达目的地。这份指南提供了详细的装配手册和故障排查表但真正的熟练还需要你亲手去拧每一个螺丝去触发并解决每一个错误。当你第一次成功看到自己模拟的水流动画时你会觉得这一切的折腾都是值得的。
)
