11-EFT.WP.Core.DrawingKinetics v1.0 | 附录B 实现绑定与函数原型

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

附录B 实现绑定与函数原型

I. 范围与目标

• 汇总 I10-* 实现绑定原型，定义输入输出、单位、异常、幂等与并发契约，并给出可执行级伪代码与报文形制，支撑第2–第13章的计算与计量流程。
• 所有符号、公式与口径与附录A一致；含除号、积分或复合算符一律以括号围定，并显式声明路径 gamma(ell) 与测度 d ell。

II. 命名、版本与通用约束

• 命名与编号
  实现绑定统一采用 I10-*；报表对象名称与第9章 schema.core.drawing/v1 对齐。
• 版本与兼容
  api.version = "I10.v1"；输入输出均携带 schema.version；小版本向后兼容，破坏性变更需递增主版本。
• 单位与量纲
  默认 SI；对所有输出执行 check_dim( expr )；发布 eps_mass、eps_norm（见附录A）。
• 冲突名强制
  T_fil 仅指张力；T_trans 仅指透射系数；n 与 n_eff 不可混用。

III. 核心数据类型与状态容器

1. state: dict（最小必需键）
   • t0: float (s, ts)；t1: float (s, ts)；tau_mono_map: dict{ ts -> tau_mono }；timebase: { alpha: float (s), beta: float }。
   • grid: { ell: array (m), d_ell: float (m) }；gamma: any（路径参数化描述）。
   • lambda: array (—)；s: array (1/s)；v: array (m/s)；A: array (m^2)；rho: array (kg/m^3)；T_fil: array (N)。
   • params: { K_el: float (N), K_vis: float (N*s), theta: float (—), tau_rel: float (s), mu: float (Pa*s) }。
   • meta: { run_id: str, schema.version: str, provenance: dict }。
2. bc: dict（边界条件与工况卡摘要，见第5章）
   • inlet: { v: float (m/s) or None, s: float (1/s) or None }；outlet: { v: float (m/s) or None }。
   • env: { T_env: float (K) or None }；contact: { slip: float (—) in [0,1], mu_k: float (—) }。
3. 报表对象（关键字段）
   StepReport，CalReport，MetricsReport：字段在各原型条目中详述。

IV. I10- 原型总览*

• I10-1 update_draw_state( state:dict, bc:dict, dt:float ) -> StepReport
• I10-2 estimate_tension( lambda:float, s:float, params:dict ) -> float
• I10-3 compute_instability_metrics( state:dict ) -> dict
• I10-4 calibrate_kinematics( trace:any, sensors:list, timebase:dict ) -> CalReport
• I10-5 emit_metrics_drawing( state:dict ) -> MetricsReport

V. I10-1 update_draw_state

1. 目的
   在时间步长 dt 上推进 state，同时执行守恒校核与异常判定，生成 StepReport。
2. 输入
   state，bc，dt: float (s)。
3. 输出 StepReport: dict
   • t0, t1: float (s, ts)；dt_eff: float (s)。
   • eps_mass: float (—)；eps_norm: float (—)；ok: bool；errors: list[str]。
   • summary: { T_fil_mean: float (N), T_fil_rms: float (N), v_mean: float (m/s), s_mean: float (1/s) }。
   • TS: { hb: bool, latency: float (s), bp: float (—), slo_pass: bool }（第10章）。
   • idem_key: str（见幂等）。
4. 幂等与可重放
   在固定三元组 ( hash(state@t0), bc, dt ) 下应返回相同 StepReport 与终态；idem_key = H( state.t0 || state.meta.run_id || bc.digest || dt )。
5. 近似与方程口径
   • 质量守恒（S12-1）离散推进：
     rho_L^{n+1} = rho_L^{n} - dt * ( d/dell ) ( J^{n} )，其中 rho_L = rho * A，J = rho_L * v。
   • 构成更新（S12-3 范式）：
     T_fil^{n+1} = K_el * ( lambda^{n+1} - 1 ) + K_vis * s^{n+1} + ...。
