03-EFT.WP.Core.Parameters v1.0 | 第1章 参数体系与编号

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

第1章 参数体系与编号

I. 命名公设与层级口径（P31-1…P31-3）

• P31-1（唯一性）：任一参数以 code 为全局唯一键；一经发布不得复用于不同语义。
• P31-2（稳定性）：code 的语义与量纲恒定；默认值、先验超参数可在小版本中调整但须记录于附录B。
• P31-3（无二义前缀）：角色前缀与家族名不得形成可互指的前缀链；别名仅能单向映射至唯一的 canonical code。
• 附加规则 R31-1：参数首现处给出 unit 与有效域；跨节引用仅以 code 出现。
• 附加规则 R31-2：涉及路径/到达时的参数必须配套书写 gamma(ell) 与 d ell，并沿用括号完整体 T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 附加规则 R31-3：禁止混用冲突名：T_fil 与 T_trans、n 与 n_eff，以及裸 c（统一使用 c_ref）。

II. 角色与编号族

1. 角色集合（role）
   • obs：观测层参数（噪声、标定、采样）。
   • proc：过程/动力学参数（输运、源汇、耦合）。
   • const：本构与映射参数（F_map(·) 的超参数）。
   • num：数值算法与求解器参数。
   • env：环境/场景基准参数（如 c_ref、背景密度）。
   • drv：派生参数（由 derive_param 显式给出依赖）。
2. 角色编号与排序
   • 角色排序表：const < env < proc < obs < num < drv。
   • 组装 theta 时默认按上述排序再按 code 字典序排列，保证跨实现一致。

III. code 语法与合法字符

1. 语法
   • code ::= role "." family "." name [ "." scale ] [ "@" scenario ] [ "#v" semver ]
   • 例：proc.transport.kappa, const.n_eff.alpha0@baseline#v1.0
2. 约束
   • role ∈ {obs,proc,const,num,env,drv}。
   • family,name,scale,scenario 使用 [a-z0-9_]+；不得使用大写与空白。
   • semver 遵循 MAJOR.MINOR[.PATCH]；发布时可省略，版本治理通过 bump_version 维持。
3. 正例
   obs.arrival.sigma_Tarr，num.solver.tol_newton，env.c_ref.si
4. 误例
   process.kappa（缺少三段式）、PROC.Transport.Kappa（大小写不合规）、const.neff.alpha（缺下划线：应为 n_eff）

IV. 参数向量与分组

1. 记号与关系
   • theta（全量参数向量），theta_g（参数组），theta_fix（冻结集），theta_free（可辨识集）。
   • theta = [ theta_free ; theta_fix ]（按 II 节角色排序与字典序拼接）。
2. 组构造
   • 以集合生成式定义：theta_free def= { code ∈ Theta | trainable(code) }。
   • 组操作：并 ∪、交 ∩、差 \ 在实现中以有序列表落地，保持稳定顺序。

V. 别名与规范化

1. 别名规则
   • 别名仅用于兼容历史或第三方命名；不得创建同义多源。
   • add_alias(canonical, alias) 后，normalize_param(alias) -> canonical 必须恒等。
2. 冲突处理
   任一别名若与现有 code 或别名冲突，必须拒绝并在变更记录给出处置（保留/废弃）。

VI. 版本、场景与生命周期

1. 场景治理
   create_scenario/activate_scenario 管理 @scenario 片段，允许同 code 在不同场景有不同默认或先验。
2. 生命周期
   • 冻结/解冻：freeze(code)、thaw(code)；冻结参数自动并入 theta_fix。
   • 废弃：在导出中以 deprecated:true 标记并提供迁移目标 see:[canonical]。

VII. 量纲、单位与无量纲映射

• 量纲闭合
  任一参数首次注册时声明 unit 并通过 check_dim(expr) 与参考尺度 L0,t0,T0 校验。
• 无量纲化
  示例：bar_kappa def= kappa * ( t0 / L0^2 )，其中 kappa 的量纲为 [L]^2/[T]。
