$ geant4-config --check-datasets
Set up your computer once, before Week 2.在第 2 周之前,一次性配置好你的电脑。
Week 1 needs only Python. From Week 2 on you need Geant4 11.4 with its physics datasets, a C++17 compiler, CMake and a few Python packages. This page gives three routes: conda-forge (no administrator rights), a container, and Windows through WSL2. Pick one, follow it, then run the check at the end.
第 1 周只需要 Python。从第 2 周起,你需要带物理数据集的 Geant4 11.4、C++17 编译器、CMake 和几个 Python 包。本页给出三条路线:conda-forge(不需要管理员权限)、容器,以及通过 WSL2 的 Windows。选一条照着做,最后运行页面末尾的检查。
Reading阅读3 min3 分钟
/control/getEnv OS0.1 · choose your route0.1 · 选择路线
Pick the route that matches your computer, not the one that sounds cleverest.按你的电脑选路线,而不是按哪条听起来更高级。
| your situation你的情况 | route路线 | needs admin rights?需要管理员权限? |
|---|---|---|
| Linux or macOS laptop, or a shared lab PC / serverLinux 或 macOS 笔记本,或共用的实验室电脑/服务器 | A · conda-forge | no不需要 |
| Docker or VS Code already installed; want the same environment as everyone else已装好 Docker 或 VS Code,希望和所有人环境完全一致 | B · container容器 | Docker itself does安装 Docker 本身需要 |
| Windows 10/11 laptopWindows 10/11 笔记本 | C · WSL2 then A or B inside it然后在其中走 A 或 B | once, to enable WSL需要一次,用于启用 WSL |
| Windows PC without admin rights没有管理员权限的 Windows 电脑 | ask IT to enable WSL2, or use route A on a university Linux server over SSH请 IT 启用 WSL2,或通过 SSH 在学校的 Linux 服务器上走路线 A | — |
Geant4 itself does not run natively on Windows for this course: every lab uses a Linux-style terminal. Plan about two hours for the first install, mostly downloading. The recipes below follow the standard conda-forge packaging and the official Geant4 install guide. The course team has not tested every route on every operating system, so if a step fails, note the exact message and bring it to the course help channel.
本课程不在原生 Windows 上运行 Geant4:所有实验都使用 Linux 风格的终端。首次安装预留约两小时,主要花在下载上。下面的步骤遵循 conda-forge 的标准打包和 Geant4 官方安装指南。课程团队并没有在每种操作系统上测试每条路线,所以如果某一步失败,请记下完整的报错信息,带到课程答疑渠道。
Hands-on lab动手实验45 min45 分钟
conda activate g4chands-on · route A: conda-forge动手实验 · 路线 A:conda-forge
Route A: Geant4 from conda-forge, in your home directory, no administrator rights.路线 A:从 conda-forge 安装 Geant4,装在你的用户目录下,不需要管理员权限。
-
Install Miniforge (conda + mamba)安装 Miniforge(conda + mamba)
Download the installer for your system from the Miniforge releases page (github.com/conda-forge/miniforge). In mainland China use the TUNA mirror of the same releases (mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/).
从 Miniforge 发布页(github.com/conda-forge/miniforge)下载与你系统对应的安装包。在中国大陆可以使用同一发布的清华 TUNA 镜像(mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/)。
terminalbash Miniforge3-$(uname)-$(uname -m).sh -b -p "$HOME/miniforge3" source "$HOME/miniforge3/bin/activate" conda --version
-
Mainland China: point conda and pip at a mirror中国大陆:把 conda 和 pip 指向镜像
Put these lines in
~/.condarc(the USTC mirrorhttps://mirrors.ustc.edu.cn/anaconda/cloudworks the same way). Outside China, skip this step.把下面几行写进
~/.condarc(中科大镜像https://mirrors.ustc.edu.cn/anaconda/cloud用法相同)。在中国大陆以外可跳过本步。~/.condarcchannels: - conda-forge show_channel_urls: true custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
terminalpip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
-
Create the course environment创建课程环境
First see which Geant4 versions conda-forge offers for your platform. The course targets 11.4; if 11.4 is not listed yet, 11.3 works for Weeks 1–8 and 11–12 (expected outputs may differ in the last digits).
先查看 conda-forge 为你的平台提供了哪些 Geant4 版本。课程以 11.4 为目标;如果还没有 11.4,用 11.3 也能完成第 1–8 周和第 11–12 周(预期输出的末几位可能不同)。
terminalGEANT4conda search -c conda-forge geant4 mamba create -n g4c -c conda-forge geant4=11.4 cmake make cxx-compiler \ python=3.12 numpy scipy matplotlib uproot awkward conda activate g4cThe conda-forge
geant4package pulls in the physics datasets as dependencies and sets their environment variables each time you runconda activate g4c. Activate the environment in every new terminal before you build or run a lab.conda-forge 的
geant4包会把物理数据集作为依赖一并安装,并在每次运行conda activate g4c时设置相应的环境变量。每打开一个新终端,编译或运行实验之前都要先激活环境。
Reading阅读3 min3 分钟
docker run g4c:11.4alternative · route B: container备选 · 路线 B:容器
Route B: the course container, the same environment for every student.路线 B:课程容器,每位同学的环境完全相同。
The course repository contains a Dockerfile that builds Geant4 11.4 from the official source release with multithreading and all datasets, plus the pinned Python packages in requirements.txt. Building it takes 30–60 minutes once and needs about 6 GB of disk. In mainland China, configure a Docker registry mirror from your university or cloud provider first; the build itself downloads from gitlab.cern.ch and PyPI (use the pip mirror above if PyPI is slow).
课程仓库里有一个 Dockerfile:它从官方源码发布版构建带多线程和全部数据集的 Geant4 11.4,并安装 requirements.txt 中固定版本的 Python 包。只需构建一次,用时 30–60 分钟,约占 6 GB 磁盘。在中国大陆,请先配置学校或云服务商提供的 Docker 镜像加速;构建过程本身会从 gitlab.cern.ch 和 PyPI 下载(PyPI 慢时使用上面的 pip 镜像)。
git clone https://github.com/kimsiang/geant4-course.git cd geant4-course docker build -t g4c:11.4 . docker run --rm -it -v "$PWD":/work g4c:11.4
Inside the container Geant4 and the Python environment are already active; your files in /work are the repository on your own disk, so edits survive when the container stops. With VS Code, open the repository and choose Reopen in Container: the .devcontainer folder uses the same Dockerfile. The container has no graphical viewer; use the VRML or PNG outputs that the labs write.
容器内 Geant4 和 Python 环境已经激活;/work 中的文件就是你硬盘上的仓库,容器停止后修改依然保留。使用 VS Code 时,打开仓库并选择 Reopen in Container:.devcontainer 目录使用同一个 Dockerfile。容器内没有图形界面可视化,请使用实验输出的 VRML 或 PNG 文件。
Reading阅读3 min3 分钟
wsl --installWindows · route C: WSL2Windows · 路线 C:WSL2
Route C: on Windows, run a real Ubuntu inside WSL2, then follow route A or B in it.路线 C:在 Windows 上用 WSL2 运行一个真正的 Ubuntu,再在其中走路线 A 或 B。
-
Turn on WSL2 and install Ubuntu启用 WSL2 并安装 Ubuntu
Open PowerShell as administrator (this is the only step that needs admin rights), run the command, restart, then open Ubuntu from the Start menu and create a Linux user name and password.
以管理员身份打开 PowerShell(这是唯一需要管理员权限的一步),运行下面的命令,重启电脑,然后从开始菜单打开 Ubuntu,创建 Linux 用户名和密码。
Windows PowerShell (admin)wsl --install -d Ubuntu-24.04
-
Install Geant4 inside Ubuntu在 Ubuntu 中安装 Geant4
In the Ubuntu window, follow route A (conda-forge) exactly as on Linux. Docker Desktop with its WSL2 back end also lets you use route B.
在 Ubuntu 窗口中,按 Linux 的方式完整执行路线 A(conda-forge)。安装带 WSL2 后端的 Docker Desktop 后,也可以走路线 B。
-
Keep course files on the Linux side把课程文件放在 Linux 一侧
Work in your Linux home directory (
~/geant4-course), not under/mnt/c: builds there are many times slower and Windows editors can add CRLF line endings that break macros. To look at output files with Windows programs, runexplorer.exe .in the folder. VS Code with the WSL extension edits the Linux files directly. On Windows 11, graphical viewers work through WSLg; on Windows 10 use the VRML and PNG outputs instead.在 Linux 用户目录(
~/geant4-course)中工作,不要放在/mnt/c下:那里编译要慢很多倍,Windows 编辑器还可能加入 CRLF 换行,导致宏文件出错。想用 Windows 程序查看输出文件,在该目录下运行explorer.exe .。装了 WSL 扩展的 VS Code 可以直接编辑 Linux 一侧的文件。Windows 11 通过 WSLg 可以显示图形可视化;Windows 10 请改用 VRML 和 PNG 输出。Ubuntu (WSL2)mkdir -p ~/geant4-course && cd ~/geant4-course explorer.exe .
Hands-on lab动手实验45 min45 分钟
/control/shell geant4-confighands-on · check your install动手实验 · 检查安装
Prove it works: versions, datasets, and a first build of Week 2.证明它能用:版本、数据集,以及第 2 周的首次编译。
-
Versions and datasets版本与数据集
terminalGEANT4geant4-config --version geant4-config --check-datasets cmake --version python -c "import numpy, uproot, awkward; print('python ok')"expected预期11.4.x # 11.3.x is acceptable for Weeks 1–8 and 11–12 # --check-datasets: every data library reported as installed, none missing cmake version 3.16 or newer python ok
If a dataset is reported missing, run
geant4-config --install-datasets(it downloads from cern.ch; allow time on slow networks), then check again.如果报告缺少某个数据集,运行
geant4-config --install-datasets(从 cern.ch 下载,网速慢时请留足时间),然后再次检查。 -
Build and run Week 2编译并运行第 2 周
Download week02-code.zip, unzip it, and build. The last line of the build should read
[100%] Built target week02; the run prints one step table that you will compare with Week 2, step 3.下载 week02-code.zip,解压后编译。编译最后一行应为
[100%] Built target week02;运行会打印一张步表,你将在第 2 周第 3 步中逐行对照。terminalGEANT4unzip week02-code.zip && cd week02 cmake -S . -B build cmake --build build -j4 cd build && ./week02 run1.mac
Reading阅读12 min12 分钟
G4Exceptioncommon errors常见错误
Four messages that mean the setup, not your code, is wrong.四条说明出错的是配置、而不是你代码的信息。
PART70000 is a Geant4 11.4 message (G4NuclideTable.cc). Codes starting with Course- are this course's notes in the same format.PART70000 是 Geant4 11.4 的真实信息(G4NuclideTable.cc)。以 Course- 开头的编号是本课程以同样格式写的提示。
Reading阅读3 min3 分钟
/musr/commandoptional · musrSim for Weeks 9–10选修 · 第 9–10 周的 musrSim
Optional: a second environment with Geant4 10.7 and ROOT for musrSim.选修:为 musrSim 准备第二个环境,含 Geant4 10.7 与 ROOT。
Only the musrSim parts of Weeks 9 and 10 need this; the muography track can skip it. musrSim needs Geant4 10.7 and ROOT 6, kept separate from the 11.4 environment. Without CERN's CVMFS, try a second conda environment; check first that conda-forge has Geant4 10.7 builds for your platform. If it does not, build Geant4 10.7.p04 from source following its own install guide, or use a Linux machine with CVMFS as described in Week 9.
只有第 9、10 周的 musrSim 部分需要它;缪子成像方向可以跳过。musrSim 需要 Geant4 10.7 和 ROOT 6,并且要与 11.4 环境分开。没有 CERN 的 CVMFS 时,可以尝试第二个 conda 环境;先确认 conda-forge 为你的平台提供了 Geant4 10.7 的构建。如果没有,请按 Geant4 10.7.p04 自己的安装指南从源码编译,或使用第 9 周介绍的带 CVMFS 的 Linux 机器。
conda search -c conda-forge "geant4=10.7" mamba create -n musr -c conda-forge geant4=10.7 root cmake make cxx-compiler conda activate musr geant4-config --version && root-config --version
The course team has not yet built musrSim in this environment: treat this route as a starting point and report what works.
课程团队尚未在这个环境中编译过 musrSim:请把这条路线当作起点,并反馈实际效果。
Reading阅读3 min3 分钟
/control/execute week02.macnext下一步
Installed and checked? Go back to Week 1, or straight on to Week 2.安装并检查完毕?回到第 1 周,或直接进入第 2 周。
Week 1 · A Monte Carlo primer →第 1 周 · 蒙特卡罗入门 → · Week 2 · Run, Event, Track, Step →第 2 周 · 运行、事例、径迹、步 →