6. 伪代码（要点）
   • 校验 check_dim 与 schema.version；失败则加入 E_DIMENSION_MISMATCH。
   • 根据 timebase 映射 ts -> tau_mono，对齐 dt_eff，更新 lambda,s,v,A。
   • 以保守格式离散 ( d/dell ) J 并更新 rho_L；累计 eps_mass。
   • 依据构成参数更新 T_fil；计算 summary 与 TS.*。
   • 若检测到失稳触发（见 I10-3）则标记 E_UNSTABLE_STEP。
7. 异常（可能集合）
   E_BC_INVALID，E_DIMENSION_MISMATCH，E_CONSERVATION_FAIL，E_UNSTABLE_STEP，E_PARAMS_MISSING，E_TIMEBASE_UNALIGNED。

VI. I10-2 estimate_tension

1. 目的
   给定局部 lambda 与 s，结合 params 返回张力估计 T_fil。
2. 签名
   estimate_tension( lambda:float, s:float, params:dict ) -> float (N)。
3. 计算口径
   • 基本式：T_fil = K_el * ( lambda - 1 ) + K_vis * s。
   • 可选速率硬化：T_fil += theta * K_el * ( s * tau_rel )（当 theta > 0）。
   • 合法域：lambda > 0，|s| < s_max（由参数卡限定）。
4. 异常
   E_PARAMS_MISSING，E_DOMAIN_VIOLATION。

VII. I10-3 compute_instability_metrics

1. 目的
   计算线性与非线性失稳指标，用于第6章的告警与控制。
2. 签名
   compute_instability_metrics( state:dict ) -> dict。
3. 输出（示例字段）
   • g_max: float (1/s)（线性增长率上界）。
   • r_neck: float (—)（颈缩风险指数）。
   • We: float (—)；De: float (—)；Re: float (—)（附录A定义）。
   • band_amp: dict{ f_band: [f1,f2], gain: float (—) }（波动放大带）。
   • stable: bool；triggers: list[str]（如 "necking", "rate_hardening", "slip_jump"）。
4. 核心计算要点
   • 线性化沿 gamma(ell)：设扰动 delta(lambda)，离散谱判据 g_max = max_eig( J_lin )。
   • 颈缩阈：当 ( d T_fil / d lambda ) < 0 区域占比超阈则 r_neck ↑。
   • 以局部 tau_rel 评估 We = tau_rel * s_mean，De = tau_rel * ( v_mean / L_char )。
   • 结合第7章谱口径，以 S_xx(f) 估计带宽放大 gain。

VIII. I10-4 calibrate_kinematics

1. 目的
   执行 Mx-11（时基与几何标定）与部分 Mx-12 的运动学校准，输出 CalReport。
2. 签名
   calibrate_kinematics( trace:any, sensors:list, timebase:dict ) -> CalReport。
3. 输出 CalReport: dict
   • timebase: { alpha: float (s), beta: float }；delta_tb: float (s)（映射残差）。
   • geo: { d_ell: float (m), scale_v: float (—), scale_A: float (—) }。
   • fit: { rmse_v: float (m/s), rmse_A: float (m^2), corr_vA: float (—) }。
   • ok: bool；errors: list[str]；provenance: dict。
4. 校准流程摘要
   • 以参考脉冲对齐 ts = alpha + beta * tau_mono；最小化 delta_tb。
   • 准直与比例标定 v、A，输出缩放因子与残差。
   • 生成 provenance（设备 ID、日期、操作者、软件指纹）。

IX. I10-5 emit_metrics_drawing

1. 目的
   汇总并发布第7、8、9、10、11章所需指标，形成标准指标报文 MetricsReport。
2. 签名
   emit_metrics_drawing( state:dict ) -> MetricsReport。
3. 输出 MetricsReport: dict
   • window: { t0: float (s, ts), t1: float (s, ts) }。
   • kinematics: { v_mean: float (m/s), s_mean: float (1/s), lambda_mean: float (—) }。
   • tension: { T_mean: float (N), T_rms: float (N) }。
   • stability: { g_max: float (1/s), r_neck: float (—), stable: bool }。
   • spectrum: { ENBW: float (Hz), var_T: float (N^2), bands: list }。
   • conservation: { eps_mass: float (—), eps_norm: float (—) }。
   • TS: { hb: bool, latency: float (s), bp: float (—), slo_pass: bool }。

X. 并发、调度与可观测性契约

• 因果与心跳
  任何跨线程调用须保持 TS.hb = true；若丢失心跳，I10-1 必须返回 ok=false 并附 E_HB_LOST。
