47-PTN Template v1.0 | 第9章 实现绑定与函数原型

目录 ／ 文档-技术白皮书 ／ 47-PTN Template v1.0

第9章 实现绑定与函数原型

I. 接口概览（Overview）

1. 范畴与命名：实现绑定统一以 Ixx-? 标识，覆盖计算、计量、同步、管线与导出。
2. 输入/输出通用约束：
   • 路径量强制：凡涉及到达时/相位等路径相关量，输入必须显式携带 gamma(ell) 与测度 d ell，并在元数据记录 delta_form。
   • 符号与单位：禁止裸用 c、T、n；统一使用 c_ref、T_fil（或具体量名）、n_eff（或 n）；所有数值字段需携带 unit 或在 see[] 指向量纲校核锚点。
   • 引用与版本：请求与响应均应包含 see[]（“卷名 + 版本 + 锚点（P/S/M/I）”）与 version（SemVer）。
3. 错误语义（统一）：
   • OK（0）｜成功；
   • E_INPUT（100）｜必填字段缺失/单位不匹配/路径-测度不成对；
   • E_DIM（110）｜量纲闭合失败；
   • E_MODEL（120）｜模型/近似条件不满足（如 |θ| > θ_max 需退出近轴）；
   • E_SYNC（130）｜时间同步失效（clock_state != locked 超阈）；
   • E_VERSION（140）｜引用版本/锚点不一致；
   • E_INTERNAL（199）｜实现内部错误。

II. 函数原型（Function Prototypes）

1. I20-compute_arrival_time(path, n_eff, c_ref, delta_form) -> T_arr
   • in：path = { gamma_ell[]: m, d_ell[]: m }；n_eff[]: 1；c_ref: m/s；delta_form ∈ {general, factored}。
   • out：T_arr: s；diagnostics = { integral, coverage }。
   • see：Core.Equations v1.1:S20-1；Core.Metrology v1.0:check_dim。
2. I21-accumulate_phase(path, n_eff, lambda_ref) -> Phi
   • in：同上并含 lambda_ref: m。
   • out：Phi: rad；window = { T_coh, L_coh }。
   • see：Core.Equations v1.1:S21-2。
3. I30-continuity_flux(rho, v, domain) -> {epsilon_flux, mass_delta}
   • in：rho: unit/vol；v: m/s；domain: mesh/BC。
   • out：epsilon_flux: 1；mass_delta: unit。
   • see：Core.Equations v1.1:S30-1。
4. I31-propagate_paraxial(A0, n_eff, k_ref, grid) -> A
   • in：A0: <field>；n_eff: 1；k_ref: 1/m；grid: {dx, dy, dz}。
   • out：传播后场 A 与能流守恒诊断。
   • see：Core.Equations v1.1:S31-1。
5. I40-fit_noise(y, H, model, opts) -> {Sigma, residuals, Q_res}
   • in：观测 y；系统算子 H；model ∈ {gaussian, student, huber}；opts。
   • out：协方差 Sigma、残差、稳健度指标 Q_res。
   • see：Methods.Cleaning v1.0。
6. I50-calibrate(u_true, theta_in) -> {u_meas, theta_out, u(theta)}
   • in：真值 u_true；初始参数 theta_in。
   • out：测量值 u_meas；更新参数与不确定度。
   • see：Core.Metrology v1.0（计量映射与量纲闭合）。
7. I60-export_manifest(obj) -> manifest.yaml
   • in：任一数据对象或结果包。
   • out：含 dataset_id/version/references[]/see[]/checksum 的发布清单。
   • see：Core.DataSpec v1.0:TARR。
8. I61-sync_lock(source) -> {clock_state, δt_abs, σ_y}
   • in：source ∈ {GNSS_PPS, PTP, NTP} 与阈值配置。
   • out：时钟状态、绝对时偏差与 Allan 偏差。
   • see：Metrology.Sync v1.0。
9. I62-path_resample(gamma_ell, d_ell, Δell_max) -> {gamma_ell', d_ell'}
   • in：原路径/测度与最大步长。
   • out：加密/重采样后的路径/测度。
   • see：Metrology.PathCorrection v1.0。
10. I63-coherence_adapt(metrics) -> {T_coh, L_coh, B_coh}
    • in：metrics = {|∇ n_eff|, SNR, σ_y}。
    • out：自适应相干窗。
    • see：Methods.Repro v1.0（运行时自监控）。
11. I70-dim_check(expr, units) -> check_dim_report
    • in：表达式与各量单位。
    • out：量纲闭合报告、问题定位。
    • see：Core.Metrology v1.0:check_dim。
