10-EFT.WP.Core.Tension v1.0 | 附录E 接口参考（I70）

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

附录E 接口参考（I70）

I. 范围与约定

• 本附录定义 I70-* 接口的签名、参数、返回与错误语义，覆盖几何/材料、静力、动力学与波、界面张力、连接与透射、到达时校准、不确定度与信息界。
• 单位、符号与测度遵循附录A与“数学表达歧义规避规则”。凡含积分与路径的量，均显式指明 gamma(ell) 与测度 d ell。
• 所有接口参数名、返回字段名一律使用英文与纯文本。跨式引用 S72-* 与 Mx-7* 处标注来源。
• 类型记号：PathRef、MatRef、TensionFieldRef、WaveRef、NetRef 为不可变句柄；标量用 float；序列用 array[float]；映射用 dict。

II. 核心类型与通用字段

1. PathRef
   • 描述：线几何路径引用，承载 gamma(ell) 与离散节点。
   • 元数据：id:str，nodes:array[[x,y,z]]，metric:str，L_gamma:float。
2. MatRef
   • 描述：路径的截面与材料属性。
   • 字段：A:float (m^2)，rho_m:float (kg/m^3)，rho_l:float (kg/m)，E:float (Pa)。
3. TensionFieldRef
   • 描述：沿 ell 的张力场与位移场。
   • 字段：T_fil:array[float] (N)，u:array[float] (m)，epsilon:array[float]。
4. WaveRef
   • 描述：时域或频域波解。
   • 字段：c:array[float] (m/s)，u(t,ell) 或 U(omega,ell) 的访问器，Z:array[float] (kg/s)。
5. NetRef
   • 描述：网络/结点解及散射量。
   • 字段：Z_ports:array[float]，S_matrix:array[array[complex]]，balance:dict。

III. I70 1 几何与属性

1. define_path(nodes:any, metric:str|None=None, base:str="euclid") -> PathRef
   • 输入
     1. nodes：array[[x,y,z]] 或带弧长的样条控制点。
     2. metric："euclid"、"geo" 或自定义度量名；缺省等同 base。
     3. base：参考空间；缺省 "euclid"。
   • 返回
     PathRef，含 L_gamma = ( ∫ 1 d ell ) 与节点弧长参数化。
   • 约束
     节点数 ≥ 2；L_gamma > 0。若参数化 ell = ell(s)，输出需包含 | d ell / ds |（见规则）。
   • 相关
     数据格式与坐标系见附录B。
2. assign_section(path:PathRef, A:float, rho_m:float, E:float) -> MatRef
   • 输入
     A、rho_m、E 单位遵循附录A；内部派生 rho_l = rho_m * A。
   • 返回
     MatRef 绑定到 path。
   • 约束
     A > 0，rho_m > 0，E > 0。
   • 相关
     可与 S72-2、S72-5 联合用于线弹性与波动。

IV. I70 2 静力张力与本构

1. tension_static(path:PathRef, loads:any, bc:any, law:str="hooke") -> TensionFieldRef
   • 输入
     1. loads：沿 ell 的分布载荷 q(ell) 与集中载荷集合。
     2. bc：边界条件集合（Dirichlet/Neumann/Robin，见附录C）。
     3. law："hooke" 或用户自定义本构。
   • 返回
     TensionFieldRef，包含 T_fil(ell)、u(ell)、epsilon(ell)。
   • 数学
     平衡：S72-1 : ∂_ell T_fil + q_tan = 0；本构：S72-2。
   • 校核
     端部牵引与内力一致性误差 <= tol；能量 path_energy 见 S72-8。
2. stress_to_tension(sigma:any, A:float, orientation:any) -> float
   • 输入
     sigma：sigma_ij 或标量 sigma；orientation：截面法向与轴向。
   • 返回
     轴向张力 T_fil = ( sigma : (t_hat ⊗ t_hat) ) * A。
   • 单位
     Pa * m^2 = N。

V. I70 3 动力学与波

1. string_wave_solve(path:PathRef, T:callable|float, rho_l:callable|float, bc:any, damping:any|None=None) -> WaveRef
   • 输入
     1. T：常量 T0 或函数 T_fil(ell,t) 的时间/空间依赖近似。
     2. rho_l：常量或函数。
     3. bc：端口与中间连接的边界条件（附录C）。
     4. damping：dict{ c_visc , eta_struc } 可选。
   • 返回
     WaveRef，含 c(ell) = sqrt( T_fil / rho_l ) 与阻抗 Z = rho_l * c。
   • 数学
     S72-5 : rho_l ∂_tt u = ∂_ell( T_fil ∂_ell u ) + q；均匀时 S72-6。
   • 稳定性
     显式推进应满足 S72-12 : Δt ≤ CFL * ( Δell / c_max )；或采用隐式/谱法。
