nvalchemi.models.base.NeighborConfig

pydantic model nvalchemi.models.base.NeighborConfig

Configuration for on-the-fly neighbor list construction.

An instance of this class attached to a ModelConfig (via its neighbor_config field) signals that the model requires a neighbor list and describes the format and parameters it expects. At runtime a NeighborListHook reads this config to compute and cache the appropriate neighbor data on each Batch before the model’s forward pass, rebuilding only when atoms have moved beyond the Verlet skin.

The single required argument is cutoff (in the same length units as positions). format selects the storage layout: COO produces a sparse [E, 2] edge index (the default, used by most GNN-based MLIPs), while MATRIX produces a dense [N, max_neighbors] neighbor matrix (used by Warp interaction kernels) — see NeighborListFormat. half_list and skin tune pair deduplication and rebuild frequency, respectively.

Examples

A minimal sparse (COO) neighbor list with a 5 A cutoff:

>>> from nvalchemi.models.base import NeighborConfig
>>> nc = NeighborConfig(cutoff=5.0)
>>> nc.format
<NeighborListFormat.COO: 'coo'>

A dense half neighbor list with a Verlet skin, e.g. for a Warp kernel:

>>> from nvalchemi.models.base import NeighborListFormat
>>> nc = NeighborConfig(
...     cutoff=5.0,
...     format=NeighborListFormat.MATRIX,
...     half_list=True,
...     skin=1.0,
... )

Attach it to a ModelConfig to declare a neighbor-list requirement:

>>> from nvalchemi.models.base import ModelConfig
>>> cfg = ModelConfig(neighbor_config=NeighborConfig(cutoff=5.0))
>>> cfg.needs_neighborlist
True

Notes

• skin=0.0 (the default) rebuilds the neighbor list every step; a positive skin defers rebuilds until any atom moves more than skin / 2, trading memory staleness for fewer rebuilds.

• half_list=True stores each (i, j) pair once; the interaction kernel applies Newton’s third law to recover forces on both atoms, so it is only appropriate for kernels that expect a half list.

field cutoff: float [Required]

Interaction cutoff radius in the same length units as positions.

field format: NeighborListFormat = NeighborListFormat.COO

Whether to build a dense neighbor matrix (MATRIX) or a sparse edge-index list (COO). Defaults to COO.

field half_list: bool = False

If True, each pair (i, j) with i < j appears only once. Newton’s third law is applied inside the interaction kernel to recover forces on both atoms. Defaults to False.

field skin: float = 0.0

Verlet skin distance. The neighbor list is only rebuilt when any atom has moved more than skin / 2 since the last build. Set to 0.0 (default) to rebuild every step.