许可证

参阅许可条款。


发行说明


流式读出需要 GEMC 0.5 的 SRO 接口，以及针对同一 GEMC 安装 重新编译的实验插件。FT-Cal 的 JLAB 编码器 属于 clas12-systems；仅安装 pygemc 不会提供原生 SRO 实现。

顶点与角度示例 包含 11 个控制卡文件和预先准备好的 Analyzer 图表。请使用 GEMC 0.5 或更高版本；GUI 图表需要 Qt Charts。这些示例的批处理模拟和 CSV 检查也可在没有 Qt Charts 的情况下运行。

下个版本即将提供：Qt Linguist 工具将在构建期间编译 GUI 翻译目录；Qt 翻译数据用于标准对话框的本地化。下文的软件包安装命令包含这两项。Homebrew Qt 提供 这些工具和翻译目录。GUI 语言会自动检测，也可通过可选的 -language=<code> 参数覆盖。

目录



安装 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 文件。

archive=gemc-dev-geant4-11.4.3-fedora-44-amd64.tar.gz
curl -L -o "$archive" "https://github.com/gemc/src/releases/download/dev/$archive"
tar -xzf "$archive" -C "$gemc_home" --strip-components=1
./install_geant4_data.sh


安装完成后，使用 source 命令加载 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. 获取源码

下载代码：

下载最新发行版：

git clone -c advice.detachedHead=false --branch 0.5 https://github.com/gemc/src
cd src


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 构建。


构建选项


安装后配置

将以下内容添加到 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

下个版本即将提供：针对已安装的 GEMC 进行构建时，CLAS12 构建过程还会在 python_env 下安装或更新 pygemc 及其命令行工具，与单独安装 GEMC 时的目录布局 保持一致。



在 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 命令中添加 --platform linux/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 类似，但需要显式使用 source 命令 加载入口脚本。

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。


dnf install -y --allowerasing ca-certificates curl gzip tar expat sqlite-libs zlib \
libX11 libXext libXmu libXt mesa-libEGL mesa-libGL qt6-qtbase qt6-qtsvg qt6-qtcharts qt6-qttranslations tbb


GEMC 构建的软件前置条件与 Geant4 安装




在 MacOS 和一些常用 Linux 发行版上安装基础软件包及依赖的单条命令：


dnf install -y --allowerasing git make cmake gcc-c++ gdb valgrind libxcrypt-devel \
expat-devel zlib zlib-devel mariadb-devel sqlite-devel python3-devel ninja-build \
mesa-libGL-devel mesa-libGLU-devel libX11-devel libXpm-devel libXft-devel \
libXt-devel libXmu-devel libXrender-devel xorg-x11-server-Xvfb xrandr \
bzip2 wget curl nano bash zsh hostname gedit environment-modules pv which \
psmisc procps mailcap net-tools rsync patch bash-completion python3-numpy \
xterm x11vnc openbox lxqt-panel dejavu-sans-mono-fonts \
qt6-qtbase-devel qt6-qtsvg qt6-qtsvg-devel qt6-qtcharts-devel \
qt6-qttools-devel qt6-qttranslations \
root liblsan libasan libubsan libtsan tbb



Important

GEMC 可以使用任何自定义安装的 CLHEP/Xerces-C/Geant4，不过 我们建议使用 g4install 仓库安装 Geant4， 因为它支持多个 Geant4 版本共存并提供安装脚本。


受支持且经过测试的平台




  1. 对于 Apple Silicon Mac，如果要使用 ↩