许可证
参阅许可条款。
发行说明
流式读出需要 GEMC 0.5 的 SRO 接口，以及针对同一套 GEMC 安装
重新构建的实验插件。FT-Cal 的 JLAB 编码器
属于 clas12-systems；仅安装 pygemc 并不会提供原生 SRO 实现。
顶点与角度示例 包含 11 个运行控制卡和预先生成的 Analyzer 图表。请使用 GEMC 0.5 或更高版本；GUI 图表需要 Qt Charts。这些示例的批处理模拟和 CSV 检查在没有 Qt Charts 时同样可用。
目录
安装 Python API
pygemc 可从 PyPI 获取。
直接使用 pip 安装时请使用虚拟环境：
python3 -m venv ~/venv/pygemc
source ~/venv/pygemc/bin/activate
python -m pip install pygemc
PyVista VTK 导出所用的可选 Jupyter 模块可通过以下命令安装：
python -m pip install "pygemc[jupyter]"
可选的 ROOT 文件分析依赖可通过以下命令安装：
python -m pip install "pygemc[root]"
从 PyPI 安装的包不包含 gemc 可执行文件，但可用于
创建和可视化几何模型或分析结果。
下载预编译的二进制发行版
二进制 tar 压缩包包含 gemc 可执行文件和示例（但不含 pygemc）。Linux 构建提供
amd64 和 arm64 版本；macOS 构建为 Apple Silicon（arm64）原生版本。
请务必查看二进制安装的软件先决条件， 然后再解压 tar 压缩包。
首先选择一个安装目录：
gemc_home=/path/to/gemc
mkdir -p "$gemc_home"
cd "$gemc_home"
然后，使用与你的 Linux 发行版和 CPU 架构相匹配的选项卡中的命令。 这将安装 GEMC 和 Geant4 data 文件。
安装完成后，加载 GEMC 环境文件。如果希望在每个 shell 中都可用，请将此行添加到
.bashrc 或 .zshrc：
source /path/to/gemc/gemc.env
运行以下几项检查以验证安装：
gemc -v
test_gdynamic_plugin_load
test_gdata_event_verbose
从源码构建
构建 GEMC 需要 Geant4。请查看附录中的 GEMC 构建的软件先决条件与 Geant4 安装 以了解完整的要求列表。
1. 获取源码
下载代码：
2. 配置构建并安装 GEMC
GEMC 使用 Meson 构建系统进行编译和安装。
配置阶段会检查所需依赖并获取外部库。
这里我们使用 build 目录。
meson setup build --prefix=/path/to/install/gemc
安装阶段会构建并安装 GEMC。这里我们使用 -q 以进行静默构建。
meson install -C build -q
安装完成后，可运行 meson test -C build 来测试已配置的 GEMC 构建。
构建选项
- 配置选项
-Droot=enabled会添加 ROOT 支持（需要系统中已安装 ROOT）。 - 配置选项
-Di_test=true会在测试中启用 GUI 界面。 - 在构建/测试时使用
-v可获得详细输出。 - 若要删除构建目录并重新开始，请使用
rm -rf build，然后重新运行配置步骤。 - 使用
-jN设置编译时的线程数。
安装后
将以下行添加到你的 shell 配置文件中（例如 ~/.bashrc 或 ~/.zshrc）：
export PATH=/path/to/install/gemc/bin:/path/to/install/gemc/python_env/bin:$PATH
第二个 PATH 条目将随附的 Python 虚拟环境加入搜索路径，使 python3
指向该虚拟环境的解释器，从而让你可以在脚本中使用
import pygemc。
使用以下命令检查已安装的模拟器和 Python 工具：
gemc -v
gemc-system-template --help
gemc-analyzer --help
从源码构建 CLAS12 探测器系统
CLAS12 探测器系统
（clas12-systems）0.3 使用相同的 Meson 流程构建，且不再
需要预先安装 GEMC。在仅具备 Geant4 的环境中，例如
g4install Docker 镜像，构建流程会从
gemc 子项目自动编译 GEMC，并将其安装到相同的安装前缀下，因此探测器几何和插件可以完全从零开始
安装。只有 Geant4 必须预先安装（构建流程不会编译它）；查找 GEMC 时，依次优先使用
显式指定的 -Duse-gemc-location=<dir>、通过 PATH/pkg-config 找到的已安装 GEMC，最后才是
从源码构建的子项目。
git clone --depth=1 --branch 0.3 https://github.com/gemc/clas12-systems
cd clas12-systems
meson setup build --prefix="$PWD/install" # builds GEMC too if none is installed
meson compile -C build
meson install -C build
在 Docker 容器中运行
你可以使用 Docker 运行 GEMC。可用的镜像列在下方。
arm64 和 amd64 均受支持（Arch Linux 镜像除外，它们只支持 amd64 1）。
| 操作系统 | GEMC 版本 | 镜像仓库地址 | arm64 | amd64 |
|---|---|---|---|---|
| AlmaLinux 10 | dev | ghcr.io/gemc/src:dev-almalinux-10 |
true | true |
| ArchLinux latest | dev | ghcr.io/gemc/src:dev-archlinux-latest |
false | true |
| Debian 13 | dev | ghcr.io/gemc/src:dev-debian-13 |
true | true |
| Fedora 44 | dev | ghcr.io/gemc/src:dev-fedora-44 |
true | true |
| Ubuntu 24.04 | dev | ghcr.io/gemc/src:dev-ubuntu-24.04 |
true | true |
| Ubuntu 26.04 | dev | ghcr.io/gemc/src:dev-ubuntu-26.04 |
true | true |
上述地址指向 Docker Hub 镜像，这些镜像通过
Docker 开源项目赞助计划发布，该计划允许
无限次匿名拉取。这些镜像由作为权威来源的
GitHub Container Registry 构建结果同步而来：两个镜像仓库的
内容和标签完全相同。若要改为从 GHCR 拉取，请将 docker.io/gemc/gemc: 前缀替换为
ghcr.io/gemc/src: 并保持相同标签，例如 ghcr.io/gemc/src:dev-ubuntu-24.04。
建议绑定一个本地目录以保存你的工作。
作为示例，下面的命令将容器路径 /mywork 绑定到
~/mywork，并使用镜像 ghcr.io/gemc/src:dev-almalinux-10。
archlinux amd64 镜像。
批处理模式
docker run -it --rm -v ~/mywork:/mywork ghcr.io/gemc/src:dev-almalinux-10 bash
浏览器图形界面
为交互式会话设置以下便捷变量。请自行选择一个密码：
VPORTS=(-p 6080:6080 -p 5900:5900)
VNC_PASS=(-e X11VNC_PASSWORD=change-me)
VNC_BIND=(-e VNC_BIND=0.0.0.0)
GEO_FLAGS=(-e GEOMETRY=1920x1200)
docker run -it --rm -v ~/mywork:/mywork $VPORTS $VNC_BIND $VNC_PASS $GEO_FLAGS ghcr.io/gemc/src:dev-almalinux-10
然后在浏览器中打开 http://localhost:6080/vnc.html 即可访问
图形界面。
使用 Apptainer 运行
Linux 主机可以使用 apptainer（原名 singularity）来运行 Docker 容器。
你可以将它与上述 Docker 镜像配合使用。它的运行方式与 Docker 类似，但需要显式加载
入口点脚本。
apptainer exec --cleanenv --bind ~/mywork:/mywork docker://ghcr.io/gemc/src:dev-almalinux-10 bash
然后：
source /usr/local/bin/docker-entrypoint.sh
gemc -v
Warning
通过远程主机连接时，图形界面，尤其是 OpenGL 窗口，可能无法在 Apptainer 中 正常工作。
注意
Apptainer 使用默认缓存目录来存储镜像。如果该目录占满了磁盘空间，请将缓存目录和 临时目录设置到有足够磁盘空间的位置。 例如，将
sim_cache设置到有足够空间的位置：export sif_cache=/path/to/$USER/cache然后设置这些变量：
export APPTAINER_CACHEDIR=$sif_cache/apptainer-cache export APPTAINER_TMPDIR=$sif_cache/apptainer-tmp export TMPDIR=$sif_cache/apptainer-tmp并再次运行 apptainer。
附录
二进制安装的软件先决条件
通过二进制 tar 压缩包安装时，只需要 gemc 可执行文件所需的运行时软件包，以及用于
下载和解压压缩包的工具。此列表特意不包含 ROOT。
GEMC 构建的软件先决条件与 Geant4 安装
-
构建工具与编译器：
-
系统软件包（通常通过系统包管理器安装）：
在 MacOS 和一些常用 Linux 发行版上安装基础软件包和依赖的单行命令：
-
外部库，使用与 GEMC 相同的 C++ 标准从源码编译（GEMC 0.5 或更高版本使用 C++20）：
Important
GEMC 可以使用任何自定义安装的 CLHEP/Xerces-C/Geant4，不过
我们建议使用 g4install 仓库来安装 Geant4，
因为它支持多个 Geant4 版本共存并提供安装脚本。
受支持且经过测试的平台
-
macOS：26（Apple Silicon，
arm64） - AlmaLinux：10
- ArchLinux：latest
- Debian：13
- Fedora：44
- Ubuntu：24.04
- Ubuntu：26.04
-
对于 Apple Silicon Mac，如果想使用以下镜像，请在
docker run命令中添加--platform linux/amd64选项： ↩