lammps_utils.graph package

Graph utilities for molecular structures.

This submodule provides functions for: - Finding the farthest-apart atoms in a molecular graph, - Identifying atoms that are part of ring structures, - Unwrapping molecular coordinates under periodic boundary conditions (PBC).

lammps_utils.graph.farthest_node_pair(graph: Graph, ignore_nodes: set[int] = {}, return_length: bool = False) → Generator[tuple[int, int], None, None] | Generator[tuple[tuple[int, int], int], None, None]

Finds the farthest node pair in each connected component of the graph.

Parameters:

  • graph (nx.Graph) – The input graph.

  • ignore_nodes (set[int], optional) – Set of nodes to ignore during the search, by default an empty set.

  • return_length (bool, optional) – Whether to return the maximum distance along with the node pair, by default False.

Yields:

  • Union[

  • Generator[tuple[int, int], None, None],

  • Generator[tuple[tuple[int, int], int], None, None]

  • ] – Yields tuples of farthest node pairs. If return_length is True, the second value in the tuple is the maximum distance.

Raises:

ValueError – If no valid pair is found in any connected component.

lammps_utils.graph.nodes_in_cycles(graph: Graph) → set[int]

Returns nodes that belong to cycles in the graph.

Parameters:

graph (nx.Graph) – The input undirected graph.

Returns:

A set of node identifiers that belong to cycles in the graph.

Return type:

set[int]

lammps_utils.graph.unwrap_molecule_under_pbc(graph: Graph, positions: ndarray, cell_size: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → ndarray

Unwrap molecular coordinates under periodic boundary conditions (PBC).

This function traverses the molecular graph and adjusts atomic positions so that bonded atoms are placed close together, eliminating jumps caused by PBC wrapping. It operates independently on each connected component of the graph.

Parameters:

  • graph (nx.Graph) – A molecular graph where nodes correspond to atoms and edges represent bonds. Each connected component is treated as an independent molecule or fragment.

  • positions (np.ndarray) – A (N, 3) array of atomic coordinates, where N is the number of atoms.

  • cell_size (ArrayLike) – A 1D array-like of length 3 specifying the dimensions of the periodic simulation box.

Returns:

A (N, 3) NumPy array of unwrapped atomic coordinates. The coordinates are adjusted such that bonded atoms are positioned contiguously within the same image of the unit cell.

Return type:

np.ndarray

Raises:

AssertionError – If input dimensions are invalid or if the number of atoms in graph and positions do not match.

Notes

This method assumes that atoms are initially located within the same periodic image, and it corrects discontinuities across periodic boundaries by walking through the molecular graph using a breadth-first traversal.

lammps_utils.graph.wrap_positions_to_cell(positions: ndarray, cell_bounds: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | ndarray) → ndarray

Wrap 3D positions into a periodic simulation cell.

This function takes an array of 3D Cartesian coordinates and wraps each position into the simulation cell defined by the given bounds using periodic boundary conditions.

Parameters:

  • positions (np.ndarray) – A NumPy array of shape (N, 3) representing the positions of N atoms.

  • cell_bounds (tuple or np.ndarray) – The simulation cell bounds. Can be provided as a tuple of ((xlo, xhi), (ylo, yhi), (zlo, zhi)) or a NumPy array of shape (3, 2).

Returns:

A NumPy array of shape (N, 3) containing the wrapped positions.

Return type:

np.ndarray