47-PTN Template v1.0 | 第12章 附录（字段清单 / 示例 / 模板）

第12章 附录（字段清单 / 示例 / 模板）

I. 字段与单位对照（最小集，可直接复用）

约定：字段名用蛇形；凡路径相关量显式 gamma(ell) 与测度 d ell；所有数值字段须带 unit 或在 see[] 指向量纲校核锚点。

II. see: / references[] 规范样例（正文与数据双端一致）

see:

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

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

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

references:

- "EFT.WP.Core.Terms v1.0:P10-3"

version: "1.0.0"

文内引用固定写法：见《EFT.WP.Core.Equations v1.1》Ch.2 S20-1。

III. 模板合集（可直接落库）

A. manifest.yaml（发布清单）

dataset_id: "ptn-demo"

version: "1.0.0"

created_at: "2025-09-24T16:00:00Z"

producer: "PTN.Workgroup.Core"

see:

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

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

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

references:

- "EFT.WP.Core.Terms v1.0:P10-3"

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

release_tier: "public"

B. schema.json（数据架构，节选）

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PTN Data Object v1.0.0",
  "type": "object",
  "required": [ "record_id", "acq", "path", "medium", "ref", "obs", "version", "see", "references" ],
  "properties": {
    "record_id": { "type": "string" },
    "acq": {
      "type": "object",
      "required": [ "ts_start", "ts_end" ],
      "properties": {
        "ts_start": { "type": "string", "format": "date-time" },
        "ts_end": { "type": "string", "format": "date-time" }
      }
    },
    "path": {
      "type": "object",
      "required": [ "gamma_ell", "d_ell" ],
      "properties": {
        "gamma_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 },
        "d_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 }
      }
    },
    "medium": {
      "type": "object",
      "required": [ "n_eff_profile" ],
      "properties": { "n_eff_profile": { "type": "array", "items": { "type": "number" }, "minItems": 2 } }
    },
    "ref": {
      "type": "object",
      "required": [ "c_ref" ],
      "properties": { "c_ref": { "type": "number", "minimum": 290000000.0, "maximum": 310000000.0 } }
    },
    "obs": {
      "type": "object",
      "properties": { "T_arr": { "type": "number" }, "Phi": { "type": "number" } }
    },
    "see": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "references": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "version": { "type": "string" }
  }
}

C. pipeline.yaml（处理管线契约）

version: "1.0.0"

pipeline:

- id: step-10-ingest

in: ["raw/*.parquet"]

out: ["stage/ingested.parquet"]

checks: ["G1","G8"]

- id: step-20-calibrate

in: ["stage/ingested.parquet"]

out: ["stage/calibrated.parquet"]

checks: ["G5"]

- id: step-30-arrival"

in: ["stage/calibrated.parquet"]

out: ["stage/arrival.parquet"]

compute:

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

requires: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.c_ref"]

delta_form: "general"

checks: ["G3","G4"]

- id: step-40-noisefit

in: ["stage/arrival.parquet"]

out: ["stage/denoised.parquet","reports/noise.json"]

model: "huber"

checks: ["G6"]

- id: step-50-exports

in: ["stage/denoised.parquet"]

out: ["PTN_EXPORT/"]

checks: ["G2","G4","G7"]

exports:

must_include: ["manifest.yaml","schema.json","check_dim_report.json","quality_report.json","audit.jsonl"]

D. protocol.yaml（实验协议卡）

version: "1.0.0"

protocol:

id: "ptn-exp-0001"

geometry:

frame: "RA-Dec"

r_hat: [<unit_vector>]

path:

gamma_ell: "<array-of-meters>"

d_ell: "<array-of-meters>"

L_min: 10.0

timebase: { fs_hz: 2000, t_exp_s: 0.01, cadence_s: 0.05 }

band: { lambda_ref_m: 1.55e-6, bandwidth_hz: 2.0e9, window: "hann" }

instrument: { id: "INS-001", mode: "timing" }

calibration:

version: "1.2.0"

timestamp: "2025-09-24T10:00:00Z"

freshness_s: 86400

sync: { ref: "GNSS_PPS", fallback: ["PTP","NTP"] }

gates: ["G1","G2","G3","G4","G5","G6","G7","G8"]

E. error_budget.csv（误差预算卡，列头）

source,symbol,unit,type,estimate,distribution,correlation,note,see[]

Absolute timing,δt_abs,s,A,u(δt_abs),approx-N,vs_channel_skew,,Core.Metrology v1.0

