volumential.rke_table_assembly

Certified RKE assembly of fixed-parameter near-field tables.

This module assembles fixed-parameter Helmholtz and Yukawa near-field interaction tables as linear combinations of canonical, parameter-independent channel tables:

• 2D: T(k) = T[Laplace] + c0(k) T[const] + sum_n ( a_n(k) T[r^{2n} log r] + b_n(k) T[r^{2n}] )

• 3D: T(k) = T[Laplace] + sum_n c_n(k) T[r^{n-1}]

with the exact small-argument series coefficients (the same series that defines the private _HelmholtzSplitSeriesRemainderKernel of volumential.wranglers). Yukawa uses the principal-branch substitution k = i lam, under which the assembled table is real.

Every channel integrand is elementary (powers and log), so all channel tables build through the batched (parallel) Duffy path; no special-function quadrature is needed. The channel family is parameter independent: once built and cached, any further parameter costs only coefficient evaluation and a linear combination over the symmetry-reduced entries.

The truncation order is chosen from the requested tolerance via an explicit majorant of the omitted series tail on the near-field separation region, and the returned certificate records that bound together with the numerically computed \(L^1\) norms of the source basis functions that convert the kernel-space bound into a table-entry bound.

Windowed mode

The windowed assembler (assemble_windowed_parameterized_table()) replaces the polynomially growing channels r^{2m} log r / r^{m-1} by Gaussian-windowed channels. It builds exactly p_star of them in either dimension, one per retained order, against the 1 + n (3D) / 2 + 2n (2D) tables the classical family needs for n retained terms – each 2D term contributing both an r^{2n} and an r^{2n} log r channel. The channels are

• 2D: chi_m(r) = (1/2) (r^2/4)^m Gamma(-m, x)

• 3D: chi_m(r) = (1/(2 sqrt(pi))) (r^2/4)^(m-1/2) Gamma(1/2-m, x)

with x = r^2 / (4 t_w) and window scale t_w = (b / Theta)^2 for source-box extent b and the single design declaration Theta (window_theta). The channels carry the kernels’ full singular germs but die off beyond r ~ b / Theta. Internally, tables store the normalized channels psi_m = chi_m / t_w^m and pair them with coefficients (-zeta t_w)^m / m!. Their magnitude is bounded by |zeta t_w|^m / m! = (theta/Theta)^{2m}/m! for every covered squared-frequency parameter zeta (zeta = lam^2 for Yukawa, zeta = -k^2 for Helmholtz, complex zeta for damped waves), so neither factor carries the opposing t_w^m scaling that overflows or underflows before their product does.

The online part is the smooth remainder R = G - sum_{m<p_star} ((-zeta t_w)^m/m!) psi_m, evaluated pointwise from the kernel and the closed channel forms and integrated against the source modes by a tensor-product Gauss-Legendre rule. Because R is defined as the exact difference, the assembly has no series truncation anywhere: the certificate’s truncation_tail_bound is structurally 0.0, and the only error terms are the two already-owned quadrature kinds (singular channel quadrature and smooth remainder quadrature). The channel family depends on the declaration Theta only — never on the swept kernel parameter — so one cached family serves every theta = parameter * b up to Theta.

volumential.rke_table_assembly.WINDOW_COVERAGE_RELATIVE_TOLERANCE = 1e-12

Relative slack on the declared-window coverage test. The declaration certifies the closed disk |zeta| <= (Theta/b)**2, so a local theta exactly at Theta must be accepted; this absorbs the rounding of parameter * root_extent * 0.5**level, and nothing more. Exported because a consumer that decides whether a refusal was legitimate has to use the same boundary the assembler refused on – a looser one turns a correct out-of-window refusal into a reported gate failure.

exception volumential.rke_table_assembly.RKETruncationError

Bases: ValueError

The series tail majorant never falls below the requested tolerance.

refusal_kind = 'uncertifiable'

exception volumential.rke_table_assembly.RKEConditioningError

Bases: RuntimeError

Float64 recombination of the assembly is not certifiably conditioned.

refusal_kind = 'ill-conditioned'

exception volumential.rke_table_assembly.RKEWindowCoverageError

Bases: ValueError

The squared-frequency parameter lies outside the declared window.

refusal_kind = 'outside-window'

exception volumential.rke_table_assembly.RKEWindowConditioningError

Bases: RuntimeError

Windowed recombination is not certifiably conditioned.

refusal_kind = 'ill-conditioned'

volumential.rke_table_assembly.choose_truncation_order(dim: int, k: complex, radius: float, tolerance: float, max_terms: int = 60) → tuple[int, float]

