molsysmt.structure.get_neighbors#

molsysmt.structure.get_neighbors(molecular_system, selection='all', structure_indices='all', center_of_atoms=False, weights=None, molecular_system_2=None, selection_2=None, structure_indices_2=None, center_of_atoms_2=False, weights_2=None, threshold=None, n_neighbors=None, pairs=False, unique_pairs=False, mutual_only=False, pbc=True, output_type='numpy.ndarray', output_indices=None, output_structure_indices=None, sorted=True, engine='MolSysMT', syntax='MolSysMT', parallel=None, num_threads=None, skip_digestion=False)[source]#

Find the neighbors of each atom (or group center) within a cutoff or by count.

Exactly one of threshold or n_neighbors must be provided:

  • Threshold mode (threshold is set, n_neighbors=None): returns all neighbors whose distance is less than or equal to the cutoff. The neighbor array has dtype object because each atom may have a different neighbor count.

  • Fixed-count mode (n_neighbors is set, threshold=None): returns the n_neighbors nearest neighbors for each atom as a fixed-size integer array.

When selection_2 is None and structure_indices_2 is None the same set is used as both query and target (self-neighbor search). Self-matches (distance ≈ 0) are automatically excluded in this case.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • center_of_atoms (bool, default=False) – Whether to compute distances relative to geometric centers.

  • weights (numpy.ndarray, list, or tuple, default=None) – Atomic mass weights array for center calculation.

  • molecular_system_2 (molecular system or None, default=None) – Second molecular system to compare with the first one.

  • selection_2 (str, list, tuple, or numpy.ndarray, default=None) – Second selection string or boolean/integer array.

  • structure_indices_2 (int, list, tuple, or numpy.ndarray, default=None) – Structure indices (0-based) for the second selection.

  • center_of_atoms_2 (bool, default=False) – Whether to compute distances relative to geometric centers for selection_2.

  • weights_2 (numpy.ndarray, list, or tuple, default=None) – Atomic mass weights array for selection_2.

  • threshold (float or quantity, default=None) – Distance cutoff threshold quantity.

  • n_neighbors (int or None, default=None) – Maximum number of nearest neighbors returned for each selected element.

  • pairs (bool, default=False) – Whether corresponding selections define explicit pairs instead of a Cartesian product.

  • unique_pairs (bool, default=False) – Whether to remove duplicate undirected neighbor pairs.

  • mutual_only (bool, default=False) – Whether to retain only neighbor relations shared in both directions.

  • pbc (bool, default=True) – Whether to take periodic boundary conditions into account.

  • output_type (str, default='numpy.ndarray') – Representation used for the returned result.

  • output_indices ({'selection', 'atom', 'group'} or None, default=None) – Index convention included with the returned values.

  • output_structure_indices ({'selection', 'structure'} or None, default=None) – Structure-index convention included with the returned values.

  • sorted (bool, default=True) – Whether to sort the returned bonded atom pairs.

  • engine (str, default='MolSysMT') – Backend used to perform the calculation.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • parallel (bool or None, default=None) – Whether to use CPU parallelism, or None to use the configured default.

  • num_threads (int or None, default=None) – Number of CPU worker threads, or None to use the configured default.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

  • neighs (numpy.ndarray or list) – Neighbor indices per query element per frame. Shape is (n_structures, n_elements_1, n_neighbors) (fixed-count mode) or (n_structures, n_elements_1) with dtype object (threshold mode) when output_type='numpy.ndarray'. A list of [query_idx, neighbor_idx] pairs per frame when output_type='pairs'.

  • dists (quantity or list) – Corresponding distances as a PyUnitWizard length quantity (numpy array output) or a list of quantities per frame (pairs output).

Raises:

  • ArgumentConflictError – If both threshold and n_neighbors are set, or neither is set.

  • NotImplementedMethodError – For output-type/index combinations not yet implemented.

  • InternalAlgorithmError – If a self-neighbor search detects an inconsistency in the distance matrix (i.e., the nearest neighbor of an element is not itself).

Added in version 1.0.0.

On this page