nvalchemi.hooks.NeighborListHook#

class nvalchemi.hooks.NeighborListHook(config, skin=0.0, max_neighbors=None, stage=None)[source]#

Compute and cache neighbor lists before each model evaluation.

This hook runs at BEFORE_COMPUTE and writes neighbor data into the batch so that the model’s adapt_input can read it. An optional Verlet skin buffer avoids rebuilding the list every step: the list is only recomputed when the maximum atomic displacement since the last build exceeds config.skin / 2, or when the set of active systems changes (detected via system_id).

For MATRIX format the following tensors are written to the atoms group of the batch (and thus accessible as batch.neighbor_matrix etc.):

neighbor_matrix — shape (N, max_neighbors), int32
num_neighbors — shape (N,), int32
neighbor_matrix_shifts — shape (N, max_neighbors, 3), int32 (only written when PBC is active)

For COO format the edges group of the batch is created or replaced on every rebuild, making the following accessible:

batch.neighbor_list — shape (E, 2), int32 (nvalchemi convention)
batch.neighbor_list_shifts — shape (E, 3), int32 (only when PBC active)
batch.edge_ptr — shape (N+1,), int32, derived on demand via the edge_ptr property

Parameters:

config (NeighborConfig) – Neighbor list configuration read from the model config.
skin (float, optional) – Verlet skin distance in the same length units as positions. The neighbor list is searched out to cutoff + skin so that atoms crossing the skin boundary but not the bare cutoff are already included. The list is only rebuilt when any atom has moved more than skin / 2 since the previous build (requires nvalchemiops >= 0.4); set to 0.0 (default) to rebuild every step.
max_neighbors (int | None, optional) – Maximum number of neighbors per atom for MATRIX format. When None (default), auto-estimated from the cutoff via estimate_max_neighbors(cutoff). Ignored for COO format.
stage (Enum | None, optional) – The workflow stage at which this hook runs. Defaults to DynamicsStage.BEFORE_COMPUTE.

__init__(config, skin=0.0, max_neighbors=None, stage=None)[source]#

Parameters:

config (NeighborConfig)
skin (float)
max_neighbors (int | None)
stage (Enum | None)

Return type:

None

Methods

__init__(config[, skin, max_neighbors, stage])