gprMax 开源项目使用手册

项目概述

gprMax 是一个基于Python的开源软件，专门用于模拟电磁波传播，特别是在地面穿透雷达（Ground Penetrating Radar, GPR）领域的应用。该项目使用有限差分时域（FDTD）方法求解麦克斯韦方程，能够进行3D电磁波传播建模。

项目目录结构

gprMax 项目采用典型的Python包结构组织，主要包含以下核心目录和文件：

• gprMax/ - 主程序包目录，包含所有核心模块
• tests/ - 测试套件，包含各种测试模型和验证案例
• tools/ - 辅助工具脚本，用于后处理和可视化
• user_libs/ - 用户贡献的库和模块
• user_models/ - 用户贡献的输入文件示例
• docs/ - 完整的用户指南文档
• conda_env.yml - Conda环境配置文件
• setup.py - 项目构建和安装脚本

安装指南

前置要求

gprMax 需要以下软件环境：

• Python 3.6 或更高版本
• 支持OpenMP的C编译器（gcc推荐）
• CUDA工具包（如需GPU加速）

使用Conda安装

推荐使用Miniconda创建隔离的Python环境：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/gp/gprMax
cd gprMax

# 创建并激活conda环境
conda env create -f conda_env.yml
conda activate gprMax

# 构建和安装gprMax
python setup.py build
python setup.py install

手动安装依赖

如果不使用Conda，可以手动安装所需Python包：

• colorama
• cython
• h5py
• jupyter
• matplotlib
• numpy
• psutil
• scipy
• terminaltables
• tqdm

核心模块介绍

主程序模块

gprMax的主要功能模块包括：

• gprMax.py - 主程序入口点
• model_build_run.py - 模型构建和运行控制
• grid.py - 网格管理模块
• materials.py - 材料属性定义
• sources.py - 源信号定义
• receivers.py - 接收器管理
• waveforms.py - 波形生成

Cython加速模块

项目使用Cython编写性能关键部分：

• fields_updates_ext.pyx - 场更新计算
• geometry_primitives_ext.pyx - 几何原语处理
• snapshots_ext.pyx - 快照功能
• fractals_generate_ext.pyx - 分形生成

使用指南

基本运行方式

激活gprMax环境后，运行模拟的基本命令格式：

python -m gprMax path_to/input_file.in

示例运行

运行测试模型示例：

# 运行A-scan示例
python -m gprMax user_models/cylinder_Ascan_2D.in

# 绘制A-scan结果
python -m tools.plot_Ascan user_models/cylinder_Ascan_2D.out

命令行选项

gprMax支持丰富的命令行选项：

# 运行多个模型（B-scan）
python -m gprMax model.in -n 60

# 使用GPU加速
python -m gprMax model.in -gpu

# 仅构建几何模型（不运行模拟）
python -m gprMax model.in --geometry-only

# 查看帮助信息
python -m gprMax -h

输入文件格式

gprMax使用文本格式的输入文件定义模拟场景，主要包含以下部分：

• 网格定义 - 设置模拟空间尺寸和分辨率
• 材料属性 - 定义各种材料的电磁特性
• 几何对象 - 创建立方体、圆柱体等几何形状
• 源定义 - 设置激励源类型和位置
• 接收器 - 定义数据采集点
• 边界条件 - 配置PML吸收边界条件

输出文件处理

gprMax生成HDF5格式的输出文件，可以使用配套工具进行处理：

• plot_Ascan.py - 绘制A-scan波形
• plot_Bscan.py - 绘制B-scan图像
• plot_source_wave.py - 可视化源波形
• outputfiles_merge.py - 合并多个输出文件

高级功能

GPU加速

gprMax支持NVIDIA GPU加速，通过CUDA实现性能提升：

# 使用默认GPU
python -m gprMax model.in -gpu

# 指定特定GPU设备
python -m gprMax model.in -gpu 0 1

并行计算

支持OpenMP多线程和MPI并行：

# 使用MPI任务分发
python -m gprMax model.in -n 60 -mpi 61

优化算法

集成Taguchi方法进行参数优化：

python -m gprMax model.in --opt-taguchi

应用案例

gprMax已成功应用于多个领域：

• 地下管线探测
• 考古遗址勘察
• 冰川厚度测量
• 混凝土结构检测
• 地质灾害评估

技术支持与贡献

项目提供完整的用户指南和API文档，位于docs目录中。开发者可以通过GitHub提交问题报告和功能请求，也欢迎提交代码贡献。

版本更新

定期更新gprMax以获取最新功能和性能改进：

git pull
python setup.py cleanall
python setup.py build
python setup.py install

gprMax作为开源的地质雷达模拟软件，为科研和工程应用提供了强大的电磁波传播仿真能力，持续推动着GPR技术的发展和创新。