Smallest series order whose tail majorant is below tolerance.

Returns (n_terms, tail_bound); raises RKETruncationError if max_terms is not enough.

volumential.rke_table_assembly.assemble_parameterized_table(queue: Any, cache_path: str | Path, dim: int, kernel_type: str, q_order: int, parameter: float, *, source_box_level: int = 0, root_extent: float = 2.0, tolerance: float = 1e-12, max_terms: int = 60, max_condition: float = 1000000.0, build_config: Any = None, force_channel_recompute: bool = False) → tuple[Any, dict[str, Any]]

Assemble a fixed-parameter near-field table from canonical channels.

Parameters:

• kernel_type – "Helmholtz" (outgoing, k = parameter) or "Yukawa" (lam = parameter).

• tolerance – certified absolute kernel-space truncation tolerance on the near-field separation region; the certificate also reports the induced per-entry bound.

• force_channel_recompute – rebuild the channel tables even when the cache already holds them. Cached channels are otherwise returned as stored, regardless of the build_config requested on this call, so pass True after tightening the quadrature configuration for an existing cache.

Returns:

(table, certificate) where table is a NearFieldInteractionTable equivalent to a direct fixed-parameter build up to the certified bound, and certificate is a dict of the assembly provenance.

volumential.rke_table_assembly.windowed_channel_profile(dim: int, m: int, window_scale: float) → Callable[[Any], Any]

Radial profile chi_m(r) of the physical windowed channel.

Defined by the generalized exponential-integral recurrences

• 2D: y_0(x) = E_1(x), y_m = (exp(-x) - x y_{m-1}) / m, chi_m = (1/2) t_w^m y_m

• 3D: z_0(x) = sqrt(pi) erfc(sqrt(x)) / sqrt(x), z_m = (exp(-x) - x z_{m-1}) / (m - 1/2), chi_m = t_w^{m-1/2} z_m / (2 sqrt(pi))

with x = r^2 / (4 t_w) and t_w = window_scale; equivalently chi_m = (1/2)(r^2/4)^m Gamma(-m, x) in 2D and chi_m = (r^2/4)^{m-1/2} Gamma(1/2-m, x) / (2 sqrt(pi)) in 3D. chi_0 in 3D is exactly the Ewald short-range kernel erfc(r / (2 sqrt(t_w))) / r. Evaluation uses SciPy’s stable integer-order expn in 2D and a direct continued fraction for the large-x half-integer integral in 3D, avoiding cancellation in the displayed upward recurrences.

Returns:

a vectorized callable chi(r) accepting scalars or arrays.

volumential.rke_table_assembly.windowed_remainder_profile(dim: int, zeta: complex, kernel_radial: Callable[[Any], Any], window_scale: float, p_star: int) → Callable[[Any], Any]

Radial profile of the exact windowed remainder

R(r) = G(r) - pref * sum_{m < p_star} ((-zeta*t_w)^m / m!) psi_m(r)

with psi_m = chi_m / t_w**m, pref = 1/(2 pi) in 2D, and pref = 1/(4 pi) in 3D. This is algebraically identical to the physical-channel sum while keeping both factors representable. It is exactly the smooth part the windowed assembler integrates, so tests can certify the coefficient/prefactor/sign conventions queue-free by probing R directly (boundedness and germ cancellation as r -> 0). At r = 0 the callable returns the analytic removable limit for the decaying Yukawa / outgoing Helmholtz branch instead of evaluating the two singular terms separately. zeta = 0 is rejected because this API does not define a zero-frequency kernel normalization or its origin limit.

Returns:

a vectorized callable R(r) (complex-valued).

volumential.rke_table_assembly.get_windowed_channel_table(cache_path: str | Path, dim: int, q_order: int, m: int, *, source_box_level: int = 0, root_extent: float = 2.0, window_theta: float = 16.0, chan_regular_order: int | None = None, chan_radial_order: int | None = None, force_recompute: bool = False) → Any

Build or load the normalized windowed channel table psi_m.

The channel family depends on the declaration window_theta (and the table geometry) only — never on any swept kernel parameter — and the cache key preserves that invariant. Channel data is stored per channel in .npz files under str(cache_path) + ".windowed/" keyed by (schema, normalization, dim, q_order, source_box_level, root_extent, window_theta, m, chan_regular_order, chan_radial_order). A load validates the full key, symmetry-reduced entry IDs, and a checksum over the IDs and values before accepting cached data. Any unreadable, stale, or corrupted file is rebuilt and atomically replaced, with the discard reason logged as a warning on this module’s logger.

