简介面向地质勘探、考古与基础设施检测等领域的科研人员和工程师这份压缩包提供了GprMax2D/3D地面穿透雷达仿真软件的完整学习资料。软件基于GPU计算支持二维与三维GPR建模可用于分析地下结构及信号传播、反射特性。包内共133个文件包含bmp、png图像结果in、geo模型配置文件out输出数据m脚本以及pdf、doc说明文档等整体约67.62MB。教程内容覆盖软件安装、用户手册、实例演练、脚本自定义与结果解读配合实际案例可帮助读者逐步掌握从建模到仿真的完整流程。已有1820人学习下载适合需要系统入门GPR模拟技术的学生和工程技术人员。1. 为什么一篇 gprmax 教程值得你从头看完做探地雷达GPR的工程师几乎都遇到过这种尴尬现场数据采回来面对一个异常反射有人说是钢筋有人说是空洞谁都不敢拍板想训练一个自动识别模型又凑不齐足够多的缺陷样本。gprmax 就是用来打破这个僵局的工具。它用 FDTD时域有限差分方法求解麦克斯韦方程把电磁波在地下介质里的传播过程在电脑上完整算一遍相当于给雷达做一次可重复的“数字预演”。gprmax2D 和 gprmax3D 分别覆盖二维快速验证和三维精细建模配合 VSCode 做开发与后处理已经是物探、无损检测和探地雷达算法验证场景里的常见流程。这篇教程会从安装、建模、参数设置讲到避坑和数据产出适合第一次接触电磁仿真的新手也适合被模型跑不通卡住的老手。2. gprmax 安装与版本选型2D、3D 和 VSCode 环境一次理顺2.1 先分清 gprmax2D 与 gprmax3D这两种维度不是同一个玩法gprmax 最早的形态就是分 gprmax2D 和 gprmax3D 两条线后来主线版本把二者收进了同一个求解框架实际是二维还是三维取决于你在模型文件里怎么定义计算域。gprmax2D 假设介质在横向y 方向无限延伸只计算 x-z 平面内的电磁场因此速度快、内存占用小特别适合做参数扫描和波形规律观察。比如我想看不同介电常数下空洞反射波形的相位变化用二维模型几分钟就能出一批结果。gprmax3D 则把 x、y、z 三个方向都作为计算维度能描述真实管线走向、钢筋网交叉、天线方向性等三维问题。代价是计算量和内存成倍上涨一个稍大的三维模型动辄占用几 GB 内存。选错维度的典型后果是用二维模拟一个球形空洞时剖面异常宽度和实测对不上或者用三维跑一个均匀介质里的平板反射其实二维就足够白白等了一宿。我自己的习惯是先二维把介质参数和波形调明白再决定要不要升三维。2.2 gprmax 安装先建虚拟环境不要直接装在系统 Python很多人第一次跑 gprmax 装了一堆依赖结果报错全是 numpy 和 scipy 版本冲突。原因是 gprmax 对底层数值库有兼容要求而系统 Python 里往往已经装了其他项目依赖的版本。我会在任何机器上都先建一个独立虚拟环境再执行 gprmax 安装。这样哪怕以后环境坏了删掉重建只需要十分钟。# 在项目根目录创建虚拟环境 python -m venv .venv # Windows 用户用下面这行激活 .\.venv\Scripts\activate # Linux/macOS 用户用下面这行 source .venv/bin/activate # 先升级 pip再安装 gprmax python -m pip install --upgrade pip python -m pip install gprmax这段命令的逻辑很直接venv把项目依赖隔离到.venv目录不会污染系统 Pythongprmax是包名安装后会在环境里提供gprmax模块入口。激活环境后后续所有python -m命令都指向这个虚拟环境。这里有一个 VSCode 环境下最容易踩的坑你在终端里 activate 了环境但 VSCode 的 Python 解释器还指向全局 Python。解决方法是按CtrlShiftP执行 “Python: Select Interpreter”选择.venv里的python.exeLinux 是bin/python。否则后处理脚本可能找不到 gprmax 模块。2.3 VSCode 环境下运行 gprmax先验证包能导入装完先不要急着写模型先确认环境已经正确握住 gprmax。在 VSCode 集成终端里执行python -c import gprmax; print(gprmax import ok)如果输出gprmax import ok说明环境没问题。接着可以把终端工作目录固定在项目根目录我一般习惯用“文件 → 打开文件夹”直接打开工程目录这样后面生成的.in模型文件和.out结果文件都在同一层排查路径问题会省很多事。运行 gprmax 的标准姿势是python -m gprmax 模型文件名.in。.in文件就是你的模型描述下一章我会写一个最简例子。注意不要把输入文件和结果文件混在别的目录VSCode 终端当前目录决定了模型输出的位置路径不一致时你会在后处理阶段到处找.out文件浪费很多时间。3. 构建第一个 gprmax 模型最小输入文件与五个必调参数3.1 输入文件结构域、网格、材料、激励、接收点、扫描gprmax 的模型不是一个 CAD 文件而是一堆带#前缀的文本命令。求解器读到这些命令后会在内存里搭出一个网格化的计算域然后开始 FDTD 迭代。理解这一点很重要你在输入文件里设置的每一个参数最终都对应到“空间被切成多少个网格单元”和“每个网格单元用什么材料属性”。一个完整模型必须回答六个问题电磁波在多大范围里算domain、每个网格切多细dx_dy_dz、地下介质是什么material、天线用什么波形激励waveform、在哪激励source、在哪个位置记录场值rx。如果你还要模拟雷达移动就额外需要扫描步长src_steps / rx_steps。把这六个问题回答了一个 gprmax 模型就不算空架子。3.2 一个二维模型的最小输入文件下面是个可以直接保存为demo.in的二维模型。它构造了一块 0.6 米宽、0.45 米深的土层内部埋了一个空气空洞天线指向 z 方向发出 1.5 GHz 雷克子波接收器放在天线旁边。#title: gprmax2D_simple #domain: 0.60 0.45 0.002 #dx_dy_dz: 0.002 0.002 0.002 #time_window: 30e-9 #material: 6 0.005 1 0 soil #waveform: ricker 1 1.5e9 my_wave #hertzian_dipole: z 0.30 0.05 0.001 my_wave #rx: 0.30 0.12 0.001 #box: 0.25 0.20 0 0.35 0.30 0.001 free_space这段命令的含义按行拆开#domain定义计算域 x、y、z 三个方向的长度y 只给 0.002 米这是二维模型的核心写法#dx_dy_dz是网格步长0.002 米意味着每个网格边长 2 毫米#material第一个参数 6 是相对介电常数0.005 是电导率1 是相对磁导率soil 是材料名#waveform定义了一个 1.5 GHz 的雷克子波my_wave是波形名#hertzian_dipole定义 z 方向电偶极子源位置在 x0.30、z0.05#rx是接收点放在 x0.30、z0.12和天线有 7 厘米偏移最后的#box在坐标范围里填了free_space等于在土里挖了一个空气空洞。参数说明time_window: 30e-9表示计算 30 纳秒的电磁波传播过程对应探测深度大约 1 米到 1.5 米。网格步长 0.002 米在这个频率下是偏保守的好处是数值色散小缺点是内存会高一些。如果内存吃紧可以把步长放到 0.003 米但前提是最高频率对应的波长不能小于 10 个网格。3.3 五个必调参数网格、时间窗、介电常数、电导率、频率第一个是网格步长dx_dy_dz。它决定 FDTD 的稳定性和精度主流经验是取最高频率波长的 1/10 到 1/12。比如土层介电常数 61.5 GHz 电磁波在土里的速度约 1.22e8 米/秒波长约 0.081 米网格步长取 0.002 到 0.003 米就够。网格太粗会出现相位超前和伪反射太细则内存和时间成本飙升。第二个是时间窗time_window。它直接关联最大探测深度。电磁波在地下往返一次走时等于2 * 深度 / 速度。要看到 0.5 米深处的目标时间窗至少要到2 * 0.5 / 1.22e8 ≈ 8.2e-9秒。我通常留 50% 余量所以常见值是30e-9甚至50e-9。第三是相对介电常数epsr。它是最影响波速的介质参数土从 4 到 20 不等混凝土通常在 6 到 9。含水率越高介电常数越大反射相位和走时变化非常敏感。先查文献取一个范围再在模型里扫参比一上来就猜一个精确值靠谱。第四是电导率sigma。它控制电磁波衰减常见干土是 0.001 到 0.01 S/m湿粘土可能到 0.1 S/m。电导率设太高雷克子波传到目标体时已经衰减得只剩一点接收波形会像噪声。设太低反射能量过强也会掩盖深层信号。第五是中心频率。它和天线尺寸、探测分辨率直接相关。频率越高分辨率越高但衰减越快频率越低穿透越深但分辨能力下降。实际做工程时先按场景选 0.5 GHz 到 2 GHz 区间试算再结合目标体尺寸微调。这个参数和网格步长要一起改不能只改频率不改网格否则结果会失真。4. 从 gprmax2D 扩到 gprmax3D改模型、批量跑参数、读 HDF54.1 三维模型要改的四个地方把二维模型升成三维不是简单把#domain的 y 长度改大。FDTD 三维求解时场分量的空间分布在 y 方向也有实际物理意义所以下面这些都要跟着变。第一个是计算域。y 方向至少要有 0.1 到 0.2 米才能容纳目标体的横向尺寸和天线旁瓣。如果只把一个二维模型里的 y 改成 0.002求解器其实还是在做二维近似等于白费内存。第二个是目标体几何。二维里的#box是 x-z 平面上的矩形三维里要描述成 x、y、z 三个方向的立方体并且 y 方向的尺寸要体现真实目标体长度。第三个是天线源。二维里常用无限长线源三维里用#hertzian_dipole精度更高但激励方向和位置要重新设计。第四个是接收点布局。三维模型里可以在一维轨迹上移动天线模拟 B-scan也可以布置二维接收面生成 C-scan接收数据维度完全不一样。改完之后内存消耗会以数量级上升。假如二维模型网格是 300 × 1 × 225只有 67500 个网格同样的精度升到三维变成 300 × 100 × 225就是 675 万网格。网格数越多时间步迭代越慢内存占用也成倍增加。所以我建议三维模型先跑通 0.01 米粗网格确认波形趋势对再加密到 0.003 米。4.2 批量跑参数用 Python 脚本生成输入文件并循环运行手动改.in再跑效率太低我会写个 Python 脚本在循环里生成多个模型并调用 gprmax。下面的例子扫描介电常数 4、6、9 三种土层每种生成一个.in文件并运行。import subprocess for epsr in [4, 6, 9]: model f#title: scan_epsr_{epsr} #domain: 0.60 0.45 0.002 #dx_dy_dz: 0.002 0.002 0.002 #time_window: 30e-9 #material: {epsr} 0.005 1 0 soil #waveform: ricker 1 1.5e9 my_wave #hertzian_dipole: z 0.30 0.05 0.001 my_wave #rx: 0.30 0.12 0.001 #box: 0.25 0.20 0 0.35 0.30 0.001 free_space with open(fmodel_eps{epsr}.in, w, encodingutf-8) as f: f.write(model) subprocess.run([python, -m, gprMax, fmodel_eps{epsr}.in], checkTrue)这段脚本的核心思路是用 f-string 把epsr参数拼进.in文件文本避免手动复制改文件。subprocess.run会等待当前模型跑完再执行下一个避免多个 gprmax 进程同时抢内存导致机器卡死。如果你机器内存大也可以改成并行但我一般不建议超过两个并行任务因为 FDTD 是纯内存密集型任务同时开四五个模型很容易把电脑拖到无响应。参数说明checkTrue会让脚本在 gprmax 返回非零状态时立即抛出异常这样批量跑模型时不会忽略某个失败任务。循环里的epsr值可以根据工程实际扩展比如混凝土是 6、8、10沥青是 4、5、6。用同样的方法也可以扫描空洞深度、目标体尺寸、天线频率。4.3 读 HDF5 输出不要用文本文件存波形gprmax 默认输出是 HDF5 格式扩展名.out。这个格式能同时存多个接收器的大量时间序列用文本文件根本无法高效处理。用 Python 读取时我会先遍历文件内部结构再提取所需分量。import h5py import numpy as np import matplotlib.pyplot as plt with h5py.File(model_eps6.out, r) as f: f.visit(lambda name: print(name)) rx1 f[rxs][rx1] # 优先取电场 z 分量这是探地雷达常用极化方式 if Ez in rx1: ez rx1[Ez][...] t np.arange(ez.shape[0]) * 2e-11 # 先按约 20ps 时间步估算 plt.plot(t, ez[:, 0, 0, 0]) plt.xlabel(Time (s)) plt.ylabel(Ez (V/m)) plt.title(A-scan at rx1) plt.savefig(ascan.png, dpi150)这里关键是f.visit先打印 HDF5 内部结构让你看到rxs/rx1/Ez的真实路径。不同 gprmax 版本输出的组名有差异不要照抄别人的路径名而是先print再写提取逻辑。ez.shape的第一个维度是时间步数第二个到第四个是接收点对应的网格坐标维数。对于单点接收索引基本是[:, 0, 0, 0]。时间步长可以严格从网格步长和 Courant 条件推算也可以从输出文件的属性里读取我这里先用近似值画图正式处理时建议从模型文件属性里读取实际dt。读取 HDF5 时最容易犯的错是以为Ez是一维数组直接取np.squeeze(ez)。如果接收点不止一个squeeze 会把多个接收点的维度也挤掉导致数据串位。更好的做法是先用 print 确认 shape再索引第一个接收点这样后续加多道数据时才不会翻车。5. gprmax 避坑指南安装到出图的 5 个常见问题5.1 现象VSCode 里报错 “No module named gprmax”这个报错几乎都出现在刚安装完但还没正确选择解释器的时候。你在 VSCode 的终端里手动pip install gprmax装进了.venv但右下角或命令面板选择的 Python 解释器还是全局 Python。解决方法是打开命令面板执行 “Python: Select Interpreter”明确选.venv环境。选完再开一个新终端先运行python -c import gprmax验证。还有一个隐蔽原因终端窗口是在激活环境之前打开的VSCode 不会自动刷新环境变量关掉终端重开一次。5.2 现象模型一运行就内存不足或直接卡死二维模型还好三维模型常见这个状况。原因一般不是 gprmax 有 bug而是网格步长太细或计算域太大。网格数每翻一倍内存占用按三维乘法增长。解决路径是分层试算先用 0.005 米粗网格跑通再局部加密先去掉目标体只跑层状介质确认背景波形正常后再加目标。还有一个技巧把时间窗先改小到 5e-9 秒跑通再逐步加长这样能在几分钟内暴露模型配置问题而不是等几小时后才发现失败。5.3 现象波形里出现明显的高频毛刺或抛物线状伪影这通常是网格步长相对最高频率太大发生了数值色散。FDTD 要求每个波长内至少有 10 个网格采样点如果激励是 1.5 GHz 雷克子波在介电常数 9 的介质里波长约 0.067 米网格至少应小于 0.0067 米。出现伪影时先看模型里的最高频率再算对应介质波长把网格步长缩小一半试试。伪影消失说明是色散问题如果还有残余则要检查吸收边界边界反射会在图像底部形成弧形假象。5.4 现象接收波形延迟很多和现场数据对不上这是介质相对介电常数设置不合理。电磁波在介质里的速度是c / sqrt(epsr)介电常数从 6 改成 9走时就会增加 22%。表面上看是波形延迟其实是材料参数和实际场地不一致。解决方法是先用已知埋深的金属板做标定反推实际介电常数再用这个值建模型。不要直接套用土的典型值现场含水率对介电常数影响太大。5.5 现象批量跑多个模型时只有第一个出结果后续全部报错通常是因为脚本里没有关闭 HDF5 文件或者上一次 gprmax 进程未退出导致内存泄漏。我写的批量脚本里用subprocess.run已经能同步等待但如果你用的是Popen又没wait()多个进程会同时写 HDF5产生文件锁错误。解决方法是改成subprocess.run并且在每个模型文件里用不同的#title和输出路径避免同名覆盖。如果仍然失败检查磁盘空间是否被巨大的.out文件占满。6. 让仿真数据可用批量生成、B-scan 合成与结果验证gprmax 的单个 A-scan 只是入门真正有价值的是把仿真结果变成能供算法使用的数据集。我在做缺陷识别训练集时常用两种方式批量生产数据第一种是改介电常数、空洞深度、目标尺寸在参数空间里扫一批独立模型第二种是在一个模型里使用扫描命令让天线沿指定方向移动生成一组成像 B-scan 剖面。以 B-scan 为例你可以在同一模型里设置#src_steps和#rx_steps让发射源和接收器同步移动。这样一次运行就能得到多道 A-scan组合起来就是一道探地雷达剖面。读取输出时每一道对应一个接收器按扫描顺序把波形纵向堆叠就能生成常见的灰度剖面图。实际操作里我会把每道波形做去直流、自动增益再拼接成二维数组这样和现场采集的剖面格式一致可以直接喂给深度学习模型。验证仿真结果可靠性的习惯很重要。我的做法是先在实验室做一块已知介电常数的混凝土板把一个金属平板埋到确定深度再用 gprmax 建一个同样参数的模型对比首波走时和反射振幅。如果走时误差超过 5%优先检查介电常数和网格步长如果振幅对不上优先检查电导率和天线的极化方向。通过这个验证流程我很少再出现“模型算得挺好看一到现场就废”的情况。最后一个建议不要一上来就追求三维精细模型。我吃过最大的亏就是把网格加密到 1 毫米三维模型跑了十几个小时最后发现目标体位置填错了一个坐标前面全部白算。现在我坚持先二维快速验证再三维复核每次只改一个参数。把每一步的输出都存成 HDF5 和 PNG方便回溯。希望帮到你。本文还有配套的精品资源点击获取