09-EFT.WP.Core.Density v1.0 | 附录B 数据与网格格式

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

附录B 数据与网格格式

I. 范围与对象类型

• 本附录定义密度卷的数据容器、网格与坐标、频时轴、元数据与校准字段，覆盖规则网格、非规则网格、点事件、谱对象与概率密度容器。
• 一切数组按 0 起始索引；除非显式声明，默认行优先存储（row-major），测度采用 lebegue 基测度；所有变量与单位、量纲遵循附录A。

II. 域、坐标与测度

• 连续域 D ⊂ R^d 上的测度为 mu，体元为 dV，曲线测度为 d ell。凡积分写作 ( ∫_D · dV ) 或沿路径 ( ∫_gamma · d ell )。
• 规则轴映射：x_i = x0 + i * Delta_x，y_j = y0 + j * Delta_y，z_k = z0 + k * Delta_z，时间 t_n = t0 + n * Delta_t，频率 f_m = m * ( fs / N )。
• 非均匀轴以坐标数组存放：x_coords[i]、t_coords[n]；积分需配套权重 w_i 以近似 ( ∫ g(x) dx ) ≈ ( ∑ g(x_i) * w_i )。

III. 规则网格（Raster/Voxel）

1. 几何字段
   • origin = (x0, y0, z0)；spacing = (Delta_x, Delta_y, Delta_z)；shape = (Nx, Ny, Nz)；axis_order = ("x","y","z")。
   • cell_centered = true|false（若为 true，则物理坐标为 x_i + 0.5 * Delta_x 等）。
2. 体素体积与守恒
   • V_cell = ( Delta_x * Delta_y * Delta_z )（缺维度时省略相应因子）。
   • 离散总量：mass_preserve = ( ∑ rho[i,j,k] * V_cell )，须与连续表达 S92-2 : M = ( ∫ rho dV ) 一致（见第2章）。
3. 边与中心的选择一致性
   边界数组 edges_x[0..Nx]、edges_y[0..Ny]、edges_z[0..Nz] 可选；若提供 edges_*，以其定义 Delta 与 V_cell 为准。

IV. 非规则网格（Mesh/Unstructured）

1. 拓扑与几何
   • nodes : float64[NumNodes, dim]；cells : int32[NumCells, k]；cell_type : enum{tri, quad, tet, hex, poly}。
   • 每单元局部雅可比 J_cell 用于变量变换与守恒：p_Y(y) = p_X(x(y)) * | det( ∂x/∂y ) |（见第9章 S92-15）。
2. 单元测度与积分
   dV_cell[c] = ( ∫_{cell c} 1 dV )；离散积分 ( ∫_D rho dV ) ≈ ( ∑_c rho_c * dV_cell[c] )。
3. 字段插值位置
   sample_location = {"cell","node"}；需与数值算子（如 ∇·J）的离散格式一致（见第2章）。

V. 时间与频率轴

1. 时间轴
   • t 单位 s；Delta_t 必报；如采用到达时校准，记录 T_arr_form = {"constant-pulled","path-wise"} 与
     delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |（见全书统一约定）。
   • 异步/丢样以 time_mask[n] 或 valid_time_intervals 指示；与《Core.Threads》第3章时基一致。
2. 频率轴与谱对象
   • S_xx(f) 存为单侧 PSD，f ∈ [0, fs/2]；同时记录 fs、window、U_w = ( 1 / N ) * ∑ w[n]^2、ENBW_Hz = fs * ( ∑ w[n]^2 ) / ( ∑ w[n] )^2、有效自由度 nu（见第6章）。
   • 能量一致性校核：var(x) ≈ ( ∫_0^{fs/2} S_xx(f) df )，以 Mx-95 报告偏差。

VI. 概率密度与直方图容器

1. 直方图密度
   • 字段：edges、counts、N、Delta、normalize=true|false。
   • 估计：p_hat = count / ( N * Delta )（S92-10）；存储 p_hat 时必须记录 Delta 或 edges。
2. 核密度估计
   • 字段：kde_values、grid、K、h、rule、CV(h)；估计公式 S92-5 与误差指标 S92-6 需在元数据中引用。
   • 多维 KDE 的 grid 以张量网格或样本点列存放，并指明测度 dx、dy… 以确保归一化 ∫ p(x) dx = 1。

VII. 空间/时空强度与事件表

1. 事件表（适用于 Poisson/Hawkes）
   • 列：x,y,z,t,weight,channel,id；可选 meta 字段存放来源与置信度。
   • 强度估计容器：lambda_grid（规则网格）或 lambda_mesh（非规则单元），单位与 lambda(x,t) 对齐（见第5章）。
2. 期望计数与区域
   区域 A 以多边形或体素掩膜表示；报告 Lambda(A) = ( ∫_A lambda dV )（S92-7）。

VIII. 归一化、校准与不确定度元数据

1. 归一化字段
   • scale、shift、mu_x、sigma_x、z_spec = {"none","zscore","minmax","custom"}；若已归一化，保持 unit(x) 与 dim(x) 的映射说明。
   • 变量变换需给出 mapping 与 jacobian 的引用（见接口 change_of_variables；第9章 S92-15）。
2. 到达时与介质
   c_ref、n_eff_model、T_arr_form、delta_form；用于跨域时间对齐（见第9章与《Core.Sea》第8章）。
