03-EFT.WP.Core.Parameters v1.0 | 附录A 参数注册表模式

目录 ／ 文档-技术白皮书（V5.05） ／ 03-EFT.WP.Core.Parameters v1.0

附录A 参数注册表模式

附录A 参数注册表模式

I. 模式概述与适用范围

• 目标：定义统一的参数注册表模式，用于 register_param、导入导出与场景治理，确保 theta 的可追溯、可校验与可复用。
• 适用：physical、constitutive、statistical、numerical、environment、derived 六类角色；支持标量、向量、矩阵、场（按形状声明）。
• 严格口径：参数名、集合名、单位与表达式全部英文与纯文本；叙述性说明可用中文。T_fil 与 T_trans 不可混用；n 与 n_eff 严格区分。

II. 字段规格与必填项

1. 标识与分组
   • code [required]：参数唯一代号（小写蛇形或驼峰，字母起始）。
   • name [required]：英文名（面向读者）。
   • aliases [optional]：同义代号列表（注册后自动归一到 code）。
   • group [optional]：参数组标识（对应 theta_g）。
   • role [required]：physical|constitutive|statistical|numerical|environment|derived。
   • see [optional]：跨卷锚点列表（如 "S20-*","S40-*","Core.Equations"）。
2. 类型、形状与单位
   • type [required]：scalar|vector|matrix|field|bool|categorical。
   • shape [conditional]：当 type ∈ {vector,matrix,field} 时给出，如 "[3]"、"[3,3]"、"[Nx,Ny]"。
   • unit [required]：单位或量纲，如 "[L][T]^-1"、"1"、"[Tension]^-1"（遵循《Metrology.*》）。
3. 缺省、边界与可行域
   • default [optional]：默认值（若无则省略）。
   • bounds [optional]：{lb: ..., ub: ..., closed: "[left|right|both|none]"}；无界用 null。
   • constraints [optional]：列表，每项 {kind: "eq|ineq", expr: "C_eq(theta)=0|C_ineq(theta) ≤ 0"}（表达式英文）。
4. 先验与变换
   • prior [optional]：{family: "Normal|LogNormal|Gamma|Beta|HalfNormal|Laplace|Uniform", hyper: {...}}（须给全量超参数）。
   • transform [optional]：{name: "log|logit|softplus|zscore|identity", args: {...}}；需保证单调与可逆域说明。
5. 可辨识性与关联
   • ident [optional]：{shared_with: ["code_a",...], tie_rule: "equality|ratio:k", rank_min: int}。
   • derived [conditional]：派生参数使用 {expr: "...", deps: ["..."]}，表达式需过 check_dim。
6. 治理与版本
   • owner [required]：责任人或团队。
   • since [required]：首次纳入版本（如 "v1.0"）。
   • status [required]：active|frozen|deprecated。
   • semver [required]：当前条目语义版本。
   • changelog [optional]：变更摘要（英文或中文叙述）。
   • scenario_overrides [optional]：按场景重载，如 {ScenarioA: {default: ... , bounds: ...}}。
7. 质量与校验钩子
   • checks [optional]：{dim: "pass|fail", lint: "pass|fail", tests: ["id:pass", ...]}。
   • notes [optional]：补充说明（中文可用，但不得含公式）。

III. 注册与校验规则（强制）

• R-A1 必填：code|name|role|type|unit|owner|since|status|semver 缺一不可入库。
• R-A2 先验–边界一致：support(prior) 必须包含于 bounds；若冲突，拒绝注册。
• R-A3 变换–域一致：domain(transform) 与 bounds 兼容；inverse_transform 存在且稳定。
• R-A4 量纲闭合：derived.expr 与任何 constraints[*].expr 必须 check_dim == "ok"。
• R-A5 Lint：表达式禁用形如 ∫ n d ell / c；必须写作 ∫ ( n_eff / c_ref ) d ell 并显式 gamma(ell) 与 d ell。
• R-A6 冻结策略：status="frozen" 的条目禁止修改 unit|bounds|transform|prior，仅允许 notes|changelog 追加。
• R-A7 别名：aliases 不得与任一现有 code 冲突；导出时一律回写 code。

IV. 字段到 API 的映射（I30 对接）

• register_param ← code|name|type|unit|role|default|bounds|prior|transform|see。
• add_alias ← aliases[*]；normalize_param 由导入环节调用。
• set_bounds、add_constraint ← bounds|constraints。
• set_prior、sample_prior ← prior。
• set_transform、forward_transform|inverse_transform ← transform。
• derive_param、tie_params ← derived|ident.tie_rule|ident.shared_with。
• freeze|thaw ← status；export_params|import_params 覆盖全模式。

V. 示例条目（YAML 片段，可直接纳入导出文件）

- code: c_ref

name: reference propagation upper bound

role: physical

type: scalar

unit: "[L][T]^-1"

default: 3.0e8

bounds: {lb: 0.0, ub: null, closed: "left"}

