topo_metrics.neighbours#

Functions#

graph_edges_by_cutoff(atoms[, cutoff, pair_cutoffs, ...])

Build periodic edges with a global cutoff or element-specific cutoffs.

autoreduce_neighborlist(...)

Simplify a periodic bonded graph by contracting out selected atoms.

Module Contents#

topo_metrics.neighbours.graph_edges_by_cutoff(atoms: ase.Atoms, cutoff: float = 0.0, pair_cutoffs: dict[tuple[str, str], float] | None = None, one_based: bool = True)[source]#

Build periodic edges with a global cutoff or element-specific cutoffs.

Parameters:

  • atoms – Input structure (ase.Atoms).

  • cutoff – Global distance cutoff used when pair_cutoffs is None. If pair_cutoffs is provided, this acts as the default cutoff for element pairs not present in pair_cutoffs. Set to 0.0 to effectively forbid unspecified pairs.

  • pair_cutoffs – Per-element-pair cutoffs, e.g. {(“Si”, “O”): 2.1, (“Al”, “O”): 2.0}. Pairs are treated as unordered; (“O”, “Si”) is the same as (“Si”, “O”). If None, a single global cutoff is used for all pairs.

  • one_based – If True, returned atom indices are 1-based. If False, they are 0-based.

Returns:

ndarray of shape (n_edges, 5). Columns: [i, j, sx, sy, sz], where (sx, sy, sz) are integer cell shifts.

Return type:

edges

topo_metrics.neighbours.autoreduce_neighborlist(cart_coords: numpy.typing.NDArray[numpy.float64] | list[None], frac_coords: numpy.typing.NDArray[numpy.float64] | list[None], symbols: list[str], edges: numpy.typing.NDArray[numpy.int_], remove_types: Iterable[Any] | None = None, remove_degree2: bool = False) → tuple[numpy.typing.NDArray[numpy.float64] | list[None], numpy.typing.NDArray[numpy.float64] | list[None], list[str], numpy.typing.NDArray[numpy.int_], numpy.typing.NDArray[numpy.int_]][source]#

Simplify a periodic bonded graph by contracting out selected atoms.

Parameters:

  • frac_coords – Fractional coordinates of all atoms.

  • symbols – Atomic symbols (length N).

  • edges – Columns: i+1, j+1, Sx, Sy, Sz (1-based atom indices).

  • remove_types – If not None, atoms whose symbol is in this set are removed and their neighbors are connected together (clique over neighbors). Example: {“O”}.

  • remove_degree2 – If True, atoms that are 2-connected are also removed (in addition to any atoms in remove_types).

Returns:

  • new_frac_coords ((N_keep,3) ndarray)

  • new_symbols (list[str] length N_keep)

  • new_edges ((M_new,5) int ndarray) – Same format as input edges (1-based indices).

  • old_to_new ((N,) ndarray of int) – Mapping from old atom index (0-based) to new index (0-based). -1 for removed atoms.