volumential.table_manager

Near-field interaction tables and the manager that owns them.

Tables are stored in SQLite format and managed through NearFieldInteractionTableManager, which resolves a TableRequest – a KernelSpec plus a TableDiscretization – to a table that is built, loaded from the database, or reconstructed from a symmetry-reduced one.

volumential.table_manager.EXTERNAL_TABLE_BUILD_METHOD = 'ExternalAssembly'

build_method recorded for a table handed to the manager from outside its own builders (see NearFieldInteractionTableManager.register_external_table()).

class volumential.table_manager.KernelSpec(dim: int, kernel_type: str)

Bases: object

What a table is a table of: a dimension and a kernel type name.

dim: int

kernel_type: str

classmethod from_args(dim, kernel_type)

Build a KernelSpec, coercing and validating dim.

class volumential.table_manager.TableDiscretization(q_order: int, source_box_level: int = 0)

Bases: object

How a table is discretized: quadrature order and source box level.

The level is what fixes the source box extent, and therefore the scale a cached table is valid at; see the table-build routing page of the documentation.

q_order: int

source_box_level: int = 0

classmethod from_args(q_order, source_box_level=0)

Build a TableDiscretization, coercing and validating both.

class volumential.table_manager.TableRequest(kernel: KernelSpec, discretization: TableDiscretization)

Bases: object

One table’s identity: a KernelSpec and a TableDiscretization.

This is the key the manager looks a table up by, builds it under, and stores it against, so the properties below are read far more often than the two nested records.

kernel: KernelSpec

discretization: TableDiscretization

classmethod from_args(dim, kernel_type, q_order, source_box_level=0)

Build a TableRequest from the four scalar fields.

property dim

Shorthand for self.kernel.dim.

property kernel_type

Shorthand for self.kernel.kernel_type.

property q_order

Shorthand for self.discretization.q_order.

property source_box_level

Shorthand for self.discretization.source_box_level.

class volumential.table_manager.TableKernelBundle(kernel_func: object, kernel_scale_type: object, sumpy_kernel: object)

Bases: object

The three kernel objects a table build needs, resolved together.

sumpy_kernel is the symbolic kernel the request resolved to (None when the kernel type has no sumpy form), kernel_func the plain callable sumpy_kernel_to_lambda() derived from it for the quadrature, and kernel_scale_type the scaling rule lookups apply when they move an entry from the template box to a real one.

kernel_func: object

kernel_scale_type: object

sumpy_kernel: object

exception volumential.table_manager.UnverifiedBuildRoutingError

Bases: RuntimeError

A cached table’s recorded build routing is refused by strict mode.

class volumential.table_manager.ConstantKernel(dim=None)

Bases: ExpressionKernel

The kernel that is identically one, as a sumpy expression kernel.

Tabulating it gives the plain volume integral of the density over each near-field case, which is what the scale-adjustment and normalizer paths are checked against.

init_arg_names = ('dim',)

has_efficient_scale_adjustment = True

property is_complex_valued

the constant kernel is real.

Type:

False

adjust_for_kernel_scaling(expr, rscale, nderivatives)

Divide expr by rscale.

The sumpy hook that rescales a term for a box of radius rscale; has_efficient_scale_adjustment above is what advertises that this kernel implements it.

mapper_method = 'map_expression_kernel'

The name of the mapper method called for the kernel.

class volumential.table_manager.CahnHilliardKernel(dim: int | None = None, b: complex = 0j, c: complex = 0j)

Bases: ExpressionKernel

The 2D Cahn-Hilliard kernel as a sumpy expression kernel.

With \(\lambda_1^2\) and \(\lambda_2^2\) the two roots of \(\lambda^2 - b\lambda + c\), the kernel is

\[-\frac{1}{2\pi(\lambda_1^2 - \lambda_2^2)} \bigl( K_0(\lambda_1 r) - K_0(\lambda_2 r) \bigr),\]

