neighbors

Neighbor-list construction for periodic MD.

import mlx_atomistic.neighbors

Classes

NeighborBlocks

class NeighborBlocks
    def __init__(left: mx.array, right: mx.array, valid_mask: mx.array, block_size: int, candidate_count: int, compact_pair_count: int)

Fixed-shape candidate pair blocks for MLX-side cutoff filtering.

Parameters

Name	Type	Default	Description
left	mx.array
right	mx.array
valid_mask	mx.array
block_size	int
candidate_count	int
compact_pair_count	int

Properties

• block_count int — Number of fixed-size candidate blocks.
• candidate_waste_count int — Number of emitted block candidates outside the neighbor radius.
• estimated_bytes int — Estimated storage bytes for block indices and validity mask.
• padded_candidate_count int — Number of candidate slots including padding.

NeighborList

class NeighborList
    def __init__(pairs: mx.array, cutoff: float, skin: float = 0.0, stats: PairListStats | None = None, blocks: NeighborBlocks | None = None)

Neighbor interactions for pairwise potentials.

Parameters

Name	Type	Default	Description
pairs	mx.array
cutoff	float
skin	float	0.0
stats	PairListStats | None	None
blocks	NeighborBlocks | None	None

Properties

• backend str — Pair-construction backend name.
• candidate_count int | None — Number of candidate interactions tested before cutoff filtering.
• candidate_waste_count int | None — Number of candidate interactions rejected by compaction/filtering.
• candidate_waste_fraction float | None — Fraction of emitted candidates rejected by compaction/filtering.
• compact_pair_count int — Number of compact pairs accepted by the neighbor search radius.
• compaction_backend str | None — Backend used to compact candidates into explicit pairs, if any.
• estimated_candidate_bytes int — Estimated bytes for backend candidate testing arrays.
• estimated_cell_list_bytes int — Estimated bytes for cell-list construction arrays.
• estimated_compact_pair_bytes int — Estimated bytes for compact int32 pairs accepted by the search radius.
• estimated_pair_bytes int — Estimated bytes for the compact int32 pair array.
• fallback_reason str | None — Reason an accelerated representation fell back or used a hybrid step.
• interactions mx.array | NeighborBlocks — Return the active force-evaluation representation.
• pair_count int — Number of unique pairs or candidate block entries.
• representation_kind str — Neighbor interaction representation shape.

NeighborListManager

class NeighborListManager
    def __init__(cell: Cell, cutoff: float, skin: float = 0.3, check_interval: int = 1, sort_pairs: bool = False, max_workers: int | None = None, backend: NeighborBackend = 'auto', max_mlx_dense_atoms: int = DEFAULT_MLX_DENSE_PAIR_LIMIT, block_size: int = DEFAULT_MLX_CELL_BLOCK_SIZE, displacement_check_backend: NeighborCheckBackend = 'numpy', neighbor_list: NeighborList | None = None, reference_positions: mx.array | None = None, rebuild_count: int = 0, last_max_displacement: float = 0.0, updates_since_check: int = 0, rebuild_wall_seconds: float = 0.0, update_wall_seconds: float = 0.0)

Manage Verlet neighbor-list rebuilds during an MD trajectory.

Parameters

Name	Type	Default	Description
cell	Cell
cutoff	float
skin	float	0.3
check_interval	int	1
sort_pairs	bool	False
max_workers	int | None	None
backend	NeighborBackend	'auto'
max_mlx_dense_atoms	int	DEFAULT_MLX_DENSE_PAIR_LIMIT
block_size	int	DEFAULT_MLX_CELL_BLOCK_SIZE
displacement_check_backend	NeighborCheckBackend	'numpy'
neighbor_list	NeighborList | None	None
reference_positions	mx.array | None	None
rebuild_count	int	0
last_max_displacement	float	0.0
updates_since_check	int	0
rebuild_wall_seconds	float	0.0
update_wall_seconds	float	0.0

Properties

• rebuild_threshold float — Maximum displacement before the Verlet list must be rebuilt.

Methods

needs_rebuild

def needs_rebuild(positions) -> bool

Return true when positions have moved too far from the reference frame.

Parameters

Name	Type	Default	Description
positions

Returns

• bool

rebuild

def rebuild(positions) -> NeighborList

Force a neighbor-list rebuild from current positions.

Parameters

Name	Type	Default	Description
positions

Returns

• NeighborList

update

def update(positions) -> NeighborList

Return a current neighbor list, rebuilding if needed.

Parameters

Name	Type	Default	Description
positions

Returns

• NeighborList

Functions

build_neighbor_list

def build_neighbor_list(positions, cell: Cell, *, cutoff: float, skin: float = 0.3, sort_pairs: bool = True, max_workers: int | None = None, backend: NeighborBackend = 'periodic_cell_list', max_mlx_dense_atoms: int = DEFAULT_MLX_DENSE_PAIR_LIMIT, block_size: int = DEFAULT_MLX_CELL_BLOCK_SIZE) -> NeighborList

Build a periodic cell-list neighbor list with unique i < j pairs.

Parameters

Name	Type	Default	Description
positions
cell	Cell
cutoff	float
skin	float	0.3
sort_pairs	bool	True
max_workers	int | None	None
backend	NeighborBackend	'periodic_cell_list'
max_mlx_dense_atoms	int	DEFAULT_MLX_DENSE_PAIR_LIMIT
block_size	int	DEFAULT_MLX_CELL_BLOCK_SIZE

Returns

• NeighborList

validate_neighbor_backend

def validate_neighbor_backend(backend: str) -> NeighborBackend

Validate and normalize a neighbor-list construction backend.

Parameters

Name	Type	Default	Description
backend	str

Returns

• NeighborBackend

validate_neighbor_check_backend

def validate_neighbor_check_backend(backend: str) -> NeighborCheckBackend

Validate and normalize a neighbor-list displacement check backend.

Parameters

Name	Type	Default	Description
backend	str

Returns

• NeighborCheckBackend