3. 不确定度
   u（标准不确定度）、u_c、k、cov、CRLB；信息矩阵 I_F(theta) 与其数值评估方法引用 I90 7（见第10章）。

IX. 文件格式与映射建议

1. 基础科学容器
   • HDF5/NetCDF4：按组组织 /grid、/mesh、/signals、/spectra、/pdf、/events、/meta。使用压缩 zlib|zstd|lz4 与按轴分块 chunks = (Nz, Ny, Nx)。
   • Zarr：层级与 HDF5 对齐，便于云端访问；元数据以 zattrs 存放上述字段。
2. 地理栅格
   GeoTIFF：GTModelType、GTRasterType、GeoTransform、EPSG；NoData 与 AREA_OR_POINT 指定为 Area 以匹配 cell-centered 假设。
3. 事件与表格
   • Parquet：列式存储 events；Arrow 类型携带单位与量纲注释。
   • CSV 仅用于小型示例；必须配套同名 *.meta.json 侧车文件记录单位与测度。
4. 轻量数组
   NPY/NPZ：单对象或小批量数组；元数据写入 *.meta.json 或 npz 内部 meta 键。

X. 编码、压缩与数值精度

1. 数值类型
   • 标量场默认 float32（大范围或布尔掩膜外推时用 float64）；计数与索引使用 int32。
   • 端序固定 little-endian；复数谱对象以实部/虚部双通道或 complex64/128 存储并在元数据注明。
2. 压缩与分块
   建议 zstd level=3 或 lz4hc level=5；块大小使单块在 0.5–4 MB；时间轴优先分块以优化流式访问。
3. 量化与缩放
   若采用整数量化，存储 scale_int、offset_int 与 dtype_raw，并在读入时应用 x = scale_int * (raw - offset_int)。

XI. 缺失值、掩膜与质量标识

1. 缺失策略
   • nodata_value、valid_min、valid_max、mask（同维布尔）；频域另存 freq_mask。
   • 质量位图 qflag 采用位域编码：如 bit0=饱和，bit1=插值，bit2=外推。
2. 采样窗口与抗混叠
   时间窗 Delta_t、空间采样间距 Delta_x,Delta_y,Delta_z 与抗混叠滤波参数需在 meta/sampling 下明确（与第7章、附录C 对齐）。

XII. 多分辨率与金字塔

• 对于大尺度栅格，建立金字塔层级 level=L，spacing_L = 2^L * spacing_0，重采样核需记录 resample_K。
• 保持质量守恒：下采样时执行 sum-preserving 聚合以维持 mass_preserve 一致（见 S92-11）。

XIII. 接口绑定（I90）与对象命名

1. 绑定关系
   • I90 1：define_measure 的返回引用写入 /meta/measure。
   • I90 2/4：kde_build、hist_density 的输出存入 /pdf，携带 K、h、CV(h)、edges。
   • I90 3：intensity_estimate、hawkes_fit 输出写入 /intensity 与 /events。
   • I90 6：spectral_density 输出写入 /spectra，并存 ENBW_Hz 与 U_w。
   • I90 7：fisher_information、crlb 输出写入 /uncertainty。
2. 命名规范
   标量场：rho、p、lambda、S_xx；向量/张量在后缀标注分量：J_x,J_y,J_z 或 Sigma_xx,Sigma_xy,…。

XIV. 最小侧车元数据（建议键集）

• 标识：title、uuid、version="DEN-1.0"、created、creator、license、provenance。
• 域与坐标：dim、origin、spacing 或 coords、shape、axis_order、cell_centered、measure="lebegue"。
• 单位与量纲：unit(var)、dim(var)；若归一化：scale、shift、mu_x、sigma_x。
• 采样与窗：fs、window、U_w、ENBW_Hz、nu、one_sided=true。
• 到达时：c_ref、n_eff_model、T_arr_form、delta_form。
• 估计器：K、h、rule、CV(h)；直方图：edges、N、Delta。
• 不确定度：u、u_c、k、cov、CRLB。
• 网格/网片：nodes、cells、cell_type、dV_cell。
• 缺失与质量：nodata_value、mask、qflag、valid_min/max。
• 存储：dtype、endianness="LE"、chunks、compressor。

XV. 一致性与发布自检（Mx-规则）

• Mx-96：离散-连续守恒校核 mass_preserve 与 ( ∫ rho dV ) 偏差低于阈值。
• Mx-95：谱能量核对 var(x) 与 ( ∫ S_xx df ) 偏差与窗 ENBW_Hz 一致。
• Mx-98：多源对齐，变换 p_Y(y) = p_X(x(y)) * | det( ∂x/∂y ) | 已应用且记录。
• KDE 报告中存在 K、h、CV(h)；直方图包含 edges/Delta；点过程有 Lambda(A) 的域定义。
• 到达时字段与两口径差异 delta_form 已给出；单位/量纲检查通过 check_dim(expr)。

XVI. 版本与变更记录

• 数据集版本标识 CL-DEN-YYYYMMDD-###；任何变更需同步更新 /meta/version 与 provenance。
• 结构性变更（新增层级、字段重命名）必须提供迁移脚本与兼容映射表。

本附录为密度卷数据与网格格式的标准化约束，落地实现应严格遵循，并与附录A符号/单位及各章 S92-*、Mx-9*、I90-* 引用保持一致。