★ FEATURED ARTICLE 简介面向核医学成像与辐射仿真方向的初学者及Linux科研环境搭建人员这份PDF文档围绕Ubuntu平台下Gate 8.0的安装部署展开重点解决Geant4、ROOT与系统依赖包的版本匹配、安装顺序及环境变量配置问题。文档内容涵盖gcc与cmake版本核查、apt依赖包按Ubuntu版本选择、ROOT二进制包解压与source配置、Geant4版本对应关系与编译前准备并对GATE_USE_OPTICAL所需libxml2等库及常见依赖报错给出排查思路同时提示建立独立软件目录、核对Gate与Geant4版本对应关系等实践细节有助于减少因组件不兼容导致的重复安装。资源包内仅含1个PDF文件大小约1.09MB篇幅集中、步骤衔接清晰便于按章节对照查阅。已有1053人学习适合希望快速搭建核医学仿真环境、核对组件版本并降低安装试错成本的读者参考也可作为实验室新成员配置环境的资料。1. 没跑过这条工具链的人先别急着解压 Gate第一次装核医学仿真软件 GATE 的人八成会在终端里刷出一屏NOTFOUND之后开始怀疑自己是不是下错了包。GATE 不是一条apt install能收工的东西它是一条四层工具链gcc/cmake 负责构建ROOT 负责数据落地Geant4 负责粒子输运GATE 只是站在最上面写 macro 脚本的那一层。这条链上任何一环版本对不上最后都会以「编译到 60% 突然报错」的形式还回来而且报错信息往往指向的是下层不是真正出问题的地方。下面按依赖顺序把这条链拆开适合要在 Ubuntu 上从零跑通 GATE 的医学物理方向学生、做 PET/SPECT 蒙卡验证的工程师以及准备在 GATE 上改几何、加源项的二次开发者。2. 依赖拓扑拆解gcc、ROOT、Geant4 与 Gate 的四层栈2.1 四层各干什么活版本怎么咬合先把每一层的职责钉死后面报错才知道该翻哪本书。GATE 本身几乎不碰物理过程它做的是「把 macro 脚本翻译成 Geant4 的调用」几何、源、物理列表、digitizer、输出格式这五件事在脚本层描述真正的粒子输运交给 Geant4 内核结果通过 ROOT 的TFile/TTree/TH1落盘。所以 benchmark 跑完你会得到一个.root文件而不是一堆文本日志。层级组件主要职责关键约束构建层gcc / g / make / cmake编译 Geant4 与 Gategcc 不低于 4.8cmake 满足最低版本数据层ROOT直方图、ntuple、结果文件读写与 gcc 版本匹配的预编译二进制包输运层Geant4粒子输运内核、物理列表必须与 Gate 版本严格对应应用层Gatemacro 解析、几何装配、digitizer依赖上面三层的路径与环境变量真正会让人卡住的是第三行和第二行之间的耦合。Gate 8.0 对应 Geant4 10.3 系列Gate 8.2 对应 Geant4 10.5.p01老一点的 Gate 7.2 对应 10.2.p01再往前的 7.1、7.0 分别对应 10.1.p02 和 9.6.p04。这个对应关系不是建议是硬约束——Gate 的源码里直接调用了 Geant4 的类成员跨大版本编译基本必炸。所以下载之前第一件事不是点 tar.gz而是回到版本对应表确认「我要装的 Gate 版本要哪个 Geant4」。还有一层容易被忽略系统版本也在三角关系里。Ubuntu 18.04 上装 Gate 8.2、Ubuntu 16.04 上装 Gate 8.0、14.04 上装 7.1、12.04 上装 7.0这是官方给过的组合。你要在 18.04 上硬装 Gate 8.0不是绝对不行但 Qt 库从 Qt4 换到 Qt5 之后libqt4-dev这类包在新源里可能已经找不到装包阶段就会开始难受。2.2 先建 workspace路径规划能省掉一半玄学血泪经验所有源码、build 目录、install 目录都放在同一个父目录下并且全程用绝对路径。ccmake 里手填相对路径时缓存变量会以 build 目录为基准解析一旦你换个目录重新 configure之前填的路径就全飘了表现出来是「明明装了却找不到」。# 统一工作区后面所有源码、编译目录、安装目录都挂在这下面 sudo mkdir -p /opt/gate_ws sudo chown -R $USER:$USER /opt/gate_ws cd /opt/gate_ws # 建议的最终结构现在只是占位后面逐步填 # /opt/gate_ws/root_v6.18 ROOT 解压后的目录 # /opt/gate_ws/geant4.10.03 Geant4 源码 # /opt/gate_ws/geant4.10.03-build 编译目录 # /opt/gate_ws/geant4.10.03-install 安装目录 # /opt/gate_ws/Gate-8.0 Gate 源码 # /opt/gate_ws/gate_v8.0-build Gate 编译目录 # /opt/gate_ws/gate_v8.0-install Gate 安装目录chown那行不是多余的。如果习惯用sudo建目录再普通用户编译后面make install会因为目标目录属主是 root 而权限失败报错还藏在几百行输出中间。要么一开始就把属主给自己要么整个编译过程都用同一个用户。2.3 CLHEP 与可选包能不装就不装CLHEP 是 Geant4 依赖的数学库。Gate 7.0 之后的做法是直接用 Geant4 内置的那份不再单独安装。对应到配置上就是编译 Geant4 时把GEANT4_USE_SYSTEM_CLHEP设为OFF。如果你强行手动装一份外部 CLHEP就必须保证它的版本和 Geant4 要求的完全一致否则链接阶段会出现一堆找不到符号的错误而且这些符号名长得几乎一样排查起来非常折磨。所以这里的取舍很明确默认走内置除非你明确知道自己需要外部版本。同理Gate 侧的 ECAT7、ITK、LMF 这些可选包普通做 PET/SPECT 蒙卡验证的用法基本用不上。它们必须在编译 Gate之前装好一旦你 configure 完之后才想起来要加只能删掉 build 目录重来。第一遍跑通流程时全部保持OFF。3. 系统层准备与前置组件apt 包清单、ROOT 解压、Geant4 的 ccmake 配置3.1 三条自检命令先看清底牌动手装任何东西之前先确认系统里已经有什么。三条命令看输出的版本号够不够。# 编译器GATE 与 Geant4 都靠它低于 4.8 直接放弃治疗 gcc --version # 构建系统ccmake 也在这个包里cmake-curses-gui cmake --version # C 编译器Geant4 源码是 C只有 gcc 不够 g --version判读的时候只看下限不看区间。有些老流程里会写「gcc 需要在 4.8-6.2 之间」实际含义是「4.8 是地板6.2 是当年验证过的天花板」你用 7.3 甚至更高完全可以只是官方没在那个版本上测过。三条命令里如果有一条提示command not found说明连构建工具都没装齐直接进下一节如果版本低于地板同样进下一节装新的。3.2 按发行版对号入座装依赖包这一步最容易翻车的地方是「照抄别人的命令」。不同 Ubuntu 版本、不同 Gate 版本对应的包名不一样尤其是 Qt 相关的包Qt4 和 Qt5 的包名完全不同。先更新索引再按自己的组合选一条执行。# 无论哪个版本第一步都是刷新包索引 sudo apt-get updateUbuntu 18.04.2 LTS 配 Gate 8.2 / Geant4 10.5.p01sudo apt-get install cmake cmake-curses-gui build-essential \ libqt4-opengl-dev qt4-qmake libqt4-dev \ libx11-dev libxmu-dev libxpm-dev libxft-devUbuntu 16.04.2 LTS 配 Gate 8.0 / Geant4 10.3.p01以及 16.04 配 Gate 7.2 / Geant4 10.2.p01sudo apt-get install cmake cmake-curses-gui build-essential \ libqt4-opengl-dev qt4-qmake libqt4-dev \ libx11-dev libxmu-dev libxpm-dev libxft-devUbuntu 14.04.3 LTS 配 Gate 7.1以及 12.04.5 配 Gate 7.0sudo apt-get install cmake cmake-curses-gui build-essential \ libqt4-opengl libqt4-opengl-dev libqt4-core qt4-qmake libqt4-dev \ libX11-dev libxmu-dev命令里的每个包都有明确用途不是凑数build-essential一次带进 gcc、g、makecmake-curses-gui提供后面要反复用的ccmake界面libxmu-dev系列是 Geant4 的 X11/OpenGL 可视化后端依赖Qt 那几个包支撑图形界面。如果执行时报依赖冲突或者提示某个包不存在处理顺序是先把提示里缺的依赖库补上再尝试给包名后面加版本号锁定形如包名1.2.5.7还不行就考虑换系统版本——16.04 在当年是兼容性最好的选择。3.3 ROOT用预编译二进制别自己编ROOT 完全没必要从源码编官方提供对应系统的二进制包解压即用能省掉一两个小时和一堆编译错误。# 解压到工作区 cd /opt/gate_ws tar -xzf root_v6.xx.xx.Linux-ubuntu-x86_64-gcc*.tar.gz # 解压出来的目录一般就叫 root改名带上版本号方便以后多版本共存 mv root root_v6.18 # 把 ROOT 的环境变量注入当前 shell source /opt/gate_ws/root_v6.18/bin/thisroot.sh # 验证能进 ROOT 的交互命令行就算成功 rootthisroot.sh干的事是设置ROOTSYS、把$ROOTSYS/bin加进PATH、把$ROOTSYS/lib加进LD_LIBRARY_PATH。这里有个必须记住的点也是后面所有诡异问题的总源头注意source只在当前这个终端窗口里有效。新开一个标签页、新开一个 ssh 会话环境变量全部清空需要重新 source 一遍。为什么这件事这么要命因为 Gate 的 ccmake 配置阶段会去环境变量里找ROOTCINT_EXECUTABLE和 Geant4 的路径。你在 A 窗口 source 过跑到 B 窗口去 configureccmake 里就是一片NOTFOUND而你会以为是安装失败了。3.4 Geant4build/install 双目录与 ccmake 六个关键项Geant4 从源码编译标准姿势是源码目录、build 目录、install 目录三分开。源码目录保持干净出了问题直接删 build 重来不用重新解压。cd /opt/gate_ws tar -xzf geant4.10.03.p03.tar.gz # 建两个空目录一个放编译中间产物一个放最终安装结果 mkdir -p geant4.10.03-build geant4.10.03-install cd geant4.10.03-build # 注意 .. 后面跟的是解压出来的源码目录名不是压缩包名 ccmake ../geant4.10.03.p03进入 ccmake 之后的操作只有三个键c配置configuree退出当前的信息面板g生成generate并退出。第一次按c会跑一遍检测把能自动找到的都填上找不到的留空或NOTFOUND然后给你一个可编辑的变量列表。缓存变量建议值说明CMAKE_INSTALL_PREFIX/opt/gate_ws/geant4.10.03-install安装路径必须写绝对路径GEANT4_INSTALL_DATAON强制项会自动下载粒子输运所需的 DATA 数据集GEANT4_USE_SYSTEM_CLHEPOFF用内置 CLHEP除非你装了外部版本GEANT4_BUILD_MULTITHREADEDON多线程后面make -jN的收益才明显GEANT4_USE_QTON图形界面需要 Qt 包纯批处理可以关GEANT4_USE_OPENGL_X11ONX11 可视化后端GEANT4_USE_GDMLOFF除非你要读 GDML 几何文件GEANT4_INSTALL_DATA这一项如果关掉编译能过但运行时物理过程会因为缺少截面数据表而报错而且报错信息藏在运行日志里不像编译错误那么显眼——这是个典型的「省一步、赔三小时」的坑。另外可视化相关的那两项如果你只在服务器上跑批处理、根本不需要弹窗关掉能少装一堆依赖编译也快。配置完再按一次c让改动生效确认没有红字的缺失项之后按g生成 Makefile。# N 填物理核心数4 核就 -j4内存小的机器往下调见下面说明 make -j4 # 装到 CMAKE_INSTALL_PREFIX 指定的目录 make install # 验证安装这个脚本里设好了 G4 相关的环境变量和动态库路径 source /opt/gate_ws/geant4.10.03-install/bin/geant4.shmake -jN里的 N 不是越大越好。Geant4 单个编译单元很吃内存8 核机器开-j8有可能因为内存不够被内核直接杀掉进程现象是编译到一半输出一个Killed没有任何 C 错误信息——这是很多人第一次遇到时会误判成代码问题的经典场景。稳妥的算法是「核数的一半且总内存每核不低于 1.5G」。4. Gate 本体编译ccmake 配置、环境脚本与 benchmark 闭环4.1 Gate 的 ccmake那两个路径不需要手填Gate 的编译流程和 Geant4 几乎一样但多了一个前置条件配置前必须已经把 ROOT 和 Geant4 都 source 过并且是在同一个终端里。cd /opt/gate_ws tar -xzf Gate-8.0.tar.gz mkdir -p gate_v8.0-build gate_v8.0-install # 关键一步在即将执行 ccmake 的这个终端里重新 source 两个依赖 source /opt/gate_ws/root_v6.18/bin/thisroot.sh source /opt/gate_ws/geant4.10.03-install/bin/geant4.sh cd gate_v8.0-build ccmake ../Gate-8.0按c配置、e返回之后重点看三个变量缓存变量正常表现异常表现与原因CMAKE_INSTALL_PREFIX手动改成/opt/gate_ws/gate_v8.0-install保持默认会装到/usr/local权限不够Geant4_DIR自动填成安装目录下的lib/Geant4-10.3.3之类显示NOTFOUND或空 geant4.sh没生效ROOTCINT_EXECUTABLE自动指到root_v6.18/bin/rootcint路径不对 thisroot.sh没生效这两个路径是 cmake 从环境变量里推出来的不是让你手敲的。看到它们不对正确的做法是退出 ccmake、重新 source、删掉 build 目录里的CMakeCache.txt、再进来一遍直接在 ccmake 里硬填一个路径后面链接阶段经常会出现版本对不上的奇怪错误。可选包那几个OFFECAT7、ITK、LMF保持默认即可。配置干净后按c再确认一次然后g生成。make -j4 make install4.2 gate_env.sh把三次 source 收进一个文件到这一步 Gate 已经装好了但直接敲Gate大概率提示找不到命令因为gate_v8.0-install/bin还没进PATH。手动 source 三个脚本当然可以但每次开终端都来一遍谁都受不了所以要做个环境脚本。#!/bin/bash # 保存为 /opt/gate_ws/gate_v8.0-install/bin/gate_env.sh # 作用一次性把 ROOT、Geant4、Gate 三层环境都注入当前 shell export GATE_WS/opt/gate_ws # 1. ROOT提供 rootcint、ROOT 库路径 source $GATE_WS/root_v6.18/bin/thisroot.sh # 2. Geant4提供 G4 数据集变量和动态库路径 source $GATE_WS/geant4.10.03-install/bin/geant4.sh # 3. Gate把可执行文件目录加进 PATH export PATH$PATH:$GATE_WS/gate_v8.0-install/bin # 如果用的是外部 CLHEP再补下面这行本例用 Geant4 内置的注释掉 # export LD_LIBRARY_PATH$LD_LIBRARY_PATH:$GATE_WS/CLHEP/lib脚本里用绝对路径、用变量收口根目录是为了以后加第二个 Gate 版本时只改一行GATE_WS就行。写完先做一次验证# 一定要用 source 执行用 sh gate_env.sh 或 ./gate_env.sh 都不会影响当前 shell source /opt/gate_ws/gate_v8.0-install/bin/gate_env.sh # 能打印出安装目录下的可执行文件路径说明 PATH 生效了 which Gate如果which Gate什么都没输出九成是把脚本当普通程序跑了而不是source。这是一个非常高频的低级错误因为两条命令看起来只差一个词。免去每次手动 source 的做法是写进~/.bashrc这个文件会在用户打开交互式终端前自动执行# 在文件末尾追加一行 echo source /opt/gate_ws/gate_v8.0-install/bin/gate_env.sh ~/.bashrc # 让改动对当前终端立即生效或者直接开个新终端 source ~/.bashrc提示改了.bashrc之后如果某个终端里Gate仍然找不到先确认是不是在这个文件里提前return了或者前面某条命令报错中断了执行。把 source 那行放在文件末尾通常最安全。4.3 用 benchPET 做端到端验证装完不验证等于没装。Gate 源码包里自带 benchmark用的是一套完整的 PET 几何和源定义跑通它就能确认「Geant4 输运 ROOT 输出 Gate 脚本解析」这条链路是通的。# 进入 benchmark 目录注意是源码目录不是 build 或 install 目录 cd /opt/gate_ws/Gate-8.0/benchmarks/benchPET # 如果之前跑过先清掉旧的输出文件否则会误以为这次跑成功了 rm -f benchmarkPET.root # 启动仿真让程序跑一会儿 Gate benchPET.mac跑大约一分钟左右按Ctrlz挂起进程这个 benchmark 默认是长时间运行的不需要跑完。然后检查目录下有没有生成benchmarkPET.root——有说明仿真层和输出层都正常。# 用 ROOT 打开结果文件并执行配套的宏看直方图 root # 进入 ROOT 交互命令行后执行 .x benchmarkPET.C能弹出能量谱或者符合计数相关的图整套安装就算闭环了。这一步的意义不只是「看看图好看不好看」它同时验证了三件事Gate 能正确解析 macro、Geant4 能正常输运粒子、ROOT 能把结果写成可读的文件。三件事里任何一件有问题你都会在这一步暴露出来比等到自己写实验脚本时才发现要省事得多。5. 踩坑排查五条从 NOTFOUND 到 Killed 的现场记录5.1 配置阶段的两类 NOTFOUND坑一ccmake 里Geant4_DIR和ROOTCINT_EXECUTABLE全是 NOTFOUND现象进 ccmake 按c之后这两个变量显示为空或NOTFOUND按g生成也能过但make一开始就报找不到 Geant4 头文件。原因99% 是在新开的终端里跑 ccmake而那个终端没有 source 过geant4.sh和thisroot.sh。cmake 只能从环境变量推路径环境里没有它就推不出来。解决退出 ccmake在同一个终端里依次source两个脚本删掉 build 目录下的CMakeCache.txt缓存会把旧的 NOTFOUND 记住重新ccmake一次。养成习惯每次进 build 目录 configure 之前先which root和echo $G4INSTALL确认环境还在。坑二照抄别人的路径source 到一个不存在的文件现象执行source xxx/geant4.10.10-install/bin/geant4.sh提示No such file or directory但明明刚才装成功了。原因很多流传的安装笔记里版本号是混着写的正文说 Gate 8.0 / Geant4 10.3下面的命令块里却出现10.10、8.2。照着敲就会 source 到一个不存在的目录而终端只给一行不痛不痒的报错很容易滑过去直到后面编译失败才回头找。解决不要相信笔记里的路径用ls确认。ls /opt/gate_ws看一眼实际目录名ls /opt/gate_ws/geant4*/bin/确认geant4.sh到底在哪。文件名和你以为的不一样的时候永远以磁盘上的为准。5.2 编译与运行阶段的三类硬故障坑三make跑到一半输出一个Killed没有任何错误信息现象编译进行到某个.cc文件时进程突然消失终端只剩Killed或者c: fatal error: Killed signal terminated program cc1plus。原因并行编译把内存吃满了被系统的 OOM killer 干掉。Geant4 里几个大文件单个编译单元就能吃掉 1G 以上内存-j8在 8G 内存的机器上基本必挂。解决把-j后面的数字降下来先试make -j2实在不行就make单线程。同时可以开一个窗口free -h盯着内存。这个坑最坑的地方在于它伪装成代码错误让人去翻源码实际上加个 swap 或者减并行度就解决了。坑四Gate 编译报一堆undefined reference to CLHEP::...现象链接阶段出现大量以CLHEP开头的未定义符号编译进度卡在最后。原因编译 Geant4 的时候GEANT4_USE_SYSTEM_CLHEP被设成了ON但系统里并没有装外部 CLHEP或者装了版本不对。Geant4 自己带的那份 CLHEP 没有被编进去。解决回到 Geant4 的 build 目录ccmake把GEANT4_USE_SYSTEM_CLHEP改成OFF重新make make install然后 Gate 侧删掉 build 目录重来。整个过程大概要重编一次 Geant4所以这个选项最好在第一次配置时就确认清楚。坑五benchPET 跑完没有生成.root文件现象Gate benchPET.mac正常启动、日志一直在刷Ctrlz之后ls却看不到benchmarkPET.root。原因三种可能。一是终止得太早一个 event 都没跑完文件还没落盘二是当前目录没有写权限比如在/usr/local下跑的三是磁盘满了ROOT 写文件失败但日志里只有一行不起眼的警告。解决按顺序排查——先pwd和touch test.txt确认写权限再df -h看磁盘余量最后让程序多跑一会儿日志里出现 event 计数再终止。终止方式也建议用Ctrlc正常中断而不是Ctrlz挂起挂起的进程还占着文件句柄有时候文件缓冲区没 flush。6. 二次开发改造从跑通 benchmark 到换掉自己的探测器几何跑通 benchmark 只是拿到入场券真正的活是把自己的几何和源定义塞进去。我的习惯是不动官方 benchmark 目录另建一个自己的实验目录用 macro 的 include 机制复用公共部分只覆盖要改的参数。# 自己的实验目录和官方 benchmark 平级 mkdir -p /opt/gate_ws/myexp cd /opt/gate_ws/myexp # 从 benchmark 拷一份作为起点别直接改原文件 cp /opt/gate_ws/Gate-8.0/benchmarks/benchPET/benchPET.mac ./mypet.mac改几何的时候只动需要改的行比如晶体尺寸、环半径、源的能量和位置。判断改动是否生效不要靠肉眼看图靠数字把/gate/application/setNumberOfPrimariesPerRun调到 1000 左右快速迭代跑完用 ROOT 打开结果文件ls一下看看有哪些TTreeTTree::Print()确认 branch 名字和条目数对不对。条目数对不上说明源或者 digitizer 的配置没被读到。多版本共存是个很实用的技巧。做对比实验时经常要同时保留 Gate 8.0 和 8.2只要给每个版本各写一个环境脚本、再用 alias 切换# ~/.bashrc 里为每个版本准备一个切换入口 alias gate80source /opt/gate_ws/gate_env_v80.sh alias gate82source /opt/gate_ws/gate_env_v82.sh两个脚本内容一样只是GATE_WS和 Geant4 路径不同。切完用which Gate和Gate --version确认切过去了再跑实验别在一个终端里混着用两个版本——那是真的会出一些查不出原因的怪结果。验证改造是否正确的标准我一般定三条macro 能无警告解析完、跑 1000 个 primary 不崩、输出文件里的 branch 结构和预期一致。三条都过才把 primary 数调回正式值跑长时间任务。从那以后我每次改完几何都会先用 1000 个 primary 空跑一遍再上床睡觉绝不让一个没验证过的 macro 占着机器跑一整晚。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
