09-EFT.WP.Core.Density v1.0 | Appendix E — Interface Reference (I90)

Home ／ Docs-Technical WhitePaper ／ 09-EFT.WP.Core.Density v1.0

Appendix E — Interface Reference (I90)

I. Scope and Unified Conventions

• This appendix specifies the interface family I90-* for the Density volume: function signatures, shared data types, and metadata contracts spanning P91-*, S92-*, and Mx-9*. Every integral must explicitly state its measure and domain; any path-dependent quantity must explicitly provide gamma(ell) and d ell. Probability densities must satisfy ∫ p(x) dx = 1; physical totals must obey M = ( ∫ rho dV ) with dimensional consistency.
• Inputs and outputs consistently use inline code marks for symbols such as rho(x,t), p(x), kde_h(x), S_xx(f), U_w, ENBW_Hz, T_arr, delta_form. Returned objects must carry ref_eqn linking back to the relevant S92-* and Mx-9* items.

II. Shared Data Types & Metadata (I90-T)

1. Common header fields (present on all Ref objects)
   • id: globally unique within the implementation (string)
   • type: object kind (MeasRef | DensRef | PdfRef | IntensRef | HawkesRef | SpecRef)
   • measure: handle/descriptor of the measure definition (see I90 1)
   • domain: domain & boundary (coordinate frame, grid/path, gamma(ell) if applicable)
   • units: unit string (e.g., kg/m^3, 1, Hz^-1)
   • dim: dimensional information (e.g., (Nx,Ny,Nz) or R^d)
   • meta: free-form metadata (e.g., created_at, algorithm, window)
   • ref_eqn: linked formula identifiers (e.g., ["S92-5","S92-6"])
   • provenance: lineage (input hashes, software versions, RNG seeds)
   • checks: quality-gate results (booleans and metrics per the mapped Mx flows)
   • delta_form: two-form disparity for arrival-time alignment if applicable; None otherwise
2. Type-specific payloads
   • MeasRef: space, metric, base (e.g., "lebegue"), differentials (e.g., ["dx","dV","dS","d ell"])
   • DensRef: field_name, rho_grid or rho_func, mass = ( ∑ rho_i V_i )
   • PdfRef: family, params or samples_hash, normalized=True|False
   • IntensRef: lambda_grid | lambda_func, events_hash
   • HawkesRef: mu, kernel (e.g., exp) with parameters, branching_ratio = ( ∫ H dt )
   • SpecRef: fs, window, U_w, ENBW_Hz, one_sided=True|False

III. I90 1 — Density Objects and Measures

1. define_measure(space:str, metric:str|None=None, base:str="lebegue") -> MeasRef
   • Purpose: declare the measure and metric structure, enforcing P91-1.
   • Inputs:
     1. space: "R" | "R^d" | "grid:cartesian" | "path:gamma"
     2. metric: "euclidean" | "geodesic:..." or None
     3. base: "lebegue" or another supported base measure
   • Output: MeasRef containing differentials and unit conventions
   • Quality gate: checks.measure_explicit=True; ref_eqn=["P91-1"]
2. density_from_field(field:any, units:str) -> DensRef
   • Purpose: bind a discrete/analytic field as a physical density.
   • Preconditions: an existing MeasRef; declared domain and voxel volumes V_i.
   • Output: DensRef with mass = ( ∑ rho_i V_i ) aligned to S92-2.
   • Quality gate: checks.mass_finite=True.

IV. I90 2 — Probability Densities & Estimation

1. pdf_fit(data:any, family:str, init:dict|None=None) -> PdfRef
   • Purpose: fit a parametric p(x|theta); ref_eqn=["S92-3","S92-4"].
   • Output: PdfRef with params, logL_max, I_F(theta) if available.
   • Quality gate: checks.normalized = ( | ∫ p dx - 1 | < tol ).
2. kde_build(data:any, kernel:str="gaussian", h:float|None=None, rule:str|None=None) -> PdfRef
   • Purpose: build kde_h(x) (S92-5) and report an AMISE proxy (S92-6).
   • Key metadata: K, h, rule ("silverman"|"scott"|"cv") and CV(h).
   • Quality gate: checks.report_h=True, checks.bias_var_reported=True.
