PyTimeTag

量子光学实验里常用 时间标签（time tagging） 记录单光子到达时刻与通道；PyTimeTag 提供 Python 库与命令行工具，覆盖时间戳的接收、分块（DataBlock）、序列化/落盘、简单监控与在线处理（含可选 DuckDB 落库）。已内置 Swabian Instruments Time Tagger 与 SeruTek HSPCL6 接入；无硬件时可用 仿真（--source simulator）。

• 仓库：https://github.com/hwaipy/PyTimeTag
• PyPI：https://pypi.org/project/pytimetag/
• 许可证：GPL-3.0

文档结构（Sphinx）

完整文档在仓库 docs/source/，中英双语。建议阅读顺序：

本地构建 HTML（需 requirements-docs.txt）：

make -C docs html-en
make -C docs html-zh

输出目录：docs/build/html/en/ 与 docs/build/html/zh_CN/。说明见 docs/README.md。

环境要求

• Python：3.9 及以上。
• 依赖：NumPy、msgpack、numba、rich、duckdb 等（见 setup.py）。

安装

python -m pip install -U pytimetag

4.0 测试版不会被普通安装命令自动选中。显式安装当前 beta：

python -m pip install "pytimetag==4.0.0b1"

若希望在 4.x 的后续预发布版本之间升级：

python -m pip install -U "pytimetag>=4.0.0b1,<5"

Swabian 硬件（可选）：

python -m pip install -U "pytimetag[swabian]"

SeruTek HSPCL6 使用 Python 标准库 ctypes，无需额外 Python 包；运行环境需要 Windows、厂商 USB 驱动和 Tdc_Libusb_Dll.dll。DLL 默认从厂商安装目录加载，也可用 --driver-path 或环境变量 SERUTEK_TDC_DLL 指定。

从源码：

git clone https://github.com/hwaipy/PyTimeTag.git
cd PyTimeTag
python -m pip install -e ".[swabian]"

入口命令：pytimetag 或 python -m pytimetag。若命令行在程序名后无任何参数，只打印帮助、不启动采集。

命令行速览

pytimetag --help

常用示例：

pytimetag --source simulator
pytimetag --source serutek --save --output-dir ./serutek_data
pytimetag --save --output-dir ./my_data
pytimetag --save --storage-db ./analytics/run.duckdb

参数说明（含在线处理开关 --post-process / --storage-db、--datablock-dir、切分模式、硬件选项等）见上文 CLI 详细手册 链接。

Web GUI（Vue + Quasar）

已提供内置 GUI 服务端（FastAPI + WebSocket + Celery）与前端工程骨架（webui/）。

启动 API + GUI（默认仅监听本机 127.0.0.1:8787）：

pytimetag gui --host 127.0.0.1 --port 8787

在连接 HSPCL6 的 Windows 主机上启动 SeruTek GUI，并允许局域网访问：

pytimetag gui --device serutek --host 0.0.0.0 --port 8787

SeruTek 默认使用 USB0、6 个通道、4194304 事件缓冲和 0.2 秒轮询。GUI 的设备页支持实时查看计数率、调整阈值以及启用/屏蔽通道；HSPCL6 不支持通用的六通道 dead-time 设置。

离线任务使用 Celery，需单独启动 worker（默认 Redis）：

celery -A pytimetag.gui.worker:celery_app worker --loglevel=INFO

若控制台出现 No supported WebSocket library detected，请补装：

python -m pip install websockets wsproto

前端源码在 webui/（Quasar）：

cd webui
npm install
npm run dev
npm run build

推荐开发调试（前后端分离，支持热更新）：

# 终端1：Python 后端（API + WS，代码变更自动重载，不托管静态前端）
pytimetag gui --host 127.0.0.1 --port 8787 --reload --no-web

# 终端2：Node 前端（Vite/Quasar HMR）
cd webui
npm run dev

调试时访问 http://127.0.0.1:5173。前端 devServer 已配置将 /api 与 /ws 代理到 127.0.0.1:8787。

也可以在仓库根目录一键启动：

make dev

可单独启动：

make dev-backend
make dev-frontend

npm run build 产物将输出到 pytimetag/gui/webui_dist/，并可随 pip 安装包一起发布。

关键接口：

• GET /api/v1/meta
• GET /api/v1/sources
• GET /api/v1/session/status
• POST /api/v1/session/start
• POST /api/v1/session/stop
• GET /api/v1/analyzers
• PUT /api/v1/analyzers/{name}
• GET /api/v1/settings
• PUT /api/v1/settings
• GET /api/v1/datablocks
• POST /api/v1/offline/process
• GET /api/v1/jobs
• GET /api/v1/jobs/{job_id}
• GET /api/v1/logs
• WS /ws/metrics
• WS /ws/logs
• GET /healthz
• GET /readyz

Docker 一键启动（Redis + API + Worker）：

docker compose up --build

默认访问：http://127.0.0.1:8787

作为库使用

安装后可 import pytimetag，使用 DataBlock、device_type_manager、TimeTagSimulator 等。硬件设备类需从子模块导入（不会随 import pytimetag.device 自动加载）：

from pytimetag.device.SwabianTimeTag import SwabianTimeTag
from pytimetag.device.SerutekTimeTag import SerutekTimeTag

API 由 Sphinx AutoAPI 生成，见各语言文档中的 API 参考 章节。

开发与测试

python -m pip install -e ".[swabian]"
python -m unittest discover -s tests -p 'test*.py'

CI 见 .github/workflows/。