• 到达时耦合参数
  任何影响 T_arr 的参数（如 c_ref、n_eff 族超参数）必须与路径声明联动，引用形如 T_arr = ( ∫ ( n_eff / c_ref ) d ell )。

VIII. 编号卡片与模板

• 命名卡片（摘录）
  role：见 II 节；family：子领域或部件名；name：量纲对象或统计对象；scale：可选尺度标识（如 si, normL0）。
• 引用模板
  文内引用：see ["S20-1","I30 5"]；跨卷固定写法：“见 配套白皮书《能量丝》 第x章 S/P/M/I…”。

IX. 注册示例（I30 1，5 条）

• 例 1
  register_param(name="Reference propagation speed", code="env.c_ref.si", type="scalar", unit="m/s", role="env", default=2.99792458e8, bounds=(1e8, 4e8), prior={"family":"LogNormal","hyper":{"mu":19.5,"sigma":0.05}}, transform=None, see=["S20-1","Core.Terms:c_ref"])
• 例 2
  register_param(name="Transport diffusivity", code="proc.transport.kappa", type="scalar", unit="m^2/s", role="proc", default=1.0e-3, bounds=(1.0e-6, 1.0), prior={"family":"LogNormal","hyper":{"mu":-6.9,"sigma":1.0}}, transform="log", see=["S50-1"])
• 例 3
  register_param(name="Effective index offset", code="const.n_eff.alpha0", type="scalar", unit="1", role="const", default=0.0, bounds=(-0.5, 0.5), prior={"family":"Normal","hyper":{"mu":0.0,"sigma":0.1}}, transform=None, see=["S30-1","Core.Terms:n_eff"])
• 例 4
  register_param(name="Arrival-time noise stdev", code="obs.arrival.sigma_Tarr", type="scalar", unit="s", role="obs", default=1.0e-4, bounds=(1.0e-6, 1.0), prior={"family":"HalfNormal","hyper":{"sigma":1.0}}, transform="log", see=["S20-2"])
• 例 5
  register_param(name="Newton solver tolerance", code="num.solver.tol_newton", type="scalar", unit="1", role="num", default=1.0e-8, bounds=(1.0e-12, 1.0e-2), prior=None, transform="log", see=["I20 3"])
• 别名示例
  add_alias(canonical="proc.transport.kappa", alias="kappa_T")；normalize_param("kappa_T") -> "proc.transport.kappa"

X. 校验清单（Lint 与一致性）

• 角色与三段式：code 必须匹配 role.family.name；可选 scale/@scenario/#v 必须位于末尾并顺序固定。
• 大小写与字符集：仅允许小写字母、数字与下划线；禁止空格与连字符。
• 冲突与别名：code 与别名空间互斥；别名仅指向一个 canonical。
• 量纲闭合：unit 与 check_dim 一致；无量纲量以 "1" 标记。
• 到达时相关：凡引用 T_arr 的参数，文本中必须出现 gamma(ell) 与 d ell 并使用 ( n_eff / c_ref ) 被积项。
• 符号隔离：严禁 T_fil ↔ T_trans 与 n ↔ n_eff 混用；严禁裸 c。
• 组装顺序：theta 拼接顺序按 II 节排序与字典序确定；theta_free、theta_fix 在导出时显式列序。

XI. 跨卷锚点与示例引用

• 本章涉及之跨卷锚点：c_ref、n_eff(x,t)、T_arr、gamma(ell)、d ell（见《Core.Terms》《Core.Equations》S20-、S30-）。
• 典型引用写法
  see=["S20-1","S30-1","S50-1","I20 3","Core.Terms:n_eff"]

XII. 小结与后续衔接

• 已确立参数命名三公设（P31-1…P31-3）、角色体系与 code 语法，定义了 theta/θ 的组装与生命周期。
• 下一章进入分类目录与词条规范，按 const/proc/obs/num/env/drv 构建可检索的参数注册表并给出跨卷引用。