10-EFT.WP.Core.Tension v1.0 | 第10章 工程化实现与测试

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

第10章 工程化实现与测试

I. 目标、范围与一致性要求

• 目标：将理论与数值方法固化为可复用、可验证的工程系统，覆盖几何与材料绑定、静/动态求解、连接与传递、校准与识别、以及全流程 QA。
• 范围：实现 I70 1–7 全量接口，建立标准数据模型、日志与误差度量，提供基准算例与回归套件，支撑 Mx-71/72/73/74/75/76/77/78/79。
• 一致性：量纲与测度显式（第1章 P71-*），冲突名强制（T_fil vs T_trans），到达时两口径并行与差异记录 delta_form（第8章），能量与功率一致（第6章）。

II. 模块分层与 I70 绑定

1. 核心分层
   • 几何层：define_path，曲线 gamma(ell) 与长度 L_gamma = ( ∫ 1 d ell )；网格与测度元 d ell/dA/dV 元数据。
   • 材料层：assign_section，存储 A,E,rho_m,rho_l；支持沿线分段与时间依赖字段。
   • 静力层：tension_static，实现 S72-2 与边界条件（Dirichlet/Neumann/Robin）求解与核查。
   • 动力层：string_wave_solve，实现 S72-5/6、阻尼与外激励；与第7章稳定性策略耦合。
   • 界面层：transmission_coeff、junction_solve，实现阻抗耦合与功率守恒。
   • 校准层：calibrate_tension_by_toa、enforce_arrival_time_convention，两口径与 delta_form 记账。
   • 识别层：fisher_information_tension、crlb_tension，产出 I_F 与 CRLB（第9章 S72-15/16）。
2. 接口契约要点
   • 所有输入的单位与测度显式声明（例如 rho_l 用 kg/m，A 用 m^2，路径积分标注 ( ∫ · d ell )）。
   • 所有输出附带 meta.units、meta.measure、meta.bc、meta.version、meta.seed 与时间基准。
   • 错误边界：对于接口处的无损连接，强制返回 check.energy = | 1 - ( R_ref + T_trans ) |。

III. 数据模型与元数据规范

1. 几何对象 PathRef
   • 字段：nodes（坐标系标注）、metric、orientation、L_gamma、measure="d ell"。
   • 约束：闭合路径需 sum(turn_angle) → 2*pi*k 容差内；参数化 ell(s) 存储 | d ell / ds |。
2. 材料对象 MatRef
   • 字段：A,E,rho_m,rho_l；支持 rho_l(ell) 与 T_fil(ell) 的 piecewise 表示。
   • 派生：rho_l = rho_m * A（若未显式给定）。
3. 观测对象 Trace
   字段：y(t)、fs 或非均匀 t_k、窗口信息 U_w,ENBW_Hz、同步戳；TOA 结果含两口径 T_arr_ref = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr_gen = ( ∫ ( n_eff / c_ref ) d ell )，并给出 delta_form。
4. 结果对象统一字段
   value、cov、crlb、checks（ΔE,ΔBC,ΔCFL,ΔTOA 等）、meta（版本、种子、时间基）。

IV. 数值内核与稳定性守则（与第7章对齐）

1. 时间步长约束
   • S72-12 : Δt ≤ CFL * ( Δell / c_max )，其中 c_max = max_ell( sqrt( T_fil(ell) / rho_l(ell) ) )。
   • 违反时需自适应缩减 Δt 并记录 ΔCFL = 1 - Δt * c_max / Δell。
2. 线性代数
   • 对 ∂_ell( T_fil ∂_ell u ) 使用对称正定装配与预条件共轭梯度（PCG）；非均匀 T_fil 用元素内高斯积分。
   • 阻尼矩阵支持 Rayleigh 型 C = a*M + b*K，约束 a,b ≥ 0。