2. estimate_tension_from_modes(freqs:any, L:float, rho_l:float) -> float
   • 输入
     freqs：基础或若干模态频率 f_n；L 取 L_gamma；rho_l 线密度。
   • 返回
     估计张力 T_fil。
   • 模型
     简支弦近似 f_n = ( n / (2L) ) * sqrt( T_fil / rho_l )，用最小二乘反推 T_fil（记录适用边界类型）。

VI. I70 4 界面张力与曲率

1. young_laplace(sigma_s:float|callable, kappa1:float, kappa2:float) -> float
   • 返回
     压差 Δp = sigma_s * ( kappa1 + kappa2 )（S72-3）。
   • 备注
     若 sigma_s 依赖位置/曲率，按调用点求值。
2. capillary_wave_dispersion(sigma_s:float, rho:float, k:float, g:float|None=None) -> float
   • 返回
     频散 omega(k)；缺省无重力：omega = sqrt( ( sigma_s / rho ) * k^3 )；若含 g：omega = sqrt( g*k + ( sigma_s / rho ) * k^3 )。
   • 单位
     omega 为 rad/s。

VII. I70 5 连接与传递

1. junction_solve(network:any, impedances:any, bc:any) -> NetRef
   • 输入
     1. network：端口/结点拓扑与连接矩阵。
     2. impedances：各支路/端口 Z_i(omega) 或时域等效。
     3. bc：入射/激励规范与开放/匹配端设置。
   • 返回
     NetRef，含 S_matrix、端口平衡与功率流。
   • 数学
     结点平衡 S72-7；无损结点 S_matrix 幺正；多端口散射推导见附录D XII。
2. transmission_coeff(Z1:float, Z2:float) -> dict
   • 输入
     Z1、Z2：相邻介质/支路的特性阻抗。
   • 返回
     dict{ r_amp:float , t_amp:float , R_ref:float , T_trans:float }。
   • 数学
     S72-9 : r_amp = ( Z2 - Z1 ) / ( Z2 + Z1 )；S72-10 : t_amp = 2 * Z2 / ( Z1 + Z2 )；S72-11 功率守恒。

VIII. I70 6 校准与到达时

1. calibrate_tension_by_toa(trace:any, L_gamma:float, rho_l:float, n_eff:any|None=None, c_ref:float|None=None) -> float
   • 输入
     1. trace：到达时提取所需波形或时间标记集合；需包含 T_arr 或可计算 T_arr 的规则。
     2. L_gamma：路径弧长；rho_l：线密度；可选 n_eff、c_ref 用于两口径一致性记录。
   • 返回
     T_fil = rho_l * ( L_gamma / T_arr )^2（S72-14）。
   • 记录
     同时输出/记录 delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |（口径一致性）。
2. enforce_arrival_time_convention(trace:any) -> None
   • 功能
     将输入 trace 对齐统一到达时口径（峰值、能量质心或首波坡度阈值），并写入元数据 toa_convention。
   • 相关
     与《Core.Density》到达时章节口径一致。

IX. I70 7 不确定度与界

1. fisher_information_tension(model:any, theta:dict) -> matrix
   • 输入
     model：似然或测量算子；theta：参数表，至少含 T_fil，可扩展 rho_l、L_gamma、噪声方差等。
   • 返回
     Fisher 信息矩阵 I_F(theta)（S72-15）。
   • 示例
     单参数到达时：I_F(T_fil) = ( (∂_{T_fil} T_arr)^2 ) / sigma_T^2，∂_{T_fil} T_arr 见附录D XIII。
2. crlb_tension(model:any, theta:dict) -> matrix
   • 返回
     Cramér–Rao 下界 cov(theta) ≥ I_F^{-1}(theta)（S72-16）。
   • 约束
     要求 I_F 可逆；若退化，返回伪逆并标注 rank_deficient=True。

X. 错误模型与返回约定

1. 通用返回封装（若使用增强模式）
   dict{ ok:bool , data:any|None , err_code:str|None , err_msg:str|None , diag:dict|None }。
