简介G4OpticksTest 是一份面向高能物理仿真与光学光子追踪开发者的 C 示例工程重点演示如何在 Geant4 框架内调用光学元件完成光子的创建与传播并完成光学环境的正确配置。它适合已具备 Geant4 基础、希望将 GPU 加速光线追踪引入探测器模拟的中高级开发者用于闪烁体、切伦科夫辐射及液氩时间投影室等场景的验证与二次开发。资源包共 105 个文件约 179KB以 27 个 hh 头文件与 27 个 cc 源文件为核心辅以 11 个 gdml 几何描述、11 个 sh 与 4 个 bash 脚本、9 个 mac 宏命令及少量 c、py、xml 等配置与辅助文件覆盖几何建模、敏感探测器定义与批处理运行等环节。目前已有 599 人学习下载。通过该示例读者可获取可编译运行的工程骨架、光学环境搭建思路与脚本化运行流程并借助内容预览中的探测器构造与绘图代码快速理解光子传播链路的组织方式为自身光学仿真项目提供可复用的参考实现。1. 从一次光学仿真翻车说起这个示例到底能干什么去年帮一个做闪烁体探测器的团队调光学仿真他们用 Geant4 跑光子输运结果探测器端收集到的光子数比预期少了将近一半。查了两天问题出在光学界面模型上——表面粗糙度参数和折射率设置不匹配光子全在界面处被“吃掉”了。这种问题在纯几何仿真里根本看不出来只有真正把光学光子当粒子去追踪才会暴露。G4OpticksTest 这个示例解决的正是这类场景它演示了如何在 Geant4 内部创建光学光子并借助 Opticks 后端完成 GPU 加速的光学光子传播。适合谁正在做闪烁体探测、Cherenkov 辐射、光学传感器响应模拟的 C 开发者尤其是那些已经被 Geant4 纯 CPU 光学追踪拖慢到想砸键盘的人。这个示例不是教程是一份可以直接编译运行的工程骨架把光学光子从生成到传播到记录的完整链路都摆出来了。2. 工程结构拆解光学光子从创建到传播的代码骨架2.1 目录布局与构建系统拿到源码包后先别急着编译花五分钟把目录结构看清楚后面改代码能省不少时间。这个示例的目录组织遵循 Geant4 官方示例的惯例但针对 Opticks 集成做了裁剪和补充。典型布局如下G4OpticksTest/ ├── CMakeLists.txt # 顶层构建脚本负责查找 Geant4 和 Opticks ├── G4OpticksTest.cc # 主函数入口初始化 RunManager 和物理列表 ├── include/ │ ├── DetectorConstruction.hh # 探测器几何定义 │ ├── PrimaryGeneratorAction.hh # 初级粒子光子生成 │ ├── RunAction.hh # 运行级数据记录 │ ├── EventAction.hh # 事件级数据收集 │ └── SteppingAction.hh # 步进级光学光子追踪 ├── src/ │ ├── DetectorConstruction.cc │ ├── PrimaryGeneratorAction.cc │ ├── RunAction.cc │ ├── EventAction.cc │ └── SteppingAction.cc └── macros/ ├── run.mac # 运行宏定义粒子数、能量等 └── vis.mac # 可视化宏调试几何用这个结构里最值得注意的是SteppingAction——光学光子的传播细节全在这里。普通 Geant4 示例中 SteppingAction 往往只做简单的能量沉积记录但这个示例里它承担了光学光子边界交互的监控职责。CMakeLists.txt 里会通过find_package(Geant4 REQUIRED)和find_package(Opticks REQUIRED)分别定位两个依赖常见做法是用OPTICKS_PREFIX环境变量指定 Opticks 安装路径避免硬编码。2.2 光学光子创建PrimaryGeneratorAction 的关键实现光学光子的创建和普通粒子不同需要显式设置偏振态和动量方向。这个示例在PrimaryGeneratorAction里用G4ParticleGun发射光子但关键在于粒子类型的选取和能量设置。核心代码大致如下// PrimaryGeneratorAction.cc void PrimaryGeneratorAction::GeneratePrimaries(G4Event* anEvent) { // 设置粒子类型为光学光子 fParticleGun-SetParticleDefinition( G4OpticalPhoton::OpticalPhotonDefinition() ); // 设置光子能量对应波长 420nm典型闪烁体发光峰 G4double photonEnergy 2.95 * eV; fParticleGun-SetParticleEnergy(photonEnergy); // 设置偏振方向光学光子必须指定偏振 G4ThreeVector polarization(1, 0, 0); fParticleGun-SetParticlePolarization(polarization); // 设置发射位置和方向 fParticleGun-SetParticlePosition(G4ThreeVector(0, 0, -10*cm)); fParticleGun-SetParticleMomentumDirection(G4ThreeVector(0, 0, 1)); fParticleGun-GeneratePrimaryVertex(anEvent); }这里有几个参数需要根据实际场景调整。photonEnergy决定了光子在介质中的折射率和吸收长度必须和材料属性表里的能量点对应。polarization在光学仿真中不是可选项——Geant4 的光学光子追踪依赖偏振态计算菲涅尔反射和透射系数不设置的话行为是未定义的。ParticlePosition和MomentumDirection决定了光子入射到探测器界面的角度这个角度直接影响全反射临界角的判断。2.3 光学界面与表面模型DetectorConstruction 里的玄学光学仿真的翻车重灾区就在界面属性定义。这个示例在DetectorConstruction里演示了如何为探测器表面设置光学边界。核心是G4OpticalSurface和G4LogicalSkinSurface的配合使用// DetectorConstruction.cc 片段 G4OpticalSurface* opticalSurface new G4OpticalSurface(DetectorSurface); opticalSurface-SetType(dielectric_dielectric); opticalSurface-SetModel(unified); // 统一表面模型 opticalSurface-SetFinish(polished); // 抛光表面 // 设置折射率能量点 const G4int numEntries 2; G4double photonEnergy[] {2.0*eV, 3.5*eV}; G4double refractiveIndex[] {1.50, 1.55}; G4MaterialPropertiesTable* mpt new G4MaterialPropertiesTable(); mpt-AddProperty(RINDEX, photonEnergy, refractiveIndex, numEntries); // 设置反射率 G4double reflectivity[] {0.95, 0.90}; mpt-AddProperty(REFLECTIVITY, photonEnergy, reflectivity, numEntries); opticalSurface-SetMaterialPropertiesTable(mpt); // 将表面绑定到逻辑体积 new G4LogicalSkinSurface(DetectorSkin, logicDetector, opticalSurface);SetType(dielectric_dielectric)表示介质-介质界面这是闪烁体到光导再到光电探测器的典型配置。SetModel(unified)启用统一表面模型它比传统的 GLISUR 模型更精确但计算量也更大——这正是需要 Opticks GPU 加速的原因。SetFinish(polished)表示理想抛光面如果实际探测器表面有粗糙度需要改成ground并配合SigmaAlpha参数。折射率数组必须按能量升序排列否则 Geant4 插值会出错这个坑我踩过不止一次。2.4 步进级追踪SteppingAction 里记录光学光子命运光学光子的传播过程需要在步进级别监控因为每个边界交互都可能改变光子状态。这个示例的SteppingAction演示了如何提取光学光子信息// SteppingAction.cc void SteppingAction::UserSteppingAction(const G4Step* step) { G4Track* track step-GetTrack(); // 只处理光学光子 if (track-GetDefinition() ! G4OpticalPhoton::OpticalPhotonDefinition()) return; // 获取当前体积 G4VPhysicalVolume* volume track-GetVolume(); G4String volName volume-GetName(); // 记录光子到达探测器时的信息 if (volName Detector) { G4double energy track-GetKineticEnergy(); G4ThreeVector pos track-GetPosition(); G4ThreeVector dir track-GetMomentumDirection(); // 存入 EventAction 的 ntuple fEventAction-AddPhotonHit(energy, pos, dir); } // 光子被吸收或超出世界体积时终止 if (track-GetTrackStatus() fStopAndKill) { fEventAction-CountLostPhoton(); } }GetKineticEnergy()返回的是光子当前能量如果发生了非弹性散射比如拉曼散射能量会变化。GetPosition()和GetMomentumDirection()记录了光子到达探测器时的状态这些数据后续可以用来重建入射角分布。fStopAndKill状态表示光子被吸收或逃逸统计这个数量可以评估光收集效率。注意这里没有用GetStepLength()做吸收长度判断——光学光子的吸收在边界处由表面属性处理体吸收则通过材料属性表的ABSLENGTH控制。3. 编译与运行从零把示例跑起来3.1 依赖安装与环境检查这个示例依赖两个核心库Geant4建议 11.x 版本和 Opticks。Geant4 的安装方式取决于系统常见做法是用包管理器装预编译版或者从源码编译。Opticks 的安装相对复杂它需要 CUDA 和 OptiX 支持对显卡有要求。安装完成后用以下命令验证环境# 检查 Geant4 是否可用 geant4-config --version # 检查 Opticks 环境变量 echo $OPTICKS_PREFIX echo $CUDA_HOME # 确认 OptiX 头文件存在 ls $OPTICKS_PREFIX/include/OptiX如果geant4-config找不到说明 Geant4 的 bin 目录没在 PATH 里。Opticks 的OPTICKS_PREFIX必须指向安装根目录CMake 会从这个路径查找库文件和头文件。CUDA 版本要和 OptiX 版本匹配常见做法是 CUDA 11.x 配 OptiX 7.x版本不匹配会在编译期报符号错误。3.2 CMake 构建与常见编译错误环境就绪后进入源码目录执行构建mkdir build cd build cmake .. \ -DGeant4_DIR$(dirname $(which geant4-config))/../lib/Geant4-11.0.0 \ -DOpticks_DIR$OPTICKS_PREFIX/lib/cmake/Opticks \ -DCMAKE_BUILD_TYPERelease make -j$(nproc)Geant4_DIR指向 Geant4 的 CMake 配置目录不同安装方式路径不同。Opticks_DIR指向 Opticks 的 CMake 配置文件所在目录。CMAKE_BUILD_TYPERelease开启优化光学光子追踪计算量大Debug 模式会慢到无法接受。编译时最常见的错误是找不到G4OpticalPhoton.hh这通常是 Geant4 的 include 路径没被正确传递检查Geant4_DIR是否指向了包含Geant4Config.cmake的目录。3.3 运行宏配置与 GPU 加速启用编译成功后用宏文件控制运行参数。macros/run.mac里定义了粒子数和能量# run.mac /run/numberOfThreads 4 /gun/particle opticalphoton /gun/energy 2.95 eV /run/beamOn 10000numberOfThreads控制 CPU 线程数但光学光子传播如果启用了 Opticks实际计算会卸载到 GPU。启用 Opticks 需要在主函数里显式初始化// G4OpticksTest.cc 片段 #include Opticks.hh #include G4Opticks.hh int main(int argc, char** argv) { // 初始化 Opticks Opticks* ok new Opticks(argc, argv); ok-configure(); G4Opticks* g4ok G4Opticks::Get(); g4ok-setOpticks(ok); // 后续 Geant4 初始化... }Opticks::configure()会解析命令行参数比如--gpu指定显卡编号。G4Opticks::Get()返回单例后续所有光学光子的传播都会经过这个接口路由到 GPU。如果初始化失败检查 CUDA 驱动版本和 OptiX 运行时是否匹配常见错误是OptiX Error: Invalid device context这通常意味着显卡不支持当前 OptiX 版本。4. 避坑与排查光学仿真里那些让人抓狂的问题4.1 光子数对不上界面属性表的能量范围陷阱现象模拟跑完探测器记录到的光子数远少于预期但几何和源项检查都没问题。原因材料属性表里定义的能量范围没有覆盖光子的实际能量。Geant4 在插值时如果光子能量超出表格范围会返回边界值或者直接报错导致折射率和反射率计算错误。解决检查所有AddProperty调用的能量数组确保最小能量低于光子最低能量最大能量高于光子最高能量。比如光子能量 2.95 eV属性表至少覆盖 2.0 eV 到 3.5 eV。用/tracking/verbose 2打印光子能量和介质属性确认插值是否正常。4.2 GPU 加速没生效Opticks 初始化静默失败现象程序正常运行但速度跟纯 CPU 跑没区别GPU 利用率几乎为零。原因Opticks 初始化时如果找不到兼容的 GPU 或驱动版本不匹配会静默回退到 CPU 模式不报错也不提示。解决在Opticks::configure()之后加一行ok-dump();打印配置信息确认compute字段是GPU而不是CPU。另外检查--gpu参数指定的设备编号是否存在多卡机器上默认可能选了不支持的卡。4.3 光子偏振丢失PrimaryGeneratorAction 的默认值坑现象光学光子追踪结果和理论计算偏差很大反射率曲线对不上。原因G4ParticleGun默认不设置偏振光学光子的偏振态是未初始化的随机值导致菲涅尔系数计算错误。解决在GeneratePrimaries里显式调用SetParticlePolarization()。偏振方向应该垂直于光子动量方向常见做法是用G4ThreeVector构造一个正交基。如果模拟的是非偏振光需要多次运行取平均每次随机化偏振方向。4.4 表面模型选错unified 和 GLISUR 的差异现象抛光表面模拟结果和实际测量对不上反射光分布过于集中。原因SetModel(unified)和SetModel(glisur)对表面粗糙度的处理方式不同。GLISUR 是早期模型对抛光面会过度简化unified 模型更精确但需要正确设置SigmaAlpha参数。解决抛光面用unified模型配合SigmaAlpha0。如果表面有微观粗糙度SigmaAlpha需要根据实际表面粗糙度换算常见做法是用原子力显微镜测量 RMS 粗糙度再按 Geant4 文档的公式转换。不确定的时候先用glisur模型快速验证几何再用unified做精确模拟。4.5 内存泄漏Opticks 事件循环里的资源释放现象长时间运行后内存持续增长最终被系统杀掉。原因Opticks 的 GPU 缓冲区在每次事件循环后没有正确释放尤其是自定义的 ntuple 数据如果直接传给 Opticks 而没有拷贝会导致悬空指针。解决在EventAction::EndOfEventAction()里显式调用G4Opticks::Get()-reset()清理 GPU 端资源。自定义数据用std::vector拷贝而不是传指针。用valgrind --leak-checkfull跑一个小规模测试定位泄漏点。5. 二次开发把示例改造成自己的光学仿真工具5.1 替换探测器几何与材料这个示例的几何是一个简化模型实际项目里需要替换成自己的探测器结构。改造入口在DetectorConstruction::Construct()常见做法是把几何参数抽成配置文件用G4GenericMessenger暴露成宏命令。比如把探测器尺寸、材料折射率、表面粗糙度都做成可配置项// 在 DetectorConstruction 构造函数里注册命令 fMessenger new G4GenericMessenger(this, /detector/, Detector control); fMessenger-DeclareProperty(size, fDetectorSize, Detector size); fMessenger-DeclareProperty(material, fMaterialName, Detector material);这样在宏文件里就能用/detector/size 50 mm动态调整不用每次改代码重新编译。材料属性表建议从外部文件读取Geant4 支持用G4MaterialPropertiesTable从文本文件加载能量-属性对方便和实验数据对接。5.2 自定义光学表面模型如果标准表面模型不够用可以继承G4OpticalSurface实现自定义模型。常见需求是模拟多层光学薄膜或者波长转换层。改造思路是重写GetReflectivity()和GetTransmittance()虚函数在内部实现自己的物理模型。注意这些函数会被每个光子边界交互调用性能敏感避免在里面做动态内存分配。5.3 数据输出与分析链路示例默认用 ntuple 记录光子命中信息实际项目里通常需要更结构化的输出。常见做法是在RunAction里创建G4AnalysisManager实例把光子能量、位置、方向、偏振、到达时间都存成 ROOT 或 CSV 格式。如果后续要用 Python 分析CSV 更方便如果数据量大ROOT 的压缩和随机访问更有优势。输出路径用宏命令控制避免硬编码。5.4 性能调优与验证方法启用 Opticks 后性能瓶颈通常从 CPU 转移到 GPU 内存带宽。调优方向包括减少每次事件循环传输到 GPU 的数据量、合并小批次光子发射、用异步传输重叠计算和通信。验证方法上我一般会做一个“回归测试”固定随机数种子用纯 CPU 模式和 GPU 模式各跑一遍对比光子命中数和能量分布偏差超过 1% 就要查原因。这个习惯帮我抓过好几次 Opticks 版本升级引入的兼容性问题。从那以后我每次改光学表面参数或者升级 Opticks 版本都强制走一遍 CPU/GPU 对比验证再急也不跳过。希望帮到你。本文还有配套的精品资源点击获取
