24-EFT.WP.Particle.TopologyAtlas v1.0 | 附录A 接口参考（I90 全集）

目录 ／ 文档-技术白皮书（V5.05） ／ 24-EFT.WP.Particle.TopologyAtlas v1.0

附录A 接口参考（I90 全集）

一句话目标：汇总本卷实现绑定 I90-* 的接口原型、输入输出、不变量与错误语义，支撑从数据→复形→图谱→检索→运行时的端到端可复现实现。

I. 说明与范围

• 覆盖：场/相位微分、拓扑密度与缺陷检测、世界线与事件、复形与滤过、持久同调与景观、图谱与坐标过渡、度量与检索、增量与运行时、用例封装与清单落盘。
• 命名：统一前缀 I90-，后随“章节号×× + 序号”。函数名用 snake_case；符号一律使用英文与反引号包裹。
• 时基：除特别说明外，时间字段以 t_event 为准；处理时间 t_proc 仅用于运行度量（见第14章）。
• 跨卷引用：时间基线与同步见 配套白皮书《能量丝》 第2章；计量契约与落盘签名见本卷第10/15章与附录E。

II. 通用类型与返回结构

• ArrayLike[float]：shape ∈ R^{d} 的实数数组（ndarray/torch.Tensor 均可）。
• Field：标量或取向场，例：theta(x,y), n(x,y,...) ∈ S^2。
• Chart = { U, phi, coords }；Atlas = { charts, T_ab, ψ_a }，满足 Σ_a ψ_a ≡ 1。
• PersistenceDiagram D = { (b, d, dim) }；Landscape λ_D(t,k)；Filtration K(τ)，non_decreasing(τ)。
• Manifest.*：本卷统一清单键，均含 TraceID, hash, RefCond, policy, signature。

III. 不变量与错误语义（通用）

• 不变量
  non_decreasing(τ)；Σ_a ψ_a ≡ 1；Δ_cyc ≤ tol_cyc；check_dim(all) 通过；seed 固定可复现。
• 错误码
  E_DIM（维度/形状不符）、E_UNIT（单位未声明或不一致）、E_CONTRACT（契约未通过）、E_RANGE（越界/非物理）、E_STATE（状态缺失/过期）。

IV. 接口清单（分组）

A. 基础/IO（I90-00x）

• I90-001 hash_data(data, policy) -> {data_hash}
  输入：任意 bytes/ArrayLike；输出：hex。不变量：稳定、与平台无关。
• I90-002 load_field(uri, schema) -> Field / I90-003 save_manifest(uri, manifest) -> ok
  约束：schema.ver 必填；失败抛 E_STATE/E_UNIT。

B. 场与微分（I90-04x，对应第4章）

• I90-041 phase_unwrap(theta, mode) -> theta_unw
  mode ∈ {quality-guided, least-squares}；保持相位 2π 连续性。
• I90-042 compute_gradient(field, spacing) -> {grad}
  输出单位：unit(grad)=unit(field)/unit(x)。
• I90-043 jacobian_orientation(n_field, scheme) -> J
  scheme ∈ {central, sobel, spectral}；返回 ∂_i n_j。
• I90-044 topo_density_from_phase(theta) -> q_vortex_map
  实现离散绕数（见 S915-2）；unit(q) = "[1]"。
• I90-045 topo_density_from_orientation(n_field) -> q_sky_map
  近似 n · (∂_x n × ∂_y n) / (4*pi)；支持面积权重。

C. 缺陷检测（I90-05x，对应第3/5章）

• I90-051 detect_defects_generic(q_map, thresh) -> {points, charge}
  阈值 thresh 基于稳健分位；输出 charge ∈ Z。
• I90-052 label_defect_cells(theta_or_n, policy) -> {labels, stats}
  统计拓扑类别、面积/周长等证据。

D. 世界线与事件（I90-06x，对应第5/6章）

• I90-061 trace_worldlines_3d(q_map_t, seed_policy) -> {Γ, tags}
  输出世界线集合 Γ = {γ_i(s)}；保持连通一致性。