2. 标准错误码
   • E_GEOM_INVALID（几何退化或 L_gamma ≤ 0）
   • E_UNIT_MISMATCH（单位/量纲不一致）
   • E_BC_INCOMPAT（边界条件不相容）
   • E_STAB_VIOLATION（违反 S72-12 稳定性）
   • E_NONCONVERGE（非线性或求解器不收敛）
   • E_SINGULAR_IF（I_F 奇异）
3. 诊断字段建议
   • energy_balance（ΔE 与相对误差）
   • residual_norm（平衡残差）
   • cfl_ratio = Δt * c_max / Δell（应 ≤ CFL）
   • delta_form（到达时两口径差）

XI. 单位与量纲校核（接口级强制）

1. 进入解算前，自动执行
   • check_dim( T_fil ) = N
   • check_dim( sigma_s ) = N/m
   • check_dim( sigma_ij ) = Pa
   • check_dim( Z ) = kg/s
2. 校核失败触发 E_UNIT_MISMATCH，并给出期望与实得单位对。

XII. QA 用例与 Mx-79 对应

• 几何与属性
  生成基线 PathRef 与 MatRef，校验 L_gamma 与 rho_l = rho_m * A。
• 静力
  tension_static 在均布载荷下对比解析悬链近似或线弹性闭式；核对 S72-1 残差与 S72-8 能量。
• 动力学
  string_wave_solve 对比 S72-6 模态频率；显式步进核查 S72-12。
• 连接
  transmission_coeff 的 R_ref + T_trans = 1 无损校核；junction_solve 幺正性。
• 校准
  calibrate_tension_by_toa 在合成波形上回代 T_fil 并记录 delta_form。
• 信息界
  fisher_information_tension 与 crlb_tension 在已知噪声下的下界对比蒙特卡洛估计方差。

XIII. 数据交换与模式引用（与附录B一致）

• 几何载体
  path.json：{ "nodes":[[x,y,z],...], "metric":"euclid", "L_gamma":float }
• 材料载体
  section.json：{ "A":float, "rho_m":float, "rho_l":float, "E":float }
• 载荷与边界
  loads_bc.json：{ "q":[ [ell,value], ... ], "bc":[ {"type":"Dirichlet","at":"left","u":0.0}, ... ] }
• 频散/阻抗
  ports.json：{ "Z":[ {"port":1,"value":float}, ... ] }

XIV. 版本、兼容与弃用策略

• 版本字段
  所有返回对象包含 api_version:"I70" 与 schema_version:"TEN/1.0"。
• 兼容性
  小版本添加字段保证向后兼容；删除或语义改变以 deprecations 列表标注并保留至少一个次要版本的过渡期。
• 不变性
  所有 *Ref 句柄为只读；修改需通过对应 assign_* 或新建对象。

XV. 符号与公式锚点（实现内联校核）

1. S72-1 至 S72-16 的实现锚点应在日志中以 anchor:"S72-*", value:... 形式记录，便于跨卷追踪。
2. 关键守恒式
   • R_ref + T_trans = 1（无损连接）
   • path_energy ≥ 0（弹性能非负）
   • delta_form 持续记录并在校准环节阈值告警。

XVI. 最小示例（签名与调用顺序）

1. 几何与材料
   • p = define_path(nodes, metric="euclid")
   • m = assign_section(p, A, rho_m, E)
2. 静力校核
   tf = tension_static(p, loads, bc, law="hooke")
3. 动力学与阻抗
   • w = string_wave_solve(p, T=tf.T_fil or T0, rho_l=m.rho_l, bc=bc)
   • Z1 = w.Z[0]; Z2 = Z_match
   • coeff = transmission_coeff(Z1, Z2)（校核 S72-9–S72-11）
4. 到达时与张力标定
   T_est = calibrate_tension_by_toa(trace, L_gamma=p.L_gamma, rho_l=m.rho_l, n_eff=n_eff, c_ref=c_ref)
5. 信息界
   • IF = fisher_information_tension(model, {"T_fil":T_est, "sigma_T":sigma_T})
   • CR = crlb_tension(model, {"T_fil":T_est, "sigma_T":sigma_T})

XVII. 依赖与外部约束

• 频域接口与谱密度 S_xx(f) 的口径与《Core.Sea》一致；到达时两口径与《Core.Density》一致；曲率计量与《Core.Metrology》一致。
• t_hat、n_hat 与测度 d ell、dA 在实现中需以附录B 的坐标与网格规范为准。