3. 能量核查
   • 宏能量：E_total(t) = ( ∫ ( T_fil * (∂_ell u)^2 / 2 ) d ell ) + ( ∫ ( rho_l * (∂_t u)^2 / 2 ) d ell )。
   • 记录 ΔE_rel = | E_total(t+Δt) - E_total(t) | / max(E_total) 并门限判定。

V. 校准与归一化管线（第8章绑定）

1. 基准量与无量纲化
   • T_star = T_fil / T_ref、c_star = c / c_ref、rho_star = rho_l / rho_ref。
   • 统一速度口径：c = L_gamma / T_arr 与 c = sqrt( T_fil / rho_l ) 交叉核对，输出 ratio_c = ( L_gamma / T_arr ) / sqrt( T_fil / rho_l )。
2. 到达时两口径差异
   • delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |。
   • 当 delta_form > delta_tol，自动降权 TOA 通道或触发重采样。

VI. 测试分类与覆盖策略

• 单元测试（API 契约）
  参数校验、量纲检查、边界条件映射、异常分支（空路径、退化截面等）。
• 性能与稳定性测试
  CFL 扫描、阻尼渐进稳定性、长时能量漂移（ΔE_rel 趋于 0 的速率）。
• 性能回归
  多网格尺度与时间步长的弱/强缩放；阻抗网络规模提升的复杂度曲线。
• 随机与性质测试
  随机生成 rho_l(ell) 与分段 T_fil(ell)；断言不变量：R_ref + T_trans = 1（无损），Z = rho_l * c。
• 端到端场景
  从 Trace→TOA→c_hat→T_fil_hat→I_F→CRLB 的完整链路再现性和数值一致性。

VII. 基准算例库（最小可复现实例）

1. 均匀弦模态（固定-固定）
   • 设 T0、rho_l、L_gamma，理论 f_n = ( n / ( 2 * L_gamma ) ) * sqrt( T0 / rho_l )。
   • 度量：err_f = max_n | f_n^{num} - f_n^{ref} | / f_n^{ref}、u(f_n) 的谱峰位置与幅度偏差。
2. 到达时基线
   给定 T_arr 与 L_gamma，由 c = L_gamma / T_arr 与 T0 = rho_l * c^2 回推；与波动求解得到的群速一致性 | c_group - c | / c。
3. 两段阻抗连接
   • Z1 != Z2，r_amp = ( Z2 - Z1 ) / ( Z2 + Z1 )、R_ref = |r_amp|^2、T_trans = 1 - R_ref。
   • 检查：数值反射能量与解析值偏差 err_R、节点平衡残差 ΔBC。
4. Young–Laplace 球形界面（跨卷对齐）
   • S72-3 : Δp = sigma_s * ( kappa1 + kappa2 )；球面 kappa1 = kappa2 = 1/R，故 Δp = 2 * sigma_s / R。
   • 检查：拟合曲率与压差一致性误差。
5. 非均匀弦阶跃张力
   T_fil(ell) = T1 与 T2 的分段常数；脉冲入射，测 R_ref/T_trans 与到达时差 ΔT_arr；验证时域与频域一致。

VIII. 误差度量与 QA 门（发布准入）

• 频率误差门限：err_f ≤ 1e-3（默认），应力/张力相对误差：err_T ≤ 1e-3。
• 能量守恒：max_t ΔE_rel ≤ 1e-4（无阻尼），≤ 1e-3（有阻尼）。
• 边界一致：ΔBC = || t - sigma · n_hat ||_2 / scale ≤ 1e-4。
• 口径一致：| ratio_c - 1 | ≤ 5e-3、delta_form ≤ delta_tol（默认 delta_tol = 1e-6 s）。
• 透射守恒：| 1 - ( R_ref + T_trans ) | ≤ 1e-6（无损）。
• 回归漂移：相对基线 ≤ 0.5%；超限则阻断发布并生成差异报告。

IX. 日志、追溯与版本治理