3. kde_eval(pdf:PdfRef, x:any, normalize:bool=True) -> array
   • Purpose: evaluate kde_h(x) at user points; optional renormalize.
   • Output: array matching the shape of x.
   • Quality gate: checks.enforce_normalization = normalize.

V. I90 3 — Spatial & Spatio-temporal Intensity

1. intensity_estimate(points:any, kernel:str, h:float, domain:any) -> IntensRef
   • Purpose: estimate lambda(x) or lambda(x,t); ref_eqn=["S92-7"].
   • Boundary handling: specify domain and edge correction (reflection/truncation/satellite).
   • Quality gate: checks.Lambda_A validates ( ∫_A lambda dV ) vs. observed counts.
2. hawkes_fit(events:any, kernel:str="exp", opts:dict|None=None) -> HawkesRef
   • Purpose: fit Hawkes intensity lambda = mu + ( ∑ H * events ).
   • Metadata: kernel_params, branching_ratio = ( ∫ H dt ), stability requires branching_ratio < 1.
   • Quality gate: checks.branching_ratio_ok=True.

VI. I90 4 — Histograms & Discretization

1. bin_edges(domain:any, rule:str="fd") -> array
   • Purpose: produce bin boundaries (FD, Scott, Sturges, …).
   • Output: monotone array of length B+1; Delta may be variable/adaptive.
   • Quality gate: checks.monotone_edges=True.
2. hist_density(data:any, edges:any, normalize:bool=True) -> PdfRef
   • Purpose: histogram density p_hat[j] = count[j] / ( N * Delta_j ) (S92-10).
   • Quality gate: checks.sum_to_one = ( ∑ p_hat[j] * Delta_j ≈ 1 ).

VII. I90 5 — Transforms, Conservation & Normalization

1. change_of_variables(pdf:PdfRef, mapping:any, jacobian:any) -> PdfRef
   • Purpose: apply p_Y(y) = p_X( x(y) ) * | det( ∂x/∂y ) | (S92-15).
   • Quality gate: checks.jacobian_provided=True, checks.normalized_after=True.
2. conserve_mass(dens:DensRef, flow:any, source:any|None=None) -> DensRef
   • Purpose: numerically advance ∂_t rho + ∇•J = s (S92-1), preserving S92-2.
   • Output: updated DensRef with mass_before/after and boundary flux report.
   • Quality gate:
     checks.mass_balance = ( | M_after - M_before + outflux - inflow - ∫ s dV | < tol ).
3. renormalize(pdf:PdfRef, domain:any) -> PdfRef
   • Purpose: enforce normalization on a finite domain.
   • Quality gate: checks.normalized=True.

VIII. I90 6 — Spectra & Energy Density (reuses Core.Sea interface norms)

1. spectral_density(sig:any, method:str="welch", window:str="hann") -> SpecRef
   • Purpose: estimate one- or two-sided S_xx(f); report U_w (S92-9) and ENBW_Hz (S92-8).
   • Metadata: fs, nperseg, noverlap, detrend, one_sided.
   • Quality gate: checks.energy_consistency = ( ∫ S_xx df ≈ var(x) ).
2. spec_to_energy(spec:SpecRef, band:any) -> float
   • Purpose: integrate energy over a band.
   • Output: E_band = ( ∫_{band} S_xx(f) df ).
   • Quality gate: checks.band_within_nyquist=True.

IX. I90 7 — Uncertainty & Bounds

1. fisher_information(pdf:PdfRef, theta:dict) -> matrix
   • Purpose: compute I_F(theta) (S92-16).
   • Quality gate: checks.psd_matrix ensures I_F >= 0 (PSD).
2. crlb(pdf:PdfRef, theta:dict) -> matrix
   • Purpose: return I_F(theta)^{-1} as a covariance lower bound (S92-17).
   • Quality gate: checks.invertible_or_pseudo=True (falls back to pseudoinverse with warning).

X. I90 8 — Metadata & Alignment

1. bind_to_parameters(ds:any, params:list[str]) -> bool
   • Purpose: bind datasets to parameter names for uncertainty propagation.
   • Result: True on success; records meta.params.
2. bind_to_equations(eqn_refs:list[str]) -> bool
   • Purpose: bind objects to S92-* and Mx-9* references for auditability.
   • Result: True on success; populates ref_eqn.
