SU2-Quantum

SU2-Quantum 是 SU2 的一个研究分支，在求解器中加入 FT 频域滤波器，用于研究量子噪声 / 有限比特精度对 CFD 数值行为的影响，并配套一套 TGV（Taylor–Green Vortex）实验台、HyperQueue 扫描与可复现的实验记录。

• 上游关系：main 跟踪上游版本点，quantum 承载项目改动
• 完整文档：使用 MkDocs 构建，运行 poe docs 可在本地预览

快速上手

uv sync --group dev   # Python 依赖（poethepoet / pytest 在 dev 组）
poe setup             # meson 配置：-O3 -march=native，开 MKL / OpenMP / MPI / pywrapper
poe build             # ninja 编译并安装到 ./bin/
poe run               # 冒烟：8 MPI × 4 OMP，16³ 网格，8 步，不开 FT 滤波

在 HPC 计算节点上改用 poe setup --hpc / poe build --hpc（走 srun，-O2，关 MKL）。

poe 会自动设置 SU2_RUN / SU2_HOME / PATH / PYTHONPATH，因此一律通过 poe 运行， 不要手写 meson / ninja / mpiexec 命令行。

⚠️ submodule：什么时候必须手动跑一次

poe setup 的内部链路是 meson.py → preconfigure.py → meson_scripts/init.py::init_submodules()。 它按 git submodule status 输出的首字符分支处理：

状态	含义	脚本行为
-	未初始化	自动执行 git submodule update --init <path>
+	已初始化，但 SHA 与 index 不符（版本漂移）	只打 WARNING，不动手
	版本正确	跳过

所以：全新克隆确实是全自动的（所有 submodule 都处于 -）。 但只要你切过分支、而两个分支记录的 submodule SHA 不同，状态就变成 +—— poe setup 此时只会警告一句

WARNING: the currently checked out submodule commit in <path> does not match the SHA-1 found in the index.

然后继续用错误版本的依赖编译下去。因此切分支之后必须手动跑一次：

git submodule update --init --recursive

poe 任务速查

任务	说明
poe setup [--hpc]	meson 配置（带 --wipe，会重建 build/）
poe build [--hpc]	ninja 编译 + 安装到 ./bin/
poe run	单算例冒烟测试
poe submit <args>	HyperQueue 多轴笛卡尔扫描
poe plot	TGV 动能 / 耗散率 / 拟涡能出图
poe clean [dir] [-a]	把算例产物移入回收站（-a 连 history / pdf / logs 一起）
poe test-py	pytest：tests/（自动跳过 @pytest.mark.integration）
poe test-tgv / poe test-tgv-fast	TGV 集成测试：tests/integration/（后者跳过 @pytest.mark.slow）
poe test-cpp	meson（C++）测试
poe test	test-py + test-cpp
poe docs / poe docs-build	MkDocs 预览（:8888）/ 静态构建到 ./site/

代码风格：只走 pre-commit

本仓库的格式化只通过 pre-commit 执行，配置在 .pre-commit-config.yaml；CI 侧由 .forgejo/workflows/code-style.yml 复跑同一套。 clone 之后请先装上 git hook：

uv tool run --from pre-commit pre-commit install

两条硬规则：

1. 工具版本被钉死，不要改：clang-format v15.0.7、black 22.6.0。 这两个工具跨版本的输出并不一致，换版本会让大量与你改动无关的文件产生 diff。 pre-commit 会自行把钉死的版本下载到 ~/.cache/pre-commit，所以你不需要在本机安装它们。

2. 绝对不要用本机 clang-format 对全仓库跑一遍。历史上正是这么做， 炸出过一个 1022 个文件的巨型提交，把真实改动完全淹没。 pre-commit 默认只处理本次暂存的文件，这才是正确用法； --all-files 只在有意做一次全仓格式化统一时才用，且必须单独成一个 style: 提交：

   uv tool run --from pre-commit pre-commit run --all-files   # 慎用
   

.pre-commit-config.yaml 把 SU2_CFD/、externals/、subprojects/、TestCases/、legacy/ 以及 CConfig.hpp / CConfig.cpp / option_structure.hpp 排除在 clang-format 之外—— 这是上游既有的约定，改到这些文件时不要顺手"格式化一下"。

测试

命令	覆盖范围
poe test-py	tests/ —— submit / manifest / FT 配置 / FT 模态计数 / 往返一致性。纯 Python，不需要编译产物；tests/integration/ 因带 @pytest.mark.integration 被自动跳过
poe test-tgv	tests/integration/ —— 端到端 TGV 集成测试（golden 值 + 冒烟校验），需要先 poe build
poe test-cpp	UnitTests/ —— meson 驱动的 C++ 单元测试

