118 lines
9.4 KiB
Markdown
118 lines
9.4 KiB
Markdown
# AGENTS.md
|
||
|
||
## 项目目标
|
||
|
||
本仓库要构建一个**离线、以物理正确性为优先的数值相对论时空视频渲染器**。最终目标是把双黑洞（BBH）并合等动态数值相对论（NR）演化输出的真实四维时空渲染为 4K 视频。
|
||
|
||
渲染器必须直接消费时间依赖的 4D metric，对每条相机光线进行向过去的 null geodesic tracing；它不是仅渲染静态快照、波形或标量诊断的工具。第一阶段只处理两种 ray 终态：被黑洞捕获，或逃逸到无穷远天球。局域物质辐射、吸积盘、流体和等离子体均不在当前范围内。
|
||
|
||
设计依据是 [`nr_spacetime_movie_renderer_design.md`](nr_spacetime_movie_renderer_design.md)。实现前应先阅读与修改内容相关的章节；该文档是架构和物理取舍的权威来源。
|
||
|
||
## 不要偏离的方向
|
||
|
||
- 不以实时性能、游戏式视觉近似或 ShaderToy 式效果为目标。
|
||
- frozen snapshot 只能作为数值演化代码内的廉价诊断，不能替代最终的动态 4D 渲染。
|
||
- 不把恒星背景预烘焙成 RGB 天球纹理；恒星是带方向、温度和振幅的点源 catalog。
|
||
- 相机不是固定三维坐标，而是 worldline 加 tetrad 的预生成轨迹。
|
||
- 第一版只做 CPU；先验证物理与数据流，再考虑 GPU。
|
||
- 不为复杂 OO/class hierarchy 增加抽象。首选 C 的 `struct`、明确 ownership、函数表和连续数组。
|
||
|
||
## 核心架构约束
|
||
|
||
### 时间组织
|
||
|
||
所有帧的 ray 必须按 coordinate time 汇总，沿时间从新到旧，通过可装入内存的 metric time slab 推进。不要按 frame 各自重复加载所需的 4D 数据。
|
||
|
||
每个 refinement pass 只追踪新请求的 samples：完整追踪后才能判断 image-plane triangle 是否需要细分，而早期 slab 此时已释放。不能在同一次 slab sweep 中临时创建新 ray 并回到相机时间重新追踪。
|
||
|
||
### Ray 与并行
|
||
|
||
- 以 coordinate time `t` 作为 geodesic ODE 自变量，使 ray 演化与 slab 边界自然对齐。
|
||
- 批量 ray 状态采用 SoA `RayPool`，避免 per-ray allocation；支持 activation、终止和 stream compaction。
|
||
- 用 OpenMP 对 active ray pool 做粗粒度循环并行。不要为单条 ray 或 triangle 创建 task，也不要引入细粒度 mutex。
|
||
- metric evaluator 的可变缓存和插值 scratch space 必须是 thread-local，不能共享可变 cache。
|
||
- 优先 bulk arrays、顺序 metric I/O、time-slab streaming 和 coarse-grained parallelism。
|
||
|
||
### 镜头映射与点源渲染
|
||
|
||
每帧在 image plane 上使用 adaptive triangle mesh。每个顶点保存 film 坐标、ray 状态、逃逸方向 `n_inf` 与频移信息。根据真实 mapping 与局部插值的误差、orientation consistency 和 Jacobian 奇异性进行局部细分。
|
||
|
||
最终从局部可逆 triangle 构造 inverse lens map：`sky direction -> image position`。同一恒星被多个局部 patch 覆盖时自然形成多像；不要依赖全局“第几阶像”分类。
|
||
|
||
catalog 内部数据保留 `(direction, temperature, amplitude)`，而非 RGB。对每个像计算局部 magnification 与频率比 `g`，用 `T_obs = g * T_emit` 处理黑体频移，并以保留亚像素位置的 PSF 直接 splat 到 HDR framebuffer。
|
||
|
||
## Backend 与模块边界
|
||
|
||
顶层 movie scheduler 不得依赖具体 metric 来源。时空 backend 至少应可替换为：Minkowski、解析 Schwarzschild，以及 nmesh 4D 数值时空；未来可加入 Kerr/BBH。
|
||
|
||
- `observer`：worldline/tetrad 读取、插值和正交化；不实现 geodesic 或渲染。
|
||
- `movie` / `frame`：帧时间表、adaptive mesh、refinement 请求与 ray 结果回填。
|
||
- `ray`：批量 ray 状态、初始化、生命周期和 compaction。
|
||
- `geodesic`：3+1 null geodesic RHS、频移、ODE stepper 和 slab 内推进；不处理磁盘 I/O 或 frame mesh。
|
||
- `spacetime`：backend 统一接口、slab、metric/导数插值以及 capture/infinity classification。
|
||
- `nmesh_backend`：读取原生 DG node 输出、AMR lookup、Lagrange 空间插值及导数、时间插值和 puncture trajectories。
|
||
- `catalog`：Gaia/2MASS 等 catalog 的读取、内部转换和天球索引。
|
||
- `optics` / `psf`：黑体频移、linear RGB、flux、PSF 和 HDR 累积。
|
||
- `output`：HDR、曝光、tone mapping、PNG/EXR 与视频编码接口。
|
||
|
||
对 nmesh 数据，直接在原生 DG nodes 上用 Lagrange basis 插值及求空间导数；不要先重采样到 Cartesian uniform grid，也不要求相邻时间 slice 的 AMR tree 拓扑对应。对固定全局点，应分别在各 slice 的空间 mesh 上求值，再进行时间插值。
|
||
|
||
优先从 3+1 identities、已知 gauge RHS 或 temporal interpolant 的解析导数获得时间导数；不要为已有插值量另行做低阶 finite difference，也不要在 geodesic RHS 中计算不会使用的量。
|
||
|
||
## 黑洞终止与暗终态
|
||
|
||
过去向光线不使用 horizon 内位置 cutoff、AH-calibrated puncture 小球或 armed/re-entry
|
||
状态机判定正常物理捕获。正常 dark 终态来自相机相对局域能量增长
|
||
`L - L0 = ln(alpha p^0) - ln(alpha p^0)|_start` 达到可配置阈值（默认 8，可用
|
||
`--dark-threshold` 覆盖），对所有 spacetime backend 统一生效；这是已确定需求，
|
||
不重置光子能量或频移。不同 dark reason 不制造 mesh seam。无法可靠推进的
|
||
积分必须报告具体数值失败，不得改写成 capture。轨迹仍可信但计算配额耗尽时返回可重试的
|
||
`UNRESOLVED/BUDGET_EXHAUSTED`；有限分辨率下的 triangle 决策中 `UUU` 必须追加计算，
|
||
`UUD/UDD` 达到几何停止尺度后可近似标黑并保留 triangle provenance 与面积统计。
|
||
不假定每次生产演化都会运行昂贵的 AH finder，也不依赖 capture sidecar。跨 chart、
|
||
跨 region 或穿越视界本身不是暗终态。
|
||
|
||
## 开发与验证顺序
|
||
|
||
按以下层级实现和回归验证，后续阶段不得绕过前一阶段的基准：
|
||
|
||
1. Minkowski + 星表：验证 observer/camera projection、天球方向、catalog、温度/振幅、PSF 和 mesh。
|
||
2. 解析 Schwarzschild：验证 capture、Einstein ring、多像、refinement、局部 inverse map、放大率和频移。
|
||
3. 数值单 Schwarzschild：验证动态 4D slab streaming，并与解析解比较逃逸方向、频移和捕获分类。
|
||
4. FOZ4c BBH：在上层架构不重设计的前提下接入成熟的 BBH 演化。
|
||
|
||
新增物理、插值或优化时，优先添加能与前一阶段比较的收敛测试或 regression test。尚未由 prototype/convergence test 决定的参数（如时间输出 cadence、时间插值阶数、slab 大小、refinement 阈值、PSF、ODE stepper）不要伪装成既定事实。
|
||
|
||
性能 benchmark 记录必须保留完整、可复制的命令及原始终端输出，不能只记录汇总耗时或吞吐量；输出中的 build/cache、输入加载、工作线程、处理数量与 fallback 等统计是后续正确归因性能变化的证据。
|
||
|
||
## 权威设计文档卫生
|
||
|
||
- 仓库级文档规则应具有跨任务适用性，不夹带单次任务的细节或案例。
|
||
- `nr_spacetime_movie_renderer_design.md` 应简明描述当前确定的架构、物理与数值约定、模块边界、数据流及 ownership；尚未确定的问题须明确标为待验证。
|
||
- 写最终设计，不写 agent 工作过程、对话经过、实现日记或备选方案淘汰史。已排除的临时设想不要改写成长期禁止条款；必要的物理与架构约束仍须保留。
|
||
- 决策依据只保留理解设计所必需的简要理由。实验过程、性能数据及详细对照放到符合仓库卫生要求的独立记录中，设计文档按需引用。
|
||
- 使用说明集中到 `usage.md`；README 保留面向使用者的简介与示例，避免在权威设计文档中重复罗列。
|
||
- 设计变更应改写并整合原有相关章节，删除过时或重复表述，检查跨章节一致性；不要通过不断追加补充段落堆积历史。
|
||
|
||
## 仓库卫生与短期产物
|
||
|
||
只有对本项目有长期记录价值、且值得进入 public repo 的测试与 benchmark 才纳入 git。
|
||
|
||
- 短期性能对照、一次性 A/B 原始日志、临时测量脚本、ad-hoc probe 与中间数据放到仓库根目录的 `local/`；该目录已被 `.gitignore` 排除，不进入版本库。
|
||
- 追踪文件必须可复现：命令把输出、原始日志写到 `/tmp` 或 `local/` 是正常的，这些仓库外/被忽略的数据无需跟踪；但复现所需的输入、脚本、fixture 必须一并纳入 git（放在 `scripts/` 或 `benchmarks/<name>/`），不得依赖未跟踪的脚本或数据。
|
||
- `benchmarks/` 只保留自包含、可复现的长期记录；`tests/` 只保留针对生产代码的回归测试，不保留为单次实验服务的一次性探针。
|
||
|
||
## 修改原则
|
||
|
||
- 改动应保持 backend、observer、geodesic、movie mesh 与 optics 的职责分离。
|
||
- 性能优化不得破坏 time-dependent tracing、局部可逆映射或点源的亚像素 PSF 渲染。
|
||
- 新增缓存先明确 ownership、生命周期和线程归属；高开销可变缓存默认 thread-local。
|
||
- 未在设计文档中明确的物理或数值取舍，应通过小型 prototype、基准或收敛实验确定，并同步更新设计文档。
|
||
|
||
## Git 提交消息
|
||
|
||
- Git 提交消息必须使用英文，包括标题和正文。
|
||
- 提交消息必须以 category 开头，格式为 `Category: 简洁说明`。
|
||
- 常用 category 包括 `Doc:`、`Fix:`、`Feat:`、`Makefile:` 等。
|
||
- 对不属于修复或功能的普通小更新，使用所涉及的模块作为 category，例如 `Catalog:`、`Geodesic:`、`Spacetime:` 或 `Output:`。
|