12. I80-citation_lint(text, see[]) -> citation_lint.json
    • in：正文片段与 see[]。
    • out：ver_presence/anchor_coverage/path_measure_presence/DAG 等指标与修复建议。
    • see：Chapter 8（G2 门）。
13. I90-bench_score(results, baseline, metrics) -> scorecard
    • in：结果集、基准、评分指标。
    • out：分项分数 Q 与总分，配对显著性。
    • see：Data.Benchmarks v1.0。

III. 配置与返回（Configuration & Returns）

• 通用配置块（建议）

config:

units: { length: "m", time: "s", angle: "rad" }

thresholds:

theta_max_deg: 3.0

tau_calib_s: 86400

sampling:

Delta_ell_max_m: 0.5

noise:

model: "huber"

params: { delta: 1.345 }

sync:

source: "GNSS_PPS"

limits: { abs_ns: 50, allan_1s: 1.0e-11 }

• 统一返回信封

return:

status: "OK" # or E_INPUT/E_DIM/...

code: 0

payload: { ... } # 函数各自的主结果对象

metrics: { # 关键诊断与自监控

p_dim: 1.0,

Q_res: 0.12

}

references:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

version: "1.0.0"

checksum:

algo: "sha256"

value: "<64-hex>"

• 错误返回（规范示例）

return:

status: "E_INPUT"

code: 100

message: "missing path.d_ell or length mismatch with gamma_ell"

details:

expect: "len(gamma_ell)==len(d_ell)>=2"

found: { gamma_ell: 128, d_ell: 127 }

references: ["Core.DataSpec v1.0:TARR"]

version: "1.0.0"

• 幂等性与可追溯：所有具副作用接口需在响应内返回 run_id、输入哈希与时间戳，以支持审计。

IV. 版本一致性（Versioning Consistency）

1. SemVer 语义：
   • MAJOR：改变输入/输出字段语义或单位；
   • MINOR：新增字段（向后兼容）；
   • PATCH：修复与性能，不改接口契约。
2. 弃用策略：新增字段至少一个 MINOR 周期内与旧字段并存；在 manifest 与变更注释中标注弃用时间线。
3. 引用锁定：实现绑定在打包发布时必须随附 references[] 与 version；正文、数据与导出清单三端一致。
4. 跨版本执行：检测到 see[] 与运行库版本不一致时应返回 E_VERSION，并给出建议目标版本。

V. 机读注册（Interfaces Registry，可直接落库）

version: "1.0.0"

interfaces:

- code: "I20"

name: "compute_arrival_time"

in:

path: { gamma_ell: "array<m>", d_ell: "array<m>" }

n_eff: "array<1>"

c_ref: "m/s"

delta_form: "enum{general,factored}"

out:

T_arr: "s"

diagnostics: { integral: "s", coverage: "1" }

see: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

- code: "I31"

name: "propagate_paraxial"

in:

A0: "<field>"

n_eff: "1 or array<1>"

k_ref: "1/m"

grid: { dx: "m", dy: "m", dz: "m" }

out:

A: "<field>"

flux_error: "1"

see: ["EFT.WP.Core.Equations v1.1:S31-1"]

- code: "I61"

name: "sync_lock"

in:

source: "enum{GNSS_PPS,PTP,NTP}"

limits: { abs_ns: "ns", allan_1s: "1" }

out:

clock_state: "enum{locked,holdover,free}"

delta_t_abs_ns: "ns"

allan_1s: "1"

see: ["EFT.WP.Metrology.Sync v1.0:PPS"]

gate:

must_include: ["references","version","checksum"]

VI. 规范示例（可直接复用）

• 到达时计算（一般口径）

T_arr = ( ∫ ( n_eff / c_ref ) d ell )

Dims : [1]/[m·s^-1]*[m] = [s] ✅

• 相位累计（带参考波长）

Phi = ( 2π / λ_ref ) ( ∫ n_eff d ell )

Unit: [rad] ✅

• 量纲校核调用

call: I70-dim_check

expr: "T_arr = ∫ ( n_eff / c_ref ) d ell"

units: { n_eff: "1", c_ref: "m/s", d_ell: "m", T_arr: "s" }

expect: "closed"

• 导出清单最小片段

dataset_id: "ptn-demo"

version: "1.0.0"

references:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

see:

- "EFT.WP.Core.DataSpec v1.0:TARR"

checksum: { algo: "sha256", value: "<64-hex>" }