测试树只有一棵（tests/），单元与集成靠 marker 区分而不是靠并列目录。 tests/integration/reference/history_golden.csv 是被版本控制的 golden 基线； 刷新它的完整步骤见 tests/integration/test_tgv_golden.py 的模块 docstring。

与上游的关系

git remote -v
# upstream  https://github.com/su2code/SU2.git   (fetch)
# upstream  DISABLED_no_push_to_official_su2     (push)   ← 防手滑推到官方仓库

• main = 上游镜像，指向当前跟踪的上游版本点，除升级外不做任何改动
• quantum = 本 fork 的主干，所有开发都在这里
• 想看本 fork 到底改了什么：git diff main quantum
• 跟进上游：更新 main 的版本点，再把 quantum rebase 或 merge 上去

提交信息遵循 Conventional Commits，由 commitizen 管理 （uvx --from commitizen cz commit）；type(scope) 使用英文约定，主题默认使用中文。

---

以下为上游 SU2 的 README（已译为中文）。

SU2（版本 8.5.0 "Harrier"）：开源 CFD 代码

计算分析工具彻底改变了我们设计工程系统的方式，但大多数成熟的代码要么是专有的、要么无法获取，要么对许多用户来说贵得令人却步。SU2 团队正在改变这一点：把多物理场分析与设计优化作为开源软件免费提供出来，并邀请所有人参与它的创建与开发。

请注意，本项目随附一份贡献者行为准则。参与本项目即表示你同意遵守其条款。

如果你使用 SU2 的最新版本，请引用 以致谢活跃的贡献者。

持续集成：

代码质量：

SU2 简介

SU2 是一套用 C++ 编写的开源软件工具集，用于偏微分方程（PDE）的数值求解，以及执行 PDE 约束优化。

其主要应用是计算流体力学与气动外形优化，但已扩展到可以处理更一般的方程，例如电动力学与化学反应流。

更多信息与最新动态请见：

• SU2 主页：https://su2code.github.io
• GitHub 仓库：https://github.com/su2code
• CFD Online：http://www.cfd-online.com/Forums/su2/
• Twitter：https://twitter.com/su2code
• Facebook：https://www.facebook.com/su2code

SU2 安装

Linux、MacOS、Windows 的预编译二进制

你可以在我们的下载页或 releases 下找到最新版本的预编译二进制文件。

构建 SU2

SU2 的构建系统基于 meson（作为前端）与 ninja（作为后端）的组合。Meson 是一个开源构建系统，设计目标是既要极快，更重要的是尽可能对用户友好。Ninja 则是一个专注于速度的小型底层构建系统。

最低依赖简述：

• C/C++ 编译器
• Python 3

注意： 其他所有必需的构建工具与依赖都随源码一同分发，或者会被自动下载。

如果你已经装好了这些工具，就可以用源码根目录下的 meson.py 创建一份配置：

./meson.py setup build

用 ninja 编译并安装代码：

./ninja -C build install

关于如何在 Linux、MacOS 或 Windows 上安装与构建 SU2 的更多信息，请参阅文档。

SU2 路径设置

安装完成后，请务必设置 $SU2_HOME 与 $SU2_RUN 环境变量，并把 $SU2_RUN 加入 $PATH。

例如，把下面几行加到你的 .bashrc 文件里：

export SU2_RUN="your_prefix/bin"
export SU2_HOME="/path/to/SU2vX.X.X/"
export PATH=$PATH:$SU2_RUN
export PYTHONPATH=$SU2_RUN:$PYTHONPATH

$SU2_RUN 应指向所有二进制文件与 python 脚本被安装到的目录，也就是你用 meson 的 --prefix 选项设置的前缀。注意 bin/ 目录会被自动追加到你的前缀路径之后。

$SU2_HOME 应指向源码分发的根目录，即 /path/to/SU2vX.X.X/。

感谢构建，祝优化愉快！

• SU2 开发团队

SU2 开发者

我们遵循流行的 "GitFlow" 分支模型来做可扩展的开发。在 SU2 仓库中，master 分支代表最新的稳定大版本或次版本发布（7.0、6.2.0 等），只应在版本发布时被修改。准备发布的工作，通过 GitHub 上的 Pull Request 从各个 "feature" 分支（大家日常写代码的地方）合入 develop 分支。发布时，已合入 develop 分支的工作会被推到 master 分支并打上 release 标签。

SU2 由世界各地的个人与有组织的团队共同开发。

当前贡献者名单见 AUTHORS.md 文件。

文档

代码文档可以通过在项目根目录调用 doxygen 生成，然后在浏览器中打开 Docs/html/index.html 查阅。