chan_regular_order / chan_radial_order default (via None) to the tested per-dimension orders of _resolve_channel_orders (48/61 in 2D, 20/61 in 3D); orders the underlying node builders would silently ignore are refused by _validate_channel_orders.

Every table handed back — freshly built or loaded from cache — passes _check_channel_table_values, so a channel that violates the analytic entry bound can never reach the recombination (where a single blown-up channel would dominate both the peak sum and the assembled maximum, leaving the reported condition number at a reassuring 1.0). The private _windowed_cache_disposition attribute is "hit" only after a fully validated load and "rebuilt" after fresh or recovery construction.

volumential.rke_table_assembly.assemble_windowed_parameterized_table(cache_path: str | Path, dim: int, kernel_type: str, q_order: int, parameter: float, *, source_box_level: int = 0, root_extent: float = 2.0, window_theta: float = 16.0, p_star: int = 6, smooth_quad_order: int | None = None, max_condition: float = 1000000.0, chan_regular_order: int | None = None, chan_radial_order: int | None = None, force_channel_recompute: bool = False) → tuple[Any, dict[str, Any]]

Assemble a fixed-parameter near-field table from windowed channels.

Parameters:

• kernel_type – "Helmholtz" (outgoing, k = parameter) or "Yukawa" (lam = parameter).

• window_theta – the declaration Theta; the local parameter theta = parameter * b (with b the source-box extent) must not exceed it.

• p_star – number of tabulated windowed channels.

• smooth_quad_order – Gauss-Legendre points per axis for the smooth remainder; defaults to max(16, 2 q_order, ceil(theta/2) + 16, ceil(1.25 window_theta) + 8) — a Nyquist-style term for the kernel oscillation plus a declaration-scaled term for the windowed-channel transition features (width b/Theta) inside the remainder.

• chan_regular_order – angular (2D) / tail (3D) Gauss order of the one-time singular channel quadrature; None selects the tested per-dimension default (48 in 2D — the high-aspect Duffy triangles of edge-adjacent 2D interpolation nodes converge slowly in this order — and 20 in 3D). chan_radial_order (radial tanh-sinh order) defaults to 61 in both dimensions.

Returns:

(table, certificate) with table a NearFieldInteractionTable (complex128 for Helmholtz, float64 for Yukawa) whose kernel identity is nulled exactly like the classical assembler’s, and certificate a dict of the assembly provenance.

volumential.rke_table_assembly.damped_kernel_radial(dim: int, zeta: complex) → Callable[[Any], Any]

Radial kernel profile for a complex squared frequency zeta, with the module’s square-root branch contract.

The selected root mu = sqrt(zeta) is the decaying branch (Re mu > 0), continued to the outgoing lower-half-plane limit mu = -i k on the negative real axis, exactly as in windowed_remainder_profile() (both call the same selector). The kernel is

• 2D: K_0(mu r) / (2 pi), which on the negative ray equals the outgoing Helmholtz kernel (i/4) H_0^(1)(k r) through the exact continuation K_0(-i z) = (i pi / 2) H_0^(1)(z);

• 3D: exp(-mu r) / (4 pi r).

zeta must be finite and nonzero (this API does not define a zero-frequency kernel normalization).

Returns:

a vectorized complex-valued callable g(r).

volumential.rke_table_assembly.assemble_windowed_damped_table(cache_path: str | Path, dim: int, q_order: int, zeta: complex, *, source_box_level: int = 0, root_extent: float = 2.0, window_theta: float = 16.0, p_star: int = 6, smooth_quad_order: int | None = None, max_condition: float = 1000000.0, chan_regular_order: int | None = None, chan_radial_order: int | None = None, force_channel_recompute: bool = False) → tuple[Any, dict[str, Any]]

Assemble a fixed-parameter table at a damped complex frequency.

zeta is the complex squared frequency; the supported coverage is the punctured closed disk 0 < |zeta| <= (Theta / b)**2 (b the source-box extent), uniformly over the phase — the conditioning certificate depends on |zeta| only. The kernel profile is damped_kernel_radial(), so the branch convention is pointwise consistent with the windowed remainder: the Yukawa ray (zeta > 0) reproduces assemble_windowed_parameterized_table() with kernel_type="Yukawa" and the negative ray (zeta < 0) the outgoing Helmholtz assembly, both through the identical channel family (the channels are real and depend only on the declaration Theta). zeta = 0 is rejected.

Returns:

(table, certificate) with a complex128 table; the certificate additionally records zeta_phase_fraction (arg(zeta) / pi in (-1, 1]).