• I90-062 compute_linking_numbers(Γ) -> {Lk_ij}
  采用 Gauss 公式（见 S915-6）；unit(Lk) = "[1]"。
• I90-063 event_graph_from_worldlines(Γ, window) -> G_event
  识别 split/merge/reconnect；事件时间窗 Δt 可配。

E. 复形与持久（I90-07x/08x，对应第7/8章）

• I90-071 build_complex(data, τ_policy) -> K(τ)
  τ_policy ∈ {Rips, Alpha, cubical, graph}；non_decreasing(τ)。
• I90-072 compute_persistence(K) -> D
  返回多维 D（H0/H1/H2…），含配对证据。
• I90-073 persistence_landscape(D, p) -> λ_D
  p ∈ {1,2,∞}；返回函数句柄或离散采样。
• I90-074 simplify_diagram(D, ε) -> D'
  稳定性保障（ε-截断）；记录丢弃对。
• I90-081 stability_window(D_seq) -> {τ_stable}
  估计稳定窗口与门限（承接第8章）。

F. 图谱构建与坐标过渡（I90-09x–11x，对应第9–11章）

• I90-091 compose_atlas(tiles, ψ, policy) -> {Atlas, Δ_cyc}
  合并图块；校核 Σ ψ ≡ 1 与循环误差。
• I90-092 estimate_transition_map(U_a, U_b, features) -> T_ab
  过渡映射估计（刚性/仿射/非线性）。
• I90-093 project_to_chart(data, phi) -> coords
  将数据投影至图表坐标。
• I90-094 normalize_blend_weights(ψ_raw) -> ψ_norm
  保证权重归一；sup_x |Σ ψ - 1| → 0。
• I90-095 check_cycle_error(T_cycle) -> Δ_cyc
  三图重叠环的误差评估。
• I90-111 merge_atlas_incremental(Atlas, patch) -> Atlas*
  增量合并（见第11章）；冲突保留证据。
• I90-112 local_match_charts(Q, A, policy) -> {π, w}
  局部图块匹配与权重（与第13章对接）。

G. 不变量计量与校准（I90-10x，对应第10章）

• I90-101 measure_invariants({q, Γ, D}) -> Inv
  汇总 Q, Lk, Tw, Wr, lifespan, count。
• I90-102 calibrate_invariant_bias(Inv, refs) -> Inv_cal, report
  基线比对与偏置回归；落盘回归系数。

H. 噪声、清洗与稳健（I90-12x，对应第12章）

• I90-121 denoise_phase_circular(theta, σ) -> theta'
  圆值 TV/Anisotropic。
• I90-122 denoise_orientation_projection(n_field, σ) -> n'
  投影回 S^2；保持单位向量。
• I90-123 robust_threshold_selection(stats) -> thresh
  Huber/分位/交叉验证三策略。

I. 度量与检索（I90-13x，对应第13章）

• I90-131 build_persistence_distance(D1, D2, policy) -> {d_B, W_p, Lp}
• I90-132 atlas_align_tau(Q, A) -> {s, b}
• I90-133 atlas_local_match(Q, A, T_ab, ψ) -> {π, w}
• I90-134 atlas_distance(Q, A, π, w, policy) -> d_exact, breakdown
• I90-135 embed_atlas(Atlas, Φ_policy) -> Z
• I90-136 build_index({Z_i}, index_policy) -> Index
• I90-137 query_index(Index, Z_Q, K) -> Cand
• I90-138 rerank_with_exact(Q, Cand, policy) -> TopK, delta_form_retr_stats
• I90-139 compare_tracks_events(Q, A) -> {d_F, d_DTW, d_GED}
• I90-13A assert_search_contracts(ds, rules) -> report
• I90-13B emit_search_manifest(results, policy) -> manifest.topo.search

J. 运行时与流式（I90-14x，对应第14章）

