Ubuntu 20.04下Geant4源码编译安装全攻略：从依赖到B1示例

如果有人告诉我装 Geant4 要花整整一个周末我大概会嗤之以鼻。但真正站在 Ubuntu 20.04 的终端前照着官方手册一步步走完才发现这个在粒子物理、核医学影像、辐射防护、空间辐射计算里几乎绕不开的开源蒙特卡罗模拟库从源码编译到第一个 B1 示例跑通最耗时间的不是 make 那一下而是依赖库、数据包和环境变量这三座大山。这篇文章就是我自己的踩坑全记录从一个周五晚上开始折腾到周日凌晨才真正看到 B1 可视化窗口弹出希望能把别人容易反复踩的坑提前帮你填平。内容按我实际操作的顺序组织适合刚从零开始、想在 Ubuntu 20.04 上用源码编译方式把 Geant4 装好并跑通基础示例的读者。1. 安装前的硬性准备系统依赖与工具链检查1.1 为什么非要走源码编译这条路不少刚接触 Geant4 的人会先问一句Ubuntu 软件源里不是有 geant4-dev 吗直接apt install geant4-dev不行吗实话说软件源里的包能用但版本通常偏旧而且最要命的是它不会帮你把物理数据包、Qt 可视化、OpenGL 渲染这些编译选项按你的实际需求配好。Geant4 本质上是一套 C 类库它的灵活性恰恰来源于编译期可配置你到底用不用多线程、要不要 Qt 交互界面、用哪种可视化驱动、数据包装到哪里这些都是在 CMake 阶段定死的。换句话说源码编译是官方推荐的正路也是你后面自己写程序、调用各类物理列表时最不容易出幺蛾子的方式。Ubuntu 20.04 在 Geant4 源码编译这个场景下兼容性很好社区里大量成熟实践都基于这个组合新手按这套流程走相对稳妥。唯一的问题是它确实有一点门槛但只要把依赖装对、数据包放对、环境变量配对编译本身并没有想象的那么可怕。1.2 先检查 gcc、g 和 CMake 版本开工之前先在终端里敲三行命令gcc --version g --version cmake --versionUbuntu 20.04 自带的 gcc/g 是 9.4 版本对 Geant4 10.7.x 和 11.x 来说完全够用这一步基本不用担心。真正需要留意的是 CMake。Geant4 新版对 CMake 的最低版本有要求我记得 11.x 系列大约需要 3.16 以上而 Ubuntu 20.04 自带的 CMake 刚好是 3.16.3属于“刚好压线”。如果你在配置阶段报错说 CMake 版本过旧别急着怀疑人生用pip install cmake装一个新版到用户目录或者从官网源码编一个新版都比硬着头皮改 Geant4 的配置靠谱得多。还有个容易忽略的小地方build-essential这个基础编译工具包很可能没装全。如果你平时不写 C 程序Ubuntu 桌面环境下默认不带完整的编译链。建议先补一刀sudo apt update sudo apt install build-essential这条命令会把 gcc、g、make 等基础工具一起装好免得后面编译到一半才发现缺少基础头文件。1.3 把图形界面和 GDML 相关依赖一次装齐Geant4 的可视化和几何导入依赖不少系统库尤其你想看到 B1 示例那个弹出来的图形窗口的话X11、OpenGL、Qt 这几条线必须打通。我这边实际验证过Ubuntu 20.04 下最省心的依赖安装命令是这么一组sudo apt install -y libx11-dev libxmu-dev libgl1-mesa-dev libglu1-mesa-dev \ libxerces-c-dev qtbase5-dev libqt5opengl5-dev libqt5printsupport5-dev \ libfreetype6-dev libmotif-dev先别急着复制粘贴我说一下每个包是干嘛的免得你后面排查时一头雾水。X11 是 Linux 图形界面的根基libx11-dev和libxmu-dev提供最底层的窗口工具OpenGL 负责三维渲染libgl1-mesa-dev和libglu1-mesa-dev是 Mesa 实现的核心开发头文件Qt 是 Geant4 新版可视化最常用的交互界面框架qtbase5-dev和libqt5opengl5-dev必不可少。libxerces-c-dev是给 GDML 几何描述文件用的如果你后面打算导入复杂几何模型这个最好装上否则 CMake 会直接跳过 GDML 支持。libmotif-dev属于可选旧界面组件装上无妨不影响主流程。我见过很多人第一步只装了libgl1-mesa-dev就开跑 CMake结果后面报Cannot find X11或者Qt5 not found回头再补装还得重新配置浪费时间。一次性装齐才是正道。装完之后建议顺手重启一下终端确保 PATH 和库缓存更新。2. 数据包提前就位最容易被低估的“最后一公里”2.1 源码和数据包的关系为什么要单独说Geant4 源码本身只包含算法框架比如粒子输运逻辑、几何求交、场传播这些“骨架”。真正让蒙特卡罗模拟结果接近物理实际的是原子核反应截面、粒子衰变分支比、光子蒸发谱、中子弹性散射数据等一系列庞大的物理数据集。Geant4 把这些数据集拆成十几个独立的数据包分别以G4NDL、G4EMLOW、G4PhotonEvaporation这样的名字命名。新手最容易踩的第一个大坑就在这里你以为编译完就算装好了打开 B1 一运行终端直接给你一句G4LEDATA not set或者类似Fatal: cannot open G4NDL data file。这不是程序写错了纯粹是数据包没准备。如果 CMake 阶段没有开启数据包安装编译再顺利运行阶段也会卡死在数据加载上。所以数据包这件事必须放在编译之前想清楚。2.2 需要准备哪些数据包大概有多大Geant4 官方数据包下载页面会对应当前版本列出一份清单常见的数据包包括数据包名称主要用途体积约G4NDL中子输运与截面数据几百 MB最大的一头G4EMLOW电磁相互作用低能数据100 MB 左右G4PhotonEvaporation光子蒸发级联数据十 MB 级G4RadioactiveDecay放射性衰变链数据十 MB 级G4PARTICLEXS粒子诱发反应截面几十 MBG4ENSDFSTATE核素能级数据几 MBG4LEVELGAMMADATA核能级伽马衰变数据几 MBG4SAIDDATA质子-质子弹性散射数据几 MBG4PII电离过程数据几 MBG4ABLA核碎裂模型数据几 MBG4INCL核内级联模型数据几 MBG4REALSURFACE光学表面处理数据几 MBG4TENDL中子诱导核数据可选较大按需下载这里要特别强调一个版本匹配问题数据包不是越新越好而是必须和你下载的 Geant4 源码版本严格对应。你用的是 Geant4 10.7.3那就必须下载 10.7.3 对应版本的数据包你装的是 11.1.x那 G4NDL、G4EMLOW 这些包的版本号也跟 10.7 的不一样。版本不匹配的经典后果是编译能过、运行也不报错但某些物理过程算出来的结果明显不对或者在某些探测器几何下出现诡异警告。最靠谱的办法是到官网对应版本的下载页去找数据包清单或者直接看源码根目录下 CMake 配置文件里列出的数据集定义照着上面的版本号逐个下载。2.3 加速下载的实操方案把数据包放到 CMake 能看见的地方官方数据包服务器在海外的下载速度确实不稳定尤其在国内网络环境下直接等 CMake 在线拉取数据包非常痛苦经常下到一半超时然后整个配置过程失败重来。我自己试过几次之后总结出一个非常管用的土办法手动提前下载并放到指定位置让 CMake 直接从本地文件解压全程不联网。具体做法是这样的。首先在 Geant4 源码根目录也就是顶层CMakeLists.txt所在目录下新建一个目录名字随意比如叫data。然后把所有需要的*.tar.gz数据包压缩文件下载到里面。注意不要解压保持压缩包的原始文件名和.tar.gz后缀。等你执行cmake配置时如果开启了数据包安装选项CMake 会优先在当前源码目录下找同名压缩包一旦找到就直接用本地文件不再走网络下载。下载工具方面我推荐两个组合拳。第一个是wget的断点续传网络断了可以接着下wget -c https://geant4-data.web.cern.ch/geant4-data/datasets/G4NDL.4.6.tar.gz第二个是aria2这个工具支持多线程分段下载速度比单线程 wget 快不少而且同样支持断点续传sudo apt install aria2 aria2c -x 8 -s 8 -k 1M https://geant4-data.web.cern.ch/geant4-data/datasets/G4NDL.4.6.tar.gz-x 8表示开启 8 个并发连接-s 8让单个文件分成 8 段-k 1M是每段大小。实测下来大数据包用 aria2 下载的速度提升非常明显。如果你在学校或科研机构还可以顺便看看自己单位是不是有比较快的科研网络通道很多时候教育网直连 CERN 的速度比家里宽带快不少。这里有个操作细节值得强调数据包压缩包放进源码目录后CMake 配置过程中会在终端里输出类似Found dataset archive: G4NDL.4.6.tar.gz的日志。看到这个说明本地识别成功。如果没有出现这行而是卡在漫长的下载进度条上多半是文件放的位置不对检查一下是不是和顶层 CMakeLists 同级或者压缩包文件名是否与官方清单完全一致。3. cmake 配置与编译一份能少踩坑的选项清单3.1 推荐的一组 CMake 配置参数进入正题直接给一份我实测过、在 Ubuntu 20.04 下能顺利走通的 CMake 配置命令mkdir geant4-build cd geant4-build cmake -DCMAKE_INSTALL_PREFIX/opt/geant4 \ -DCMAKE_BUILD_TYPERelWithDebInfo \ -DGEANT4_USE_QTON \ -DGEANT4_USE_OPENGL_X11ON \ -DGEANT4_BUILD_MULTITHREADEDON \ -DGEANT4_INSTALL_DATAON \ -DGEANT4_INSTALL_DATA_TIMEOUT3600 \ ../geant4-v11.1.0逐个解释一下这些参数在干嘛。CMAKE_INSTALL_PREFIX指定安装路径我习惯装到/opt/geant4不污染系统目录卸载也干净。CMAKE_BUILD_TYPE选RelWithDebInfo也就是带调试信息的发布版既兼顾运行效率又保留后续用 gdb 调试的可能性。GEANT4_USE_QTON打开 Qt 交互界面后面 B1 可视化窗口就靠它。GEANT4_USE_OPENGL_X11ON配合前面的 Mesa 依赖提供 OpenGL 渲染。GEANT4_BUILD_MULTITHREADEDON开启多线程模式现在跑模拟基本都靠多线程分摊任务这个必须开。GEANT4_INSTALL_DATAON的意思是在编译安装时把之前手动放入数据包目录的文件自动安装到共享位置。GEANT4_INSTALL_DATA_TIMEOUT3600是给远程下载限时设置的单位是秒。如果你按我说的提前把数据包放进源码目录这个超时值其实用不太上但设置了也无所谓给自己留条后路。还有一个值得留意的参数是GEANT4_BUILD_EXAMPLES。官方默认会顺手构建一部分示例但这些示例会明显拉长编译时间。如果你只想先把基础环境跑起来我建议把它显式关掉后面单独编译 B1 也很快-DGEANT4_BUILD_EXAMPLESOFF3.2 编译过程的资源控制与时间预估配置完成之后就是编译命令很简单make -j4这里真心建议别一上来就无脑make -j$(nproc)。Geant4 编译起来是出了名的吃内存我见过八核机器上-j8编译直接内存占满系统卡死最后编译进程被 OOM 杀掉还得从头再来。用nproc看看你机器有几个逻辑核建议编译线程数不要超过内存大小的一半单位是 GB。比如 16GB 内存的机器开到-j4或-j6比较稳妥32GB 内存可以开到-j8。多线程编译省下的时间远远抵不上一次内存爆掉重来的代价。编译时间方面主流配置的台式机或笔记本-j4大概需要 40 分钟到一个半小时不等。这段时间不用干等可以准备后面的环境变量内容。如果编译过程中途报错中断别慌make有增量编译能力修复问题后重新执行make -j4会接着上次的进度继续不用全部重来。3.3 安装与验证编译通过之后sudo make install这一步会把库文件、头文件、CMake 配置脚本和之前的数据包安装到/opt/geant4目录。安装完成后看下目录结构ls /opt/geant4 ls /opt/geant4/share/Geant4/data预期能看到bin、lib、include、share这几个主要目录share/Geant4/data下面则是按数据包名命名的子目录比如G4NDL4.6。检查数据目录时注意一个小坑有些数据包安装之后会自动解压成以版本号结尾的目录比如G4NDL4.6这很正常别以为装错了。下一步用geant4-config验证安装是否完整/opt/geant4/bin/geant4-config --version如果输出版本号说明主程序安装成功。如果提示找不到命令确认一下bin目录里有没有geant4-config这个可执行文件没有的话回头查安装日志。4. 环境变量与 B1 示例让第一个模拟跑起来4.1 环境脚本的加载别把 csh 和 sh 搞混Geant4 安装完成后自带环境变量脚本位于安装目录的bin下分别是geant4.sh和geant4.csh。前者给 bash/zsh 用后者给 csh/tcsh 用。大部分 Ubuntu 用户默认 shell 是 bash所以加载方式为source /opt/geant4/bin/geant4.sh这个脚本会把动态库路径、数据包路径、可执行文件路径全部设置好。你可以马上验证一下echo $G4LEDATA如果输出类似/opt/geant4/share/Geant4/data/G4EMLOW8.2说明数据路径已经正确加载。这里有个常见误区有些人把命令写成bash /opt/geant4/bin/geant4.sh这样会在子 shell 中执行环境变量根本传不回当前终端等于白执行。必须用source。为了让以后每个终端都能直接用可以把它写进.bashrcecho source /opt/geant4/bin/geant4.sh ~/.bashrc source ~/.bashrc注意一点如果你的 zsh 或其他 shell 里也用了.bashrc的逻辑小心不要重复加载导致 PATH 里出现重复项一般没什么大碍但干净一些总没错。4.2 编译并运行 B1 示例环境变量就绪后就可以编译基础示例 B1 了。B1 是 Geant4 的入门示例模拟一个简单的质子和伽马射线入射到球形靶物质的过程适合验证安装环境。整体流程cd geant4-v11.1.0/examples/basic/B1 mkdir B1-build cd B1-build cmake .. make -j4cmake 配置时注意看一下输出里有没有自动找到 Geant4 的提示比如Found Geant4: /opt/geant4。如果这一步提示Geant4 not found多半是geant4-config不在 PATH 里回到上一步重新source一下。编译完成后你会看到可执行文件exampleB1运行它./exampleB1正常情况下终端会先输出一段初始化信息然后弹出一个 Qt 界面窗口你可以用鼠标旋转视角看到靶几何和粒子轨迹。终端里会持续输出每个事件的处理信息比如Event 1 processed这类的日志。如果看到这些说明 B1 已经成功跑通Geant4 安装基本宣告完成。如果你是在没有图形界面的服务器环境下操作或者窗口因为驱动问题黑屏B1 也支持批处理模式运行。先创建一个简单的宏文件比如run.mac/run/initialize /run/beamOn 100然后运行./exampleB1 run.mac这样不会弹可视化窗口直接跑 100 个事件终端输出每个路的处理摘要同样能验证环境是否正常。4.3 在 B1 里做一些最简单的修改B1 跑通之后很多人会想知道怎么改成自己的初始条件毕竟这才是 Geant4 真正开始有用的起点。打开 B1 源码目录下的B1.cc你会看到初始化动作里定义了粒子能量、粒子种类、靶材质等关键参数。默认情况下B1 使用的是简单的质子束能量和几何都可以改。比如把入射粒子能量改大只要找到G4ParticleTable和G4ParticleGun相关的代码块修改能量数值然后回到B1-build目录重新执行make -j4重新编译再运行就能看到新的模拟结果。这一步看似简单但能帮你理解 Geant4 的 “改了代码需要重新编译” 工作流后面写自己的模拟程序时都是这套模式。5. 常见问题与排查技巧实录5.1 高频报错速查表我在实际安装和给朋友远程Debug的过程中积累了几个出现频率极高的报错整理成表格方便你对照排查现象原因解决方案CMake 报Cannot find X11缺少 X11 开发库安装libx11-dev libxmu-devCMake 报Qt5 not found缺少 Qt5 开发包安装qtbase5-dev libqt5opengl5-dev编译时报GL/gl.h: No such file缺少 OpenGL 头文件安装libgl1-mesa-dev libglu1-mesa-devmake中途卡死然后 OOM编译线程开太多内存不够降低-j参数必要时加 swap运行 exampleB1 报G4NDL not found数据包没装或路径没设置检查echo $G4NDLDATA重跑数据包安装运行时报Geant4 command not found环境脚本没加载重新source /opt/geant4/bin/geant4.sh可视化窗口黑屏但程序在跑OpenGL 驱动/兼容问题尝试设置LIBGL_ALWAYS_SOFTWARE1运行数据包运行警告版本不匹配数据包和主程序版本不一致核对官网版本重新下载对应数据包5.2 几条只有装过才知道的土经验第一CMake 缓存这东西配置错了优先考虑清掉。很多人第一次配置时忘了开 Qt发现没有可视化就直接在原构建目录再执行一遍 cmake。短期看没问题但一些缓存项会导致新选项没有真正生效最后阶段出现怪问题。我在遇到类似情况时会直接删掉构建目录重新创建一次rm -rf geant4-build mkdir geant4-build cd geant4-build重新配置一遍省去很多玄学问题。第二数据包的版本号千万别拍脑袋改。网上随便搜到旧教程里面给出的是 Geant4 10.6 时代的包名和版本号直接用在 11.x 上面会出各种匪夷所思的警告。我吃过一次亏G4EMLOW装成了旧版粒子输运结果偏得离谱查了半天最后才发现数据版本不对。一定要以自己源码包对应版本号为准。第三多线程和 Qt 可视化同时跑容易出小毛病。用 Qt 界面互动时CPU 负载本来就高如果你再同时开多线程跑大数据量容易出现界面卡顿甚至闪退。我现在的习惯是调试几何和粒子轨迹用 Qt 可视化正式批量跑数据用批处理宏文件方式两者分开效率最高。第四编译的时候不要急着开一堆其他应用。Geant4 编译前期不吃内存到链接阶段有几个大目标文件会瞬间拉高内存峰值如果这时浏览器开着几十个标签页内存很容易被顶到上限。我比较推荐编译期间把 Electron 应用这类吃内存大户关掉给 make 留出余量。6. 写在最后的一点个人体会这套流程前前后后我重复过好几遍后来帮几个师弟师妹装的时候已经快变成肌肉记忆了。如果让我重来一次我最想对自己说的其实是数据包下载这件事一定放在最前面并且用 aria2 先拉大包别傻乎乎地等 cmake 在线下载编译线程数宁少勿多内存爆掉的损失远比多等几分钟大环境变量脚本用source这是无数人栽过的坑。Geant4 作为一套功能庞大的模拟框架安装过程确实算不上轻松但只要你把依赖、数据包、环境变量这三件事理顺跑通 B1 只是时间问题。真到了那一步后续写自己的模拟程序反而比安装过程有意思得多也顺畅得多。