volumential.list1

List 1 (near-field) potential evaluation from CSR tree data.

This module owns the loopy kernel that adds the near-field (list 1) contribution to a volume potential: for every target box it walks its neighboring source boxes, encodes the box-center displacement into an interaction case id, looks the corresponding table entry up (densely, or through one of the ORBIT reconstruction schemes) and accumulates the scaled contribution.

NearFieldEvalBase holds the table-shape bookkeeping and the kernel scaling policy; NearFieldFromCSR generates and runs the kernel.

class volumential.list1.KernelScalingPolicy(kernel_name: str, mode: str, infer_kernel_scaling: bool, single_table_scaling_supported: bool, reference_table_level: int | None, scaling_code: str, displacement_code: str, table_level_code: str, notes: str)

Bases: object

Describes how a List 1 evaluator selects and rescales table data.

kernel_name: str

mode: str

infer_kernel_scaling: bool

single_table_scaling_supported: bool

reference_table_level: int | None

scaling_code: str

displacement_code: str

table_level_code: str

notes: str

class volumential.list1.NearFieldEvalBase(integral_kernel, table_data_shapes, potential_kind=1, options=None, name=None, device=None, **kwargs)

Bases: KernelCacheWrapper

Base class of near-field evaluator.

default_name = 'near_field_eval_base'

get_cache_key() → tuple

Return the loopy kernel cache key for this evaluator.

class volumential.list1.NearFieldFromCSR(integral_kernel, table_data_shapes, potential_kind=1, options=None, name=None, device=None, **kwargs)

Bases: NearFieldEvalBase

Evaluate the near-field potentials from CSR representation of the tree. The class supports auto-scaling of simple kernels.

default_name = 'near_field_from_csr'

get_kernel_scaling_policy(box_name: str = 'sbox') → KernelScalingPolicy

Return the table-level and scaling policy used by generated List 1 code.

mode == "canonical_single_table" means table level 0 is reused for all source-box levels with scaling_code and displacement_code. mode == "fixed_single_table" means table level 0 is used without scaling and runtime checks require all source boxes to match the table starting level. mode == "per_level_tables" means no kernel scaling is applied and the table level is selected from the source-box level.

codegen_vec_component(d: int | None = None) → str

Generate the code for one component of the encoded case vector.

codegen_vec_id() → str

Generate the code that encodes a case vector into a single id.

codegen_compute_scaling(box_name: str = 'sbox') → str

box_name: the name of the box whose extent is used.

codegen_compute_displacement(box_name: str = 'sbox') → str

C code for the kernel displacement to apply to box box_name.

The displacement_code of the policy get_kernel_scaling_policy() returns, which is the caller’s own kernel_displacement_code under custom_single_table, the rule inferred from the box extent under canonical_single_table, and 0.0 under the two modes that do not scale at all.

codegen_get_table_level(box_name: str = 'sbox') → str

C code that picks which table level box box_name reads from.

The table_level_code of the policy get_kernel_scaling_policy() returns: the inferred rule under canonical_single_table, the constant table level 0 under the two other single-table modes, and under per_level_tables the box’s level as an offset from table_starting_level, clamped to the cached range – so it is an index into the cached levels, not the absolute level of the box.

codegen_exterior_part() → str

Computes the exterior contribution. This is nonzero for inverse-type potentials like the fractional Laplacian.

get_kernel()

Generate the loopy kernel that evaluates the list 1 contribution.

get_cache_key() → tuple

Return the loopy kernel cache key for this evaluator.

get_optimized_kernel(ncpus=None)

Return the transformed kernel, tagged for hardware parallelism.