• 版本号：语义版本 MAJOR.MINOR.PATCH，与文档版本 v1.0 对齐。
• 变更记录：CL-TEN-YYYYMMDD-###，记录接口变更、数值核修改与 QA 结果摘要。
• 可追溯性：每次运行保留 rng_seed、git_sha、build_id、meta.units、meta.measure、meta.bc；输出附带校验和。
• 日志级别：INFO（口径与配置）、WARN（近阈值）、ERROR（越阈）、CRITICAL（终止）。

X. 部署与性能工程

• 并行化：频域与模态求解对 n 并行；时域显式步进对时间块并行（保证因果）。
• 内存策略：稀疏装配与按需缓存 T_fil(ell)、rho_l(ell)；长时仿真启用检查点。
• 精度选择：默认双精度；在保能格式下允许混合精度但需加严 ΔE_rel 门限。
• 跨平台：统一时间基与随机数；FFT/线性代数库需固定后端与版本以确保可复现。

XI. 运行时自检与故障切换

• 单位审计：自动检查 T_fil（N）、sigma_s（N/m）、sigma_ij（Pa）、rho_l（kg/m），发现不一致即拒绝运行。
• CFL 监控：动态评估 Δt 与 c_max，超限自动减半 Δt 并记录。
• 口径冲突：检测 T_fil 与 T_trans 混用即报错；检测 R_ref + T_trans 偏离即提示损耗模型。
• TOA 冲突：delta_form 超阈自动降权 TOA 通道并建议复采 n_eff,c_ref。

XII. 标准工作流 Mx-79（实现→验证→发布）

• 载入几何 gamma(ell) 与材料字段；执行单位审计与测度审计。
• 绑定边界与连接；生成网格与测度元，计算 L_gamma 与 | d ell / ds |。
• 选择求解器与时间步；计算 c_max 与 CFL，并锁定 Δt。
• 若含 TOA：执行两口径到达时测量，记录 T_arr_ref,T_arr_gen,delta_form。
• 静力/动态求解：tension_static 或 string_wave_solve；在接口处调用 junction_solve。
• 识别与不确定度：estimate_tension_from_modes 或到达时反演；计算 I_F 与 CRLB。
• QA 核查：ΔE_rel,ΔBC,ΔCFL,err_f,err_T,ratio_c,(R_ref+T_trans)；生成报告与可视化。
• 回归比对：与基线数据集对齐，生成差异清单。
• 发布封版：写入 CL-TEN-YYYYMMDD-###，归档工件（配置、日志、报告、快照）并更新基线。

XIII. 常见问题与诊断指引

• 频率系统性偏低：rho_l 过估或 L_gamma 过长；检查网格与截面、端部条件。
• 反射能量超额：接口阻抗不匹配或损耗未显式；核查 Z = rho_l * c 与连接条件。
• 长时能量漂移：步长过大或阻尼离散不稳定；收紧 Δt 与能量守恒格式。
• 到达时不一致：delta_form 超阈或时基漂移；复核 n_eff,c_ref 与采样时钟。
• CRLB 过松：可辨识性不足；引入 R_ref/TOA 组合或延长基线 L_gamma 提升灵敏度（第9章）。

XIV. 交叉引用与必记清单

• 必记符号：T_fil,sigma_s,sigma_ij,epsilon_ij,E,A,rho_m,rho_l,u,c,Z,omega,k,R_ref,T_trans,T_arr,n_eff,c_ref,L_gamma,delta_form,I_F,CRLB。
• 关键方程：S72-2, S72-3, S72-4, S72-5, S72-6, S72-9, S72-10, S72-11, S72-12, S72-15, S72-16。
• 口径锚点：测度显式与单位守恒（第1章 P71-*）、本构与静力（第2章）、界面张力（第3章）、波动与速度（第4章）、网络耦合（第5章）、阻抗与透射（第6章）、稳定性（第7章）、归一化与到达时（第8章）、识别与信息界（第9章）。