ROOT 与 JupyterLab 安装及运行检查

本页介绍如何配置 notebook，并通过绘图和 ROOT 文件读写检查环境是否可用。完成这些检查后，就可以运行课程作业中的示例。

PyROOT 用 Python 调用 ROOT，ROOT C++ 用 C++ 调用 ROOT；JupyterLab 提供 notebook 界面。选择一种语言即可，两者使用相同的 ROOT 对象和文件格式。

如果已有可用的 ROOT notebook 环境，或使用课程提供的 Jupyter 服务，可直接进行运行检查。以下用 Miniforge 在 Linux、macOS 或 Windows WSL2 中的 Ubuntu 上配置本地环境。

1. 准备终端环境

Linux 用户可直接进入第 2 节。macOS 用户使用系统终端；若尚未安装 Apple Command Line Tools，先运行 xcode-select --install，按提示完成安装。

在 Windows 10（2004 或更新版本）或 Windows 11 中，以管理员身份打开 PowerShell，安装 Ubuntu：

wsl --install -d Ubuntu

如有提示，先重启电脑，再从开始菜单打开 Ubuntu，设置 Linux 用户名和密码。在 PowerShell 中检查：

wsl --list --verbose

Ubuntu 对应的版本应为 2；若显示 1，运行 wsl --set-version Ubuntu 2。后续命令均在 Ubuntu 终端中输入，不是在 PowerShell 中。

2. 安装 ROOT 与 JupyterLab

安装 Miniforge

Ubuntu 用户先安装下载工具；macOS 用户跳过下面两条命令：

sudo apt update
sudo apt install -y curl ca-certificates

下载与操作系统和处理器架构匹配的安装程序：

mkdir -p ~/Downloads
cd ~/Downloads
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash "Miniforge3-$(uname)-$(uname -m).sh"

保留默认安装目录，并在询问是否初始化 conda 时输入 yes。关闭并重新打开终端，运行 conda --version 检查。

安装课程所需的软件包

conda config --set channel_priority strict
conda config --set auto_activate_base true
conda install -n base -c conda-forge root jupyterlab notebook ipykernel metakernel numpy

ROOT 提供数据分析类和 PyROOT 接口，NumPy 提供数值数组，其余软件包支持 Jupyter 及 Python、ROOT C++ notebook。RooFit 不需要单独安装。

这里使用 Miniforge 默认的 base 环境，新终端会自动加载它。如果已有可用环境，可以继续使用；注意不要混用不同安装来源的 ROOT、Python 和 Jupyter。

3. 启动 notebook

mkdir -p ~/experimental-methods
cd ~/experimental-methods
jupyter lab --no-browser

在浏览器中打开终端给出的完整地址，包括其中的 token。WSL 用户使用 Windows 浏览器。使用 JupyterLab 期间保持终端运行。

在 JupyterLab 中打开本次作业的文件夹，点击 +，选择 Python 3 运行 PyROOT，或选择 ROOT C++ 运行 C++。课程 HTML 页面用于阅读；运行示例时，新建 .ipynb notebook，或打开课程提供的 notebook 文件。

按 Shift+Enter 运行当前单元格。需要输入文字和公式时，将单元格类型改为 Markdown。
选择 Kernel → Interrupt Kernel，可以中断正在运行的计算。
选择 Kernel → Restart Kernel and Run All Cells，可以重启计算内核（kernel）并从头运行所有单元格。保存 notebook 不会保存 kernel 内存中的变量。
按 Ctrl+S 保存，macOS 使用 ⌘+S。结束使用时，在启动 JupyterLab 的终端中按 Ctrl+C。

4. 检查绘图与 ROOT 文件读写

按所选语言运行下面的单元格。%jsroot on 用于开启 Jupyter 中的交互式绘图，不用于普通 Python 脚本或 C++ 源文件。

代码语言：

import ROOT
print(ROOT.gROOT.GetVersion())

%jsroot on

创建直方图，并显示在画布上：

c = ROOT.TCanvas("c", "Installation check", 600, 400)
h = ROOT.TH1F("h", "Test histogram;x;Counts", 20, 0, 10)
h.Fill(4.5)
h.Draw()
c.Draw()

将直方图写入测试文件，再重新打开文件并读出：

fout = ROOT.TFile("root_check.root", "RECREATE")
h.Write()
fout.Close()

fin = ROOT.TFile.Open("root_check.root")
fin.ls()
hread = fin.Get("h")
print("Entries:", hread.GetEntries())
fin.Close()

#include <iostream>
#include <TROOT.h>
#include <TCanvas.h>
#include <TH1.h>
#include <TFile.h>
std::cout << gROOT->GetVersion() << std::endl;

%jsroot on

创建直方图，并显示在画布上：

TCanvas *c = new TCanvas("c", "Installation check", 600, 400);
TH1F *h = new TH1F("h", "Test histogram;x;Counts", 20, 0, 10);
h->Fill(4.5);
h->Draw();
c->Draw();

将直方图写入测试文件，再重新打开文件并读出：

TFile *fout = new TFile("root_check.root", "RECREATE");
h->Write();
fout->Close();

TFile *fin = TFile::Open("root_check.root");
fin->ls();
TH1F *hread = nullptr;
fin->GetObject("h", hread);
std::cout << "Entries: " << hread->GetEntries() << std::endl;
fin->Close();

运行后应看到一个仅有一个 bin 被填入的直方图；文件列表中应包含 h，并输出 Entries: 1（或 1.0）。RECREATE 会覆盖同名文件，只用于自己的输出文件，不要用它打开原始实验数据。

5. 准备作业文件

每份作业的 notebook 和输入数据放在同一个文件夹中，例如：

coursework3.1/
    analysis.ipynb
    gamma.root

从 HPGe 作业下载 gamma.root；PSD 作业使用 liquidpsd_tree.root。将数据上传或复制到 notebook 所在文件夹，再按示例中的文件名打开。计算结果另存为其他文件名。

进行布拉格曲线和望远镜模拟作业时，也将导出的阻止本领、射程表放在 notebook 所在文件夹。可用 LISE++ 或 SRIM 获得这些表格，使用方法见能量损失计算实例。

WSL 用户可运行 explorer.exe .，在 Windows 文件资源管理器中打开当前 Ubuntu 目录，再复制文件。也可以使用 JupyterLab 的上传按钮。

平时如何启动

cd ~/experimental-methods
jupyter lab --no-browser

打开作业文件夹及其中的 notebook。Tutorial I 介绍作业 1–3 所需的 ROOT 操作；Tutorial II 介绍作业 4.1 和 5.1 所需的 TTree 方法。

6. 常见问题

import ROOT 失败，或找不到 ROOT C++ kernel：在终端中运行下面的命令，检查程序路径和 kernel。按本页配置时，ROOT、Python 和 Jupyter 应来自同一套 miniforge3 安装。
图没有显示：绘制对象后，调用 c.Draw() 或 c->Draw()。如果交互式显示失败，可尝试 %jsroot off，改用静态图。
找不到数据文件：检查 notebook 所在文件夹及完整文件名，注意大小写。成功打开 ROOT 文件后，fin.ls() 可列出文件中的对象。

which root
which python
which jupyter
root-config --version
python -c 'import ROOT; print(ROOT.gROOT.GetVersion())'
jupyter kernelspec list

寻求帮助时，请提供出错的命令和报错信息，不要公开包含 Jupyter token 的地址。

接下来

在课程主页选择相应的编程基础与 Tutorial I。