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, tiles: NeighborTiles | 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
tiles	NeighborTiles | 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.
• diagnostic_pairs mx.array — Return the compact cutoff-plus-skin pairs for this generation.
• 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 | NeighborTiles — Return the active force-evaluation representation.
• pair_count int — Number of unique pairs or candidate block entries.
• representation_kind str — Neighbor interaction representation shape.

Methods

force_candidates

def force_candidates(*, prefer_tiles: bool) -> mx.array | NeighborTiles

Select compact pairs or exact tiles for force binding.

Parameters

Name	Type	Default	Description
prefer_tiles	bool		Return exact tiles when they are present. Otherwise, return the compact pair representation.

Returns

• mx.array | NeighborTiles — Exact tiles only when requested and available, or compact pairs.

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

build_cell_candidate

def build_cell_candidate(positions, cell: Cell) -> NeighborListManager

Build an isolated neighbor state for a proposed periodic cell.

Parameters

Name	Type	Default	Description
positions			Candidate particle positions.
cell	Cell		Candidate periodic cell.

Returns

• NeighborListManager — A distinct manager with one neighbor list built for the candidate state. This manager does not mutate the current manager.

commit_cell_candidate

def commit_cell_candidate(candidate: NeighborListManager) -> None

Replace the current cell-bound state with a compatible candidate.

Parameters

Name	Type	Default	Description
candidate	NeighborListManager		Isolated candidate returned by build_cell_candidate.

Returns

• None

Raises

• ValueError — If the candidate uses different neighbor-list policy.

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

NeighborTiles

class NeighborTiles
    def __init__(atom_blocks: mx.array, tile_blocks: mx.array, member_mask: mx.array, exact_pair_count: int, raw_candidate_count: int, force_group_starts: mx.array | None = None, force_group_counts: mx.array | None = None, generation: int = 0, block_size: int = DEFAULT_MLX_CELL_TILE_BLOCK_SIZE)

Exact Verlet membership encoded over fixed eight-atom block tiles.

The representation is geometry-only. Each bit in member_mask records one pair that was inside cutoff + skin at rebuild time. Empty tiles are omitted, and materializing explicit pairs is an opt-in diagnostic action.

Parameters

Name	Type	Default	Description
atom_blocks	mx.array
tile_blocks	mx.array
member_mask	mx.array
exact_pair_count	int
raw_candidate_count	int
force_group_starts	mx.array | None	None
force_group_counts	mx.array | None	None
generation	int	0
block_size	int	DEFAULT_MLX_CELL_TILE_BLOCK_SIZE

Properties

• block_count int — Number of fixed-width atom blocks.
• estimated_bytes int — Estimated persistent bytes for block, tile, and membership arrays.
• force_group_count int — Number of same-left-block tile groups in the direct-force schedule.
• lanes_per_tile int — Number of atom-pair lanes in one padded tile.
• mask_word_count int — Number of 32-bit membership words stored for each tile.
• padded_lane_count int — Number of scheduled tile lanes including inactive padding.
• padding_waste_count int — Number of scheduled lanes that are not exact Verlet members.
• padding_waste_fraction float — Fraction of scheduled tile lanes outside exact Verlet membership.
• tile_count int — Number of retained non-empty block-pair tiles.

Methods

materialize_pairs

def materialize_pairs(*, sort: bool = True) -> mx.array

Decode exact Verlet members for diagnostics and tests.

Parameters

Name	Type	Default	Description
sort	bool	True	Whether to return canonical lexicographic pair order.

Returns

• mx.array — Exact unique atom pairs with shape (exact_pair_count, 2).

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