50-参数注册卡 Template v1.0 | 第3章 参数分类与命名（编码规则）

目录 ／ 文档-技术白皮书（V5.05） ／ 50-参数注册卡 Template v1.0

第3章 参数分类与命名（编码规则）

I. 目的与范围（Purpose & Scope）

• 建立参数的分类法（Taxonomy）与编码/命名规则，覆盖参数标识、别名与弃用、跨链路一致性与可追溯性。
• 涉及路径量（到达时/相位）时，正文显式 gamma(ell) 与测度 d ell，并在卡片数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

II. 参数分类（Categories）

• PHY｜物理常量：c_ref、λ_ref、k_ref、基本常数等。
• CAL｜计量/标定：τ_sys、Δτ_ch、gain、PSF、distortion 等。
• ALG｜算法超参：阈值、正则系数、迭代步长、停止准则等。
• ENV｜环境：α_T、ΔT、湿度/压强、温度系数等。
• GEO｜几何：q_att、FOV、像素标定、畸变网格等。
• TIM｜时基：f_s、t_exp、时间窗、心跳间隔等。
• IO｜输入输出：文件/流的编码、量化位宽 q_bits、通道映射等。
• SEC｜安全与访问：掩码与策略枚举、最小化暴露级别等。

复合参数按主类确定 CAT，辅类记录于 tags[]（如 CAL 主类 + GEO 标签）。

III. 命名与编码（Naming & Coding）

1. 参数卡 ID：param_id = "<CAT>-<两位序号>-<短名可选>"，如 CAL-01-τ_sys；注册表主键唯一。
2. 符号（symbol）：使用国际短符号（如 c_ref、λ_ref、τ_sys、n_eff）；避免大写全词。
3. 字段风格：标识与列名使用 snake_case；单位与量纲使用 SI 与国际符号。
4. 别名与弃用：
   • 别名写入 aliases[]，仅内部解析；对外以 symbol 为准。
   • 弃用通过 status: "deprecated" 标注，并给出 replaced_by。
5. 路径口径：与路径量耦合的参数（如 n_eff(ell)、路径权重）必须携带 delta_form，并在注释中标明 gamma(ell)/d ell。
6. 冲突名：T_fil ≠ T_trans、n ≠ n_eff；禁止裸用 c、T、n。
7. 版本：卡片版本采用 SemVer，字段 version 必填并随注册更新。

IV. 编码规则（细则）

• CAT 集合：PHY|CAL|ALG|ENV|GEO|TIM|IO|SEC。
• 序号：两位递增（01–99），每类各自独立计数；预留 00 作保留位。
• 短名：可选，以 ASCII 字母/下划线组成，长度≤16；推荐与 symbol 一致的可读缩写。
• 派生链：派生参数在 constraints.derived 中以公式声明，示例：τ_sys = τ_base + α_T·ΔT；若跨卡依赖，补充 depends_on[]。
• 协方差分组：cov_group ∈ {"timing","optics","medium","algo","env","geo"}；用于误差合成的块结构。
• 新鲜度：校准/环境敏感参数必须设置 freshness.valid_to 与 policy{tau_calib_s_max, clock_state}。

V. 规范示例（Valid Examples）

# 1) 计量/标定类：系统延时

version: "1.0.1"

param_id: "CAL-01-τ_sys"

name: "system_delay"

symbol: "τ_sys"

domain: { type: "real", unit: "s", range: [0, 1e-3], default: 1.0e-6, precision: "float64" }

lineage: { source_type: "measured", method: "loopback", instrument: "DPO-7k", calib_run_id: "CAL2025-09-24-01" }

freshness: { valid_from: "2025-09-24T00:00:00Z", valid_to: "2025-10-24T00:00:00Z",

policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "A", estimate: 2.0e-8, distribution: "normal", coverage: { k: 2 } }

constraints: { depends_on: ["TEMP"], derived: "" }

cov_group: "timing"

status: "stable"

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

# 2) 介质/路径类：有效折射率剖面

version: "1.0.0"

param_id: "PHY-03-n_eff_profile"

name: "effective_index_profile"

symbol: "n_eff(ell)"

domain: { type: "array", unit: "1", range: [0.8, 2.5], precision: "float64" }