3. enforce_arrival_time_convention(trace:any) -> None
   • Purpose: mandate recording of both arrival-time forms and their disparity:
     1. Constant-pulled: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
     2. Path-wise: T_arr = ( ∫ ( n_eff / c_ref ) d ell )
     3. Disparity: delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |
   • Action: writes both forms and delta_form into trace.meta.arrival_time with a timestamp.

XI. Quality Gates & Auto-Audit (Mx mappings)

• Mx-91 conservation check: DensRef.checks.mass_balance, boundary flux and source/sink closure (S92-1/2)
• Mx-92 sample→parameter→density: PdfRef.checks.normalized, publish I_F and logL_max (S92-3/4)
• Mx-93 bandwidth selection: report K(•), h, CV(h), AMISE proxy (S92-5/6)
• Mx-95 spectrum→energy reconciliation: SpecRef.checks.energy_consistency (S92-8/9)
• Mx-96 grid refine/coarsen: mass_preserve = ( ∑ rho_i V_i ) constant (S92-11)
• Mx-97 regularization parameter search: objective value, KKT residuals, AIC/BIC (S92-12/13)
• Mx-98 multi-source alignment: delta_form recorded and propagated (two-form arrival time; S92-15 transform optional)

XII. Errors & Return Codes (suggested)

• E90-01 measure undeclared (violates P91-1)
• E90-02 unit inhomogeneity (violates P91-2)
• E90-03 probability not normalized (|∫ p dx - 1| > tol)
• E90-04 mass non-conservation (|ΔM - flux - ∫ s dV| > tol)
• E90-05 missing or singular Jacobian (S92-15)
• E90-06 non-monotone bin edges or out-of-range bins
• E90-07 branching_ratio >= 1 (unstable Hawkes)
• E90-08 band out of Nyquist or inconsistent PSD convention
• E90-09 Fisher information non-invertible (pseudoinverse taken with warning)

XIII. Serialization & Exchange

• Required keys: type, units, domain, measure, ref_eqn, provenance, checks.
• Arrays use row-major layout; grids use shape=(Nz,Ny,Nx) with spacing=(dz,dy,dx).
• Float fields should carry dtype and scale (e.g., 1e-6) to limit storage jitter.

XIV. Reproducibility Conventions

• Stochastic interfaces record RNG seed, library lib, version ver, and thread count: provenance.rand = {seed:int, lib:str, ver:str}.
• Numerical integration reports integrator and tolerances: integrator="trapz|simpson|ode45-like", atol, rtol.

XV. Minimal End-to-End Example (Interface Chain)

• Define measure & load a field
• m = define_measure("grid:cartesian","euclidean","lebegue")
• dens = density_from_field(field=rho_grid, units="kg/m^3")

Quality: ∑ rho_i V_i reported into dens.mass (S92-2).

• Histogram PDF & KDE side-by-side
• 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") # S92-5/6
• kde_eval(k_pdf, x)
• Change of variables & normalization
• pY = change_of_variables(h_pdf, mapping=x_of_y, jacobian=abs_det_dxdy) # S92-15
• pY = renormalize(pY, domain=[ymin,ymax])
• Spectrum & energy reconciliation
• spec = spectral_density(sig, method="welch", window="hann") # S92-8/9
• spec_to_energy(spec, band=[f1,f2])

Verify ∫ S_xx df ≈ var(x).

• Record both arrival-time forms
• enforce_arrival_time_convention(trace) # stores both T_arr forms and delta_form
• Information bounds
• I = fisher_information(k_pdf, theta=params) # S92-16
• B = crlb(k_pdf, theta=params) # S92-17

XVI. Versioning & Deprecation

• Interfaces follow semantic versioning I90.major.minor.patch; breaking changes only at a major bump.
• Deprecated fields carry deprecated_since at a minor release and remain for at least two subsequent minors.
• ref_eqn and checks are mandatory; absence constitutes E90-01.

XVII. Pre-Publish Validation Checklist

• Measure explicitness and unit homogeneity (P91-1/2); probability and mass normalization closure (S92-2, S92-10).
• KDE reports K(•), h, CV(h), and an AMISE proxy (S92-5/6).
• PSD reports U_w, ENBW_Hz, side convention, and energy reconciliation (S92-8/9).
• Variable transforms include the Jacobian (S92-15); CRLB invertibility handled (S92-17).
• Any arrival-time alignment records both forms and delta_form, and persists the path gamma(ell) (cross-volume anchor).