阅读与运行指南

在线站点 · 版本发布与下载 · 返回项目首页 · 课程 1 · 课程 2 · 课程 3 · 课程 4

先找到一个实验

从首页课程表进入课程目录，再点击实验名称查看完整入口。目录提供在线报告、HTML 计算阅读版、Jupyter、Wolfram 与源报告 PDF 的直达链接。

源报告 PDF 用于对照原始资料；重新整理和核算的报告位于各实验的 report/。源资料的文件名保留原样，实验归属以课程目录和 PDF 清单为准。

在浏览器中查看 HTML

从在线站点或课程目录中的在线入口进入实验。HTML 计算阅读版可直接操作已有控件，报告阅读版提供完整排版。例如：单摆在线计算 · 单摆在线报告。

克隆或下载完整仓库后，也可在本机浏览器打开仓库中的原始 HTML；保留完整目录可同时使用报告引用的相对路径图片。

下载版本阅读包

从版本发布下载 general-physics-lab-v0.1.0-reading.zip，解压后进入其中的 general-physics-lab-v0.1.0 文件夹，启动随包提供的本地阅读服务：

Expand-Archive .\general-physics-lab-v0.1.0-reading.zip -DestinationPath .\reading
cd .\reading\general-physics-lab-v0.1.0
python serve.py

在浏览器打开：

http://127.0.0.1:8000/general-physics-lab/

阅读包保持在线站点的 /general-physics-lab/ 路径，serve.py 将该目录、公式资源和图表一起提供给本机浏览器。服务仅绑定本机地址；结束时按 Ctrl+C。使用其他版本时，将文件名与解压目录中的版本号相应替换。

阅读包用于报告、图表和已有控件；编辑数据或重新运行 Python、Wolfram 计算时，使用完整仓库与对应运行环境。

克隆仓库的本地预览

在仓库根目录启动本地预览服务：

python -m http.server 8000 --bind 127.0.0.1

然后打开：

http://127.0.0.1:8000/experiments/course-01/pendulum/notebooks/analysis.html

其中 course-01/pendulum 可替换为其他实验标识。查看报告阅读版则将后半段改为 report/report.html。结束时在启动服务的终端按 Ctrl+C。

HTML 中的滑块、菜单、曲线提示与缩放在浏览器中执行。数学公式由 MathJax 排版。

运行 Jupyter Notebook

以下命令在 Windows PowerShell 中执行。已有本地仓库时直接进入仓库根目录。

git clone https://github.com/HNNUYUXUAN/general-physics-lab.git
cd general-physics-lab
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]" jupyterlab
.\.venv\Scripts\python.exe -m ipykernel install --user --name general-physics-lab --display-name "General Physics Lab"
.\.venv\Scripts\python.exe -m jupyterlab

Python 要求 3.11 及以上。macOS／Linux 的虚拟环境解释器路径为 .venv/bin/python；按本机环境调整命令。

在 JupyterLab 打开一个实验的 notebooks/analysis.ipynb，选择 General Physics Lab 内核，重启内核并运行所有单元。Notebook 自带执行输出；GitHub 静态预览可用于阅读，较大的文件可下载到本机查看。

成稿图表使用宋体（SimSun）与 Times New Roman。运行前安装这两种字体。Markdown／Jupyter 的数学公式使用标准 LaTeX，可在 VS Code 或 Jupyter 中查看。

只想重新检查某个已保存 Notebook 的执行情况：

.\.venv\Scripts\python.exe scripts/execute_notebooks.py --experiment course-03/rlc-resonance

执行结果保存在 .build/notebook-checks/。使用 --all 可检查全部 45 个实验。

打开 Wolfram Notebook

每个实验提供独立 Paclet。推荐使用实验入口中的安装包，这样代码、数据和 Notebook 可一起加载。

下面以物质密度实验为例，在 Wolfram Notebook 中运行。将 root 改为本机仓库路径：

root = "D:/general-physics-lab";
PacletInstall[FileNameJoin[{
  root, "notebook", "paclets", "DensityLab", "dist",
  "DensityLab-0.1.0.paclet"
}]];
Needs["DensityLab`"];
DensityLab`OpenNotebook[]

打开后，从新内核依次求值。安装包自带规范数据，可以独立于本仓库使用。单摆使用 PendulumLab 包，其打开入口为 PendulumLab`PLOpenNotebook[]；其他实验的包名见课程目录及 experiments/registry.json。

直接阅读 .nb 的已保存输出也需要 Wolfram 前端。若要重新生成安装包或完整三稿，还需可调用的 WolframScript、指定字体和可用前端。

修改数据与重新构建

先阅读数据与方法。规范读数位于实验的 data/，参数与单位位于 experiment.json。修改后运行该实验的完整双端流程：

.\.venv\Scripts\python.exe scripts/pipeline.py all --experiment course-03/rlc-resonance
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe scripts/check_delivery.py --experiment course-03/rlc-resonance

通过 WOLFRAMSCRIPT 指定本机 WolframScript 路径；Windows 可用 PHYSICSLAB_BUILD_ROOT 设置较短的暂存目录。构建、呈现检查和结果发布流程见开发文档。

--all 批量构建单摆以外的 44 个实验。单摆使用 scripts/pipeline.py all 重建。

计算记录与问题定位

每个实验的 results/verification.json 记录双端数值对照；执行、呈现和交互核验分别保存在本实验的 results/ 中。验收汇总集中列出资料限制。