开发

q2m3 使用 src 布局，以 uv 管理依赖、Ruff 检查代码、Black 格式化代码，并用 pytest 测试。

环境配置

安装任务所需的开发工具和 extras。工作流 extras 见 快速开始。

uv sync --frozen --extra dev

测试

先使用范围最小且能验证目标的命令。

uv run pytest tests/test_basic.py -v
uv run pytest tests/solvation -v -m "not slow and not gpu"
uv run pytest tests/ --collect-only -q --no-cov
uv run pytest tests/ --cov=src/q2m3 --cov-report=term-missing

已注册的标记包括 slow、solvation、catalyst、gpu、rdm 和 sqd。标准 CI 路径跳过慢速测试和 GPU 测试。

标记为 external 的测试需要独立的 conda-forge Psi4 环境。未设置 Q2M3_PSI4_PYTHON 时，测试跳过。将该变量设为这个环境的 Python 解释器路径：

Q2M3_PSI4_PYTHON=/abs/path/to/psi4-env/bin/python \
  uv run pytest tests/fragments -m external -n 0

安装配置

从仓库根目录执行这些命令。每个配置使用独立环境。core 环境不得包含 SQD 或 Catalyst extras。sqd 环境必须包含 SQD 依赖，不得包含 Catalyst。包含全部 extras 的环境无法检查这两个隔离边界。

在 Python 启动前设置这些变量：

export OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 NUMEXPR_NUM_THREADS=1
export JAX_PLATFORMS=cpu
UV_PROJECT_ENVIRONMENT=.cache/venvs/core uv sync --frozen --extra dev
UV_PROJECT_ENVIRONMENT=.cache/venvs/core uv run --no-sync pytest -n 0 --q2m3-profile core --collect-only --no-cov
UV_PROJECT_ENVIRONMENT=.cache/venvs/core uv run --no-sync pytest -n 0 --q2m3-profile core

UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd uv sync --frozen --extra dev --extra sqd
UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd uv run --no-sync pytest -n 0 --q2m3-profile sqd --collect-only --no-cov
UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd uv run --no-sync pytest -n 0 --q2m3-profile sqd

UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd-catalyst uv sync --frozen --extra dev --extra sqd --extra catalyst --extra solvation
UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd-catalyst uv run --no-sync pytest -n 0 --q2m3-profile sqd-catalyst --collect-only --no-cov
UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd-catalyst uv run --no-sync pytest -n 0 --q2m3-profile sqd-catalyst

测试收集检查依赖隔离与测试选择，不满足执行门槛。运行完整配置时不得限制测试路径，以检查必需节点和覆盖率。仅通过子集不足以满足要求。各配置默认排除 slow 和 GPU 测试。非 Catalyst 配置还排除 Catalyst 与 solvation 测试。

可选的串行慢速测试使用已配置的 sqd-catalyst 环境，以及上文导出的变量：

UV_PROJECT_ENVIRONMENT=.cache/venvs/sqd-catalyst uv run --no-sync pytest -n 0 --q2m3-profile sqd-catalyst --q2m3-include-slow

该命令仍排除 GPU 测试。较大的教程实验应放入手动 slow-science 工作流。共享 CI 不保证重新生成本地校准、历史 G2B 或回放研究，也不保证生成占位实验报告。

共享产物检查位于 tests/examples/test_sqd_showcase.py。它们检查保存字段、有符号误差、对照、失败记录和输出目录。test_real_h2_tutorial_matches_independent_casci 检查真实 H₂ 教程。test_saved_showcase_directories 还要求设置 Q2M3_SHOWCASE_ROOT，且目录含 ci-scan、ci-embedding 和 ci-integrals。缺少该输入时，测试跳过。仅收集测试无法检查这些产物。

代码检查与格式化

uv run ruff check src/ tests/
uv run black --check src/ tests/ --line-length 100
uv run black src/ tests/ --line-length 100

面向 GitHub 的改动还需运行：

uv run pre-commit run check-yaml --all-files

文档工作流

在 doc/source/ 中使用 RST 编写英文页面。中文目录位于 doc/locales/zh_CN/LC_MESSAGES/，包含英文 docstring 提取的 API 文本。源码 docstring 保持英文。

修改文档或 API 文档字符串时：

  1. 编辑并简化英文源文。

  2. 提取消息并更新翻译目录。

  3. 审校中文译文。保留条件、单位、公式、引用目标，以及负面或无定论的结果。

  4. 构建并检查两种语言。

make docs-gettext
uv run python doc/translations.py update
# Review and translate the updated PO files before the check.
uv run python doc/translations.py check
make docs
make docs-doctest

make docs 提取消息、检查译文，并以警告视为错误的方式构建两种语言；还会检查生成的站点。英文默认入口为 /q2m3/，中文位于 /q2m3/zh_CN/。使用侧栏语言链接打开另一种语言的对应页面。切换不保留查询参数或段落锚点。

项目界面消息清单位于 doc/ui-messages.json。主题文本改变时更新此文件。doc/site-baseline.json 记录初始提交和发布页面路径。只有计划增删发布页面时才修改页面清单。移动页面还需移动翻译目录、更新传入链接和检查跳转。conf.py 与 _templates/redirect.html 保留原 SQD 和核心概念网址。

仅预览英文时，使用：

make -C doc html

提交 PO 目录。POT、MO、HTML 和 doctree 文件属于构建产物。Sphinx 将英文 HTML 写入 doc/build/html/。中文 HTML 位于 zh_CN/ 子目录。两种语言使用独立 doctree。

默认文档示例应保持小规模。将 H3O+、8 位 QPE、动态 Trotter 扫描和内存剖析放入可选诊断章节。入门教程应使用较小示例。

贡献说明

对照源码、测试、维护中的示例和当前 README 检查公开文档。如果这些来源与旧计划说明冲突，以当前源码和测试为准。

当科学结论的解释依赖相关取值时，应说明活性空间、量子比特数、QPE 精度、Trotter 设置和单位转换假设。

贡献者不应提交生成的覆盖率报告、Sphinx 构建输出、Catalyst IR 缓存文件、基准输出或临时剖析产物。