Optics: cache pixel-area Moffat kernels

benchmarks/2mass_all_sky_psf_lookup_2026-08-28.md

@@ -0,0 +1,65 @@
+# 2MASS 全天 1080p Moffat lookup 基准（2026-08-28）
+
+## 目的
+
+测量 `PsfKernelCache` 在真实全天 2MASS catalog、高星像数单帧中的端到端
+收益，并与查表实现之前的直接 Moffat 路径比较。两个运行使用相同的相机、
+catalog、输出尺寸与曝光；唯一意图中的算法差异是 PSF 计算。
+
+## 可复现环境
+
+- Git base revision: `a71180706f3abfb9fe7669a2366944ea3141d78c`。查表结果来自
+  其上的 PSF lookup 工作树，随后由本次提交固化；基线为改动前二进制。
+- Host CPU: 12th Gen Intel Core i7-12700K，16 个 online logical CPUs。
+- Build defaults: C11、`-march=native -O2 -pipe`、OpenMP、PNG output。
+- Catalog loading: `--catalog-load-workers 4`（默认值）。
+- Render workers: 1920 x 1080 的 RGB `double` private HDR buffer 约为
+  47.5 MiB；在 `FRAME_SPLAT_MAX_PRIVATE_HDR_BYTES = 512 MiB` 限制下，
+  最多使用 **10 个** private-HDR render workers。
+- Catalog: `assets/2mass/processed/all_sky`；本视场请求并加载 9,328 个
+  tiles，共 18,148,775 颗 catalog stars。
+
+## 控制变量与命令
+
+相机朝向南天极 `(RA, Dec) = (0 deg, -90 deg)`，60-degree 水平视场，
+1920 x 1080，`--coarse-cell-pixels 16`，exposure `1e12`。两次均产生
+16,555,241 个星像。
+
+```sh
+time ./build/minkowski_sky \
+  --all-sky-catalog assets/2mass/processed/all_sky \
+  --look-ra-deg 0 --look-dec-deg -90 \
+  --width 1920 --height 1080 \
+  --coarse-cell-pixels 16 --fov-deg 60 \
+  --exposure 1e12 \
+  --output output/imgs/2mass_1080p_60deg_south_pole_1e12_psf_cache.png
+```
+
+用 `--psf-direct` 可在同一查表版本中运行 8-point 直接积分参考；历史基线
+在该选项加入前使用逐像素 `pow()` 直接 Moffat 求值。
+
+## 结果
+
+| 路径 | images | cache build | cached / direct fallback | prefetch | user | system | wall |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| 历史直接 Moffat | 16,555,241 | — | — | 3.913 s | 1617.84 s | 2.33 s | 165.59 s |
+| 64x64 lookup | 16,555,241 | 6.520 s | 16,555,241 / 0 | 3.981 s | 645.24 s | 4.02 s | 74.48 s |
+
+查表版本端到端 wall time 加速为 `165.59 / 74.48 = 2.22x`，节省 91.11 s
+（55.0%）；user CPU time 加速为 `2.51x`。预取差异仅 0.068 s，不能解释
+该提升。扣除一次性 kernel build 后，查表运行剩余 67.96 s；该数仅用于说明
+多帧或更多星像时的摊销潜力，不应与没有建表步骤的历史单帧总时间混为同一
+端到端指标。
+
+这次 lookup 运行的 `cached splats` 等于 image count，且 direct fallback 为
+零，因此该速度结果没有把亮星回退的成本隐藏在统计之外。
+
+## 输出一致性与范围
+
+本基准确认 catalog 预取、source-triangle 查询和星像计数在优化前后不变。
+PSF 的 float-HDR 像素精度验收另见单星直接积分比较：默认 `FWHM=2.7,
+beta=4.5` 的最大误差为直接参考峰值的 `3.18e-5`，RMS 为 `8.25e-7`。
+
+本记录比较的是历史点采样直接路径与新的像素面积积分 lookup 路径的性能。
+在需要逐像素数值回归时，使用新二进制的 `--psf-direct`（8-point
+pixel-area reference）而非历史路径。