Path measure,d ell,m,B,u(d ell),uniform,with gamma(ell),,Core.DataSpec v1.0:TARR

Medium index,n_eff(ell),1,A/B,u(n_eff),GP(L_c),length L_c,,Core.Terms v1.0

F. scorecard.json（评分卡，节选）

{
  "version": "1.0.0",
  "dataset_id": "ptn-demo",
  "baseline": { "id": "base-001", "version": "1.2.3" },
  "method": { "id": "mA-010", "version": "2.0.0" },
  "metrics": {
    "DeltaT_arr_s": { "mean": -2.3e-09, "std": 4.8e-09, "U_k2": 1.5e-09 },
    "r_phi": { "value": 0.72, "ci95": [ 0.61, 0.8 ] },
    "epsilon_flux": { "median": 0.004, "p95": 0.011 },
    "p_dim": 1.0,
    "Q_res": 0.13
  },
  "score": { "Q": 0.78 },
  "see": [
    "EFT.WP.Core.Equations v1.1:S20-1",
    "EFT.WP.Core.Metrology v1.0:check_dim",
    "Data.Benchmarks v1.0:PROTO"
  ],
  "version_lock": true
}

IV. 常用规范片段（直接贴用）

1. 到达时（两种等价口径，需显式路径与测度）
   T_arr = ( ∫ ( n_eff / c_ref ) d ell ) = ( 1 / c_ref ) * ( ∫ n_eff d ell )
2. 相位累计（带参考波长）
   Phi = ( 2π / λ_ref ) ( ∫ n_eff d ell )
3. 量纲校核调用（机读）

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"

4. 禁止裸用与冲突名

• 禁止：c、T、n → 使用：c_ref、T_fil（或具体量名）、n_eff（或 n）。
• 不可混用：T_fil（张力）与 T_trans（透射系数）；n（数密度）与 n_eff（有效折射率）。

V. 导出目录结构（发布版建议）

PTN_EXPORT/

manifest.yaml

data/

observations.parquet

paths.parquet

schema/

schema.json

reports/

check_dim_report.json

quality_report.json

audit.jsonl

figs/

*.pdf

*.png

scorecard.json

results.md

SIGNATURE.asc

VI. 自动化检查配置（Citation & Dim Lint）
lint_config.yaml

version: "1.0.0"

rules:

version_presence: 1.00

anchor_coverage: 0.90

path_measure_presence: 1.00

forbid_raw_symbols: ["c","T","n"]

conflict_pairs:

- ["T_fil","T_trans"]

- ["n","n_eff"]

dag_enforce: true

outputs:

report: "reports/citation_lint.json"

gate: "G2"

VII. 结果页模板（最小必填，Markdown）

# PTN Results — v1.0.0

## 1. Summary

- One-liner; core metrics with uncertainty (ΔT_arr, r_phi, ε_flux, p_dim, Q_res).

## 2. Methods & Data

- dataset_id / method_id / baseline_id / versions / seeds.

## 3. Core Metrics

- ΔT_arr (s): mean±U, histogram, BA plot.

- r_phi: value + 95% CI; phase scatter vs. identity.

- ε_flux: distribution; paraxial guard.

## 4. Compliance & Audit

- check_dim_report.json, audit.jsonl, see[], references[], version.

## 5. Figures

- PDF/PNG list with units & legends.

VIII. 术语与符号注册（最小清单，YAML）

version: "1.0.0"

symbols:

- { name: "c_ref", kind: "constant", unit: "m/s", desc: "reference propagation limit", see: ["EFT.WP.Core.Terms v1.0:P10-3"] }

- { name: "n_eff", kind: "variable", unit: "1", desc: "effective refractive index", see: ["EFT.WP.Core.Terms v1.0:P10-3"] }

- { name: "T_arr", kind: "variable", unit: "s", desc: "arrival time", requires: { path: "gamma(ell)", measure: "d ell" },

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

IX. 发布前自检清单（一页式）

• 文内与数据 see[]/references[] 为“卷名+版本+锚点”，直指率≥90%。
• 所有路径型表达显式 gamma(ell) 与 d ell，并记录 delta_form。
• p_dim = 1.0，τ_calib 合规，clock_state = locked。
• 采样满足 Δell 与 f_s 约束；窗函数与波段声明完整。
• 结果包包含 manifest.yaml / schema.json / check_dim_report.json / quality_report.json / audit.jsonl / scorecard.json。
• 禁止裸用 c、T、n；不得混用 T_fil 与 T_trans、n 与 n_eff。