build_neighbor_list

mdcraft.lib.neighbor.build_neighbor_list(positions: np.ndarray[float_t] | 'unit.Quantity' | Q_, cutoff: float_t | 'unit.Quantity' | Q_, box_size: np.ndarray[float_t] | 'unit.Quantity' | Q_ | None = None, *, pbc: bool = True, algorithm: str = 'cell_list') → List[set[np.uint32]]

Builds a half neighbor list containing particle pairs within a cutoff distance.

Parameters:

positionsnumpy.ndarray, openmm.unit.Quantity, or pint.Quantity

Particle positions \(\mathbf{r}\).

Shape: \((N,d)\), where \(d\in\{2,3\}\) is the dimensionality.

Reference unit: \(\mathrm{nm}\).

cutofffloat, openmm.unit.Quantity, or pint.Quantity

Cutoff distance \(r_\mathrm{cutoff}\) for neighbor search.

Reference unit: \(\mathrm{nm}\).

box_sizenumpy.ndarray, openmm.unit.Quantity, or pint.Quantity, optional

Dimensions \((L_x,L_y[,L_z])\), lattice parameters \((a,b[,c,\alpha,\beta],\gamma)\), or box vectors \((\mathbf{a};\mathbf{b}[;\mathbf{c}])\).

Note

Lattice parameters should always be provided in an array without explicit units.

Shapes: \((d,)\) for dimensions, \((3,)\) (2D) or \((6,)\) (3D) for lattice parameters, and \((d,d)\) for box vectors.

Reference units: \(\mathrm{nm}\) for lengths and degrees (\(^\circ\)) for angles.

pbcbool, keyword-only, default: True

Specifies whether to apply periodic boundary conditions (PBC) and use the minimum image convention when calculating separation distances between particles.

algorithmstr, keyword-only, default: "cell_list"

Algorithm to use for building the neighbor list.

Valid values: "brute_force", "bvh", and "cell_list".

Returns:

neighbor_listslist

A list of neighbor lists (sets) for all particles \(i\), with each inner variable-length set containing the indices of nearby particles \(j\), where \(i<j\), that are within the cutoff distance of particle \(i\).

Shape: \((N,)\).