09-EFT.WP.Core.Density v1.0 | 附录E 接口参考（I90）

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

附录E 接口参考（I90）

I. 作用域与统一口径

• 本附录定义密度卷实现绑定层 I90-* 的接口、数据类型与元数据契约，贯穿 P91-*、S92-*、Mx-9*。所有积分显式标注测度与域，路径相关量显式给出 gamma(ell) 与 d ell；概率密度满足 ∫ p(x) dx = 1，物理密度总量 M = ( ∫ rho dV ) 按单位齐次性核对。
• 统一入参与出参使用内联反引号标记，如 rho(x,t)、p(x)、kde_h(x)、S_xx(f)、U_w、ENBW_Hz、T_arr、delta_form。返回对象必须携带 ref_eqn 引用 S92-* 与 Mx-9*。

II. 共享数据类型与元数据（I90-T）

1. 通用头部字段（所有 Ref 对象均包含）
   • id：实现内唯一标识（字符串）
   • type：对象类别（MeasRef|DensRef|PdfRef|IntensRef|HawkesRef|SpecRef）
   • measure：测度定义句柄或描述（见 I90 1）
   • domain：域与边界（坐标系、网格/路径、gamma(ell) 如适用）
   • units：单位字符串（如 kg/m^3、1、Hz^-1）
   • dim：维度信息（如 (Nx,Ny,Nz) 或 R^d）
   • meta：键值元数据（含 created_at、algorithm、window 等）
   • ref_eqn：相关公式编号（如 ["S92-5","S92-6"]）
   • provenance：数据血缘（输入数据哈希、软件版本、随机种子）
   • checks：质量门结果（布尔与数值报告，见 Mx 对应流程）
   • delta_form：如涉及到达时对齐则填入两口径差值；否则为 None
2. 类型特定字段
   • MeasRef：space、metric、base（如 "lebegue"）、differentials（如 ["dx","dV","dS","d ell"]）
   • DensRef：field_name、rho_grid 或 rho_func、mass = ( ∑ rho_i V_i )
   • PdfRef：family、params 或 samples_hash、normalized=True|False
   • IntensRef：lambda_grid|lambda_func、events_hash
   • HawkesRef：mu、kernel（如 exp）及其参数、branching_ratio = ( ∫ H dt )
   • SpecRef：fs、window、U_w、ENBW_Hz、one_sided=True|False

III. I90 1 密度对象与测度

1. define_measure(space:str, metric:str|None=None, base:str="lebegue") -> MeasRef
   • 目的：声明测度与度量结构，落实 P91-1。
   • 输入
     1. space：如 "R"|"R^d"|"grid:cartesian"|"path:gamma"
     2. metric：如 "euclidean"|"geodesic:..."；可为 None
     3. base："lebegue" 或其他受支持基测度
   • 输出：MeasRef，包含 differentials 与单位约定
   • 质量门
     checks.measure_explicit=True；ref_eqn=["P91-1"]
2. density_from_field(field:any, units:str) -> DensRef
   • 目的：将场量离散/解析表示绑定为物理密度对象。
   • 前置：提供 MeasRef；声明 domain 与体素体积 V_i
   • 输出：DensRef，含 mass = ( ∑ rho_i V_i ) 对齐 S92-2
   • 质量门：checks.mass_finite=True

IV. I90 2 概率密度与估计

1. pdf_fit(data:any, family:str, init:dict|None=None) -> PdfRef
   • 目的：拟合参数族 p(x|theta)；ref_eqn=["S92-3","S92-4"]
   • 输出：PdfRef，params、logL_max、I_F(theta) 如可得
   • 质量门：checks.normalized = ( | ∫ p dx - 1 | < tol )
2. kde_build(data:any, kernel:str="gaussian", h:float|None=None, rule:str|None=None) -> PdfRef
   • 目的：构造 kde_h(x)（S92-5），并报告 AMISE 代理（S92-6）
   • 关键元数据：K、h、rule（如 "silverman"|"scott"|"cv"）与 CV(h)
   • 质量门：checks.report_h=True、checks.bias_var_reported=True
3. kde_eval(pdf:PdfRef, x:any, normalize:bool=True) -> array
   • 目的：在给定点集评估 kde_h(x)；可选择再归一化 renormalize
   • 输出：数值数组，与输入 x 同形
   • 质量门：checks.enforce_normalization=normalize

