From Track to Truth从径迹到真相Start here从这里开始Week 0 · Set up your computer第 0 周 · 配置你的电脑

$ 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。选一条照着做,最后运行页面末尾的检查。

  • ≈ 2 hfirst-time setup首次配置
  • ≈ 3 GBGeant4 + datasetsGeant4 与数据集
  • 3routes: conda · container · WSL2条路线:conda · 容器 · WSL2
Start开始Go to the lab直接去实验8 items · about 1 h 55 min8 项 · 约 1 小时 55 分钟
you install你要安装
Geant411.4 + datasets数据集
compiler编译器C++17 · CMake ≥ 3.16
Pythonnumpy · scipy · matplotlib · uproot · awkward
Weeks 9–10 only仅第 9–10 周Geant4 10.7 + ROOT 6

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-forgeno不需要
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 或 Bonce, 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,装在你的用户目录下,不需要管理员权限。

  1. 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/)。

    terminal
    bash Miniforge3-$(uname)-$(uname -m).sh -b -p "$HOME/miniforge3"
    source "$HOME/miniforge3/bin/activate"
    conda --version
  2. Mainland China: point conda and pip at a mirror中国大陆:把 conda 和 pip 指向镜像

    Put these lines in ~/.condarc (the USTC mirror https://mirrors.ustc.edu.cn/anaconda/cloud works the same way). Outside China, skip this step.

    把下面几行写进 ~/.condarc(中科大镜像 https://mirrors.ustc.edu.cn/anaconda/cloud 用法相同)。在中国大陆以外可跳过本步。

    ~/.condarc
    channels:
      - conda-forge
    show_channel_urls: true
    custom_channels:
      conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
    terminal
    pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  3. 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 周(预期输出的末几位可能不同)。

    terminalGEANT4
    conda 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 g4c

    The conda-forge geant4 package pulls in the physics datasets as dependencies and sets their environment variables each time you run conda 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 镜像)。

terminal
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。

  1. 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
  2. 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。

  3. 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, run explorer.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 周的首次编译。

  1. Versions and datasets版本与数据集

    terminalGEANT4
    geant4-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 下载,网速慢时请留足时间),然后再次检查。

  2. 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 步中逐行对照。

    terminalGEANT4
    unzip 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.四条说明出错的是配置、而不是你代码的信息。

-------- EEEE ------- G4Exception-START -------- EEEE ------- *** G4Exception : PART70000 issued by : G4NuclideTable G4ENSDFSTATEDATA environment variable must be set Course note: datasets are missing or the environment is not active. Activate the environment in this terminal, then run geant4-config --check-datasets. *** Fatal Exception *** core dump *** -------- EEEE -------- G4Exception-END --------- EEEE -------
-------- EEEE ------- G4Exception-START -------- EEEE ------- *** G4Exception : PART70000 issued by : G4NuclideTable G4ENSDFSTATEDATA environment variable must be set 课程说明:数据集缺失,或当前终端未激活环境。 先在本终端激活环境,再运行 geant4-config --check-datasets。 *** Fatal Exception *** core dump *** -------- EEEE -------- G4Exception-END --------- EEEE -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-a issued by : the shell geant4-config: command not found The environment is not active in this terminal: conda activate g4c, or source <install>/bin/geant4.sh. *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-a issued by : the shell geant4-config: command not found 当前终端未激活环境: conda activate g4c,或 source <安装目录>/bin/geant4.sh。 *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-b issued by : cmake Could not find a package configuration file provided by "Geant4" Same cause, or pass -DGeant4_DIR=<install>/lib/cmake/Geant4. *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-b issued by : cmake Could not find a package configuration file provided by "Geant4" 原因相同;或传入 -DGeant4_DIR=<安装目录>/lib/cmake/Geant4。 *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-c issued by : bash (WSL2) run1.mac: line 1: $'\r': command not found The file was saved with Windows line endings. Edit it on the Linux side, or run: sed -i 's/\r$//' run1.mac *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------
-------- WWWW ------- G4Exception-START -------- WWWW ------- *** G4Exception : Course-W00-c issued by : bash (WSL2) run1.mac: line 1: $'\r': command not found 文件以 Windows 换行保存。请在 Linux 一侧编辑, 或运行:sed -i 's/\r$//' run1.mac *** This is just a warning message. *** -------- WWWW -------- G4Exception-END --------- WWWW -------

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 机器。

terminalMUSRSIM
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 周 · 运行、事例、径迹、步 →

Your progress on this page本页学习进度