volumential.orbit_arithmetic

Arithmetic ORBIT addressing for near-field interaction tables.

This module owns the arithmetic (closed-form) variant of the ORBIT table compression scheme. Instead of storing an explicit orbit lookup table, it derives, per interaction case, an axis permutation, an axis sign pattern and an axis grouping from the case vector alone. Entry addresses can then be computed with integer arithmetic both on the host and inside the generated List 1 OpenCL kernel.

The public entry points are build_arithmetic_case_metadata(), which builds the per-case descriptor arrays a table needs, and enumerate_scalar_arithmetic_representatives(), which lists the full-table entry id of every compact orbit representative.

volumential.orbit_arithmetic.build_arithmetic_case_metadata(table, arithmetic_symmetry: dict[str, Any] | None = None) → dict[str, Any] | None

Build the per-case arithmetic ORBIT descriptors for table.

Parameters:

• table – A NearFieldInteractionTable from volumential.nearfield_potential_table.

• arithmetic_symmetry – Optional kernel symmetry description, as returned by the kernel analysis in the expansion wrangler. None requests the symmetry-free (scalar) descriptors.

Returns:

A dict of descriptor arrays and counts, or None when the case orbit count or the compact entry count overflows the index dtypes the generated kernel uses.

volumential.orbit_arithmetic.enumerate_scalar_arithmetic_representatives(table, metadata) → ndarray

List the full-table entry id of each compact arithmetic representative.

The result is indexed by compact entry id, so entry_ids[i] is the case_id * n_pairs + source_mode_id * n_q_points + target_point_id address that compact slot i stands for.