written in the Hankel form \(K_0(z) = \tfrac{\pi}{2} \mathrm{i}\, H^{(1)}_0(\mathrm{i}z)\) that sumpy’s Bessel callables provide.

The constructor rejects near-degenerate coefficients, and the test is an absolute one: \(\lvert \lambda_1^2 - \lambda_2^2 \rvert < 10^{-15}\) raises, which catches coincident roots and also genuinely distinct roots whose separation is that small in absolute terms – at coefficient scales near \(10^{-16}\), say, where no pair of distinct roots passes.

init_arg_names = ('dim', 'b', 'c')

property is_complex_valued

the Hankel form above is complex even for real b, c.

Type:

True

prepare_loopy_kernel(loopy_knl)

Register sumpy’s Bessel callables on loopy_knl.

Without them the generated code has no hankel_1 to call.

mapper_method = 'map_expression_kernel'

The name of the mapper method called for the kernel.

class volumential.table_manager.NearFieldInteractionTableManager(dataset_filename='nft.hdf5', root_extent=1, dtype=<class 'numpy.float64'>, read_only='auto', **kwargs)

Bases: object

A class that manages near field interaction table computation and storage.

Tables are stored in an SQLite database and keyed by (dimension, kernel_type, quadrature order, source_box_level).

Only one table manager can exist for a dataset file with write access. The access can be controlled with the read_only argument. By default, the constructor tries to open the dataset with write access, and falls back to read-only if that fails.

get_table(dim, kernel_type, q_order, source_box_level=0, force_recompute=False, queue=None, **kwargs)

Primary user interface. Get or build a cached table.

get_table_from_request(table_request, force_recompute=False, queue=None, **kwargs)

Get or build a table using a volumential.table_manager.TableRequest.

load_saved_table(dim, kernel_type, q_order, source_box_level=0, **kwargs)

Load a table saved in the SQLite cache.

load_saved_table_from_request(table_request, **kwargs)

Load a cached table using a volumential.table_manager.TableRequest.

get_kernel_function(dim, kernel_type, **kwargs)

Return a numerical kernel callable derived from a sumpy kernel.

get_sumpy_kernel(dim, kernel_type, **kwargs)

Sumpy (symbolic) version of the kernel.

get_kernel_function_type(dim, kernel_type)

Determines how and to what extend the table data can be rescaled and reused.

compute_and_update_table(dim, kernel_type, q_order, source_box_level=0, cl_ctx=None, queue=None, **kwargs)

Performs the precomputation and stores the results.

compute_and_update_table_for_request(table_request, cl_ctx=None, queue=None, **kwargs)

Build/update a cached table using a volumential.table_manager.TableRequest.

register_external_table(dim, kernel_type, q_order, table, source_box_level=0, provenance=None, **kwargs)

Register an externally assembled table for a cache slot.

Stores a built NearFieldInteractionTable (for example the product of volumential.rke_table_assembly.assemble_windowed_parameterized_table()) under the standard (dim, kernel_type, q_order, source_box_level) cache slot, so that subsequent get_table() calls load and apply it exactly like a direct-built fixed-parameter table. As for direct builds, the kernel parameter itself (e.g. lam or k) is carried in the stored scalar kwargs and validated on load, so a load request with a different parameter value misses the cache instead of silently returning the wrong table.

The stored payload keeps the table’s compact symmetry-reduced (ORBIT) representation and carries a content checksum over the entry IDs and values that is verified on every load; the record’s build method is EXTERNAL_TABLE_BUILD_METHOD, so the provenance remains distinguishable from a DuffyRadial build.

Parameters:

• table – a built table whose geometry (dimension, quadrature order, source-box extent for the requested level under this manager’s root extent) matches the requested slot.

• provenance – optional dict of scalar provenance entries (e.g. certificate fields); stored as provenance_<key> kwargs.

• kwargs – stored alongside the record like build kwargs; must include the kernel parameters the slot’s kernel type requires (validated exactly as on load).

Returns:

the normalized TableRequest of the stored slot.