prior: {family: LogNormal, hyper: {mu: 19.52, sigma: 0.05}}

transform: {name: softplus, args: {beta: 1.0}}

see: ["S20-*","Core.Equations"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

​

- code: n_eff_k

name: effective refractive index (segment k)

role: constitutive

type: scalar

unit: "1"

bounds: {lb: 1.0, ub: 5.0, closed: "both"}

prior: {family: LogNormal, hyper: {mu: 0.1, sigma: 0.5}}

transform: {name: log, args: {}}

group: n_eff_segments

see: ["S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

​

- code: n0

name: baseline effective index factor

role: constitutive

type: scalar

unit: "1"

bounds: {lb: 1.0, ub: 3.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 1.2, sigma: 0.1}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

​

- code: a_T

name: tension sensitivity coefficient

role: constitutive

type: scalar

unit: "[Tension]^-1"

bounds: {lb: -10.0, ub: 10.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 0.0, sigma: 1.0}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

​

- code: a_G

name: tension-gradient sensitivity coefficient

role: constitutive

type: scalar

unit: "[TensionGradient]^-1"

bounds: {lb: -10.0, ub: 10.0, closed: "both"}

prior: {family: Normal, hyper: {mu: 0.0, sigma: 1.0}}

transform: {name: identity, args: {}}

see: ["S40-*","S20-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

​

- code: n_eff_from_T

name: effective index from tension field

role: derived

type: field

shape: "[Nx,Ny]"

unit: "1"

derived:

expr: "n0 * ( 1 + a_T * T_fil(x) + a_G * |grad[T_fil](x)| )"

deps: ["n0","a_T","a_G","T_fil"]

constraints:

- {kind: "ineq", expr: "n_eff_from_T(x) - 1.0 ≥ 0"}

see: ["S40-*","S20-*","S70-*"]

owner: EFT.Core

since: "v1.0"

status: active

semver: "1.0.0"

checks: {dim: pass, lint: pass}

VI. CSV 平面格式（导入最小头部）

• 头部：code,name,role,type,unit,default,lb,ub,closed,prior_family,prior_hyper,transform_name,transform_args,group,see,owner,since,status,semver
• 示例行：
  c_ref,reference propagation upper bound,physical,scalar,"[L][T]^-1",3.0e8,0.0,,left,LogNormal,"{mu:19.52,sigma:0.05}",softplus,"{beta:1.0}",,["S20-*"],EFT.Core,v1.0,active,1.0.0

VII. 表达与维度 Lint 规则（登记时自动触发）

• L1：任一积分/除号表达式须加括号并显式路径与测度，如 T_arr = ( ∫_gamma ( n_eff / c_ref ) d ell )。
• L2：禁止使用 n 代替 n_eff；禁止 T_fil 表示时间或温度。
• L3：constraints.expr 与 derived.expr 不得包含中文字符；单位串必须为法定维度符号。
• L4：bounds.lb > bounds.ub 或 closed 非法取值直接拒绝。
• L5：prior.family 缺失或超参数不全直接拒绝。

VIII. 可行集与先验支持一致性卡片

• 可行集定义：Theta = { theta | C_eq(theta)=0, C_ineq(theta) ≤ 0, lb ≤ theta ≤ ub }。
• 先验支持：support(prior(theta_i)) ⊆ [lb_i, ub_i]；若 transform 存在，则在原始坐标 theta 上核验。
• 典型冲突示例与修复：
  prior(theta_i)=Normal(mu, sigma) 但 lb=0：改用 HalfNormal 或应用 softplus 变换。

IX. 发布与版本治理约定

• 版本推进：字段或单位变更为 MAJOR；先验/边界微调为 MINOR；默认值与备注更新为 PATCH。
• 场景覆写：scenario_overrides 仅允许更改 default|bounds|prior，不改变 unit|type。
• 冻结与退役：status="frozen" 用于回归基线；deprecated 需给出替代 code 并保留一个发布周期。

X. 常见误用与修正

• 误用：在 derived.expr 写 ∫ n d ell / c。
  修正：derived.expr: "( ∫_gamma ( n_eff / c_ref ) d ell )" 并提供 see: ["S20-*"]。
• 误用：a_T 标注 unit: "1" 导致 a_T * T_fil 量纲不闭合。
  修正：将 unit 设为 "[Tension]^-1" 或调整映射使乘积无量纲并通过 check_dim。
• 误用：省略 prior.hyper。
  修正：补全如 Normal 需 {mu, sigma}；Gamma 需 {k, theta} 或 {alpha, beta}。

XI. 最小清单检查表（提交前）

• code|name|role|type|unit|owner|since|status|semver 全部存在。
• bounds 合法且与 transform 域一致。
• prior 支持包含于 bounds；超参数完备。
• constraints|derived 通过 check_dim 与 lint。
• 跨卷 see 已给出（若条目参与 S20-*|S40-*|S50-*）。
• 导出 export_params("yaml") 能复现本条目且回归比对通过。