topo_metrics.io.lammps_data
===========================

.. py:module:: topo_metrics.io.lammps_data


Classes
-------

.. autoapisummary::

   topo_metrics.io.lammps_data.LammpsDataComponents


Functions
---------

.. autoapisummary::

   topo_metrics.io.lammps_data.load_lammps_data


Module Contents
---------------

.. py:class:: LammpsDataComponents

   Components extracted from a LAMMPS data file.


   .. py:attribute:: ase_atoms
      :type:  ase.Atoms

      ASE atoms object with cell/pbc/positions populated.


   .. py:attribute:: edges
      :type:  numpy.typing.NDArray[numpy.int_]

      [i, j, sx, sy, sz] (1-based indices).

      :type: Neighbourlist with image shifts


   .. py:attribute:: symbols
      :type:  list[str]

      Per-node symbols/types used for Topology node types.


   .. py:attribute:: cart_coords
      :type:  numpy.typing.NDArray[numpy.floating]

      Cartesian coordinates, shape (N, 3).


   .. py:attribute:: frac_coords
      :type:  numpy.typing.NDArray[numpy.floating] | list[None]

      Fractional coordinates, shape (N, 3) if periodic, else list[None].


.. py:function:: load_lammps_data(filename: pathlib.Path | str, *, atom_style: str = 'atomic', units: str = 'metal', sort_by_id: bool = True, prefer_bonds: bool = True, cutoff: float = 0.0, pair_cutoffs: dict[tuple[str, str], float] | None = None, contract_neighborlist: bool = False, remove_types: Iterable[object] | None = None, remove_degree2: bool = False, omit_node_types: bool = False) -> LammpsDataComponents

   Load a LAMMPS data file into ASE plus a periodic bond graph.

   This reader uses ASE's LAMMPS-data support to obtain an ``ase.Atoms``
   object. If a ``Bonds`` section is present, bonds are used to construct the
   neighbourlist; otherwise, a neighbour list can be inferred by cutoff using
   :func:`topo_metrics.neighbours.graph_edges_by_cutoff`.

   The neighbour list uses the convention ``[i, j, sx, sy, sz]`` where indices
   are 1-based and the image shift ``(sx, sy, sz)`` is chosen assuming the
   minimum image convention (MIC).