nvalchemi.hooks.NeighborListHook

class nvalchemi.hooks.NeighborListHook(config, skin=0.0, max_neighbors=None, stage=None, method=None)

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 raw Cartesian 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’s raw Cartesian position 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) – Explicit workflow stage at which this hook runs. Defaults to None; when None the hook fires at DynamicsStage.BEFORE_COMPUTE (see the class description above).

• method (str | None, optional) – Explicit nvalchemiops neighbor-list method to use. When None (default), the hook selects an appropriate method from the batch shape and periodic-cell metadata.