V. I90 3 空间与时空强度

1. intensity_estimate(points:any, kernel:str, h:float, domain:any) -> IntensRef
   • 目的：估计 lambda(x) 或 lambda(x,t)；ref_eqn=["S92-7"]
   • 边界：提供 domain 与边界校正策略（反射/截断/卫星点）
   • 质量门：checks.Lambda_A = ( ∫_A lambda dV ) 与事件计数一致性核对
2. hawkes_fit(events:any, kernel:str="exp", opts:dict|None=None) -> HawkesRef
   • 目的：拟合 Hawkes 强度 lambda = mu + ( ∑ H * events )
   • 元数据：kernel_params、branching_ratio = ( ∫ H dt )、稳定性 branching_ratio < 1
   • 质量门：checks.branching_ratio_ok=True

VI. I90 4 直方图与离散化

1. bin_edges(domain:any, rule:str="fd") -> array
   • 目的：生成分箱边界（FD、Scott、Sturges 等）
   • 输出：长度 B+1 的单调数组；Delta 可变或自适应
   • 质量门：checks.monotone_edges=True
2. hist_density(data:any, edges:any, normalize:bool=True) -> PdfRef
   • 目的：输出直方图密度估计 p_hat[j] = count[j] / ( N * Delta_j )（S92-10）
   • 质量门：checks.sum_to_one = ( ∑ p_hat[j] * Delta_j ≈ 1 )

VII. I90 5 变换、守恒与归一化

1. change_of_variables(pdf:PdfRef, mapping:any, jacobian:any) -> PdfRef
   • 目的：实现 p_Y(y) = p_X( x(y) ) * | det( ∂x/∂y ) |（S92-15）
   • 质量门：checks.jacobian_provided=True、checks.normalized_after=True
2. conserve_mass(dens:DensRef, flow:any, source:any|None=None) -> DensRef
   • 目的：数值推进 ∂_t rho + ∇·J = s（S92-1），保持 S92-2
   • 输出：更新后的 DensRef，并报告 mass_before/after 与边界通量
   • 质量门：checks.mass_balance = ( | M_after - M_before + outflux - inflow - ∫ s dV | < tol )
3. renormalize(pdf:PdfRef, domain:any) -> PdfRef
   • 目的：在有限域上强制归一化
   • 质量门：checks.normalized=True

VIII. I90 6 频谱与能量密度（复用《Core.Sea》接口约定）

1. spectral_density(sig:any, method:str="welch", window:str="hann") -> SpecRef
   • 目的：估计单侧或双侧 S_xx(f)；报告 U_w（S92-9）与 ENBW_Hz（S92-8）
   • 元数据：fs、nperseg、noverlap、detrend、one_sided
   • 质量门：checks.energy_consistency = ( ∫ S_xx df ≈ var(x) )
2. spec_to_energy(spec:SpecRef, band:any) -> float
   • 目的：在频带 band 上积分能量
   • 输出：E_band = ( ∫_{band} S_xx(f) df )
   • 质量门：checks.band_within_nyquist=True

IX. I90 7 不确定度与界

1. fisher_information(pdf:PdfRef, theta:dict) -> matrix
   • 目的：计算 I_F(theta)（S92-16）
   • 质量门：checks.psd_matrix = I_F >= 0（半正定）
2. crlb(pdf:PdfRef, theta:dict) -> matrix
   • 目的：返回 I_F(theta)^{-1} 作为 cov 下界（S92-17）
   • 质量门：checks.invertible_or_pseudo = True（奇异时回退伪逆并标注）

X. I90 8 元数据与对齐

1. bind_to_parameters(ds:any, params:list[str]) -> bool
   • 目的：把数据集与参数名表绑定，便于不确定度传播
   • 成功返回 True，并在对象 meta.params 中注册
2. bind_to_equations(eqn_refs:list[str]) -> bool
   • 目的：把对象与 S92-*、Mx-9* 引用绑定，利于稽核
   • 成功返回 True，并填充 ref_eqn
3. enforce_arrival_time_convention(trace:any) -> None
   • 目的：强制记录到达时两口径与差值
     1. 常量外提：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
     2. 一般口径：T_arr = ( ∫ ( n_eff / c_ref ) d ell )
     3. 口径差：delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |
   • 行为：在 trace.meta.arrival_time 写入两口径与 delta_form 并加盖时间戳