• I90-141 assign_windows(events, policy) -> {W_k}
• I90-142 advance_watermark(state, L) -> ω(t)
• I90-143 build_stream_complex(data[W_k], τ_policy, S_cache) -> {K_t, D_t, state'}
• I90-144 update_atlas_incremental(Atlas, {K_t, D_t}, scope) -> Atlas_t, patch_t
• I90-145 reconcile_transitions(U_a∩U_b, D_a, D_b) -> {T_ab, Δ_cyc}
• I90-146 recompute_subset(Atlas, scope) -> Atlas_offline_subset
• I90-147 compare_stream_offline(D_stream, D_offline, metric) -> delta_form_rt
• I90-148 manage_cache(S_cache, policy) -> {state', H_cache}
• I90-149 update_runtime_panel(stats) -> panel.topo.runtime
• I90-14A rate_limit_and_backpressure(stats, policy) -> mode
• I90-14B emit_runtime_manifest(results, policy) -> manifest.topo.runtime

K. 用例封装与发布（I90-15x，对应第15章）

• I90-151 detect_vortices_phase(theta, policy) -> {points, q_vortex, Q, evidence}
• I90-152 measure_skyrmion_charge(n_field, scheme) -> {q_map, Q, lattice, evidence}
• I90-153 trace_worldlines(n_field_t, seed_policy) -> {Γ, tags}
• I90-154 detect_reconnection(Γ, window) -> {E_reconn, Lk_series, evidence}
• I90-155 build_case_complex(data, τ_policy) -> {K(τ), D, λ_D}
• I90-156 compose_case_atlas(tiles, ψ, T_ab) -> Atlas_case, Δ_cyc
• I90-157 compare_case_forms(resultsA, resultsB, metrics) -> delta_form_case
• I90-158 assert_case_contracts(results, rules) -> report
• I90-159 emit_case_manifest(results, policy) -> manifest.topo.case

V. 每个接口的共同字段要求

• 单位与量纲：进入方程的任意字段必须声明 unit(field) 与 dim(field)，并通过 check_dim( y - f(x) ) 校核。
• RefCond：涉及阈值/滤过/核宽度/时间窗的接口需接受 RefCond = {τ_policy, σ, p, window, norm} 并落盘。
• 两口径记录：若存在 form=exact/approx，必须同时返回并记录 delta_form 相关统计。
• 签名与可追溯：{code.ver, deps, seed, data_hash} 必存于 manifest.*。

VI. 典型流水线（端到端示例）

• 读数与清洗：load_field → denoise_phase_circular / denoise_orientation_projection。
• 场→密度：phase_unwrap / jacobian_orientation → topo_density_* → detect_defects_generic。
• 数据→复形：build_complex → compute_persistence → persistence_landscape。
• 图谱构建：compose_atlas → estimate_transition_map → normalize_blend_weights → check_cycle_error。
• 不变量与校准：measure_invariants → calibrate_invariant_bias。
• 检索与比对：embed_atlas → build_index → query_index → rerank_with_exact。
• 运行时：assign_windows → build_stream_complex → update_atlas_incremental → compare_stream_offline → emit_runtime_manifest。
• 用例发布：compose_case_atlas → emit_case_manifest。

VII. 版本与兼容策略

• 语义化版本：I90.x.y；x 为破坏性变更，y 为向后兼容增强。
• 清单兼容：旧版本 manifest.* 可经 upgrade_manifest(manifest) 升版；降级需显式声明字段丢失。
• 弃用周期：deprecate → warn → remove 三阶段各至少一个小版本周期。

VIII. 安全与合规

• 数据最小化：运行态缓存仅保最小充分统计（见第14章）。
• 隐私与脱敏：对外发布图谱/证据时须脱敏位置与标识；保留内部签名以供审计。
• 审计与回放：所有接口应支持 replay(trace) 并逐位复现（seed 固定，哈希一致）。

小结

• 本附录提供 I90-* 全集的统一接口参考，覆盖构建、度量、检索与运行全链路。
• 依托本卷 P/S/M/C 与附录E 的误差传播口径，接口产物均可计量、追溯与复现，并通过 manifest.topo.* 规范化落盘。