• 背压与限流
  当 TS.bp > bp_max 时，I10-1 可下调 dt 或丢弃非关键谱窗口，状态变更记入 StepReport.policy = "backoff"。
• SLO 与超时
  执行期限 TS.slo.deadline 由第10章设定；违约时将 TS.slo_pass = false 并记录 E_SLO_BREACH。
• 幂等等价类
  以 idem_key 分类幂等等价；重复请求返回缓存的 StepReport 与快照哈希 state.hash@t1。

XI. 错误枚举与严重级别

• E_BC_INVALID（高）：边界条件不完备或矛盾。
• E_DIMENSION_MISMATCH（高）：单位或量纲不一致。
• E_CONSERVATION_FAIL（高）：eps_mass 超阈 gate.mass。
• E_UNSTABLE_STEP（中）：g_max > 0 且 r_neck 超阈。
• E_PARAMS_MISSING（中）：构成参数缺失。
• E_TIMEBASE_UNALIGNED（中）：alpha,beta 未收敛。
• E_HB_LOST（中）：跨线程心跳丢失。
• E_SLO_BREACH（中）：SLO 违约。
• E_SCHEMA_VERSION（低）：schema.version 不受支持。
• 恢复策略
  高：立即中止并转入回退工况；中：降级、缩步长或触发再标定；低：告警并记录。

XII. 参考伪代码与状态机片段

1. 更新状态（离散守恒 + 构成）
   • 计算 J^n = rho^n * A^n * v^n。
   • rho_L^{n+1} = rho_L^{n} - dt * ( d/dell ) ( J^{n} )（迎风或 TVD 格式）。
   • s^{n+1} = ( d/dt ) ( ln( lambda^{n+1} ) )；T_fil^{n+1} = K_el * ( lambda^{n+1} - 1 ) + K_vis * s^{n+1}。
   • 评估 eps_mass，若超阈则记 E_CONSERVATION_FAIL。
   • 调用 compute_instability_metrics 决定 stable 与 E_UNSTABLE_STEP。
2. 失稳评估（谱 + 斜率判据）
   • 以第7章口径计算 S_TT(f)；选取带宽 [f1,f2]，得 gain。
   • 若存在 ( d T_fil / d lambda ) < 0 的空间片段且 gain > gain_thr，则置 r_neck ↑。

XIII. 计量与校核钩子

• 单位校核
  对关键表达执行 check_dim( T_fil ) = N，check_dim( J ) = kg/s，check_dim( S_TT ) = N^2/Hz。
• 报表一致性
  var( T_fil ) 应满足 var( T_fil ) ≈ ∫_{0}^{Fs/2} S_TT(f) df；若偏差超 gate.norm 则在 MetricsReport.flags 加注 "PSD_MISMATCH"。
• 到达时两口径（若涉及）
  必并行发布 T_arr 两口径与 delta_form，并回填到 MetricsReport.arrival.*。

XIV. 接口安全与合规模块

• 指纹与签名
  fingerprint = H( code.digest || data.digest || param.digest || H(alpha || beta) )；sig 存证随 CalReport 与 MetricsReport 发布。
• 数据最小化
  仅输出第9章定义的最小字段集；含个人或设备唯一信息需在 provenance 下脱敏。

XV. 版本迁移与兼容策略

• 新增字段以可空方式发布，旧客户端忽略未知键；破坏性变更使用 api.version 与 schema.version 双轨迁移。
• 迁移门限
  在 Mx-14 benchmark-report 中同时发布新旧口径指标与 d_spec、D_rep 差异，直至 D_rep < D_gate 为止。

XVI. 快速索引与交叉引用

• 与章节对应
  守恒与构成：第3章、 第4章；稳定性：第6章；谱与抖动：第7章；计量与校准：第8章；数据清单：第9章；并行与执行：第10章；误差预算：第11章；基准与标定：第12章；复现与合规：第13章。
• 统一符号
  lambda(x,t)，s(x,t)，v(x,t)，A(x,t)，rho_L(x,t)，J(x,t)，T_fil(x,t)，S_xx(f)，U_w，ENBW，tau_mono，ts，alpha，beta，c_ref，n_eff(x,t)，Re，We，De（见附录A）。