XI. 质量门与自动稽核（Mx 映射）

• Mx-91 守恒检查：DensRef.checks.mass_balance、边界通量与源汇闭合（S92-1/2）
• Mx-92 样本→参数→密度：PdfRef.checks.normalized、I_F 与 logL_max 公示（S92-3/4）
• Mx-93 带宽选择：报告 K(·)、h、CV(h) 与 AMISE 代理（S92-5/6）
• Mx-95 谱→能量核对：SpecRef.checks.energy_consistency（S92-8/9）
• Mx-96 网格细化/粗化：mass_preserve = ( ∑ rho_i V_i ) 恒定（S92-11）
• Mx-97 正则参数寻优：目标值、KKT 残差、AIC/BIC（S92-12/13）
• Mx-98 多源对齐：delta_form 写入与流转（到达时两口径，S92-15 变换可选）

XII. 错误与返回码（建议枚举）

• E90-01 未声明测度（违反 P91-1）
• E90-02 单位不齐次（违反 P91-2）
• E90-03 概率未归一（|∫ p dx - 1| > tol）
• E90-04 质量不守恒（|ΔM - flux - ∫ s dV| > tol）
• E90-05 缺失雅可比或奇异（S92-15）
• E90-06 分箱边界非单调或溢界
• E90-07 branching_ratio >= 1（Hawkes 不稳定）
• E90-08 频带越界或 PSD 口径不一致
• E90-09 Fisher 信息不可逆（返回伪逆并置警告）

XIII. 序列化与交换格式

• 最小要求字段：type、units、domain、measure、ref_eqn、provenance、checks
• 数值数组使用行优先布局；网格采用 shape=(Nz,Ny,Nx) 并附 spacing=(dz,dy,dx)
• 所有浮点字段推荐携带 dtype 与 scale（如 1e-6）以减小存储抖动

XIV. 可复现性约定

• 随机过程接口需记录 seed、库版本、线程数；provenance.rand = {seed:int, lib:str, ver:str}
• 数值积分需报告积分器与容差：integrator="trapz|simpson|ode45-like"、atol、rtol

XV. 最小工作示例（跨接口串联）

1. 定义测度与载入场量
   • m = define_measure("grid:cartesian","euclidean","lebegue")
   • dens = density_from_field(field=rho_grid, units="kg/m^3")
   • 质量门：∑ rho_i V_i 报告至 dens.mass（S92-2）
2. 直方图密度与 KDE 对照
   • edges = bin_edges(domain=[xmin,xmax],"fd")
   • h_pdf = hist_density(data, edges, normalize=True)（S92-10）
   • k_pdf = kde_build(data,"gaussian",rule="scott")，kde_eval(k_pdf,x)（S92-5/6）
3. 变量变换与归一化
   • pY = change_of_variables(h_pdf, mapping=x_of_y, jacobian=abs_det_dxdy)（S92-15）
   • pY = renormalize(pY, domain=[ymin,ymax])
4. 频谱与能量核对
   • spec = spectral_density(sig, method="welch", window="hann")（S92-8/9）
   • 验证 ∫ S_xx df ≈ var(x)，再用 spec_to_energy(spec, band=[f1,f2])
5. 到达时两口径记录
   enforce_arrival_time_convention(trace) 写入 T_arr 两口径与 delta_form
6. 信息界
   I = fisher_information(k_pdf, theta=params)；B = crlb(k_pdf, theta=params)（S92-16/17）

XVI. 版本与弃用策略

• 接口采用语义化版本：I90.major.minor.patch；破坏性变更仅在 major 提升时发生
• 弃用字段在 minor 版本标记 deprecated_since，至少保留两个次版本周期
• ref_eqn 与 checks 字段为强制项，缺失视作 E90-01

XVII. 发布前核对清单

• 测度显式与单位齐次（P91-1/2）；概率与质量归一闭合（S92-2、S92-10）
• KDE 报告 K(·)、h、CV(h) 与 AMISE 代理（S92-5/6）
• PSD 报告 U_w、ENBW_Hz、单/双侧口径与能量核对（S92-8/9）
• 变量变换含雅可比（S92-15）；CRLB 的可逆性处置（S92-17）
• 涉及到达时对齐者记录 delta_form 与路径 gamma(ell) 并落盘传递（跨卷锚点）