lineage: { source_type: "derived", method: "kernel_fit", instrument: "—", calib_run_id: "—" }

freshness: { valid_from: "2025-09-24T00:00:00Z", valid_to: "2026-09-24T00:00:00Z", policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "A/B", estimate: 3.0e-3, distribution: "gaussian", coverage: { k: 2 } }

constraints: { depends_on: ["ENV-01-α_T","ENV-02-ΔT"], derived: "" }

path:

gamma: "gamma(ell)" # 显式路径

measure: "d ell" # 显式测度

delta_form: "general" # 或 "factored"

cov_group: "medium"

tags: ["coherence_window"]

status: "stable"

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

# 3) 算法超参：Huber 损失的 δ

version: "1.0.0"

param_id: "ALG-05-huber_delta"

name: "huber_delta"

symbol: "δ_huber"

domain: { type: "real", unit: "1", range: [0.1, 5.0], default: 1.345, precision: "float64" }

lineage: { source_type: "configured", method: "benchmark", instrument: "—", calib_run_id: "—" }

freshness: { valid_from: "2025-01-01T00:00:00Z", valid_to: "9999-12-31T23:59:59Z", policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "B", estimate: 0.0, distribution: "degenerate", coverage: { k: 2 } }

constraints: { depends_on: [], derived: "" }

cov_group: "algo"

status: "stable"

see: ["ErrorBudget.Template v1.0:Ch.6","PTN.Template v1.0:Ch.7"]

VI. 别名、弃用与回滚（Aliases, Deprecation & Rollback）

• 别名：aliases[] 仅用于兼容旧脚本或外部导入，发布版不得以别名替代 symbol。
• 弃用流程：设置 status: deprecated 与 replaced_by，保留一个次要版本周期；在 report_manifest.yaml 中标注弃用说明。
• 回滚点：通过 I27-lock_version(param_id, semver) 生成不可变标签，支撑审计追溯。

VII. 质量门映射（Gates Mapping）

• G2 引用合规：see[]/references[] 采用“卷名+版本+锚点”，锚点直指率 ≥ 90%。
• G4 量纲闭合：字段 domain.unit 与派生关系通过 I70-dim_check；p_dim = 1.0。
• G5 新鲜度：带 freshness 的参数需在有效期内；否则进入限制模式或触发再标定。
• G8 唯一性：param_id 与 checksum 不可重复。

VIII. 表模式与校验（Schema & Validation）

{

"$schema": "https://json-schema.org/draft/2020-12/schema",

"title": "param_card v1.0.0",

"type": "object",

"required": ["param_id","symbol","domain","status","version","see"],

"properties": {

"param_id": {"type": "string","pattern":"^[A-Z]{3}-\\d{2}(-[A-Za-z_]{1,16})?$"},

"symbol": {"type": "string"},

"domain": {

"type":"object",

"required":["type","unit"],

"properties":{"type":{"enum":["real","integer","enum","array","tensor"]},"unit":{"type":"string"}}

},

"status":{"enum":["draft","stable","deprecated"]},

"see":{"type":"array","items":{"type":"string"}, "minItems":1}

}

}

IX. 与其它章节衔接（Cross-Refs）

• 与第4章（域、单位与默认）联动进行单位/量纲与合法性校验；
• 与第5章（来源、血缘与追踪）记录 lineage；
• 与误差预算卡（Ch.5/Ch.8/Ch.9）对接 cov_group 与门阈映射；
• 与PTN Template（Ch.5/Ch.11）对接数据契约与发布页。

X. 执行勾选清单（Checklist）

• param_id = "<CAT>-<两位序号>-<短名可选>"，唯一且通过正则校验。
• symbol 采用国际短符号；无冲突名与裸用符号。
• 路径相关参数已显式 gamma(ell)/d ell 并记录 delta_form；p_dim = 1.0。
• domain/unit/range/default/precision 完整；lineage/freshness/policy 明确。
• cov_group、uncertainty、constraints.depends_on/derived 已登记；see[]/version 合规且直指率 ≥ 90%。
• 弃用/替换关系与回滚点（锁版本）已设置；注册表 checksum 唯一。